[rkward-cvs] SF.net SVN: rkward:[3301] branches/jss_dec_10/FINAL_JSS_TEX
sjar at users.sourceforge.net
sjar at users.sourceforge.net
Thu Dec 23 02:05:01 UTC 2010
Revision: 3301
http://rkward.svn.sourceforge.net/rkward/?rev=3301&view=rev
Author: sjar
Date: 2010-12-23 02:05:00 +0000 (Thu, 23 Dec 2010)
Log Message:
-----------
* numerous additions to many sections
* some corrections
* @ Thomas.
+ Please check my comment to you comment in the conclusion section.
+ In my opinion the plugin example needs some more explaination (not much). I added a figure for the plugin map und referenced for the t-test code to other figures. Maybe this is a starting point. Moreover I added the code which would be readable by the user at the end.
Modified Paths:
--------------
branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex
branches/jss_dec_10/FINAL_JSS_TEX/background.tex
branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.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-23 01:58:33 UTC (rev 3300)
+++ branches/jss_dec_10/FINAL_JSS_TEX/GUI_elements.tex 2010-12-23 02:05:00 UTC (rev 3301)
@@ -36,7 +36,7 @@
\begin{figure}[htp]
\centering
- \includegraphics[width=15.5cm]{../figures/main_window.png}
+ \includegraphics[width=15.446cm,height=10.949cm]{../figures/main_window.png}
\caption{Default RKWard main window after start up.
A) Menu bar, B) navigator element, C) editor, output,
and data management. D) embedded \proglang{R} console.
@@ -181,13 +181,10 @@
\begin{figure}[htp]
\centering
- \includegraphics[width=8cm]{../figures/special_paste.png}
+ \includegraphics[width=8.042cm,heigth=8.143cm]{../figures/special_paste.png}
\caption{Special paste dialog. This tool allows to paste data (e.g. tabular, text) from the clipboard, directly to an
\proglang{R} script and therefore accelerates the work process with data from different sources
like spread-sheet applications.
-%% TF: Yes, to my knowledge, too, it is unique. But I think the feature description can really stand for itself.
-%% Let's not compare against other GUIs *too* often.
-% To our knowledge approach is unique among the currently existing \proglang{R} GUIs.
}
\label{fig:special_paste}
\end{figure}
@@ -322,22 +319,22 @@
the \proglang{R} Console (Section~\ref{sec:using_R_console}). To import CSV
data, select ``File->Import format->Import Text->CSV''
data from the menu. This will open a dialog as shown in
-figure XXX. The central area of this dialog is concerned with setting
+Figure~\ref{fig:import_data}A. The central area of this dialog is concerned with setting
the options to control the import. Here, the input field for
File name is highlighted to indicate that
it is required to specify a file, before the dialog can proceed.
Further options are available from tabbed pages of the central area.
-The right-hand area (figure XXX-B) is common to all data handling
+The right-hand area is common to all data handling
dialogs. Here, the Submit button is used
to start the import action. It will become enabled once all required
settings have been made, i.e. in this case, a file name has been
selected. The Close button will close the
dialog without taking any action.
-The bottom area (figure XXX-C) shows the \proglang{R}
-code which corresponds to the current settings, and which will be run
-upon pressing the Submit button. The
+The bottom optionally presents the \proglang{R}
+code (not shown) which corresponds to the current settings, and which will be run
+upon pressing the Submit button (see Section~\ref{sec:importing_data} for generated \proglang{R} code). The
display is updated dynamically, as the user changes settings, allowing
to see the effect of each change. The code display can be hidden using
the Code button in the right-hand section
@@ -375,8 +372,12 @@
\begin{figure}[htp]
\centering
\includegraphics{../figures/plot_history_cropped.png}
- \caption{Onscreen graphics device window in RKWard. The plot history is available as a drop-down list, allowing to
- jump directly to a previous plot.}
+ \caption{Onscreen graphics device window in RKWard. The plot history is
+ 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...''.
+}
\label{fig:plot_history}
\end{figure}
@@ -400,7 +401,11 @@
be used in RKWard, 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 output is presented as journal view. Therefore all results are presented
+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
+to a desired font size for easy reading from the menu. Images contained in the output will not get resized.
+Since the output is based on \proglan{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.
It is also possible to write to the output from \proglang{R}
scripts by using a number of dedicated \proglang{R}
@@ -411,7 +416,7 @@
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} objectsf in
+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
@@ -424,7 +429,7 @@
\begin{figure}[htp]
\centering
- \includegraphics{../figures/results_output_cropped.png}
+ \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
identical or similar parameters.}
@@ -519,7 +524,9 @@
\proglang{HTML} form, help pages on
\proglang{R} functions and packages, help pages on
RKWard in general, and help pages on specific GUI dialogs within
-\proglang{R}. All types of help can be browsed in the
+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
RKWard GUI dialogs will typically link to documentation for both
related RKWard dialogs, and the underlying
Modified: branches/jss_dec_10/FINAL_JSS_TEX/background.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/background.tex 2010-12-23 01:58:33 UTC (rev 3300)
+++ branches/jss_dec_10/FINAL_JSS_TEX/background.tex 2010-12-23 02:05:00 UTC (rev 3301)
@@ -26,7 +26,7 @@
immediately, without having to learn anything about the \proglang{R} programming language,
first. At the same time RKWard tries to support users who want to learn and
exploit the full flexibility of the \proglang{R} language for automating or customizing
-analyses. At the other end of the learning curve, RKWard provides advanced IDE (integrated development environment)
+an analysis. At the other end of the learning curve, RKWard provides advanced IDE (integrated development environment)
features to \proglang{R} experts to assist in the development of \proglang{R} scripts. Yet, the idea
is that \proglang{R} experts, too will benefit from the availability task-oriented GUI
dialogs from time to time, such as when exploring an unfamiliar type of analysis
Modified: branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex 2010-12-23 01:58:33 UTC (rev 3300)
+++ branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex 2010-12-23 02:05:00 UTC (rev 3301)
@@ -6,9 +6,15 @@
a simple dialog for a t-test. For brevity, the help-file is omitted.
\subsection{Defining the menu hierarchy}
+\label{sec:defining_menu_hierarchy}
A so called ``.pluginmap'' file declares each plugin, and - if appropriate - defines where it should
be placed in the menu hierarchy. Usually each .pluginmap-file declares many plugins. In this example
-we only show one.
+we only show one. Since the files are editable with a text editor it is possible for the user to adjust
+the menus as desired.
+In this example we describe the definition entry for a two variable t-test (see Figure~\ref{fig:ttest-gui-example}).
+The pluginmap (<!DOCTYPE rkpluginmap>) gives a unique identifier ("id"), the location of the GUI description ("file") and the label. The menu
+is defined in a hierarchical structure (see code example below). Moreover the position within the menu can be defined.
+This might be required if menus should not be ordered in alphabetical order.
\begin{Code}
<!DOCTYPE rkpluginmap>
@@ -33,12 +39,27 @@
</document>
\end{Code}
+\begin{figure}[htp]
+ \centering
+ \includegraphics{../figures/ttest-gui-example.png}
+ \caption{Generated menu GUI as defined by the pluginmap.}
+ \label{fig:ttest-gui-example}
+\end{figure}
+
+
\subsection {Defining the dialog UI}
+\label{sec:defining_dialog_ui}
The main \proglang{XML} file of each plugin defines the layout and behavior of the GUI, and references the
\proglang{ECMAScript} file that is used for generating \proglang{R} code from UI settings, and the help file (not included in this article).
GUI behavior can also be scripted in \proglang{ECMAScript}. In this example, the logic is defined in \proglang{XML} (the ``Assume equal variances'' checkbox
is only enabled for paired sample tests).
+
+The \proglang{XML} defines the t-test plugin (<!DOCTYPE rkplugin>) to be organized in two tabs (Figure~\ref{fig:t_test}A) asking for the variables
+to analyze in the first tab and optionally in the second tab for specific settings like the confidence level (default 0.95). Note that this \proglang{XML} file
+also invokes the \proglang{XML} help file. The plugin was defined to require two variables (<varslot .../>). If not provided RKWard does not perform the test.
+
+
\begin{Code}
<!DOCTYPE rkplugin>
<document>
@@ -86,6 +107,7 @@
\end{Code}
\subsection{Generating R code from UI settings}
+\label{sec:generating_r_code_from_ui_settings}
A simple \proglang{ECMAScript} script is used to generate \proglang{R} code from UI settings (using \code{echo()} commands).
Generated code for each plugin is divded into three sections ``Preprocess'', ``Calculate'', and ``Printout'', although each
may be empty.
@@ -144,3 +166,30 @@
echo ('))\n');
}
\end{Code}
+
+The corresponding code readable for the user is \proglang{R} code.\code{rk.header} and \code{rk.results}
+are RKWard functions provided by the package \pkg{rkward}. In case the package is installed the code below
+can be run from any R engine.
+
+\begin{Code}
+local({
+## Prepare
+names <- rk.get.description (my.csv.data[["before"]], my.csv.data[["after"]])
+## Compute
+result <- t.test (my.csv.data[["before"]], my.csv.data[["after"]], alternative="less", paired=TRUE)
+## Print result
+rk.header (result$method,
+ parameters=list ("Comparing", paste (names[1], "against", names[2]),
+ "H1", rk.describe.alternative (result)))
+
+rk.results (list (
+ 'Variable Name'=names,
+ 'estimated mean'=result$estimate,
+ 'degrees of freedom'=result$parameter,
+ t=result$statistic,
+ p=result$p.value,
+ 'confidence interval percent'=(100 * attr(result$conf.int, "conf.level")),
+ 'confidence interval of difference'=result$conf.int ))
+})
+
+\end{Code}
Modified: branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex 2010-12-23 01:58:33 UTC (rev 3300)
+++ branches/jss_dec_10/FINAL_JSS_TEX/example_session.tex 2010-12-23 02:05:00 UTC (rev 3301)
@@ -3,7 +3,7 @@
This section describes an example RKWard session, in order to give an idea
what working with RKWard is like in practice.
The session is organized along the routine tasks of importing,
-analyzing, and visulazing data. In this example, we assume that an experimental
+analyzing, and visualizing data. In this example, we assume that an experimental
treatment was given to 20 test subjects and the values of the dependent
variable before and after the treatment should be compared.
@@ -48,7 +48,8 @@
\begin{figure}[htp]
\centering
\includegraphics[width=15.5cm]{../figures/t-test.png}
- \caption{A) Student's t-test dialog for a two variables. B) Test results in \proglang{HTML} format.}
+ \caption{A) Student's t-test dialog for a two variables. B) Test results in tabular \proglang{HTML} format.
+Besides the result information like the date of analysis and relevant test parameters are reported.}
\label{fig:t_test}
\end{figure}
@@ -64,7 +65,9 @@
\begin{figure}[htp]
\centering
\includegraphics[width=15.5cm]{../figures/boxplot1.png}
- \caption{Boxplot dialog.}
+ \caption{Boxplot dialog. The first tab (``Variables``) is used to select a set of data for analysis. It is possible to
+ combine any data present in the .GloabelEnv. The second tab (''Options'') allows further adjustments (e.g the addition
+ of mean and standard deviation) of the plot (not shown).}
\label{fig:boxplot1}
\end{figure}
@@ -76,6 +79,9 @@
\begin{figure}[htp]
\centering
\includegraphics[width=15.5cm]{../figures/boxplot2.png}
- \caption{Plotted data and plot export dialog.}
+ \caption{Plotted data and plot export dialog. The export dialog provides numerous
+ options like resolution and size for different vector formats (e.g. SVG, PDF) and
+ pixel formats (e.g. PNG, JPG). Note: The RKWard boxplot plugin was extended to present optionally
+ the mean (square) and standard deviation (cross) for all data.}
\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-23 01:58:33 UTC (rev 3300)
+++ branches/jss_dec_10/FINAL_JSS_TEX/technical.tex 2010-12-23 02:05:00 UTC (rev 3301)
@@ -2,7 +2,7 @@
\label{sec:technical}
In this section we will give a compact overview over key aspects of RKWards
technical design. We will give slightly more attention to the details of the
-plugin framework used in RKWard, since this is central to the extensibility of
+plugin framework (Section~\ref{sec:technical_plugins}) used in RKWard, since this is central to the extensibility of
RKWard.
\subsection{Asynchronous command execution}
@@ -10,7 +10,7 @@
One central design decision in the implementation of RKWard is that the
interface to the \proglang{R} engine operates asynchronous. The intention is to
remain the application usable to a high degree, even during the computation of
-time-consuming analyses. 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
@@ -24,7 +24,7 @@
\proglang{R} engine during interactive use. This is one of several reasons for
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 quering information about the
+A further implication is that RKWard avoids querying information about the
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}),
@@ -200,12 +200,17 @@
kate part supports extensions via plugins and user scripts. At this point we
will focus only on plugins generating R code.
}. Thus, the plugin framework is basically a tool set 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
+GUIs for the automatic generation of \proglang{R} code. Plugins provide users in many cases
+with reasonable default values, force to use a certain input (factor, integer) or usage
+(e.g. Section~\ref{sec:defining_dialog_ui}) in a given context
+in order to protect them from errors. An example which shows the difference between code interanally used by
+RKWard and presented to the user is shown in Section~\ref{sec:generating_r_code_from_ui_settings}.
+
+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
-statistical analysis.
+statistical analysis.
\subsubsection{Defining a plugin}
\label{sec:technical_plugins_defining}
@@ -223,14 +228,16 @@
\begin{itemize}
\item
- An \proglang{XML} file, called a ``plugin map,'' is used to declare one or more plugins, each
+ An \proglang{XML} file (Section~\ref{sec:defining_menu_hierarchy}),
+ called a ``\textbf{plugin map}'', is used to declare one or more plugins, each
with a unique identifier. For most plugins, the plugin map also defines the
placement in the menu hierarchy. Plugin maps are meant to represent groups of
plugins. Users can disable/enable such groups of plugins in order to reduce the
complexity of the menu hierarchy.
\item
- A second \proglang{XML} file describes the plugin itself. Most importantly this includes
+ 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
@@ -242,7 +249,8 @@
behavior using \proglang{ECMAScript} is also supported.
\item
- A separate \proglang{ECMAScript}-file is used to translate GUI settings into \proglang{R}
+ 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.
@@ -254,7 +262,7 @@
without the danger of overwriting user data.
\item
- A third \proglang{XML} file defines a help page. This help page usually links to the \proglang{R} help
+ A third \proglang{XML} file defines a \textbf{help page}. This help page usually links to the \proglang{R} help
pages of the central functions/concepts used by the plugin. Compared to \proglang{R} help
pages, the plugin help pages try to give more hands-on advice on using the
plugin. Plugins can be invoked from their help page by clicking on a link near
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