RXGENSTAT procedure

Submits a set of commands externally to R and reads the output (M.F. D’Antuono & D.A. Murray).

Options

PRINT = string tokens	Controls printed output (summary, output); default outp
RPATH = text	Path specifying the location of the R executable
REXE = text	Name of the R executable to run; default 'Rterm.exe'
RARGS = text	Command line arguments to be used with the R executable; default '--no-restore --no-save'
SCRIPT = text	A set of R commands to run within R
SFILE = text	A file containing a set of R commands to run within R
RGEN = text	Name of a file to save the full set of commands used within R
ROUT = text	Name of a file to save the output from R

Parameters

WORKDIRECTORY = texts	Working directory to use within R; default current Genstat working directory
IDATA = pointers	Pointer to data structures to export to R (the data are exported into the file specified by the IRDAFILE parameter)
IRDAFILE = texts	Name of an R data (rda) file to import into R
ISAVE = texts	Pointer to data structures to import from R (the data are imported from the file specified by the ORDAFILE parameter)
ORDAFILE = text	Name of an R data (rda) file used to export data from R

Description

RXGENSTAT allows a set of commands to be submitted externally to R and can read output generated from the run. To use RXGENSTAT, the R software must be installed on the current system. The R executable used when submitting a script is specified using the REXE option, by default this uses the R for Windows terminal front-end executable (Rterm.exe). The location of the R executable (usually the bin directory of the R installation) used to run the R script should be specified using the RPATH option. The directory for the path should be specified as a text containing the absolute pathname, for example in Windows the default directory for the executables for R version 2.3 would be

C:/Program Files/R/R-2.3.1/bin

Additional command line arguments to be used when submitting commands can be supplied using the RARGS option, by default '--no-restore --no-save'.

Data can be exported from Genstat to R by supplying a pointer to the data structures using the IDATA parameter. The data structures can either be factors, variates and texts of equal length, scalars, or a matrix. RXGENSTAT saves the data to an R data (rda) file using the EXPORT procedure and then the data can be accessed within the R script in the usual way. For example, data from a file called idata.rda could be accessed as idata$x etc. The name of the R data file should be supplied using the IRDAFILE parameter. Data can be imported back into Genstat by saving data within R into a rda file and then specifying the name of this R data file in Genstat using the ORDAFILE parameter. The ISAVE parameter can also be used to save a pointer to the imported data structures. A set of R commands can either be supplied within a text using the SCRIPT option or within an R script file (.r) using the SFILE option.

To execute commands within R, RXGENSTAT creates an R script file (.r) that contains the commands for setting the working directory, loading any data and running additional R commands (supplied using the SCRIPT or SFILE option). This file can be saved using the RGEN option. The output generated by R can also be saved using the ROUT option. By default, the working directory will be the current directory, however, an alternative directory can be supplied using the WORKDIRECTORY parameter.

The PRINT option controls printed output, with the settings:

summary	to print a summary of any data that are imported, and
output	to print the R output.

Options: PRINT, RPATH, REXE, RARGS, SCRIPT, SFILE, RGEN, ROUT.

Parameters: WORKDIRECTORY, IDATA, IRDAFILE, ISAVE, ORDAFILE.

Method

In Windows the commands are submitted to R by creating a bat file containing a command line and then executing this within a windows command processor.

Action with RESTRICT

Any data restrictions will be ignored.

See also

Directive: SUSPEND.

Procedure: A2RDA, BGXGENSTAT.

Commands for: Program control.

Example

CAPTION   'RXGENSTAT Example'; style=meta
VARIATE   [VALUES=1,2,3,4,5,6,7,8,9,10] y
POINTER   [VALUES=y] pdata
TEXT      rscript; VALUES=\
          !t('res<-idata$y^2','save(res,file=""mydata.rda"")')
" The R output is suppressed below, by the option setting PRINT=*;
  to see the output, set PRINT=output instead. "
RXGENSTAT [PRINT=*; SCRIPT=rscript]\ 
          IDATA=pdata; IRDAFILE='idata.rda';\ 
          ORDA='mydata.rda'; ISAVE=newp
PRINT     newp[]