-------------------------------------------------------------------------------
help for rsource                                                 (Roger Newson)
-------------------------------------------------------------------------------

Run R from inside Stata using an R source file

rsource using R_source_filename [ , noloutput lsource rpath(R_pathname) roptions(R_options) ]

where R_source_filename is the name of a file containing R source code, R_pathname is the name of the path of the R command to be used under the user's system, and R_options is a set of options for the R command.

Description

rsource runs an R source file in batch mode from within Stata, optionally listing the R output and/or the R source file to the Stata Results window and/or the Stata log file. This allows the user to call R at a point in the execution of a Stata program to input data files previously created by Stata and/or to create output data files for later input by Stata. The R software system must be installed on the user's system if the rsource package is to work.

Options for use with rsource

noloutput specifies that the output from the R command is not listed to the Stata Results window and/or the Stata log file. If noloutput is not specified, then the output from the R command is listed.

lsource specifies that the R source file specified by the using modifier is listed to the Stata Results window and/or the Stata log file. If lsource() is specified and noloutput is not specified, then the R source file is listed before the output from the R command.

rpath(R_pathname) specifies a path name for invoking the R command. If rpath() is not specified, then it is set to the value of the global macro Rterm_path, if that macro has been specified, and to "Rterm.exe" otherwise. (See Technical note below.)

roptions(R_options) specifies a set of options for the R command. If roptions() is not specified, then it is set to the value of the global macro Rterm_options, if that macro has been specified, and to the empty string "" otherwise. (See Technical note below.)

Remarks

The R statistical software system can be downloaded from the R Project Website. It is complementary to Stata in its capabilities, as it contains implementations of many methods unavailable in Stata, but does not have as many easy-to-use data management tools as Stata. It may therefore be useful to be able to call R in batch mode from within a Stata do-file. R can read Stata dataset files using the read.dta and write.dta modules of the foreign package. Alternatively, it is possible to translate between Stata and R datasets using Version 9 of Stat/Transfer, which can be accessed from within Stata using the stcmd package, downloadable from SSC. For more about import and export of data to and from R, refer to R Data Import/Export (see References)

Technical note

rsource works by running the Rterm.exe program of R. The assumed R program path is displayed by rsource before any other output, and is the assumed name and address of the R program run by rsource. If the user does not specify the rpath() and roptions() options, then rsource sets defaults. In the case of rpath(), the default is the value of the global macro Rterm_path, if that macro has been specified, and otherwise is "Rterm.exe" if the operating system is Windows and "/usr/bin/r" otherwise. In the case of roptions(), the default is the value of the global macro Rterm_options, if that macro has been specified, and is the empty string "" otherwise. Therefore, the user should either set the system default file search path to include the directory containing the current version of R, or set the global macros Rterm_path and Rterm_options to sensible default values before using rsource.

The setting of default values for Rterm_path and Rterm_options is probably done most easily by inserting two lines into the user's Stata profile do-file to initialize these global macros every time the user starts Stata. For instance, under Windows, if the user's profile do-file contains the lines

. global Rterm_path `"c:\r\R-2.5.0\bin\Rterm.exe"' . global Rterm_options `"--vanilla"'

and the Rterm.exe program of R, in the user's system, has path c:\r\R-2.5.0\bin\Rterm.exe, then the user does not need to specify the rpath() and roptions() options of rsource, because the R path is then set to its correct value, and the R options are set to the sensible default value --vanilla. Other possible R options, which can be set using roptions(), are listed in Appendix B of An Introduction to R (see References).

Note that, when the user downloads a new version of R, the installation process creates a new directory, containing the new version of Rterm.exe. Therefore, when R is upgraded, the user should either change the system default file search path, or change the line of code in the profile do-file setting the global macro Rterm_path.

Examples

. rsource using nitz2.R

. rsource using nitz2.R, lsource

. rsource using nitz2.R, noloutput roptions(--slave)

Author

Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk

References

Venables W. N., D. M. Smith, and the R Development Core Team. An Introduction to R. Downloadable from the R Project Website.

The R Development Core Team. R Data Import/Export. Downloadable from the R Project Website.

Also see

Manual: [GSW] C.3 Executing commands every time Stata is started, [GSM] C.1 Executing commands every time Stata is started, [GSU] C.1 Executing commands every time Stata is started On-line: help for profile, profilew, profilem, profileu help for stcmd if installed