help for importr

Import R data files into Stata via R or Python

importr
using filename
[, clear rds]

Description

importr (v2.0.2) imports R data files (.Rdata, .Rda, .Rds) into Stata.
R stores these as compressed binary objects in its own serialization format,
so something outside Stata has to do the decoding. importr can use
either of two external routes, so it works on machines with R and on machines
without it.

How it Works

importr tries each bridge in turn and keeps whichever one actually
returns a dataset. It reports the bridge that succeeded, so you always know
which route ran.

1. R bridge: writes a short R script and runs it with Rscript,
converting the file through the haven package.

2. Python bridge: if the R bridge does not produce a dataset,
importr falls back to Stata's python integration, reading the
file with pyreadr and writing the .dta with pyreadstat.

Note on R factors. The two bridges do not encode factors identically.
The R bridge returns a factor as a numeric variable carrying a Stata value
label; the Python bridge returns it as a string variable. Everything else
(integers, doubles, logicals, character) lands the same way either route.
If your do-file depends on a factor's storage type, check it after import
rather than assuming.

Requirements

Stata 16 or newer, plus one of the following.

For the R bridge:

- R installed, with Rscript on the PATH that Stata sees.

- R package haven.

For the Python bridge:

- Stata's Python integration configured (python query).

- Python libraries pyreadr and pyreadstat.

- Install with: python pip install pyreadr pyreadstat

If R is installed but importr does not find it, the usual cause is that
Rscript is not on the PATH Stata inherits, which need not match the PATH
in your terminal. On macOS an R installed under
/Library/Frameworks/R.framework is a common example.

Files that ship with the package

Two small example R files ship with the package,
importr_example.rdata and importr_example.rds, so the examples
below are runnable. They are ancillary files, which ssc install importr
does not copy, so fetch them with net get importr.

For conversion work outside Stata, the source repository also carries two
standalone Python utilities, RtoStata.py and pythontoR.py, for
bi-directional conversion between R and Stata formats:
https://github.com/ericabooth/importR-stata.

Options

clear clears any data currently in Stata's memory before importing.

rds specifies that the source file is an RDS file. Usually detected
automatically.

Stored results

importr stores the following in r():

r(nobs) number of observations imported

r(nvars) number of variables imported

r(filename) the file that was read

Examples

The package ships a small example file. Retrieve the ancillary files first
with net get importr, then run these from the same folder.

Import an R workspace file (tries R first, then Python):

. importr using "importr_example.rdata", clear

. describe

. list

Import an RDS file:

. importr using "importr_example.rds", clear

. summarize revenue

Check what was read, without looking at the data:

. importr using "importr_example.rdata", clear

. display r(nobs) " obs, " r(nvars) " vars from " r(filename)

A file that is not there is reported as such, with return code 601, rather
than as a bridge or library failure:

. importr using "nosuch.Rdata", clear

Author

Eric A. Booth

eric.a.booth@gmail.com

http://www.eric-booth.com

Also see

On-line: help for import, python, shell