-------------------------------------------------------------------------------
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