[rkward-cvs] SF.net SVN: rkward:[3316] branches/jss_dec_10/FINAL_JSS_TEX
m-eik at users.sourceforge.net
m-eik at users.sourceforge.net
Sat Dec 25 14:20:40 UTC 2010
Revision: 3316
http://rkward.svn.sourceforge.net/rkward/?rev=3316&view=rev
Author: m-eik
Date: 2010-12-25 14:20:40 +0000 (Sat, 25 Dec 2010)
Log Message:
-----------
some more minor editing.
Modified Paths:
--------------
branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex
branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex
branches/jss_dec_10/FINAL_JSS_TEX/technical.tex
Modified: branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex 2010-12-24 19:05:50 UTC (rev 3315)
+++ branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex 2010-12-25 14:20:40 UTC (rev 3316)
@@ -73,21 +73,21 @@
Windows can be shown (or activated) using a mouse device with point \&
click, as well as using a series of keyboard shortcuts (defined by
default) for switching between the different tool and document windows.
-Key bindings can be configured from the GUI via ``Settings->Configure Shortcuts''.
+Key bindings can be configured from the GUI via ``Settings$\rightarrow$Configure Shortcuts''.
However, for technical reasons only the shortcuts of currently active components
will be listed. Thus, for example, to
configure data editor shortcuts, one has to open a data editor first and
-then to select ``Settings->Configure Shortcuts''. Since RKWard relies on the
+then to select ``Settings$\rightarrow$Configure Shortcuts''. Since RKWard relies on the
\proglang{KDE} SC editor component,
shortcuts for the script editor (Section~\ref{sec:code_editor}) are managed separately using
-``Settings->Configure Editor->Shortcuts''. On most systems, it is also
+``Settings$\rightarrow$Configure Editor$\rightarrow$Shortcuts''. On most systems, it is also
possible to configure shortcuts by right-clicking on the respective
menu item.
The choice of available actions on the tool bar can be
-configured via ``Settings->Configure Toolbars``. Further, it is possible to add and remove sets
+configured via ``Settings$\rightarrow$Configure Toolbars``. Further, it is possible to add and remove sets
of data manipulation and analysis features from the GUI, using
-``Settings->Configure RKWard/Plugins``.
+``Settings$\rightarrow$Configure RKWard/Plugins``.
\subsection{Workspace browser and object viewer}
\label{sec:workspace_browser_object_viewer}
@@ -99,8 +99,8 @@
\proglang{R} search path (typically
\proglang{R} package environments). Objects are shown
in a hierarchical tree structure. For instance, an object of class
-\proglang{list} can be expanded to show all contained objects
-by clicking on the \proglang{+}-symbol left to the object name.
+\code{list} can be expanded to show all contained objects
+by clicking on the \code{+}-symbol left to the object name.
The basic type of each object is indicated by different icons. Further
information on each object can be obtained by hovering the mouse
pointer over the respective icon. A tooltip window will appear,
@@ -235,7 +235,7 @@
Similarly, an editable column showing the row names of the \code{data.frame}
can be shown or hidden separately from the data.
-For columns of type \proglang{factor}, factor levels can be edited by double-clicking on the
+For columns of type \code{factor}, factor levels can be edited by double-clicking on the
``Levels'' row of the meta information. Levels can also be assigned to other types of
variables, but only for consecutive integer values. These levels will
be displayed instead of the underlying value, if applicable. Each
@@ -247,7 +247,7 @@
automatically convert data types of columns. For instance, if a
non-numeric string is entered into a cell of a numeric column, the data
type of the column remains numeric, and the entered value is
-highlighted in red. Internally, the invalid cell is set to \proglang{NA}.
+highlighted in red. Internally, the invalid cell is set to \code{NA}.
The entered value is stored separately, in an attribute of the column.
The rationale for this approach is that it offers protection against
accidental -- and probably undetected -- conversion of data types. The
@@ -273,7 +273,7 @@
\includegraphics{../figures/data_editors.png}
\caption{RKWard with several \code{data.frame}s in use at the same time. A) One \code{data.frame} is opened for editing in the
main window. B) A second \code{data.frame} is opened as detached window. C) \proglang{R}'s standard data editing features
-(e.\,g. \code{fix()},\code{edit()}) are also usable within an RKWard session.
+(e.\,g. \code{fix()}, \code{edit()}) are also usable within an RKWard session.
In this example \code{fix(DNase)} was invoked from the console (arrow).}
\label{fig:data_editors}
\end{figure}
@@ -310,7 +310,7 @@
also be imported using copy \& paste (see Sections~\ref{sec:code_editor} and \ref{sec:spreadsheet}), or by
manually entering appropriate \proglang{R} commands in
the \proglang{R} Console (Section~\ref{sec:using_R_console}). To import CSV
-data, select ``File->Import format->Import Text->CSV''
+data, select ``File$\rightarrow$Import format$\rightarrow$Import Text$\rightarrow$CSV''
data from the menu. This will open the dialog shown in
Figure~\ref{fig:import_data}A. The central area of this dialog is concerned with setting
the options to control the import. The input field for
@@ -368,7 +368,7 @@
available as a drop-down list, allowing to jump directly to a previous
plot. In this example, five different plots were performed on the same data
set of a random sample (\code{rnorm()}). The plot can be
- selectively exported as described in Figure~\ref{fig:boxplot2} via ``Device->Export...''.
+ selectively exported as described in Figure~\ref{fig:boxplot2} via ``Device$\rightarrow$Export...''.
}
\label{fig:plot_history}
\end{figure}
@@ -385,56 +385,52 @@
the convergence while teaching. Such ``preview plots'' are not added to
the history.
-%% TODO: Santa Claus: merry X-mas ;-)
-%% this comment is just to remind we where i was :: MM
-
\subsection{Results output}
\label{sec:results_output}
While all basic mechanisms of
capturing and documenting \proglang{R} output can also
-be used in RKWard, RKWard provides a dedicated output file and output
+be used, RKWard provides a dedicated output file and output
window for the documentation of results. All GUI-driven data handling
functions (see Section~\ref{sec:analyzing_data}) write their output to this file.
-The same applies to error messages in case a plugin fails to perform the task.
-The output is presented as journal view\footnote{Note: The view of the output can be adjusted in
+The same applies to error messages, in case a plugin fails to perform its task.
+The output is presented in journal view\footnote{Note: The view of the output can be adjusted in
to a desired font size for easy reading from the menu.
Since the output is based on \proglang{HTML} it is also possible to view the source code
-(see below).}. Therefore all results are presented
-sequentially with the most current performed task on the bottom.
+(see below).}. All results are presented
+sequentially with the last performed task at the bottom.
It is also possible to write to the output from \proglang{R}
scripts by using a number of dedicated \proglang{R}
functions. For the GUI-driven data handling functions, the output is
standardized to include the name of the feature, the date and time of
-the execution of the feature, and other basic parameters (if
-applicable). Further, a clickable Run
-Again-link is rendered below the output of each data
-handling feature, which allows to invoke the same feature again, with
+its execution, and other basic parameters, if
+applicable. Further, a clickable ``Run
+Again'' link is rendered below the output of each data
+handling feature, which allows to invoke the same feature again with
identical parameters\footnote{In case not all parameters could be
applied, since some of the \proglang{R} objects in
question are no longer available, the user will be notified.} (see
-figure \ref{fig:results_output}). Thus, the Run
-Again feature combines the documentation of the result
-with a mostly automated way to conduct the same analysis again, on new
-data, providing benefits similar to the automated report generation as
-available for example from RreportGenerator
-\citep{RaffelsbergerW2008} which generates automatic
+figure \ref{fig:results_output}). Thus, the ``Run
+Again'' feature combines the documentation of the result
+with an automated way to conduct the same analysis again on new
+data, providing benefits similar to, i.\,e., the automated report generation
+available from \pkg{RreportGenerator}\footnote{The application generates automatic
reports from routine statistical analysis in bioinformatical
-applications.
+applications} \citep{RaffelsbergerW2008}.
\begin{figure}[htp]
\centering
\includegraphics[width=15.5cm]{../figures/results_output_cropped.png}
\caption{Sample contents of the output window. Standard elements of plugin output include
- a standardized header, and a ``Run again''-link, which allows to repeat the analysis with
+ a standardized header, and a ``Run again'' link, which allows to repeat the analysis with
identical or similar parameters.}
\label{fig:results_output}
\end{figure}
-The formatting of the output is kept to a minimum, and in particular,
+The formatting of the output is kept to a minimum. In particular,
RKWard is very reluctant to round numerical results for the sake of a
-pretty output. Rather the focus is on making the results easily
-accessible to further processing, typically in a dedicated word
+pretty output. Rather, the focus is on making the results easily
+accessible for further processing, typically in a dedicated word
processor. Output is based on
\proglang{HTML} (hypertext markup language), and the raw
\proglang{HTML} file and any images can be directly
@@ -442,19 +438,19 @@
(\~{}/.rkward, by default). It is also
possible to select and copy sections of the output directly from the
output window, and to paste them into office applications as
-\proglang{HTML} code. In future releases RKWard will
-try to integrate with existing office suites, and it is possible that
-this will also mean changing to a different file format such as ODF (open
+\proglang{HTML} code. In future releases, RKWard will
+try to integrate with existing office suites. This
+will possibly also mean changing to a different file format such as ODF (open
document format, and technologies such as \pkg{sweave} and \pkg{odfWeave}
\citep{Leisch2002, Kuhn2006}.
Images contained in the output are stored as
PNG\footnote{\url{http://www.libpng.org/pub/png/}} by
-default, but JPG\footnote{\url{http://www.jpeg.org/index.html}} and
+default, but JPEG\footnote{\url{http://www.jpeg.org/index.html}} and
SVG\footnote{\url{http://www.w3.org/Graphics/SVG/}}
-can also be used as the output format. Similarly, the size of the
+can also be used. Similarly, the size of
images can be configured by the user. It is expected that SVG will
-become the default output format, eventually, but currently some SVG
+become the default output format eventually, but currently some SVG
files produced by \proglang{R} are not properly
rendered by older supported versions of the
\proglang{KDE} libraries.
@@ -466,29 +462,31 @@
(2001) to \proglang{R} v. 2.7 (2008) \citep{Fox2008, Ligges2003, Visne2009}. RKWard
utilizes functionality from a growing number of these packages, but avoids
making the installation of all supported packages a pre-requirement to using
-RKWard at all. Once a non-installed package is required to conduct a certain
-action, the package management dialog is invoked automatically, which allows to
+RKWard at all. Only once a not yet installed package is required to conduct a certain
+action, a package management dialog is invoked automatically, which allows to
download and install the package from a repository such as CRAN. The package
management dialog can also be invoked manually from the menu
-(``Settings->Configure Packages``) for installing new or updating existing \proglang{R}
+(``Settings$\rightarrow$Configure Packages'') for installing new or updating existing \proglang{R}
packages. The underlying package management technology is that of \proglang{R}
\citep{Ligges2003, Ripley2005}.
RKWard supports installing packages to any user writable location. If no current
-library location is user writable, RKWard offers to create a new library
-location. On UNIX-systems, interactively acquiring administrator privileges for
-installation to the system-wide library is also supported. The dialog can be
-used for updating already installed packages. The user can choose whether to
+library location is user writable, RKWard offers to create a new one.
+On UNIX systems, interactively acquiring root privileges for
+installation to the system-wide library is also supported. If used to
+update already installed packages, the user can choose whether to
update all packages at once, or only selected packages. The installation process
-itself can be monitored from the interface for error tracking. At the time of this writing, RKWard has no
+itself can be monitored at the interface for error tracking. At the time of this writing, RKWard has no
built-in tools for the interactive exploration of \proglang{R} packages. However, it is
possible to invoke external helpers \citep{Zhang2004}.
\subsection{Further tool windows}
\label{sec:further_tool_windows}
+%%TODO: MM: shouldn't the names of the interesting tools
+% in this section be highlighted, maybe at least by ``name'' ?
The file browser tool window can be
-used to open supported file types (e.g. \proglang{R}
+used to open supported file types (e.\,g. \proglang{R}
scripts, \proglang{HTML} files) inside the main RKWard
window. For unsupported file types (such as PDF), the
systems default external applications can be used.
@@ -496,17 +494,16 @@
The command log window contains a log of the commands that have been
evaluated by the \proglang{R} engine, and any output
produced by these commands. By default, the log shows only commands
-which have been entered by the user, or directly correspond to user
+which have been entered by the user or directly correspond to user
actions, but it can be configured to include commands which are run for
application internal purposes such as keeping the workspace browser up
to date.
Commands can be submitted while the \proglang{R} engine
has not yet started, or while another lengthy calculation is still
-performing. In this case commands are placed into a queue, first, and
+performing. In these cases commands are placed into a queue first, and
executed as soon as the \proglang{R} engine becomes
-available. The pending jobs windows (not
-shown) lists current \proglang{R} commands waiting for
+available. A pending jobs window lists current \proglang{R} commands waiting for
evaluation by the \proglang{R} engine. While this
window is mostly of interest to application developers for diagnostic
purposes, it can also be used to interrupt selected commands.
@@ -522,32 +519,32 @@
RKWard\footnote{For technical backgound of RKWard GUI help pages
please refer to Section~\ref{sec:technical_plugins_defining}}.
All types of help can be browsed in the
-same document window, and can be cross-linked. For example help pages for
+same document window, and can be cross-linked. For example, help pages for
RKWard GUI dialogs will typically link to documentation for both
-related RKWard dialogs, and the underlying
+related RKWard dialogs and the underlying
\proglang{R} functions.
-The help system can be invoked from several action in the
-Help menu. Help on RKWard dialogs can be
+The help system can be invoked through several actions in the
+Help menu. Help pages on RKWard dialogs can be
accessed from the dialog itself using the
-Help button. Help pages on RKWard dialogs
+Help button. They
also allow starting the respective dialog by click on a link near the
top of the page. Help on \proglang{R} specific
-\proglang{R} functions can be invoked from the context
+functions can be invoked from the context
menu of the workspace browser, by pressing F2 (Function
reference) while the cursor is on a function name in the
code editor or the \proglang{R} console, or by using
the \proglang{R} \code{help()}
-command. In addition a tool view is provided as an interface to the
+command. In addition, a tool view is provided as an interface to the
\code{help.search()} command in
\proglang{R}. This allows to search all installed, all
loaded, or specific \proglang{R} packages for a
specified topic.
The help browser window is based on the \proglang{KDE}
-\proglang{HTML} viewer component, and supports
-features like increasing / decreasing the font size, or searching text
+\proglang{HTML} viewer component and supports
+features like increasing/decreasing the font size or searching text
within a help page. \proglang{R} code inside a help
page can be sent to the \proglang{R} engine for
-evaluation by selecting it, and pressing F8 (Run/Run
+evaluation by selecting it and pressing F8 (Run/Run
Selection).
Modified: branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex 2010-12-24 19:05:50 UTC (rev 3315)
+++ branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex 2010-12-25 14:20:40 UTC (rev 3316)
@@ -5,7 +5,7 @@
of what working with RKWard is like in practice.
The session is organized along the routine tasks of importing,
analyzing, and visualizing data. In this example, it is assumed that an experimental
-treatment was given to 20 test subjects and the objective is to compare the responses
+treatment was given to 20 test subjects, and the objective is to compare the responses
before and after the treatment.
\subsection{Importing data}
@@ -15,7 +15,7 @@
comfortably read it into a new \proglang{R} object.
The import dialog (``File$\rightarrow$Import$\rightarrow$Import
format$\rightarrow$Import Text / CSV data'') assists in reading the
-data by a common point and click interface (Figure~\ref{fig:import_data}A). In this
+data by a common point \& click interface (Figure~\ref{fig:import_data}A). In this
example, ``comma'' and ``period'' were chosen via ``Quick mode'' as the field
separator and decimal point characters respectively.
@@ -43,7 +43,7 @@
To test the hypothesis that the given treatment significantly increased the response, a Student's
t-test for a paired sample is conducted using the
``Analysis$\rightarrow$Means$\rightarrow$t-Tests$\rightarrow$Two variable t-test'' plugin.
-In the object browser on the left side the two variables from the expanded
+In the object browser on the left side, the two variables from the expanded
\proglang{R} object containing the table of imported data
are selected (Figure~\ref{fig:t_test}A).
Pressing the ``Submit'' button opens the output document tab
@@ -65,15 +65,14 @@
and the two variables, corresponding to the t-test above, are selected.
The dialog allows to define custom variable labels (Figure~\ref{fig:boxplot1}).
Checking the ``Preview'' box opens a graphics window showing the boxplot as
-it is configured and updates the window, in real time, on any changes to plot parameters. From
+it is configured, and updates the window in real time on any changes to plot parameters. From
that window, the plot can then be exported to several image formats (Figure~\ref{fig:boxplot2}).
\begin{figure}[htp]
\centering
\includegraphics[width=15.5cm]{../figures/boxplot1.png}
\caption{Boxplot dialog. The first tab (``Variables'') is used to select the variables for analysis. It is possible to
- combine any data present in the .GlobalEnv. The second tab (``Options'') allows further adjustments (e.g the addition
- of mean and standard deviation) to the plot (not shown).}
+ combine any data present in \code{.GlobalEnv}. The second tab ``Options'' allows further adjustments (e.\,g. the addition of mean and standard deviation) to the plot (not shown).}
\label{fig:boxplot1}
\end{figure}
@@ -82,8 +81,8 @@
\centering
\includegraphics[width=15.5cm]{../figures/boxplot2.png}
\caption{Plotted data and plot export dialog. The export dialog (``Device$\rightarrow$Export'') provides numerous
- options like resolution and size for different vector formats (e.g. SVG, PDF) and
- pixel formats (e.g. PNG, JPG). (Note: For the shown figure, the optional
+ options like resolution and size for different vector formats (e.\,g. SVG, PDF) and
+ pixel formats (e.\,g. PNG, JPEG). (Note: For the shown figure, the optional
mean ($\blacksquare$) and standard deviation ($+$) parameters were selected in the boxplot plugin.)}
\label{fig:boxplot2}
\end{figure}
Modified: branches/jss_dec_10/FINAL_JSS_TEX/technical.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/technical.tex 2010-12-24 19:05:50 UTC (rev 3315)
+++ branches/jss_dec_10/FINAL_JSS_TEX/technical.tex 2010-12-25 14:20:40 UTC (rev 3316)
@@ -8,16 +8,16 @@
\subsection{Asynchronous command execution}
\label{sec:technical_asynchronous}
One central design decision in the implementation of RKWard is that the
-interface to the \proglang{R} engine operates asynchronous. The intention is to
+interface to the \proglang{R} engine operates asynchronously. The intention is to
remain the application usable to a high degree, even during the computation of
-time-consuming analysis. For instance while waiting for the estimation of a
+time-consuming analysis. For instance, while waiting for the estimation of a
complex model to complete, the user should be able to continue to use the GUI to
prepare the next analysis. Asynchronous command execution is also a prerequisite
-for a implementation of the plot-preview feature (see Section~\ref{sec:plot_previews}). Commands
+for an implementation of the plot-preview feature (see Section~\ref{sec:plot_previews}). Commands
generated from plugins or user actions are placed in queue and are evaluated in
a separate thread in the order they were submitted\footnote{
- It is possible, and in some cases necessary to enforce a different order of command execution in
- internal code. For instance RKWard makes sure that no user command can
+ It is possible, and in some cases necessary, to enforce a different order of command execution in
+ internal code. For instance, RKWard makes sure that no user command can
potentially interfere while RKWard is loading the data of a \code{data.frame} for
editing.
}. The asynchronous design implies that RKWard avoids to rely on the
@@ -25,25 +25,25 @@
the use of \proglang{ECMAScript} in plugins, instead of scripting using
\proglang{R} (see Sections~\ref{sec:technical_toolkit} and \ref{sec:technical_plugins}).
A further implication is that RKWard avoids querying information about the
-existence and properties of objects in \proglang{R}, interactively. Rather
+existence and properties of objects in \proglang{R} interactively. Rather,
RKWard keeps a representation of \proglang{R} objects and their basic properties
-(e.g. class and dimensions), which is used for the workspace browser (Section~\ref{sec:workspace_browser_object_viewer}),
+(e.\,g. class and dimensions), which is used for the workspace browser (Section~\ref{sec:workspace_browser_object_viewer}),
object name completion, function argument hinting and
other occasions. The object representation includes objects in all environments
-on the search path, and any objects contained within these environments in a
+in the search path, and any objects contained within these environments in a
hierarchical tree\footnote{
Currently, environments of functions or formulas are not taken into account.
}. The representation of \proglang{R} objects is gathered
-pro-actively. This has a notable impact on performance when loading packages
-(specifically, objects which would usually be ``lazy loaded'' only when needed \citep[see][]{Ripley2004} are
-accessed in order to fetch information on their properties; this means the data
+pro-actively. This has a notable impact on performance when loading packages.
+Specifically, objects which would usually be ``lazy loaded'' only when needed \citep[see][]{Ripley2004} are
+accessed in order to fetch information on their properties. This means the data
has to be loaded from disk; however, the memory is freed directly after fetching
-information on the object).
+information on the object.
A further side-effect of the asynchronous threaded design is that there is
inherently a rather clear separation between GUI code and code making direct use
of the \proglang{R} API (see also Figure~\ref{fig:design_sketch}). In the current development version, the evaluation
-of \proglang{R} commands has even been moved into a separate process. In the somewhat longer term it could even
+of \proglang{R} commands has even been moved into a separate process. Therefore in future releases it could
be possible to run GUI and \proglang{R} engine on different computers.
\begin{figure}[htp]
@@ -60,8 +60,8 @@
\subsection{Object modification detection}
\label{sec:technical_omd}
RKWard allows the user to run arbitrary commands in \proglang{R} at any time, even while
-editing a \code{data.frame} or while selecting objects for analysis in a GUI dialog. Any user
-command could potentially add, modify, or remove objects in \proglang{R}. RKWard tries to
+editing a \code{data.frame} or selecting objects for analysis in a GUI dialog. Any user
+command can potentially add, modify, or remove objects in \proglang{R}. RKWard tries to
detect such changes in order to always display accurate information in the
workspace browser, object selection lists, and object views. Beyond that,
detecting any changes is particularly important with respect to objects which
@@ -70,9 +70,9 @@
the data between \proglang{R} and the GUI in both directions.
For simplicity and performance, object modification detection is only
-implemented for objects inside the ``global environment'' (including in environments
+implemented for objects inside the ``global environment'' (including environments
inside the global environment), since this is where changes are typically done.
-Currently object modification detection is based on active bindings.
+Currently, object modification detection is based on active bindings.
Essentially, any object which is created in the global environment is first
moved to a hidden storage environment, and then replaced with an active binding.
The active binding acts as a transparent proxy to the object in the storage
@@ -80,9 +80,9 @@
This is similar to the approach taken in the \pkg{trackObjs} package \citep{Plate2009}.
}.
-The use of active bindings has significant performance implications, when
+The use of active bindings has significant performance implications when
objects are accessed very frequently. This is particularly notable where an
-object inside the global environment (i.e. an object wrapped into an active
+object inside the global environment (i.\,e. an object wrapped into an active
binding) is used as the index variable in a loop, as illustrated by the
following example:
@@ -103,8 +103,8 @@
f ()
\end{Code}
-It may be possible to overcome this performance problem in future versions of
-RKWard. One approach that is currently under consideration is to simply perform
+Future versions of RKWard will try to avoid this performance problem.
+One approach that is currently under consideration is to simply perform
a pointer comparison of the SEXP records of objects in global environment with
their copies in the hidden storage environment. Due to the implicit sharing of
SEXP records \citep{RDCT2010a, RDCT2010b}, this should provide for a reliable
@@ -118,10 +118,10 @@
on \proglang{Qt}, and implemented mostly in \proglang{C++}. Compared to many competing libraries,
this constitutes a rather heavy dependency. Moreover, the \proglang{KDE} libraries are
still known to have portability issues especially on Mac OS, and to some degree
-also on the Windows platform.
+also on the MS Windows platform.
-The major reason for the choice of the \proglang{KDE} and \proglang{Qt} libraries is that they provide
-many high level features which have allowed RKWard development to make quick
+The major reason for chosing the \proglang{KDE} and \proglang{Qt} libraries was their providing
+of many high level features which have allowed RKWard development to make quick
progress despite limited resources. Most importantly, the \proglang{KDE} libraries provide a
full featured text editor \citep{CullmannND} as a component which can be
seamlessly integrated into a hosting application using the KParts technology
@@ -132,7 +132,7 @@
%% NOTE: It's ``XMLGUI'' in one word, even though it's XML and GUI
Another technology from the \proglang{KDE} libraries that is important to the development
-of RKWard is the ``XMLGUI''-technology
+of RKWard is the ``XMLGUI'' technology
\citep{Faure2000}. This is especially helpful in providing an integrated GUI for
the various components of RKWard.
@@ -140,11 +140,11 @@
and \proglang{ECMAScript}\footnote{\url{http://www.ecmascript.org/}} (see Section~\ref{sec:technical_plugins}). \proglang{XML} is not
only well suited to describe the layout of the GUI of plugins, but simple
functional logic can also be represented \citep{Visne2009}. \proglang{ECMAScript} was
-chosen for the generation of \proglang{R} commands within plugins in particular due to its
+chosen for the generation of \proglang{R} commands within plugins, in particular due to its
availability as an embedded scripting engine inside the \proglang{Qt} libraries. While at
-first glance, \proglang{R} itself would appear as a natural choice of scripting language as
+first glance \proglang{R} itself would appear as a natural choice of scripting language as
well, this would make it impossible to use plugins in an asynchronous way.
-Further, the main functional requirement at this place is the manipulation and
+Further, the main functional requirement in this place is the manipulation and
concatenation of text strings. While \proglang{R} provides support for this, concatenating
strings with the \code{+}-operator, as available in \proglang{ECMAScript}, allows for a much
more readable way to perform such text concatenation.
@@ -155,7 +155,7 @@
not technically provide a custom on-screen graphics device. RKWard detects when
new graphics windows are created via calls to \code{X11()} or \code{windows()}. These windows
are then "captured" in a platform dependent way (based on the XEmbed \citep{Ettrich2002} protocol
-for X11, on reparenting for the Windows platform). An RKWard menu bar and a
+for X11, on reparenting for the MS Windows platform). An RKWard menu bar and a
toolbar is then added to these windows to provide added functionality. While
this approach requires some platform dependent code, any corrections or
improvements made to the underlying \proglang{R} native devices will automatically be
@@ -170,16 +170,16 @@
changes to the on-screen canvas and record the existing plot before a new plot
wipes it out. A single ``global'' history for the recorded plots is maintained
which is used by all the on-screen device windows. This is similar to the
-implementation in Rgui.exe (Windows platform) but unlike the one in Rgui.app
-(MacOS X platform). Each such device window points to a position in the history
+implementation in \code{Rgui.exe} (MS Windows), but unlike the one in \code{Rgui.app}
+(MacOS X). Each such device window points to a position in the history
and behaves independently when recording a new plot or deleting an existing
-plot.
+one.
-The lattice system is implemented by inserting a hook in the \code{print.lattice()}
+The \pkg{lattice} system is implemented by inserting a hook in the \code{print.lattice()}
function. This hook retrieves and stores the \code{lattice.status} object from the
\code{lattice:::.LatticeEnv} environment; thereby making \code{update()} calls on trellis
objects transparent to the user. Any recorded trellis object is then replayed
-using \code{plot.lattice()} bypassing the recording mechanism. The standard graphics
+using \code{plot.lattice()}, bypassing the recording mechanism. The standard graphics
system, on the other hand, is implemented differently because the hook in
\code{plot.new()} is ineffective for this purpose. A customized function is overloaded
on \code{plot.new()} which stores and retrieves the existing plot, essentially, using
@@ -188,24 +188,24 @@
The actual plotting calls are tracked using appropriate \code{sys.call()} commands in
the hooks. These call strings are displayed as a drop-down menu on the toolbar
for non-sequential browsing (see Figure~\ref{fig:plot_history}) providing a very intuitive browsing
-interface unlike the implementation for windows or quartz devices.
+interface unlike the implementation for MS Windows or Quartz devices.
\subsection{Plugin infrastructure}
\label{sec:technical_plugins}
One of the earliest features of RKWard was the extensibility by plugins.
Basically, plugins in RKWard provide complete GUI-dialogs, or re-useable
-GUI-components, which accept user settings, and translate those user settings
+GUI-components, which accept user settings and translate those user settings
into \proglang{R} code\footnote{
Plugins are also used in some other contexts within RKWard, for instance the
- kate part supports extensions via plugins and user scripts. At this point we
+ Kate part supports extensions via plugins and user scripts. At this point we
will focus only on plugins generating \proglang{R} code.
-}. Thus, the plugin framework is basically a tool set used to define
+}. Thus, the plugin framework is basically a toolset used to define
GUIs for the automatic generation of \proglang{R} code.
Much of the functionality in RKWard is currently implemented as plugins. For example, import of different file
-formats relying on the foreign package is achieved by this approach. Similarly,
-RKWard provides a modest GUI driven tool set for statistical analysis,
-especially for Item response theory (IRT), distributions and descriptive
+formats relying on the \pkg{foreign} package is achieved by this approach. Similarly,
+RKWard provides a modest GUI driven toolset for statistical analysis,
+especially for Item Response Theory (IRT), distributions and descriptive
statistical analysis.
\subsubsection{Defining a plugin}
@@ -235,22 +235,22 @@
A second \proglang{XML} file describes the \textbf{plugin GUI layout} itself (Section~\ref{sec:defining_dialog_ui}).
Most importantly this includes
the definition of the GUI-layout and GUI-behavior. High level GUI-elements can
- be defined with simple \proglang{XML}-tags. Layout is based on ``rows'' and ''columns'',
- instead of pixel-counts. In most cases this allows for a sensible resizing
+ be defined with simple \proglang{XML} tags. Layout is based on ``rows'' and ''columns'',
+ instead of pixel counts. In most cases this allows for a sensible resizing
behavior. RKWard supports single-page dialogs, and multi-page wizards, however,
- most plugins define only a single-page UI. GUI behavior is can be programmed by
+ most plugins define only a single-page UI. GUI behavior can be programmed by
connecting ``properties'' of the GUI elements to each other. For example the state
of a checkbox could be connected to the ``enabled'' property of a dependent
- control. More complex logic is also supported. Procedural scripting of GUI
- behavior using \proglang{ECMAScript} is also supported.
+ control. More complex logic is also supported, as is procedural scripting of GUI
+ behavior using \proglang{ECMAScript}.
\item
A separate \textbf{\proglang{ECMAScript}-file} (Section~\ref{sec:generating_r_code_from_ui_settings})
is used to translate GUI settings into \proglang{R}
code\footnote{
In earlier versions of RKWard, \proglang{PHP} was used
- as a scripting engine, and \proglang{PHP}-interpreters were run in a separate process.
- Usage of \proglang{PHP} was abandoned in RKWard version 0.5.3.
+ as a scripting engine, and \proglang{PHP} interpreters were run in a separate process.
+ Usage of \proglang{PHP} was abandoned in RKWard version 0.5.3 for performace reasons.
}. This \proglang{ECMAScript} file is evaluated asynchronously in a separate thread. RKWard
currently enforces structuring the code into three separate sections for
preprocessing, calculating, and printing results. The generated code is always
@@ -265,26 +265,29 @@
the top, which can be useful after following a link from a related help page.
\end{itemize}
-Basically the source code of these elements can be changed without a requirement to recompile.
+Changes to the source code of these elements take effect without the requirement to recompile RKWard.
\subsubsection{Embedding and reuse of plugins}
\label{sec:technical_plugins_embedding}
RKWard supports several mechanisms for modularization and re-use of
functionality in plugins. File inclusion is one very simple but effective
-mechanism, which can be used in the \proglang{ECMAScript} files but is also supported in
-the \proglang{XML}-files. In script files this is most useful by defining common functions
-in an included file. For the \proglang{XML}-files, the equivalent is to define ``snippets''
+mechanism, which can be used in the \proglang{ECMAScript} files, but is also supported in
+the \proglang{XML} files. In script files, this is most useful by defining common functions
+in an included file. For the \proglang{XML} files, the equivalent is to define ``snippets''
in the included file, which can then be inserted.
A third mechanism allows to completely embed one plugin into another. For
-instance the \code{plot\_options} plugin is used by many plugins in RKWard to provide
-common plot options such as plot labels, axis options, and grids. Other plugins
-can embed this using the \code{embed}-tag in their \proglang{XML} file (the plugin supports
+instance the \code{plot\_options} plugin is used by many plugins in RKWard, to provide
+common plot options such as labels, axis options, and grids. Other plugins
+can embed it using the \code{embed} tag in their \proglang{XML} file (the plugin supports
hiding irrelevant options). The generated code portions can be fetched from the
\proglang{ECMAScript} file just like any other GUI settings, and inserted into the complete
code. Other examples of embedded plugins are options for histograms, barplots,
and ECDF plots (which in turn embed the generic plot options plugin).
+%% TODO: Santa Claus: merry X-mas ;-)
+%% this comment is just to remind we where i was :: MM
+
\subsubsection{Enforcing a consistent interface}
\label{sec:technical_plugins_consistency}
RKWard tries to make it easy to create a consistent interface in all plugins.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list