RGrace-GUI {RGrace} | R Documentation |
The short description of RGrace's GUI controls (GTK version).
Although you can use RGrace window from command line interface as
standard R Graphic device with commands like ggplot
and
current.Figure$...
,current.Panel$...
one of the goals of RGrace
was to let user create and edit simple graphics through GUI
without applying to R command line. Typical usage of RGrace would be -
opening text file with data table, plotting some of this data table
columns on the current figure (menu item File->Download),
changing the appearance of this data curve (with controls on
Panel/Element notebook), adding text annotation to the graphic
(Annotation page), making some sort of simple data analysis (Hooks
menu), saving resulting graphic as R script or/and printing to
ps/pdf/png file (menu items File->Save as
/ File->Print->PS,PDF,PNG,PDFwrite).
RGrace figure has a notebook with "Panels", "Elements", "Annotations" pages, short menu ("File","Edit",...) and interaction context selection option menu. All these controls are located at the initially collapsed slide panel to the left of the drawing area, so to make them visible one should drag out slide panel by its handle. Let us look at the notebook: begin{description} item[Panels.]
Here you can select and edit properties of panel
s(axes) located in this figure.
begin{description}
item["Apply" button] - changes you made in GUI controls are submitted to panel after this button is pressed.
item["Add New" button] - add new blank panel with default values. Make it the current one.
item["Delete" button] - delete the current panel from figure.
item["Autorange" button] - rescales current panel so all elements in it will be shown.
item[Unnamed combo box] - list of panels in this figure. Selecting entry in it made selected panel current. Also updates GUI controls with the values of panel's properties.
item["X Range", "Y Range" text entries] - max and min values for panel's X,Y axes.
item[Notebook "Left","Bottom","Top","Right"] with two entries on
each page for controlling corresponding axes ticks positions,labels
and titles. Axis title may be plain text (in this case you should
quote text title in Label text entry) or any mathematical formula
(see plotmath
) 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 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 figure's
environment with RANGE
and TICK.LAB
variables set to
the current panel's range and TICK.LAB
is either "tick" or
"label". This means you can specify the value
list(tick=c(0,18,22),label=c("Nothing","Enough","Too
much"))[[TICK.LAB]]
for axis ticks and have a graph with 3 ticks
at positions 0,18,22 labeled as "Nothing","Enough","Too
much". 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).
item["Grilled?" and "Ticks in?" check boxes] - add/remove grid from panel and controls direction of ticks (inward or outward of plotting area).
item["Panel placement" frame] - set the position of panel with respect to figure's border. end{description}
item[Elements.]
Here you can select and edit properties of elements (data lines) located in the panel you have selected beforehand on "Panels" page. begin{description} item["Apply" button] - changes you have made in GUI controls are submitted only after this button is pressed.
item["Delete" button] - delete the selected element.
item[Unnamed combo box] - list of elements in the current panel. Selecting entry in it updates GUI controls with element's properties values.
item["Symbol:..." combo box] - symbol to be drawn at data line's nodes.
item["Line:..." combo box] - type of line to be draw between data line's nodes.
item["Symbol size" spin box] - size of symbol in "chars" unit (see grid documentation).
item["Line width" spin box] - width of line in points. Zero means to use default line width (lwd field is not set inside gpar structure)
item["Outline color" combo box] - line's color ("default" - means what col field is not set in gpar structure).
item["Fill color" combo box] - the color data points are filled with ("default" - means what fill field is not set in gpar structure).
item["Data" frame] - simple editor which allows to edit values of data line's points. "Index" spin-box selects index of data point to edit. Coordinates/error bars lengths of selected data point are displayed in "X","Y","W" and "H" entries and there new values for this point can be entered.
item["Error Representation" combo box] - how w
,h
parameters are drawn on graphic. Possible choices are: as error
bars ("whiskers"), colored area ("areafill") or arrows.
item["Apply Color/Symbol Values to" combo box] - if individual
points of selected data line have different fill
color, symbol size and symbol type
(i.e. at least one of the parameters gp=gpar(fill=...)
,
size
, pch
to element
or
ggplot
or grid.data
functions is
vector) then this combo box allow user to
control the way changes made in the GUI controls are applied to
selected data curve. In this case changing the value of "Index"
spin-box in "Data" frame changes the selection of "Fill color",
"Symbol:..." combo-boxes and the value of "Symbol size" spin-box
too. If in this combo-box "All Points" item is selected then
pressing "Apply" button sets the color/symbol value of all points in data
curve to the values of selected point; "Selected point" -
changes the values of currently selected point; "Points with the
Same Values" - changes the value of points which have the symbol
size or symbol type or fill color value the same as the selected
one. Note that this operation does not change the length of the
vectors (the vectors with different lengths are recycled as usual),
so you can not use this controls to insert new "type" of data
point into existing data line, but only to tune an appearance of
already existing one. If the color/symbol values are the same
along the curve then
effect of selection made in this
combo box is just the same.
end{description}
item[Annotations] Here you can select and edit properties of text annotations located in the panel you have selected beforehand on "Panels" page.
begin{description}
item["Apply" button] - changes you have made in GUI controls are submitted only after this button is pressed.
item["Delete" button] - delete the selected annotation.
item["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.
item[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.
item["Color" combobox] - foreground color of text("default" - means what col field is not set in gpar structure) .
item["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 selected style is not applied to expressions (math text) - in that case you have to explicitly specify style inside expression() command.
item["Rotation" spinbox] - rotates selected annotation counterclockwise.
item["Framed?" check-box] - adds a 2-point frame around annotation. end{description} end{description}
At the top of slide panel there is a short menu bar with two items: begin{description}
item["File" menu.] Almost standard. begin{description}
item["Save as","Save","Open" menu-items] - 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 RGrace 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
dumped into it with serialize()
call, so manually editing them
may prove to be not so easy.
item["Download from File" menu item] - read ascii data tables and
plot them on the figure. After clicking it the user presented with
standard File selection dialog and after selecting appropriate file
its content read with read.table
function. The columns
of resulting data.frame
are fed into the form where user
supposed to select how this data.frame
will be plotted on the
figure. The form itself has two columns - in the first column is the
text entries with the names of data frame's columns (as the text of this entries
will be parsed and evaled before plotting, you can enter here any
valid R expression), in the second the combo-boxes with the "role" of
the data column (i.e. how the values of the column will be interpreted
by RGrace). Suppose we have data.frame with columns
X
,Val1
,Val2
,Val1Err
,SampleGroup
(independent variable, results of two type of measurements, errors of
the 1st type of measurements and numerical values identifying the
samples these measurements was taken on). In this case in the form we
will have five rows, the names of columns will be displayed in the
text entries and combo boxes will contain 16 items
"None", "X", "Y1"-"Y5", "ErrX", "ErrY1"-"ErrY5", "Color", "Symbol",
"Size". Suppose we want to visualize our data at its best and plot not
the Val2
but its logarithm. In this case we select in
combo-boxes: items "X" (x-value for all curves, if "X" is not present
as a "role" then data of all curves will be plotted against theirs indices), "Y1" (value of first
data-line), "Y2" (value of the second data line), "ErrY1" (vertical
error bar of first curve) and "Color" (or "Size" or "Symbol", the difference
between them is that in the first case data is scaled to
fit in palette()
range, in the second is plotted as is,
i.e. size of data line's symbols is proportional to the data values
and in the third data is coerced to integer and this value is used as
a symbol code, does it fall in range 0-26 or not is not checked). In the
text entry corresponding to "Y2" we also type
log10(Val2)
. Pressing button "Apply" on the form will plot
the data we have selected and "Quit" just closes the form.
item["Upload to File" menu item] - puts the selected data line to the ascii file as a text table.
item["Print" menu] - hardcopies the figure into file ("RPlots.*" in
the current directory, extension depends on the selected print
driver). The available choice of print drivers is "PS","PDF","PNG"
with backends postscript
, pdf
and png
; and
"PDFwrite" with backend
bitmap(type="pdfwrite",...)
which requires ghostscript
being present in your system (this is just a shortcut for calling
postscript(...)
function and massaging the resulting ps file with
ps2pdf ghostscript utility).
item["Quit" menu item] - close this figure. If it is also the
current.Figure
, then current.Figure
variable is NULL
-ed.
end{description}
item["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.
item["Hooks" menu (optional)] - this menu is created in
figure.startup
script, so it is visible only if
figure.startup
is redefined with hooks.user.menu
in
.Rprofile file (my .Rprofile is in Example section below). Selecting
menu item in this menu sets one of the RGrace's hooks
to
the sample scripts available in RGrace (i.e. this menu is an
alternative to setting on.select.xxx<-...
functions in command line
interface, see hooks
for detail). One of the reason not
merging this menu code into RGrace is that user would like to have his
own utility scripts which he would like to make available as subitem
of "Hooks" menu. It is can be done easily by editing
RGrace/inst/figure.startup.exmpl.R
script.
end{description}
Beside the menubar there is a "Select Something" option menu which
selects which one of the hooks
(on.select.annotation
,on.select.element
,
on.select.region
, on.select.points
) will be played when we press mouse buttons
or keyboard keys inside plotting area (see hooks
for more
details).
M.Kondrin
#do not run #define code for future figure.startup function user.menu <- function(...){ #build menu items to access mysql database db.user.menu(...) #build menu with available hooks hooks.user.menu(...) } .First<-function(...){ library(grDevices) #redefine palette with all system's named colors palette(colors()) #source scripts from RGrace scripts directory source(system.file("scripts","db.wizards.R",package="RGrace")) source(system.file("scripts","figure.startup.exmpl.R",package="RGrace")) #redefine figure.startup hook figure.startup<<-user.menu library(RGrace) #install postscript fonts with cyrillic glyphs ps.options(family=c( system.file("CyrFonts","textb19.afm",package="RGrace"), system.file("CyrFonts","textb20.afm",package="RGrace"), system.file("CyrFonts","textb18.afm",package="RGrace"), system.file("CyrFonts","textb18.afm",package="RGrace"),"sy______.afm"), encoding=system.file("CyrFonts","koi8r.enc",package="RGrace"),override.check=T,reset=F) }