SciViews Manual
127
SciViews-R A GUI API and a suite of applications for R Version 0.8-9 (2005-10-10) Philippe Grosjean ([email protected]), Eric Lecoutre ([email protected]) and José Cláudio Faria ([email protected]), with contributions of Marta Rufino ([email protected]) 1
Transcript of SciViews Manual
SciViews-RA GUI API and a suite of applications for R Version 0.8-9 (2005-10-10)
Philippe Grosjean ([email protected]), Eric Lecoutre ([email protected]) and Jos Cludio Faria ([email protected]), with contributions of Marta Rufino ([email protected])
1
2
PART I: INSTALLING AND USING SCIVIEWS-R.......................................................... 6 1. INTRODUCTION ....................................................................................................... 7
EXAMPLE OF A SESSION USING R WITH THE COMMAND LINE INTERFACE ........................... 7 A GRAPHICAL USER INTERFACE FOR R ................................................................................ 17 ACKNOWLEDGEMENTS .......................................................................................................... 19 2. INSTALLATION OF SCIVIEWS-R, R AND R PACKAGES ............................. 20
CONDENSED INSTALLATION INSTRUCTIONS ........................................................................ 21 DETAILED INSTALLATION OF SCIVIEWS-R .......................................................................... 21 INSTALLING R UNDER WINDOWS .......................................................................................... 27 FINALIZING SCIVIEWS-R / R INSTALLATION ....................................................................... 31 FIXING THE RSCIVIEWS SHORTCUT......................................................................................... 31 INSTALLING ADDITIONAL R PACKAGES ................................................................................... 34 MANUALLY INSTALLING ADDITIONAL R PACKAGES ............................................................... 39 STARTING AND STOPPING THE SCIVIEWS-R GUI................................................................ 42 HOW TO START RGUI IN SDI MODE ......................................................................................... 44 SAVING WORKSPACES FROM SESSION TO SESSION WITH SCIVIEWS-R.................................... 47 3. COMPANION APPLICATIONS FOR WINDOWS IN SCIVIEWS-R............... 48
OVERVIEW OF THE APPLICATIONS ....................................................................................... 48 SCIVIEWS R CONSOLE ........................................................................................................... 49 SCIVIEWS R CONSOLE BARS ................................................................................................... 51 COMMAND BAR / SCRIPT EDITOR ............................................................................................ 52 DOCK WINDOWS ...................................................................................................................... 54 ADDING CUSTOM TOOLS .......................................................................................................... 57 SCIVIEWS R REPORT ............................................................................................................. 60 TINN-R, A R CODE EDITOR .................................................................................................... 62 MAIN CHARACTERISTICS OF TINN-R ....................................................................................... 62 TIPS FOR USING TINN-R........................................................................................................... 63 USING SCIVIEWS R CONSOLE WITH R COMMANDER .......................................................... 68 4. PRESENTATION OF SOME FUNCTIONS IN THE SCIVIEWS BUNDLE .... 69 69 71 75 76
EXPORT AND COPY FUNCTIONS ............................................................................................. VIEW FUNCTIONS .................................................................................................................... CLIPPASTE FUNCTION ............................................................................................................ REPORT FUNCTION .................................................................................................................
PART II: THE SCIVIEWS GUI API .................................................................................. 77 5. CONCEPTION OF A CODE-CENTRED GUI.................................................. 78
THE CONSOLE IS STILL THERE BUT IT IS SUPPORTED BY A SCRIPT EDITOR ................... 78 MENUS, TOOLBARS AND DIALOG BOXES ............................................................................... 81
3
THE OBJECT EXPLORER AND DATA EDITOR ......................................................................... 83 OTHER EXPLORERS............................................................................................................ 85 VIEWS AND REPORTING FEATURES ....................................................................................... 86 FACILITATED INPUT AND OUTPUT......................................................................................... 88 MANAGEMENT OF THE SYSTEM ............................................................................................ 88 OTHER ASSISTANTS ................................................................................................................ 88 SIMPLIFIED ONLINE HELP AND MANUALS............................................................................. 89 TEXT EDITOR AND IDE .......................................................................................................... 89 6. 7. 8. OVERVIEW OF THE SCIVIEWS R GUI API ..................................................... 90 SVGUI, FUNCTIONS TO INTERFACE GUI CLIENT APPLICATIONS........ 91 SVIO AND SVVIEWS: FORMATTED DATA EXCHANGE.............................. 92
EXTENDING EXPORT, VIEW AND REPORT FUNCTIONS........................................................ 92 9. 10. SVMISC: MISCELLANEOUS UTILITARY FUNCTIONS ................................ 95 SVDIALOGS: REUSABLE DIALOG BOXES ...................................................... 96
BUILDING DIALOG BOXES ...................................................................................................... 96 THREE LEVELS OF MAKING DIALOG BOXES IN YOUR GUI....................................................... 97 APPROACH USED IN SVDIALOGS .............................................................................................. 99 TOOLKIT-INDEPENDENT API AND TOOLKIT IMPLEMENTATIONS........................................... 100 SPECIFICATION OF STANDARD DIALOG BOXES .................................................................. 106 THE MESSAGE BOX ................................................................................................................ 106 THE INPUT BOX ...................................................................................................................... 108 THE OPEN FILE(S) DIALOG BOX .............................................................................................. 109 THE SAVE FILE DIALOG BOX .................................................................................................. 111 THE CHOOSE DIRECTORY DIALOG BOX .................................................................................. 113 THE LIST SELECTION DIALOG BOX ......................................................................................... 114 THE VARIABLE SELECTION DIALOG BOX ............................................................................... 115 THE VARIABLE/ITEM SELECTION DIALOG BOX ...................................................................... 115 THE DOUBLE LIST DIALOG BOX ............................................................................................. 115 THE FORMULA DIALOG BOX .................................................................................................. 116 THE COLOUR SELECTION DIALOG BOX .................................................................................. 116 THE FONT SELECTION DIALOG BOX ....................................................................................... 116 SPECIFICATION OF STANDARD WINDOWS ........................................................................... 116 THE TEXT WINDOW ................................................................................................................ 117 THE GRID WINDOW ................................................................................................................ 117 THE VIEW WINDOW ................................................................................................................ 117 THE EXPLORER WINDOW ....................................................................................................... 118 THE OBJECT EXPLORER WINDOW........................................................................................... 120 THE PROGRESSION WINDOW .................................................................................................. 121 SPECIFICATION OF FLEXIBLE DIALOG BOXES .................................................................... 121 THE FUNCTION ASSISTANT DIALOG BOX ............................................................................... 123 THE OPTIONS DIALOG BOX..................................................................................................... 124 THE GRAPH OPTIONS DIALOG BOX ......................................................................................... 124 THE ASSISTANT DIALOG BOX ................................................................................................. 124
4
11. TCLTK2: ADDITIONAL TCL/TK FEATURES FOR R ...ERROR! BOOKMARK NOT DEFINED. REFERENCES .................................................................................................................... 127
5
PART I: INSTALLING AND USING SCIVIEWS-R
6
1. INTRODUCTIONR (Ihaka and Gentleman 1996, R Development Core Team 2004, but see http://www.R-project.org) is a wonderful environment for statistics, data analysis, modelling and other scientific calculations. It is based on a rich and powerful language: S, as is S-PLUS, its commercial equivalent. It is a functional language1. It is a matrix calculation software. It is object-oriented2. It features thousands of functions, collected in hundreds of packages that can be installed to tailor it from general to very specific purposes. It is excellent in making complex and high-quality plots. And, last but not least, it is free and the whole code source is available for everybody! All these characteristics make the success of R, and it is almost certain that this success will still grow in the future.
Example of a session using R with the command line interfaceThis example shows a non trivial analysis run in R using his default command line interface. We choose a non trivial application to demonstrate both strengths and difficulties of R. Indeed, it is easy to show that a menu / dialog box paradigm is much easier to use for standard analyses, but this does not promote trials and experimentations for more complex examination of the data, a field where R is shinning! There were a few discussions on the R-help mailing list (https://stat.ethz.ch/mailman/listinfo/r-help, another excellent place where beginner or occasional statisticians and R users get pertinent advices from international experts) about how large is the community of R users and how large it will grow in the future. It appears that it is indeed both difficult to evaluate (because R is free, there is no procedure to get it that can be easily monitored), and it is probably not the most interesting aspect: there is no need to monitor or plan its growth, because there is no business plan for its development! R is done by passionate people aiming to get a complete and high-quality statistical environment. Those passionate users/developers are indeed not much concerned whether R is more or less used than, say S-PLUS, or SAS (at least, I suspect that people behind S-PLUS and SAS are more concerned about the growth of R than the contrary ;-). However, we could analyze the amount of email exchanges on the R-help mailing list per time unit as an indirect measurement of the activity around R, This activity is measured, as a rough proxy, by the size of gzipped archives over the last seven years (thanks Martin
1
Most code is accessed by calling functions.
2 Put shortly, object-oriented programming is an efficient way to organize data and code. In this paradigm, an object contains both the data and the code to manipulate it, and the way data is manipulated depends on the nature of the object (which is called its class).
7
Maechler for this suggestion and for providing these data). We propose to analyze these data using R itself:> RhelpUsage RhelpUsage Jan Feb 1997 1998 55 32 1999 99 60 2000 96 144 2001 240 272 2002 455 320 2003 450 487 2004 519 703 Mar Apr 55 50 55 84 80 173 153 262 195 418 453 535 658 886 May 19 41 76 226 236 468 573 Jun 19 49 75 202 244 422 606 Jul 18 50 78 131 285 447 659 Aug 19 28 61 165 249 400 543 Sep 17 53 83 183 326 323 655 Oct 35 42 97 175 345 516 722 Nov 27 81 141 168 392 478 677 Dec 47 54 122 187 268 327 567
and the default graphical presentation:> plot(RhelpUsage)
8
RhelpUsage
0 1997
200
400
600
800
1998
1999
2000
2001 Time
2002
2003
2004
Although using specific objects for storing data looks intimidating and complex at the beginning, it is a very efficient approach for two reasons. First, data storage is optimized for such an object (for instance, here, time is internally recorded with only three numbers: the start time, in any time units that best fits that time series, the end time and the frequency). This is obviously more efficient than storing the time at which each observation is done, that is here, 84 numbers for the 84 observations in the series. Second, R knows about its objects and its behaviour is adapted to the context. Hence, it nicely prints the time series automatically when you type the name of the variable that holds it. Also, the default graphical presentation is also optimized (using lines to show continuity between values, and nicely formatting the time axis). So, a difficulty (use of specialized objects) reveals as a very convenient feature once you manipulate these objects. Coming back to our analysis, we can plot also a log-transformed series3.
3 The reason why we use a log transformation here is not important for the sake of the demonstration. For those who want to know, it is because the high-frequency signal appears multiplicative with the general trend (its amplitude increases proportionally with the value of this trend). In this case, a log transformation makes those two signals additive and stabilizes the variance of the high-frequency signal (i.e., the residuals in the models we apply, further in the analysis).
9
> LogRhU plot(LogRhU)
LogRhU
3 1997
4
5
6
1998
1999
2000
2001 Time
2002
2003
2004
At this stage, we could wonder if a monthly interval is really the best one to maximize the signal/noise ratio in this time series. The turnogram is one method that uses information theory to answer this question (interested readers should look at Dallot and Etienne 1990, or Grosjean and Ibanez 2004):> library(pastecs) Loading required package: boot > RhU.turno summary(RhU.turno) Simple turnogram for: RhelpUsage options : call : max. info. : turning points extract level: interval 1 2 3 4 5 6 sum / two-tailed probability turnogram(series = RhelpUsage, FUN = sum) 35.34312 at interval 6 (P = 2.294349e-11: 0 for 14 observations) 6 ()
1 2 3 4 5 6
n turns info 84 49 2.8550122 42 27 -0.2299715 28 11 7.8110573 21 7 8.6546750 17 7 3.7143862 14 0 35.3431242
10
7 8 9 10 11 12 13 14 15 16
7 12 8 11 9 10 10 9 11 8 12 7 13 7 14 6 15 6 16 6
0 1 1 1 1 0 1 0 1 1
27.8354558 14.2519023 11.7938816 9.4747796 7.3105233 11.2992080 5.3219281 8.4918531 3.5376568 3.5376568
Simple turnogram for: RhelpUsage
I (bits) 0 1 10
20
30
2
5 interval () sum / two-tailed probability
10
This method tells us clearly that information (expressed in bits) in this time series is the highest with an interval of six months. In other words, the ratio signal/noise is significantly lowered with such a time interval, compared to the original monthly time series. We could decide, thus, to recalculate the time series with biannual sums of the activity:> RhU6 plot(RhU6)
11
RhU6
0 1997
1000
2000
3000
4000
1998
1999
2000 Time
2001
2002
2003
2004
Indeed, the series looks much cleaner now, isnt it? Notice how simple was the analysis (once you know which function you have to call, of course!). We just had to load a package containing additional functions called pastecs with the instruction library(pastecs). Then, we used a specialized function called turnogram() on our data with an argument, FUN = sum. We got a summary of the results simply by calling summary() on the object we just created and extraction of the optimized series was not more complex, just calling extract() on the same object! Lets look now at the graph of the log-transformed form of our time series:> LogRhU6 plot(LogRhU6)
12
LogRhU6
5.0 1997
5.5
6.0
6.5
7.0
7.5
8.0
1998
1999
2000 Time
2001
2002
2003
2004
Can we fit a linear model on this? (take care! This is a time series. There is probably some autocorrelation. So, the ANOVA on the regression and the t-tests on parameters are not valid here!)> LogRhU6.lm summary(LogRhU6.lm) Call: lm(formula = LogRhU6 ~ time(LogRhU6)) Residuals: Min 1Q -0.23652 -0.10947 Coefficients: Estimate Std. Error t value (Intercept) -1.018e+03 4.095e+01 -24.85 time(LogRhU6) 5.121e-01 2.047e-02 25.02 --Signif. codes: 0 `***' 0.001 `**' 0.01 `*' Pr(>|t|) 1.09e-11 *** 1.01e-11 *** 0.05 `.' 0.1 ` ' 1
Median 0.03873
3Q 0.12922
Max 0.20945
Residual standard error: 0.1544 on 12 degrees of freedom Multiple R-Squared: 0.9812, Adjusted R-squared: 0.9796 F-statistic: 625.8 on 1 and 12 DF, p-value: 1.009e-11 > abline(coef = coef(LogRhU6.lm), col = 2)
13
LogRhU6
5.0 1997
5.5
6.0
6.5
7.0
7.5
8.0
1998
1999
2000 Time
2001
2002
2003
2004
Humm! Could we do better than this? We could use polynomials to fit a curve on these data, but I dont like them much. For this series, we could prefer to fit something like a simple asymptotic growth model:> abline(coef = coef(LogRhU6.lm), col = 2) > df1 LogRhU6.nls summary(LogRhU6.nls) Formula: load ~ SSasympOff(time, Asym, lrc, c0) Parameters: Estimate Std. Error t value Asym 11.1333 0.9797 11.364 lrc -2.1036 0.2320 -9.067 c0 1992.3589 0.6269 3177.920 --Signif. codes: 0 `***' 0.001 `**'
Pr(>|t|) 2.03e-07 *** 1.95e-06 *** < 2e-16 *** 0.01 `*' 0.05 `.' 0.1 ` ' 1
Residual standard error: 0.09667 on 11 degrees of freedom Correlation of Parameter Estimates: Asym lrc lrc -0.9938 c0 -0.9521 0.9791
14
> plot(df1$time, df1$load, type = "l") > lines(df1$time, predict(LogRhU6.nls), col = 2)
df1$load
5.0 1997
5.5
6.0
6.5
7.0
7.5
8.0
1998
1999
2000
2001
2002
2003
2004
df1$time
Again, we should not use t-tests on the parameters, keeping in mind that we probably have autocorrelation in the series. Otherwise, this model does not look too bad. The code we used was a little bit more complex here, because we had to use a nonlinear regression and had to transform the time series object into another object (a data frame). Otherwise, we had to use summary() and plot() + lines() in a similar way as we did before. Now, thats fine, but we need a refined graph, ready for publication. Should we have to switch to a specialized graphing package for that purpose? No! R is capable of drawing very nice and refined graphs. So, with a little more work, we can get something like this (converting the size of gzipped archives to number of messages, according to a rough estimation of the mean size per messages done in March 2004):> > + + > > + > # Plot of the dots for observations plot(df1$time, exp(df1$load) * 1949 / 886, xlab = "time (years)", ylab = "nbr. of messages / semester", main = "R-help mailing list usage (estimation)") # Superposition of a red curve for the model lines(df1$time, exp(predict(LogRhU6.nls)) * 1949 / 886, col = 2) # Vertical grid lines
15
> abline(v = 1998:2003, col= "gray", lty = 2) > # Horizontal grid lines > abline(h = (1:9)*1000, col= "gray", lty = 2)
R-help mailing list usage (estimation)
nbr. of messages / semester
0 1997
2000
4000
6000
8000
1998
1999
2000
2001
2002
2003
2004
time (years)
Wow! It looks like the R-help mailing list is still in an exponential growth phase in 2004. Is it the same for R use? Probably! This graph is showing that point very well. So, why the use of R is growing so fast? Perhaps because you can do things like that in a very flexible and convenient way! Now, the challenge to convince sceptical people: try doing the same analysis in your favourite software. Keep also in mind traceability and potential to easily run the same analysis on several datasets, after collecting all the commands in a script in R. Do you have the same facility in your favourite software? Do you have easy access to numerous specialized analyses like the turnogram (there are almost 400 additional packages available for free on the R distribution web site, http:///www.cran.r-project.org, for doing almost everything you can imagine)? This little session in R was conducted primarily to give you a feeling on how it can be used today: it is a command-line driven program and users need to key in commands at a prompt. This approach is very flexible, and R has a lot to offer to those who can manage entering commands in its language and who know how and where to find specialized features.
16
If you feel comfortable with this user interface, then probably you do not need the SciViews-R extension. You may even consider using (X)Emacs with ESS extension (http://stat.ethz.ch/ESS/) if you want more power to control R from a textual-based user interface. Windows users may also be interested by http://socserv.mcmaster.ca/jfox/Books/Companion/ESS/ which explains how to install and configure Xemacs and ESS under Windows4. On the contrary, if you want a graphical user interface to drive R, either for yourself, or for your students (in your courses), or for your collaborators, then you should give a try to SciViews-R. Other reasons why you could be interested by SciViews-R are: It is bunded with an advanced script editor with syntax highlighting, set-by-step execution, bookmarks and many more, There is help everywhere to write your code, especially, function tips which display the syntax of functions whenever you use them, and completion lists that propose context-sensitive lists of terms to help writing your code, An object explorer proposes a convenient centralized place where you can manage your variables easily, find functions or data and look at their help or content instantly, Views and reporting features add rich-formatting outputs you can quickly integrate in the reports you build from your analyses, Its user interface is fully customizable: you can place up to five docked windows wherever you like, and you can fully redefine menus and toolbars, and add custom tools to them.
A graphical user interface for RR is often considered as a hard-to-learn and hard-to-use system done by and for experts (at least, I know many biologists that believe so). It is intimidating because R lacks an advanced friendly user interface for beginners or occasional users what we call a GUI (Graphical User Interface). Several projects are developed to fill the gap, see http://www.r-project.org/GUI. One of these projects is SciViews-R (http://www.sciviews.org/SciViews-R). It aims to bring a GUI to R, but not any kind of GUI: one that helps beginners from start, progressively gives him good working habits and seamlessly teaches him how to write scripts and how to programs in S language, the underlying statisticaloriented language build in R. The language, the command line (R console) and the script editor are still central elements in such a GUI. We do not intend to hide this horrible code and replace it completely with sexy dialog boxes! We prefer instead to support the user in
4 Note from Marta Rufino : it seems that Emacs could cause problems under Windows. However, following instructions in John Foxs page, I (Ph.G.) was able to install and run it smoothly on my Windows XP. I have no further experience of Emacs-ESS, beyond this quick trial.
17
writing its code, to show him by the example how to write a script for a given analysis. What does the beginner or occasional user need? He needs plenty of help: syntax highlighting, code completion wizards, code tips displaying the syntax of functions, an assistant for writing calls to functions, a graphical object explorer, a simple but efficient script editor, electronic reference cards and a simplified help system that presents only the most important features of R. These are precisely the tools we provide (or plan to provide) in SciViews-R. However, instead of writing proprietary tools, we want to make them available also for other R GUI projects. It means that the core of these additional features is written in R itself, and in such a way that it is easily reusable. All these functions are implemented into eight different R packages: svGUI: the core GUI package that implements functions to communicate with the GUI client, svDialogs: the dialog boxes, svIDE: specific features for IDE (Integrated Development Environment) and script editors, svIO: import and export functions, svViews: implementation of the views and the reporting system, svSocket: a ssimple ocket connection to R, for client/server architecture. svMisc: various other supporting functions used by the other packages, and tcltk2: an enhanced Tcl/Tk addition to supplement the core tcltk package.
These eight packages are collected together in the bundle SciViews (except tcltk2, for it is is not platform-independent yet, and only runs on Windows, currently) and constitute the SciViews GUI API for R. It is this API that we present in this document, together with the SciViews-R suite of applications that use it to implement a complete GUI for R (currently, only under Windows). All programs developed by the SciViews team are distributed under an Open Source license (GPL 2 or above), as R itself. Our goal is to contribute in providing a high-quality GUI for this statistical system that can be freely used by everyone. SciViews-R is also programmed in an expendable way, which means any programmer may implement additional features, or even a different suite of fully-compatible companion applications. This way, we hope to encourage intercompatibility between the various R GUI projects. We wish others implementations, possibly in Tcl/Tk, Gtk, Java, Aqua, will develop. However, we anticipate great potentials of the wxPython (wxWidgets + Python) as a powerful platform-independent solution for these
18
companion applications. R-wxPython (http://bioinf.wehi.edu.au/folders/james/wxPython/) uses RSPython but RPy (http://www.omegahat.org/RSPython/), (http://rpy.sourceforge.net/) is a possible, although unidirectional, alternative to write a Python/wxWidgets GUI for R. We warmly encourage any initiative in this direction and will support and help any volunteer that would like to write a platform-independent version of SciViews-R with these tools. Remember: your contributions are welcome! Indeed, all this should be regarded as a work in progress, as more and better features will be gradually added to the system. The current version of SciViews-R, 0.8-9 is not the final implementation. However, we believe that the general framework is now established, after more than three years of research and experiments in GUIs for data analysis systems (mainly in the ecology/biology/environmental science field). SciViews-R has already evolved much since its first trial presented at DSC 2003 (Grosjean, 2003)! The first part of this manual is intended for R users that would like to use SciViews-R as an alternate (GUI) interface for R. The second part is dedicated to developers that either want to contribute to the SciViews R GUI API, or want to use it for writing, or extending their own R GUI.
AcknowledgementsWe would like to tank the R Core Team for providing such an excellent piece of software as R. We are particularly grateful to Duncan Murdoch for his efforts in implementing features for R that ease writing of a GUI on top of it. We also thank Peter Dalgaard for the tcltk package and James Wettenhall for his preliminary version of R-wxPython.
19
2. INSTALLATION OF SCIVIEWS-R, R AND R PACKAGESIn this chapter, we deal with the installation procedure of SciViews-R + R + additional R packages/bundles. The installation procedure may look complicated, because there are several steps. Please, consider that this is not the final version of the SciViews-R installer: it is still in development! Of course, we aim an installation as simple as possible. SciViews-R is mainly dedicated to beginners or occasional users, and a straightforward installation is required for them. In the future, we will work towards a simplification of the installation process. Currently, R and SciViews-R must be downloaded and installed separately. Moreover, the bare installation of R is not enough: several additional R packages/bundles must be installed. Starting from version 0.7-2 of SciViews-R, there is a function to automatically prompt the user with a GUI in case these packages are missing (thanks to James Wettenhall). This works only for computers connected to the Internet. So, the alternate method (manual installation of these additional packages) is still valid as an alternative. First section, condensed installation instructions is for experienced users that do not need all the details to install the software properly (they probably already have installed R and know how to install additional R packages in R). Subsequent sections are very detailed instructions for novices. If you have problems installing and/or running SciViewsR, please, make sure you followed all steps explained here, and you read the detailed instructions carefully before calling for help. If, despite this, you still cannot install or run SciViews-R, then, send an email to [email protected]. You should provide as much details as possible, otherwise we cannot help you! You should at least indicate: Which version of Windows you use, which processor and how many RAM memory you have (these data are available from Start menu -> Control Panel -> System). Which version of R you run, and whether is correctly configured to use Tcl/Tk. To get these data, enter the following commands at the R prompt and copy/paste result to your email:> R.Version() > capabilities("tcltk")
Which version of SciViews-R you are installing. The version number is in the name of the installer. For instance, the installer SciViews-R_0.8-9Setup.exe installs version 0.8-9. Optionally, it may help to list loaded packages at the point where starting of SciViews R Console fails. Use the following command and copy/paste result to your email:> search()
20
Condensed installation instructionsTO DO
Detailed installation of SciViews-RSciViews-R is distributed on the SciViews web site (http://www.sciviews.org/SciViews-R). Download the installer for Windows 98se/2000/XP (sorry, not compatible yet with Windows 95, or other platforms). On the web page, it is the binaries of SciViews-R that you have to download at this stage (the whole installation procedure is given with lots of details, to help beginners; more advanced users can browser this section rapidly). To run SciViews-R, you need: a recent computer (equivalent to a Pentium III, or IV) with at least 256 Mb of RAM memory (512 Mb is preferred to analyse large data sets), and at least 60 Mb available on the hard disk where you install SciViews-R and R. Once downloaded, you have a file named SciViews-R_0.8-9.exe. To install it, you have to log on temporarily with administrative rights (this is not necessary for using the program after its installation). If you installed one of the previous versions of SciViews-R, you should better uninstall it first (go to start menu -> Control Panel -> Add or Remove Programs -> SciViews-R version 0.x-y). Then, just follow instructions in the setup assistant. Figures 2-1 to 2-9 present the sequence of installation of SciViews-R 0.7-0 (should be updated to version 0.8-9). Just double-click on the downloaded file in the files explorer, and you face the welcome screen of the setup assistant
21
Figure 2-1: the welcome screen of the SciViews-R 0.7-0 setup assistant. If you see this screen after launching SciViews-R_0.7-0.exe, you are certainly logged with administrative rights on Windows 98se, 2000, or XP (otherwise, an error message explains the origin of the problem). Click Next.
Figure 2-2: second screen of the assistant. You have to accept the license terms (click I accept the agreement) to be allowed to continue. Click Next.
22
Figure 2-3: the setup assistant asks you where you want to install SciViews-R. You can install it where you want, preferably on a local hard disk with enough free space. Most of the time, the default directory is fine. Click Next.
Figure 2-4: this screen presents components to install. In 0.7-0, there is no optional components just click Next.
23
Figure 2-5: it is strongly advised to create shortcuts for the programs in the start menu. The default folder SciViews-R should be fine. Just click Next.
Figure 2-6: this screen presents various additional tasks. You can create a desktop icon for the program, either for yourself only, or for all users of this computer. This is a convenient shortcut to start R with the SciViews-R interface
24
rapidly. If you had to log off your account, and log on as administrator, make sure you select For all users, otherwise this shortcut will not be available in your own user session. The other task is to associate files with specific extensions to SciViews-R applications there is no reasons for not doing this. So, leave the Associate files option checked and click Next.
Figure 2-7: a summary of tasks that will be done if you click Install. You can check if everything is fine, and then start the installation with Install (or exit it with Cancel). Note that you can fully uninstall SciViews-R at a later time by going in Start menu -> control panel -> Add or Remove Programs -> SciViews-R version 0.7-2.
25
Figure 2-8 : the installation of SciViews-R is in progress
Figure 2-9 : SciViews-R is now installed. It is generally a good idea to read the README file, which may provide latest news and information. Click Finish.
26
Installing R under WindowsOnce SciViews-R is installed on your computer, it is not yet operational: you also need to install R and a couple of additional R packages to be able to use it. It is not important whether you install SciViews-R before or after R, but you must make sure you install at least R version 2.2.0 (SciViews-R is not compatible with previous version of R)! You can download a setup for Windows of the latest R version from http://cran.r-project.org/bin/windows/base/. The file you need is RX.X.X-win32.exe where X.X.X is the version (for instance, 2.2.0). It weights about 25Mb. You can also download it from one of the CRAN mirror sites. If you have time, browse the README and the FAQ from this web page. These give useful additional information about R. When R-2.2.0-win32.exe is downloaded on your hard disk, run it (double-click on this file in the files explorer). The setup assistant of R is similar to the SciViews-R one. Figures 2-10 to 2-17 detail the step-bystep installation of R (version 2.0.0, should be updated to R 2.2.0).
Figure 2-10: the welcome screen of the R setup assistant. Click Next.
27
Figure 2-11: the license agreement. You must click I accept the agreement to be allowed to continue. Then, click Next.
Figure 2-12: where do you want to install R? Usually, the default directory provided is fine. Especially if you run R with SciViews-R, it is advised (but not required) to keep this default directory. Click Next.
28
Figure 2-13: choose components. Select as in the figure. Make sure Support Files for library(tcltk) is checked! Click Next.
Figure 2-14: it is advised to create a shortcut in the start menu. The R folder should be fine. So, you do not need to change default options. Click Next.
29
Figure 2-15: additional tasks. It does not hurt to run them all. So, unless you know what you do, check all options and then click Next.
Figure 2-16: R is now installing. It takes a couple of minutes. Be patient
30
Figure 2-17: R is now installed on your computer! Just click Finish.
Finalizing SciViews-R / R installationNow that both R and SciViews-R are installed on your computer, you have almost done with installation. However, there is an extra step: to install a couple of additional R packages and possibly fix the shortcut that starts R from SciViews-R. This is a critical step where you ensure that SciViews-R will run correctly with R. So, be careful to follow all instructions! Fixing the RSciViews shortcut If R was installed in C:\Program Files\R\R-2.2.0 (the default directory where R version 2.2.0 is installed on an English system), you do not need to change the shortcut. Just go to the next section, Installing additional R packages. If you installed R in a different directory, you have to fix the RSciViews shortcut in the SciViews-R installation directory. To do so, just follow instructions bellow: 1. Start the file explorer, and locate the SciViews-R installation directory. By default, it is C:\Program Files\SciViews (fig. 2-18).
31
Figure 2-18: locate the RSciViews shortcut in the SciViews-R installation directory with the files explorer.
2. Right-click with your mouse on the shortcut named RSciViews, the one with an R icon surrounded by three balls of different colors and with an arrow in its lower left side (fig. 2-19). A context menu is displayed.
Figure 2-19: the context menu when you right-click on the RSciViews shortcut. Select Properties.
32
3. Select properties in this menu. The RSciViews Properties dialog box is displayed (fig. 2-20).
Figure 2-20: the RSciViews Properties dialog box. You have to fix the Target entry in the Shortcut tab.
4. Change the Target field in the Shortcut tab to reflect the actual location where you installed R. By default, this target is:"C:\Program RSciViews.RData. Files\R\R-2.2.0\bin\Rgui.exe" --sdi
You just need to change the first part of it (C:\Program Files\R\R2.2.0) to reflect the actual directory where you installed R. Note that, if you give a wrong directory, a message box will tell you that there is a problem when you click OK in this dialog box. 5. Accept your changes by clicking OK. If there is no error message, the shortcut should be fixed now, and points to the right place (thus, SciViews-R should be able to find and run R properly).
33
Installing additional R packages There are different procedures to install additional packages, depending if your computer is connected to the Internet, or not. If yes, follow these instructions; otherwise, go to Manually installing additional R packages. In SciViews-R, there is a sophisticated procedure to install missing R packages, using a graphical user interface (thanks to James Wettenhall). So, at this stage, you could simply run SciViews R Console, and the program will prompt automatically to install these additional packages. Here is the detailed procedure: 1. Launch SciViews R Console from its shortcut, either on the desktop, or from the start menu. Double-click on the SciViews R Console icon on your desktop, or do Start menu -> App programs -> SciViews-R -> R Console (fig. 2-21).
Figure 2-21: you can start SciViews R Console from its shortcut in the Start menu.
2. A R Console window should appear shortly after that. This is R that is launched by SciViews-R. If you see this window, it means that both R and SciViews-R are correctly installed and that SciViews-R knows where R resides, that is, the RSciViews shortcut possibly fixed in the previous stage is correct.
34
3. The SciViews bundle is probably missing on your computer at this point. So, R should prompt you to install it (fig 2-22).
Figure 2-22: the message that appears the first time you start SciViews R Console when the SciViews bundle is missing. If your computer is connected to Internet, click Yes and continue. Otherwise, click No and follow instructions in the next section to install it manually.
4. R gives you now the choice of several places from where you can install the SciViews bundle. Since it is currently only available on the SciViews web site, select the first entry, SciViews, exclusively (see fig. 2-23).
Figure 2-23: select from where you want to install the SciViews bundle. Currently, the only valid location is the SciViews web site (it may be installable from other locations as well in the future). Select this entry and click OK.
5. The bundle is automatically installed from the web site (fig. 2-24).
Figure 2-24: the Download progress dialog box while the SciViews bundle is being downloaded. Then it is automatically installed on your computer (version number may change: you got always the very last one from the web site).
6. At the end of the installation, you should read a message like in fig. 2-25. R asks you if you want to delete the installation file. Answer y(es), except if you want to install it on several other computers. In this case, it could be faster to click N(o), and then to save the file SciViews_0.8-9.zip from the location given by R to a separate directory, or even, on a CD. On the other computers where you want to install SciViews-R, at stage (4), you could then
35
select Local Zip File and locate the file where you saved it. This way, you do not have to download it every time from the Internet!
Figure 2-25: here is the text that appears in the R Console when the SciViews bundle is correctly installed. You have the opportunity to save the installation file to reuse it in the future (enter N), otherwise, enter y.
7. If this procedure failed at stage 5 (you read an error message), you computer is probably not well connected to the Internet, or it is connected through a firewall that is not well recognized by R (the last possibility is a failure of Internet or of the SciViews web site, but this is less likely to happen). In such a case, proceed in the next section, Manually installing additional R packages. 8. After a while, you will probably be prompted to install another package: R2HTML (fig. 2-26). Proceed the same way, but you can select either SciViews, or CRAN this time in the list.
Figure 2-26: you are now prompted to install the R2HTML package. Proceed and install it the same way (click Yes), but select either SciViews, or CRAN in the list this time.
36
9. Check that the R2HTML package is correctly installed (fig. 2-27), and enter either y, or N, depending if you want to save the installation file of R2HTML for reuse or not.
Figure 2-27: now, R2HTML is installed in R. Click y to delete installation file and continue, or N to save it and continue.
37
10. After a while, you should see the main window of SciViews R Console, as in fig. 2-28. The SciViews-R graphical user interface is now installed properly on your computer!
Figure 2-28: the main SciViews R Console window that appears when SciViews-R, R and required additional R packages are correctly installed on your computer. Note that the Dock1 and Dock2 panels at right could be different, or even not be displayed at this stage. This is perfectly normal.
11. If the loading of SciViews R Console failed somewhere (most of the time, you read a message like in fig. 2-29 after roughly 30 seconds), close any opened window (especially R Console), and try again from stage 1. On some computers, we have observed that SciViews R Console do not start correctly the first time it is launched, for unknown reasons. Everything should work properly the second time you start it. Otherwise, check that you followed the right procedure from the beginning.
38
Figure 2-29: the error message displayed when SciViews R Console cannot connect to R. It proposes an alternate way to start it than the one explained here. You can either retry the current procedure (close R and close this dialog box, and then try again launching SciViews R Console from its icon in the start menu or on the desktop), or you could try this alternate procedure (see later in this manual: starting and stopping the SciViews-R GUI at the end of this chapter). Note that the message anticipates the availability of the SciViews bundle on CRAN (http://cran.r-project.org), while it is currently only available at http://www.sciviews.org/SciViews-R!
Since your computer is able to download additional R packages from the Internet when they are required, you should not worry if all additional R packages are installed or not (indeed, several ones will be installed later, especially if you want to use R Commander wit SciViewsR). Just follow the same procedure and try first the CRAN entry in the list to download and install subsequent additional R packages. You may skip next section. However, if you want to install all these packages manually right now, proceed to the next section. Manually installing additional R packages Especially if you want to run R Commander (basic statistics accessed through menus and dialog boxes) with SciViews-R, you will have to install several additional R packages. First of all, make sure that the tcltk package is properly installed. The tcltk package is provided with the plain R distribution. Moreover, you also need Tcl/Tk files. All this is optionally installed at the same time as R (see fig. 2-13 above). To know if your current R installation supports Tcl/Tk, use the following command:> capabilities("tcltk")
It should answer TRUE. Otherwise, reinstall R and check the tcltk feature this time in optional components. Then, you will need the following additional R packages/bundles (table 2-1):
39
Table 2-1: additional packages required to run SciViews-R and R Commander. Package /bundle SciViews(1) R2HTML(1) Hmisc(3) acepack(3) Rcmdr(4) abind car effects leaps lmtest multcomp mvtnorm relimp rgl sandwich strucchange zoo wxPython(5) RSPython(5)(1) (2)
Minimal version 0.8-9 1.4-3 2.2-3 1.3-2 1.1-1 1.1-0 1.0-13 1.0-3 2.7 0.9-6 0.4-7 0.7-0 0.8-4 0.64-13 0.1-3 1.2-5 0.2-0 0.2.4 0.5-4
Where can it be obtained? http://www.sciviews.org/SciViews-R CRAN(2) or http://www.sciviews.org/SciViews-R CRAN(2) CRAN(2) CRAN(2) or http://www.sciviews.org/SciViews-R CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) CRAN(2) http://www.sciviews.org/SciViews-R or http://bioinf.wehi.edu.au/folders/james/wxPython/ http://www.sciviews.org/SciViews-R or http://bioinf.wehi.edu.au/folders/james/wxPython/
SciViews and R2HTML are always required. To download Windows binaries of R packages from CRAN manually, navigate to http://cran.r-project.org/bin/windows/contrib/, then click an the folder that matches your R version (for instance, folder 2.0 for R 2.0.x) and download corresponding package_version.zip files. Hmisc (which itself requires acepack) is optional and is only used to export objects in LaTeX format (if you dont know what LaTeX is, you probably dont need them). Rcmdr (R Commander) offers menus and dialog boxes to access basic statistic tests. It requires itself abind, car, effects, It is optional. wxPython and RSPython are also optional. They provide wxWidgets/Python dialog boxes to R. Note that you have also to install Python 2.2.x and wxPython binaries 2.5.x. see: http://bioinf.wehi.edu.au/folders/james/wxPython/ for further instructions.
(3)
(4)
(5)
If you failed with the automatic method to install additional R packages as explained in the previous section (for instance, if the computer where you install SciViews-R is not connected to the Internet), or if you prefer to install all required packages at once, follow this procedure:
40
1. Download all windows binaries of the R packages you need (files with names package_version.zip) in a common directory on your hard disk, or better, on a network directory or a CD-Rom if you want to install SciViews-R on several computers. Use table 2-1 to determine which R packages/bundles you need. 2. Start R from its icon in the desktop, or from the Start menu -> All programs -> R -> R x.x.x. 3. When R is loaded, go to menu Packages -> Install package(s) from local zip files 4. In the Select files dialog box, navigate to the folder where you saved your files, and select them all (fig. 2-30). Click Open.
Figure 2-30: select all the packages you downloaded in your installation directory. R will install them all in turn.
5. R installs all these additional packages. Be patient, it takes a couple of minutes. At the end of the installation, R indicates if he could successfully unpack (install) them, and checks that these unpacked versions are correct (MD5 checksums). The latest line updating HTML package descriptions tells that the HTML help is updated to include help of these new packages (fig. 2-31). Look if there is no error message. If everything is OK, you have done. All additional packages are installed! Otherwise,
41
Figure 2-31: the messages you should get when all the additional packages and bundles are correctly installed in R.
6. If R failed to install one or several packages, there may be various reasons for that: (1) you did not download the right version, (2) you downloaded the source or a corrupted version of the package, or (3) the download process failed and you have an incomplete version of them. Try downloading these packages again and restart from step (3). If it still fails, look who is the package maintainer, and send him an email with a full description of your problem.
Starting and stopping the SciViews-R GUIHere are the different ways you can now start and stop the SciViews-R GUI on top of R, once it is properly installed: 1. Double-click on the SciViews R Console icon on the desktop (if you installed it), 2. Select Start menu -> All programs -> SciViews R -> R Console. Note that you can can start the same way the other application in the SciViews-R suite: SciViews R Report and Tinn-R. 3. Start R alone (either from its desktop icon, or from the Start menu -> All programs -> R -> R x.x.x), or in any other way you use to start R (for instance, from a .Rdata file, look at R documentation). In this case, RGui must be started in SDI mode exclusively see hereunder, how to start RGui in SDI mode. If you enter the following instruction:> library(svGUI)
42
The svGUI package is loaded and it automatically starts SciViews R Console, providing RConsole.exe is located in C:\Program Files\SciViews\bin. [PhG TO DO: explain how to customize this!!!]. This third way to start SciViews R Console is interesting if you want to save/load workspaces from session to session (see R documentation if you dont know what a workspace is [PhG or explain this here]). Whatever the way you start SciViews R Console, you should end up with a window similar to this (fig. 2-31; the Dock1 panel at right is probably not the same at this stage, or it can even not be visible this is normal):
Figure 2-31: The SciViews R Console window at startup.
Note that you can start the SciViews R Console from its icon, and stop it by selecting File -> Exit SciViews only, or by clicking on the top-left x button to close the window without closing the R session, once the svGUI package is loaded. You can thus switch from the plain Rgui to SciViews R Console back and forth several times in the same session! This way, it is always possible to free some memory by temporarily switching the GUI extensions off, if required. If you just want to hide or show these extensions, but do not care about memory usage, you can also use Misc -> Hide/Show bars, or Ctrl-H in the SciViews R Console.
43
How to start RGui in SDI mode SciViews R Console cannot start if RGui (the default R program run under Windows) is started in MDI mode (fig. 2-32; Multiple Document Interface). Unfortunately, the MDI mode is the default one when you install R. So, you need to switch to the SDI mode (fig. 2-33; Single Document Interface) manually. Here is the procedure to use:
Figure 2-32: RGui started in MDI mode (default mode). The main window, called RGui contains one or several child windows like R Console.
44
Figure 2-33: RGui started in SDI mode the large, parent window called RGui is not there any more. Only R Console is there, and the main menu is displayed in this window. SciViews R Console can only be started when RGui is in this mode.
1. Start R (RGui) from its desktop icon, or from the start menu. 2. If it is in SDI mode, you are done. 3. If it is in MDI mode, select menu entry Edit -> GUI preferences You should see a dialog box like in fig. 2-34. 4. Select Single or multiple windows -> SDI in this dialog box (fig. 2-34).
45
Figure 2-34: The Rgui Configuration Editor. You have to select SDI in the top of this dialog box to switch RGui in SDI mode.
5. Click Save. R asks you where to save this configuration file (called Rconsole). Do not change it, and click Save (fig. 2-35). 6. Click Cancel in the Rgui Configuration Editor (fig 2-34). It is not useful to click either Apply, or OK here, because these changes cannot be applied directly: you have to stop and restart RGui in order to get it in SDI mode. That is why we just save the configuration file and cancel the configuration editor. 7. Stop RGui (File -> Exit). Click No at the question Save workspace image?. 8. Start R again from its desktop icon, or Start menu entry. You should have RGui running in SDI mode now (fig. 2-33).
46
Figure 2-35: the file selector displayed when you click Save in the Rgui Configuration Editor. Do not change the default file and path proposed and just click Save.
Saving workspaces from session to session with SciViews-R [TO DO: explain how one can save and restore sessions in R / SciViews-R; explain also the difference between the workspace and the script edited in the command bar this appears to be often confusing for beginners!]. [TO DO: a summary and flow chart of installation procedure for very beginners, suggested by M. R.]
47
3. COMPANION APPLICATIONS FOR WINDOWS IN SCIVIEWS-RTwo distinct parts compose SciViews-R: 1. A platform-independent layer, mainly represented by R code collected in the SciViews bundle (note: some part of it is not platform-independent yet, but it is planned for the future), but also, by menus and other items written in HTML code. This layer does not only care of providing GUI extensions to R, but it also expands the way data and results are manipulated and explored. For instance, import, export, copy and clippaste concern communication between R and other software and view implements a flexible way to have visual insights on R objects, combining text, tables and graphs. 2. Companion applications that actually implement the GUI. They are interchangeable. It means that other applications can replace existing ones, possibly with a particular look and feel more adapted to a given platform. The SciViews team currently develops such a suite of GUI satellite applications for the Windows platform: SciViews R Console enhances the classical Rgui with functionalities like an object browser, a context-sensible script editor, customizable toolbars or dockable windows displaying menus, graph galleries, assistants, electronic reference cards, Tinn-R is a code editor with syntax highlighting, contextual help and integration with R for running and debugging R scripts. SciViews R Report is an HTML wysiwyg editor designed to quickly write reports of your analyses made with R. All these applications communicate with each other and with R. They constitute a powerful, integrated and complete statistical analysis environment, with R as the corner stone.
Overview of the applicationsSciViews R Console is a GUI that supplements the classical Rgui with various tools. It adds some functionality such as an object browser, basic script edition and customizable toolbars and menus. It also handles views and can communicate with R as well as with the others applications in the suite. SciViews R Report is a HTML text editor you can use to edit reports. When used conjointly with the SciViews R Console, you can append directly your graphs or your views in it. The report function, accessible from command line or via the contextual menu of objects in the object explorer also interacts with it. Tinn-R is a code editor with syntax highlighting, contextual help and functions to submit code to R in whole or line-by-line from the editor. You can use it as a powerful replacement of the script editor provided with SciViews R Console.
48
SciViews R ConsoleSciViews R Console is the main application. It consists in an enhanced Graphical User Interface (GUI) you can use instead on top of the basic Rgui that comes with R (providing it is running in SDI mode, see installation of SciViews-R and the SciViews bundle). Since SciViews R Console runs with Rgui and do not replace it, it remains 100% compatible with the latter. No worry thus, about compatibility issues between the two!
49
From classical Rgui (in SDI mode)
to SciViews R Console [TO DO: increase resolution!]
50
At any time, you can come back to the classical Rgui:
either by quitting completely SciViews R Console, which will restore Rgui to its usual state. Or by using Ctrl-H shortcut which toggles Show/Hide bars.
SciViews R Console bars SciViews R Console comes with several add-on bars you can show or hide, depending on what you want. In this section, we will describe those bars. Available toolbars are listed in the menu Misc -> Toolbars. [note that the more bars entry in not implemented yet in SciViews-R 0.8-9]
51
Command bar / Script Editor
The command bar allows editing R code and acts as a rapid script editor (look at Tinn-R for a fully-featured code editor). Associated toolbar includes buttons to: create a new script file, open a script file (default .R extension, could be changed), save the current script file, run the script in part or in whole: what is submitted is either the active line or the current selection ; a useful shortcut is F5 key for this button. Note that, if you click Shift-F5, then you source the whole script in the console. This is dramatically faster, but you have no details on the operation. The script must be saved on disk for this to be operational. Last changes in the script are automatically committed to the file on disk when you click ShiftF5. Recall history (not programmed yet in this version). Send a piece of code to the Report application (not done yet).
On-the-fly execution of code when you key it in the script window is ensured by using Shift-Enter instead of Enter to go to a new line. In this case, the corresponding command is immediately issued at the prompt in the console. Within the editor, the code is syntax-highlighted. When the name of a function is written and you enter the open bracket (, a code tip appears with the syntax of the function. In the current version, it is not terribly smart yet. It cannot resolve generic function/methods, nor a few commands like for (, or length (. This will be fixed later. To dismiss a code tip, hit ESC, or click anywhere outside the tip in the command window.
52
For your convenience, you can drag and drop items from the object explorer (see hereunder) to the script. If it is a function, the opening bracket is added automatically as well as the corresponding code tip. Double-click on an item in the object explorer has the same effect, except that it will send the variable name either to the script or directly to the console, depending which one currently owns the caret. With double-click, the name of the variable is naturally send to the caret position, while with drag and drop you can freely decide where to drop it. You can even use drag and drop from the object explorer to any external text editor that is drag&drop compatible! If you only remember the beginning of a function or variable name, just enter it and hit Ctrl-Space. You then obtain a completion list with all variables starting with this string (example at right). Select in the list, or click Tab to autocomplete the word. Hit Esc to cancel the completion list. Icons recall the type of variable it is, like function, method, data frame, vector, etc If you call the completion list without entering the beginning of a variable name, the list of all variables currently in the user workspace is displayed. Methods are displayed in the list and are pasted as such (example, plot.default). For sure, the function should paste only plot, since it is the recommended way to call a generic function. This will be fixed in later versions of the software. The completion list is automatically displayed and shows components of a list or a data frame when you follow the name of the list/data frame variable by $. Try for instance to issue mylist explain how do we change and customize the dockable windows. For example, if I want to create one that is called geostatistics and opens the library gstat and geoR, and has the graph whatever I do I do it ? I saw in the example that you can create other dockwindows, but when I press customize it states that it is still not implemented. Ph.G.: yes, good idea, we should add a section explaining how to write such dock contents] Available components are categorized according to the following classification: Libraries Libraries are web pages that can interact with the R Console, or the script panel. Since you use HTML code, you are only limited by your imagination here! In this version of SciViews-R, we have only added a few of them, to illustrate their great potentials. Here is an overview of the few libraries that come with the program:
54
R Reference card is an electronic version of Jonathan Barons R reference card. Items are classified by categories and could be clicked to be inserted in your R session.
Colour picker allows choosing colours. Hexadecimal RGB representation code is inserted within your R session [to do: link to RColorBrewer + include ideas from http://geography.uoregon.edu/dat agraphics/color_scales.htm].
The SciViews version of the R Commander menu, that interacts with the Rcmdr package (>= 1.1-1).
55
Libraries are stored in the user directory. You can add your own libraries (a document will explain how to do that in future versions; in the meantime, just study the code of example libraries). Scratchpads Scratchpads are little RTF document editors you can use in several ways: as session clipboards to store pieces of code, text, ideas, graphs, to do lists and so on. In the current version, many tools are missing to open, close and edit them. Basically, you can copy and paste text and access basic editing features. Scratchpads also support drag and drop from the object explorer, from the script window, from compatible text editors, or word processors. Documents in scratchpads are automatically saved at regular intervals, and they are restored from session to session.
Object Explorer The object explorer allows browsing the R objects accessible from the active R session. Environments are listed, beginning by the user workspace (.GlobalEnv). Objects existing in the selected environment are listed in the panel below. You can filter objects depending on types (data, vectors, functions) or by using regular expressions. Combining both filters you can easily find functions or variables, even from large environments, like base. To obtain information about regular expressions, you can have a look at the help of the function grep. Here are some expressions you could use: Expression/pattern \\. frame$ ^f [0-9] ^.$ ^$ ^.[0_9] Objects returned contain a dot (usually a method) ends with frame begins with f contains at least one figure its name is of length 1 its name is of length 3 has a figure in second position
56
The contextual menus of the object explorer are generated in pure R code in the current R session. They adapt, thus, to the current state of R, and custom items can be easily added, just with R functions. The list of available views, by example, is generated on the fly, so that if you add a view it will appear next time you right-click on an object of the given class. [TO DO: redraw the picture: bad resolution, unreadable in PDF!] Adding custom tools SciViews R Console allows you to customize your environment in several ways. Here are the steps to add a custom button to a toolbar and use it to call a R function (steps are identical to add menus items in the SciViews R Console menu).
57
1. Call Customize dialog box Go to Commands tab, category Custom
2. Drag Custom Button and drop it on a toolbar. Once the button is positioned, click on it. The following dialog box appears:
Click on R Command button.
Enter the R code to submit with this button and press OK.
58
You can change other attributes of the button if you want (icon, caption, description, tooltip text). Close the customize dialog box. A list of all custom buttons and corresponding R commands appear. You can put it in clipboard and paste it in a text editor to remember those commands you added to the toolbars/menus. Changes in toolbars/menus are automatically saved from session to session for each user separately. The location and visibility of the bars, including the command bar and the dock panels is also saved. If you want to save and retrieve given configurations, you can use the menu entries Edit -> Save/Load Settings Customizations are saved in binary format, in files with .RconsoleTB2 and .RConsoleTBM. They can be reused by other users, or on other computers.
59
SciViews R Report
60
SciViews R Report is a separate, lightweight HTML editor that communicates with SciViews R Console to easily build nicely formatted reports during the analysis. Interactions are the following: Insert the default view associated with an object: call the menu and select Report. Insert a graph from the SciViews graphic device. Two icons are available to export it in PNG format only, or both in PNG and PDF formats, respectively. [todo: explain how to report a plot from the command line] Invokes report R function directly from command line:> report(iris)
When using SciViews viewer for a given view, use the Report icon to append the content of the current view to the report.
Within SciViews R Report, you benefit of all classical formatting options. In fact, you can use any formatting based on HTML language. In future versions of SciViews R Report, you will be able to transfer your HTML report to Microsoft Word, without any lost of formatting (the button already exists in View -> Import in Word, but it is not programmed yet). A reason why we programmed SciViews R Report, instead of using a link to Microsoft Word, is to remain independent from the office suite of Microsoft. The main reason, however, is to provide a lightweight editor (about 12 Mb when loaded in memory) that does not uses to much RAM and leave it for R. If you open a program like Microsoft Word at the same time as R, you will waste as much as 50 to 60 Mb!
61
Tinn-R, a R code editorTinn is a text editor developed with Borland Delphi 5 for Windows. It is designed as a small, simple, but richer replacement of the default Notepad.exe under Windows. It is distributed under a GPL license. The original Tinn was adapted to edit R scripts. This special release is called Tinn-R. It is made and maintained by Jos Cludio Faria (DCET/UESC/Brasil), Philippe Grosjean (UMH/Belgium) and collaborators. Tinn-R uses a SendKeys component kindly donated to the project by MJT NET (http://mjtnet.com/). It is tested so far under Windows 98, 2000 and XP.
Main characteristics of Tinn-R 1. Syntax highlight of S language, 2. Menu and toolbar with specific tools to interact with R, 3. Allows working with the following R user interfaces: RGui (in MDI mode), R Console (RGui in SDI mode), SciViews R Console (it is suggested to close the command editor if you work with Tinn-R)
4. It works also with S-PLUS.
62
Tips for using Tinn-R This is a quick tour of Tinn-R, showing its major features: 1. Define if the specific menu and toolbar is displayed in Tinn-R (R Resources Visibles checkbox). You can also indicate which is you favourite Rgui program (Rgui.exe in the \bin subdirectory of R, or RConsole.exe in the \bin subdirectory of SciViews).
2. Visualization of the specific menu and toolbar:
63
3. All highlighters are user configurable:
4. Warning! Do not use accents or symbols (@, #, $, %, ^, &) in the path or files names of your scripts. Tinn-R do not work properly (yet) in such a case! 5. Details of the specific R menu:
64
65
6. The specific R toolbar can be placed everywhere on the screen:
7. Files with *.r, *.R, *.q and *.Q extensions are recognized as R/SPLUS scripts. If the file does not have one of these extensions, or if it has not been saved yet, some R tools are disabled
66
8. To send code line by line from Tinn-R to RGui, it is recommended to dispose the two windows (RGui and Tinn-R) side-byside. If you want to place Tinn-R on top of Rgui / R Console or SciViews R Console, you have to set the On Top option of Tinn-R for this purpose (the button with an icon representing a pushpin):
There are far more tools and features in Tinn-R. You can discover them by using the program and experimenting with its menus. You can also read the Tinn-R FAQ, whose latest version is available at: http://www.sciviews.org/tinn-R/Tinn-R_FAQ.txt. [TO DO: indicate how to change hotkeys in Tinn-R to match those in SciViews R Console]
67
Using SciViews R Console with R CommanderR Commander (Rcmdr) is an R package from John Fox that offers a basic-statistics Tcl/Tk GUI for R. You can download it from CRAN (http://cran.r-project.org), or from John Foxs web pages (http://socserv.socsci.mcmaster.ca/jfox/Misc/Rcmdr/). The target audience consists mainly in student users, for teaching purpose. Under SciViews, Rcmdr seamlessly integrates within its environment, starting from version 0.9-12 (but SciViews-R 0.8-9 requires at least Rcmdr 1.1-1). The main window of R Commander is not displayed there. SciViews uses instead a dock menu. State (which data set and which model is in use) is displayed in the status bar of SciViews R Console. Log of commands is done directly in the script panel. At left, a representation of the SciViews version of the R Commander menu. Items are accessed in tabbed sheets. When clicking an item, the corresponding svRcmdr menu is called, thus invoking a Tcl/Tk window. Simply use this window to enter the parameters of your analyses. Note that in this version of SciViews, dialog boxes do not always appear on top of SciViews R Console. Just activate them from the command bar, if required. This will be fixed in next release.
68
4. PRESENTATION OF SOME FUNCTIONS IN THE SCIVIEWS BUNDLEIn this section, we present some of the R functions in the SciViews bundle that can be called directly from the command line within an R session. This section is not an exhaustive presentation of all the functions in this bundle. Please, refer to the online help of the respective packages (svGUI, svMisc, svIO, svViews, svDialogs, svIDE, svSocket and tcltk2) for further information. We focus here on the practical use of some of these functions.
export and copy functionsMain usage syntax:export(x, type = ,file = ) copy(x, type = ) export function provides a convenient way to export data or other objects from R. It is a generic function, which means different methods can be defined for different classes of objects. At the moment, we define specific methods for matrices and data frame. Any other objects are treated by export.default. Other methods can be easily added in the future, using the traditional implementation of methods in the S language.
For a given object (lets say a data frame), we would like to make different types of exportation available from the same function, like raw text, HTML, LaTeX The argument type controls this. Depending on the object, different types of exportation may be available (including custom ones). To know which types are available for a given object in a given environment, use export(x, type = "typelist") as shown below:> library(svIO) > data(iris) > export(iris, type = "typelist") [1] "raw" "ascii" "html" "latex"
"sascode"
The different types in the previous example correspond to:raw:
exports an internal representation of the object which could be sourced to recreate the object in another R session. For details, see the help page of dput function. exports a text (ASCII) version of the object, with values separated by tabulations. This version could be read directly by many external applications, such as text editors, spreadsheets, or other statistical software.
ascii:
html:
exports the object as HTML code (we may consider in the future to export as XML).
69
latex:
exports the object as LaTeX code. It uses the code from HMisc package, which is thus required. Useful for pasting the object in a LaTeX document. export the SAS code which defines the object within SAS (only for data frames).
sascode:
As we want to output the object, we clearly have to indicate the destination. This is done using the file argument. In any case, an empty string for this argument redirects the output to the R Console, which could be useful for debugging. In many cases, you will want to write to a file on disk (provide the complete path). Depending on the type of exportation (and so on the underlying called export function), the value could be any type of connexion R could handle, as listed in the help page of file function.> x export(x, file = "", type = "latex") % latex.default(x, file = tmpfile, ...) \begin{table}[!tbp] \begin{center} \begin{tabular}{r}\hline\hline \multicolumn{1}{c}{} \\ \hline $1$\\ $2$\\ \hline \end{tabular} \end{center} \end{table} > export(x, file = "", type = "ascii") 1 2
Here is an example exportation into SAS code :> export(iris, file = "iris.sas", type = "sascode")
The result is visible at: http://www.stat.ucl.ac.be/R2HTML/iris.sas. You may easily add your own export types, by adding a function whose name is: export.class..type. Please, refer to the second part of this manual for further information on how to extend features of the SciViews bundle. Instead of exporting the whole object, one could also export a part of it or the result of any calculation: export also accepts expressions as first argument. Keep in mind, however, that the expression will always be evaluated in the user workspace, whatever the place it is called (a restriction required by the GUI extensions of SciViews-R). Use get(x, pos = ) to retrieve an object in a particular environment. An expression as first argument of the export or copy function will be evaluated in the user workspace:
70
> export(as.data.frame(apply(iris[ , 1:4], 2, mean)), file = "", + type = "sascode") DATA work.asdataframeapplyiris_14_2_mean; INFILE cards missover; INPUT applyiris142mean ; CARDS; 5.84333333333333 3.05733333333333 3.758 1.19933333333333 ; RUN;
This last example would benefit from some additional parameters: the name of the SAS data set is computed from the input but this may be override with the option sasmember:> export(as.data.frame(apply(iris[ , 1:4], 2, mean)), file = "", + type = "sascode", sasmember = "iris") DATA work.iris; [...]
[to do: an example using the argument append, and also, an example with HTML format] One current use when working on projects with several applications is the copy/paste (the clipboard metaphore). R addresses this issue by allowing to write to the clipboard by using file = type = "sascode", file = "clipboard". Thus, export(iris, "clipboard") writes the generated SAS code to the clipboard.copy is a simple wrapper of export that automatically adds this argument, so that you may find quicker to type: > copy(iris, type = "sascode")
Be careful: with clipboard operations, there is a limit of 32 Kb! Export in files for larger objects.
view functionsMain usage syntax:view(x, type = )
Data analyses require in-depth browsing of data and results. Statistical analyses fruitfully begin with some descriptive graphs and sometimes well-established suites of steps to check and explore them. R allows doing this, of course, but it separates textual output (in ASCII format at the console) from graphics (in graph devices), which is not always easy to collate together. Moreover, ASCII formatted tables are a nightmare to paste and convert into publication quality tables in a report. It is where views come in help. Views are HTML pages that include graphs, text and nicely formatted tables. Their primary goal is to provide insight on objects.
71
Comparing two different objects is as simple as looking at two views side-by-side. As a side effect, they are also nice chunks of results to feed your reports! Although the svViews package in the SciViews bundle comes with some predefined views, they should be considered as examples of what could be done. In fact, this feature is intended to be customized by the statistician to fit its particular requirements with its own favourite views. The basic mechanism is the same as for export. view is also a generic function, admitting different methods for different classes of objects. Its first argument can be an expression, but it will always be evaluated in the global environment. The list of all available views for a given object is obtained with type = "typelist":> library(svViews) > view(iris, type = "typelist") [1] "summary" "print" "twovars" "missing" "sascode"
> view(sum, type = "typelist") [1] "print" "methods"
view(x). Lets try the default view > view(iris)
Each object has a default view, so that one could always simply call on the iris data frame.
The view function could work jointly with an external application (the viewer). If such an external application is unavailable, the viewer will be displayed in the default web browser (see browser function). A dedicated viewer could add some functionality. The one provided within SciViews R Console displays tabs for all available views and allows direct inclusion of the current view in the report (see previous section). Further control of views parameters is another, planned, additional feature of the dedicated viewer. Below is an excerpt of the default view obtained with view(iris):
View of iris [summary]Sepal.Length Min. :4.300 1st Qu.:5.100 Median :5.800 Mean :5.843 3rd Qu.:6.400 Max. :7.900 Sepal.Width Min. :2.000 1st Qu.:2.800 Median :3.000 Mean :3.057 3rd Qu.:3.300 Max. :4.400 Petal.Length Min. :1.000 1st Qu.:1.600 Median :4.350 Mean :3.758 3rd Qu.:5.100 Max. :6.900 Petal.Width Min. :0.100 1st Qu.:0.300 Median :1.300 Mean :1.199 3rd Qu.:1.800 Max. :2.500 Species setosa :50 versicolor:50 virginica :50
72
Sepal.Length Numeric
Range: 4.3-7.9
Scatterplot is colorized according to factor: Species
Coming back to the list of available views for data frames, we could see that there is also a view called twovars. As this is not the default view, we have to precise the type in order to call it:> view(iris, type = "twovars")
73
This view presents graphs for all pairs of variable within the data frame and a correlation matrix with different colors according to correlations values.
74
Lets recall views are HTML pages. They rely also on so-called Cascading Style Sheets (CSS), which allow separating the content from the formatting. You can change the colours of this correlation matrix by editing the associated CSS file (in fact, you can even give colours only to the correlation up to 0.9, by example). In SciViews R Console, you switch to a different CSS file just by selecting a different entry in the Style dropdown list that appears in the View window. We show here the same correlation matrix, just using a different style:
clippaste functionMain usage syntax:clippaste("name", type = ,objclass = )
The export and copy functions allow both exporting objects to the clipboard. The function clippaste is complementary: it reads from the clipboard and creates an R object from its content. When using directly as the counterpart of copy, one should specify the type argument. In any other situations, the default value (ascii) should be suitable. The first argument is the name of the object to be created. A third argument allows controlling the class of the object to be created, as there is no way to know it from the clipboards content (except when its content is a raw R structure). [PhG: shouldnt the raw format be used as default here]> library(svIO) > copy(iris, type = "ascii") > clippaste("irisCP") > irisCP[1, 1] [1] 5.1
The main use of this function is to import quickly data from external application such as spreadsheets, without having to use intermediary files in suitable formats. Indeed, most applications propose to copy data in the clipboard and can then be retrieved with clippaste. [TO DO: a clippaste example from Excel!]
75
An import function is planned for the future, as the counterpart ofexport.
report functionreport in svViews, together with all guiXXX functions (not described here, see SciViews-Internals online help) in the svGUI package wont work without an external application. Its purpose is to append a suitable representation of an R object to a report edited in that external application. On Windows platform, SciViews-R proposes the SciViews R Report application to create reports in HTML format and rapidly publish them on the inter/intranet, or import it to Microsoft Word for further edition.
76
PART II: THE SCIVIEWS GUI API
77
5. CONCEPTION OF A CODE-CENTRED GUIIn this section, we will develop our vision of an efficient GUI for scientific computing software, that is a code-centred GUI that does not hide code, but instead, place it at the centre of the user interface and provides tools to help writing it. It is certainly not the only valid GUI, but it is one that proves to be efficient for several reasons: 1. It is didactic because the user learns how to write code. How a beginner in face of a GUI that hides code completely, or presents it as an internal complex thing, will acquire the skills to write good scripts and automate its analyses? It is also useful for teachers for a second reason: code traces work done by students. How will a teacher judge students analyses based on (sometimes truncated) outputs obtained after tens, or hundreds of mouse clicks that are lost for the eternity? It is flexible. Scripts and programs have proven to be an efficient and flexible way to run analyses. That is why experts prefer CLI (Command Line Interface). A well-designed code-centred GUI inherits this flexibility. On the contrary, other types of GUI, especially those based on menus and dialog boxes exclusively, are rather inflexible and constitute a major waste of time with interminable mouse-clicks!
2.
3.
Based on a few R GUI projects, like R Commander (http://socserv.socsci.mcmaster.ca/jfox/Misc/Rcmdr/index.html), JGR (Java GUI for R, pronounce jaguar, see http://stats.math.uniaugsburg.de/JGR/) or SciViews-R (http://www.sciviews.org/SciViewsR), we will sketch major features of a code-centred GUI as it progressively develops for R.
The console is still there but it is supported by a script editorAs being a code-centred GUI, the major element to interact with code, the console is still there and at the middle of the interface. However, despite powerful line editing and a history recalling feature, the console appears terribly limited: edition of one line at a time, no syntax highlighting or other forms of unattended help in writing the code. In the best case, we have just a different colour to separate input and output! If this console is supplemented with a simple script editor above or below it, it already gains some friendliness. Of course, being a GUI, there is also a menu and a toolbar to access frequently-used functions! Next figures present the appearance of this console-script editor that forms the main window of a code-centred GUI.
78
Figure 5-1: The main window of R Commander (version 0.9-12). The lower panel (1) collects inputs and outputs and is similar to a console, even if it is not editable, if it collects only outputs from R Commander itself and if the actual R console is not hidden (separate window). Above it (2), there is a simple script editor. No syntax highlighting, or other help like code completion or code tips, but the tendency is there: a script panel supplements a console! Finally, on top (3), there is a menu and a toolbar. In R Commander, menus are particularly rich and give access to many different dialog boxes to parameterize the analyses.
79
Figure 5-2: The main window of JGR (version DP3). It is also centred on a non-editable console (1), with the lower panel (2) being a multi-line code editor with syntax highlighting and code completion. In this case, however, this panel is not a true script editor: once a line is issued on the console, its content is cleared from this panel. Yet, the concept is very close. It should not be difficult to transform it into a real script editor (unless their programmers believe it is an unnecessary duplication of the separate script edition windows of JGR). On top, one finds the traditional menus and toolbar (3).
80
Figure 5-3: The main SciViews-R window (version 0.7-2). The console (1), which is editable here, is supported by a script editor, called a Command window. It permits the edition of one script at a time, with syntax colouring, step-by-step execution, code tips and code completion (like here, a code completion for iris list items). This panel also has its own little toolbar at left, in supplement to the main menu and toolbar(s) at top (3). The script editor can be docked at the bottom or at the top of the console. It can also be hidden or separated (in this case, it floats on top of the console window).
As these figures suggest it, there seems to be a convergence between these three different GUIs that ultimately propose a relatively similar organisation of their main window. The user still writes code, but it is supported in this (difficult) task by a richer command/script editor and various assisting tools. It is probably in tools like syntax highlighting, code tips or code completion, that edition of code in R acquires a new dimension, and becomes easier for the beginner. These tools should thus not be regarded as details or gadgets, but on the contrary, as the major features that differentiate a plain CLI from a code-centred GUI! Other tools that potentially enrich a code-centred GUI are presented hereunder.
Menus, toolbars and dialog boxesAs we have seen, menus and, at least, a simple toolbar are also part of the main windows of these three GUIs. In the case of R Commander, this menu calls different dialog boxes to parameterize analyses (the same dialog boxes are also accessible from SciViews-R, because the latest version of R Commander is now compatible with SciViews-R).
81
Figure 5-4: an example of an R Commander dialog box: the independent ttest.
The idea is simple: for beginners, a dialog
![MeV+R: using MeV as a graphical user interface for ... · SciViews [7]. However, these GUIs are not designed for microarray analysis. There are Bioconductor packages, such as limmaGUI](https://static.fdocuments.us/doc/165x107/5e88f79f947c700f7029aa19/mevr-using-mev-as-a-graphical-user-interface-for-sciviews-7-however-these.jpg)
