Disgrace package for R Statistical System.
Note Please!
The support for this package is discontinued. It is replaced now with
newer package RGrace.
Purpose.
Disgrace is a package for creation of simple every-day diagramms and
charts, although it is suited for production of publiction-quality
scientific graphics. It combines easy to use point-and-click interface,
ability to interact with graphic with mouse clicks and drags and
possibility to incorporate rather sophisticated R-scripts in the process
of plotting. It is written (almost) entirly in R language (as it heavily
depends on environment() I think it is not compatible with S-language)
and use GTK (ver. 1.2.x) as a front end toolkit.
Its name mean nothing except what it was loosely modelled after Grace charting
application.
Dependencies.
To install Disgrace package you need GTK-1.2 and Glade system libraries
(www.gtk.org). Also you need RGtk,
RGtkGlade, gtkdevice and grid R-packages installed (you can find them
on CRAN or Omegahat sites). Of course you will
need R Statistical System and I
highly recommend to install an Emacs
Speaks Statistics package - it makes a process of developing R
scripts under Emacs a lot easier.
And last but not least - you will need Linux. This package is tested
and supported under Linux only (!).
Downloads.
Stable (more or less) version:
Disgrace_0.2-5.tar.gz
The last one:
Disgrace_0.2-5.tar.gz
ChangeLog
Install and kick-start.
Install as usual - under root do R INSTALL Disgrace-x.x.tar.gz. From
version 0.2.2 up Disgrace has a C-code inset and if R INSTALL fails
first check Makevars file in src sub-directory. In this file you have to
specify paths to gtk, glib and gdk includes and libraries. Edit it to
match your system installation.
Run R and issue command library(Disgrace).
After that you can call plotting window by command figure() or plot
something at once by command ggplot(c(1,2,3,4),c(1,2,3,4)) (or any other
numerical vectors). ggplot() is a shortcut for figure()$panel(
)$element(c(1,2,3,4),c(1,2,3,4)).
When data is plotted you may change its appearence by GUI controls that
are located at slide panel to the left of plotting area.
GUI Help.
Some "theory". You can have in R sessiom multiple figure()'s, in each of them may be
severals panel()'s and in each
panel (i.e. 4 axes with labels and tags) may be several data curves
("elements") and text annotations bound to these axes coordinate system
("native units" in terms of grid package). In every moment only one of
figures is active and current.Figure
global variable holds currently active figure. "Current panel" may be
chosen by combo box in this figure or selected from console by
command current.Figure$panel(select=x)
where x is panel number and x corresponds to position of this panel in
combobox. Plotting is done by command ggplot(x,y)
with suitable data vectors x,y and output of this command will be
directed to current panel inside current.Figure(if
either of them does not exist it will be created). You can in any time
create blank figure or panel by command figure()->fig and fig$panel() and assign returned
values to variables (this functions has an side effect of setting current.Figure and "current panel"
to returned values). Say you have created panel as current.Figure$panel()->SavedPanel. Then
in any time you may add plot to SavedPanel
(irrespective what "current panel" is) by command SavedPanel$element(x,y) (should I
mention what SavedPanel$element(select=num)
return you a element's "handle" for editing/contemplating?).
Selecting/setting annotations works just the same - SavedPanel$annotation("test label",x=1,y=1)
(or SavedPanel$annotation(label=list("test
label",expression(frac(x,y))),x=1,y=1) - for multilined text)
to add annotation and SavedPanel$annotation(select=num)
to select an existing num'th one. Figure selecting can not be done
through command line (DO NOT do asignments to current.Figure variable !) but
usually this is not needed - then you edit plots, panels, annotations
through GUI current.Figure is
set to the figure you will expect changes will be applyed to.
The most obvious side effect of all these commands is
graphic output produced in drawing area of the figure and also changes
in GUI controls located on left hand slide panel (then you first opens
figure slide panel is collapsed and you should drag its handle to make
it visible).
It has a notebook with "Panels", "Elements", "Annotations" pages and
short menu. Let us look at the notebook:
Panels.
Here you can select and edit properties of panels(axes) located in this
figure.
"Apply" button - changes you
made in GUI controls are submitted to panel after this button is pressed.
"Add New" button - add new blank
panel with default values. Make it the current one.
"Delete" button - delete the
current panel.
"Autorange" button - rescales
current panel so all elements in it will be shown.
Unnamed combo box - list of
panels in this figure. Selecting entry in it made selected panel
current. Also updates GUI controls with the panel properties values.
"X Range", "Y Range" text
entries - max and min values for panel's X,Y axes.
Notebook "Left","Bottom","Top","Right"
with two entries on each page for controlling corresponding axes ticks
positions,labels and its title. Axis title may be plain text (in this
case you should quote text title in Label text entry) or any
mathematical formula (see plotmath in Reference manual) and should be
wrapped with expression()
command. Example you may see on screenshot.Blank
entry for "Ticks" means what ticks are evenly distributed along axes
and located in places with "pretty" labels. Specify Inf if you do not want ticks be
drawn on this axes. c(1,2,3) -
if you want 3 ticks in position 1,2,3.
NOTE. Note please that "ticks" parameter is string (class character)
which is parsed and evaluated when it is first set or when panels's
x/yscale are changed. This is different from other plot functions in R
which take a numeric vector as value for at parameter. Evaluation takes
place twice in an environment with RANGE and TICK.LAB variables set
(RANGE is current range for panel and TICK.LAB is either "tick" or
"label"). So you may specify the value list(tick=c(0,18,22),label=c("Nothing","Enough","Too
much"))[[TICK.LAB]] for axis ticks and have a graph like this. RANGE variable is provided
in case you will want to override default procedure of automatic
calculation of tick placement (for example if you want to draw
non-linear axis, e.g. logarithmic or reciprocal ones).
"Grilled?" and "Ticks in?" check
boxes - add/remove grid from panel and controls direction of ticks
(inward or outward of plotting area).
"Panel placement" - set the
position of panel with respect to figure's border.
Elements.
Here you can select and edit properties of elements (data lines)
located in the panel you have selected beforehand on "Panels" page.
"Apply" button - changes you
have made in GUI controls are submitted only after this button is
pressed.
"Delete" button - delete the
selected element.
Unnamed combo box - list of
elements in the current panel. Selecting entry in it updates GUI
controls with element's properties values.
"Symbol:..." option menu -
symbol to be drawn at data line's nodes.
"Line:..." option menu - type of
line to be draw between data line's nodes.
"Symbol size" spin box - size of
symbol in "chars" unit (see grid documentation).
"Line width" spin box - width of
line in points. Zero means to use default line width (lwd field is not
set inside gpar structure)
"Outline color" combo box -
line's color ("default" - means what col field is not set in gpar
structure).
"Fill color" combo box - the
color data points are filled with ("default" - means what fill field is
not set in gpar structure).
Annotations.
Here you can select and edit properties of text annotations located in
the panel you have selected beforehand on "Panels" page.
"Apply" button - changes you
have made in GUI controls are submitted only after this button is
pressed.
"Delete" button - delete the
selected annotation.
"Place new" button - clicking
this button and after that clicking left mouse button in plotting area
will place new text annotations in mouse cursor position inside current
panel with properties you have specified in GUI controls.
Text widget - annotation's text.
Each line can either be a plain string (class character) or mathematical
expression (class expression). The same rules regarding
quoting/expression() as for axis title apply. There is also one
exception: you can use command BULLET(panel=n,element=m) (with no
quotes) to have a graphical representation of m'th element from the n'th
panel in the selected annotation. Note that this representation is
persistent and does not track changes that you have made to data line.
So after editing data line you have to re-Apply changes to the
annotation containing BULLET comand representing this data line.
"Color" combobox - foreground
color of text("default" - means what col field is not set in gpar
structure) .
"Text Style" frame - select here
font size (in points) and style (bold,italic...) for the text
annotation. "Apply to panel" and "Apply to figure" buttons set all
annotations and axis titles to this style and size. Zero text size and
"default" text style means what fontsize and fontstyle fields are not
set in gpar structure). Note,
please, that the slected style is not applied to expressions (math text)
- in that case you have to explicitly specify style inside expression()
command.
"Rotation" spinbox - rotates
selected annotation counterclockwise.
"Framed?" check-box - adds a
2-point frame around annotation.
"File" menu.
Standard. "Save as","Open" allow you to save figure in
file and to open it later for further editing. It saves figure as
R-script which can be edited by your favorite text editor if something
goes wrong. This "format" has also one nice feature - there is no
questions of incompatibilities. You can save and open figure script
files made in different versions of Disgrace as long as R versions you
do it in is compatible between themselves. And one more note - although
the figure file itself is a text file, some objects are stored in it
with serialize() call, so manually editing them may prove to be not so
easy. "Print" menu is a fake. It
does not print but rather creates (or overwrites existing one - you are
warned!) "RPlots.ps" postscript file in the working directory.
"Edit" menu.
Operations with internal copy/paste buffer (it has nothing to do with
X-selection mechanism). You can copy selected panel or element ("Copy panel", "Copy element" menu items) into this
buffer and paste ("Paste" menu
item) selected structure into the figure/panel in the same R-session.
"Graph Interaction" menu.
When you "click-and-drag" left mouse button inside plotting area some
code will be executed depending on value you have set in this radio-menu.
Some "theory" again. Disgrace supports "hooks" mechanism which somewhat
resembles one in Emacs. So beside "hard-coded" default
action Disgrace executes when you click and drag mouse
pointer you may provide your own code to be executed. This is rather
simple - just write a function according to some
template and assign this function to variable "on.select...." in
user's (AKA global) environment (it will be explained further).
Disgrace looks after these variables and tries to call them as function
when specific event has occured. All hooks are defined as on.select.xxx<-function(region,handle,index,data), so the
same function may be shared among hooks, although the exact meaning of
parameters may be different. All hooks are called when left mouse button
is released.
"Select Annotation" - selects
the annotation closest to "press" point inside current panel. It
also write annotation's properties to GUI controls at
"Annotations" page. The hook is on.select.annotation
with handle set to grid.text
structure representing selected annotation. region is a matrix
with coordinates of press and release poins. All other parameters are
always NULL. Default hook moves
the selected annotation from its position to the release point.
"Select Element" - clicking
selects the element closest to "press" point inside the current
panel. It also write its properties to GUI controls on
"Elements" page. It has a hook on.select.data
with parameters:
handle - grid.grob representing
element's structure (which is grid.data). See grid.get,grid.edit in grid
package documentation.
data - 2-column matrix with x,y
coordinates of element's nodes.
index - integer value - index
of point in the selected element closest to "press"
point. I.e. x[index],y[index] - are
roughly coordinates of the point where you have clicked the
mouse button.
region - matrix with
coordinates of press and release poins (sorted in ascending order).
Default hook exports all parametrs to global environment as .DATA,.HANDLE,.REG,.INDEX matrices.
Try to set on.select.element<-sort.data
for points in selected curve to be sorted according to x-values and
curve to be redrawn.
"Select Region" - clicking and
dragging sweeps a rectangular region inside current panel. It has a hook on.select.region with parameters:
region - rbind(c(xmin,xmax),c(ymin,ymax)) - rectangular region
handle - grid.grob of
previously selected element
index - indexes of points of
previously selected element that are inside the selected region.
data - coordinates of the
points of previously selected element that are inside the selected
region.
Default hook exports all parametrs to global environment as .DATA,.HANDLE,.REG,.INDEX matrices.
Try to set on.select.region <-
delete.in.range and erase part by part selected data curve.
"Select Points" - just get
coordinates of "press" point inside current panel. The hook on.select.points is called after
every left mouse button click and whenever Esc or Return key is clicked
inside plotting area.
Parameters are: region -
coordinates of click point (if you have clicked mouse button) or NULL
(if you have clicked Esc/Enter key) and data - 2-column matrix with
coordinates of previously clicked points. When you hit Esc the first row
(i.e. coordinates of last point selected) are deleted and after that
hook is called. When you hit Enter the hook is called and after that data matrix is NULLed so the next
click will call hook with data containing only one row. All other
parameters are NULLs. Default hook exports all parametrs to global
environment as .DATA,.HANDLE,.REG,.INDEX
matrices.
"Zoom" - click and drag zoom the
selected area. No hook. You may restore previously selected scales by
clicking Esc key inside plotting area.
Thanks.
Paul Murrell - for grid package.
Duncan Temple Lang - for RGtk and RGtkGlade packages.
Lyndon Drake Packaging,Martyn Plummer and Duncan Temple Lang - for
gtkDevice package.
And all R-project team for great data analysis software.
Feedback