help rscript

Title

rscript -- Call an R script from Stata.

Syntax

rscript using filename.R, [rpath(pathname) args(stringlist)
rversion(# [#]) require(stringlist) async force]

where

pathname specifies the location of the R executable, and

stringlist is a list of quoted strings.

The R executable can be specified by rpath() or by the global macro RSCRIPT_PATH.
Otherwise, rscript will search for the R executable on its own.

Description

rscript calls filename.R from Stata. It displays the R output (and errors, if applicable) in the Stata console.

Options

rpath(pathname) specifies the location of the R executable.
If not specified, rscript will use the location specified by the global macro RSCRIPT_PATH.
If rpath() is not specified and RSCRIPT_PATH is undefined, then rscript will search for the R executable on its own.

args(stringlist) specifies arguments to pass along to R.

rversion(# [#]) instructs script to break if the R version is less than #. You can also optionally provide a second #, which generates a break if the R version is greater than #.

require(stringlist) specifies a list of required R packages and generates a break if any are missing from the user's default library.

async instructs rscript to run filename.R in the background. rscript will immediately exit after beginning the script.
It will not wait for the script to finish and will not display any R output or errors in the Stata console.

force instructs rscript not to break when filename.R generates an error during execution.

Notes

rscript has been tested on Windows, Mac OS X, and Unix (tcsh shell).

The async option can be used to launch a large number of jobs at the same time, all running in parallel.

The options rversion() and require() can be used without specifying using filename.R.
For example, to ensure that the R installation is version 3.6 or higher, type:

. rscript, rversion(3.6)

Stored results

rscript stores the following in r():

Macros

r(path) location of the R executable

Examples

1. Call an R script using the default location specified by RSCRIPT_PATH and pass along the names of an input file and output file.

. global RSCRIPT_PATH "/usr/local/bin/Rscript"
. rscript using my_script.R, args("input_file.txt" "output_file.txt")

2. Same as Example 1, but specify the location of your R executable using the rpath() option.

. rscript using my_script.R, rpath("/usr/local/bin/Rscript") args("input_file.txt" "output_file.txt")

3. Same as Example 1, but generate a break if the user's R version is less than 4.0.1 or does not include the 'tidyverse' package.

. rscript using my_script.R, args("input_file.txt" "output_file.txt") rversion(4.0.1) require(tidyverse)

Authors

David Molitor, University of Illinois

dmolitor@illinois.edu

Julian Reif, University of Illinois

jreif@illinois.edu

Also see

rsource (if installed), rcall (if installed)