{smcl} {right:version 1.4.0} {title:Title} {phang} {cmd:{opt R:call}} {hline 2} seamless interactive {bf: {browse "https://cran.r-project.org/":R}} in Stata. The command automatically returns {help return:rclass} R objects with {it:integer}, {it:numeric}, {it:character}, {it:logical}, {it:matrix}, {it:data.frame}, {it:list}, and {it:NULL} classes to Stata. It also allows passing Stata variable, dataset, macro, scalar, and matrix to R as well as load a dataframe from R to Stata automatically, which provides an automated reciprocal communication between Stata and R. For more information and examples visit {browse "http://www.haghish.com/packages/Rcall.php":Rcall homepage}. {title:Syntax} {p 4 4 2} To call R from Stata use the following syntax {p 8 16 2} {opt R:call} [{help Rcall##modes:{it:mode}}] [{cmd::}] [{it:R-command}] {p_end} {p 4 4 2} the package also includes a few subcommands to facilitate integrating R in Stata {p 8 16 2} {opt R:call} [{help Rcall##subcommand:{it:subcommand}}] {p_end} {p 4 4 2} the following functions can be used to communicate data from Stata to R: {synoptset 22 tabbed}{...} {synopthdr:Function} {synoptline} {synopt:{opt st.scalar(name)}}passes a scalar to R{p_end} {synopt:{opt st.matrix(name)}}passes a matrix to R{p_end} {synopt:{opt st.var(varname)}}passes a numeric or string variable to R{p_end} {synopt:{opt st.data(filename)}}passes Stata data to R. without {it:filename}, the currently loaded data is used. {p_end} {synopt:{opt st.load(dataframe)}}loads data from R dataframe to Stata{p_end} {synoptline} {p2colreset}{...} {p 4 4 2} programmers can use {bf:Rcall_check} to evaluate the required version of R or R packages: {p 8 16 2} {browse "http://www.haghish.com/packages/Rcall.php#check":{bf:Rcall_check}} [{it:pkgname>=ver}] [{it:pkgname>=ver}] [...] , {opt r:version(ver)} {p_end} {marker modes}{...} {title:Modes} {p 4 4 2} The {it:mode} changes the behavior of the package and it can be {bf:vanilla} or {bf:sync}. When the {it:mode} is not specified, R is called interactively which is the default mode. Finally, when the [{it:R-command}] is not specified, the console mode will be executed which simulates R console within Stata results window for interactive use. In all of these modes, {bf:Rcall} returns {it:rclass} objects from R to Stata. These modes are summarized below: {* the new Stata help format of putting detail before generality}{...} {synoptset 22 tabbed}{...} {synopthdr:Mode} {synoptline} {synopt: {bf: {browse "http://www.haghish.com/packages/Rcall.php#vanilla_mode":vanilla}} }Calls R non-interactively. This mode is advised for programmers who wish to embed R in Stata packages{p_end} {synopt: {bf: {browse "http://www.haghish.com/packages/Rcall.php#sync_mode":sync}} }executes R interactively and synchronizes {it:matrices} and {it:scalars} between R and Stata. Making a change in any of these objects in either Stata or R will change the object in the other environment. {break} {p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#interactive_mode":interactive}}when the mode is not specified, R is called interactively which memorizes the actions, objects available in the R memory, the attached datasets, and the loaded packages. {p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#console_mode":console}}when the R command is not specified, R is called interactively and in addition, R console is simulated within the results windows of Stata. In the console mode users can type R commands directly in Stata and get the results back interactively. Similarly, the results are returned to Stata in the background and can be accessed in Stata when quiting the console mode. {p_end} {synoptline} {p2colreset}{...} {marker subcommand}{...} {title:Subcommands} {p 4 4 2} {bf:Rcall} allows a few subcommands which provide several features to facilitate working with the package interactivey. The subcommands are summarized in the table below: {* the new Stata help format of putting detail before generality}{...} {synoptset 22 tabbed}{...} {synopthdr:Subcommand} {synoptline} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#setpath_subcommand":setpath} {it:"path/to/R"}}permanently defines the path to executable R on the machine.{p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#clear_subcommand":clear}}erases the R memory and history in the interactive mode. {p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#describe_subcommand":describe}}returns the R version and paths to R, RProfile, and Rhistory {p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#history_subcommand":history}}opens {bf:Rhistory.do} in do-file editor which stores the history of the interactive R session. {p_end} {synopt: {browse "http://www.haghish.com/packages/Rcall.php#site_subcommand":site}}opens {bf:Rprofile.site} in do-file editor which is used for customizing R when is called from Stata. {p_end} {synoptline} {p2colreset}{...} {title:Description} {p 4 4 2} {bf: {browse "https://cran.r-project.org/":R statistical language}} is a free software and programming langage for statistical computing and graphics. The {opt R:call} package combines the power of R with Stata, allowing the Stata users to call R interactively within Stata and communicate data and analysis results between R and Stata simultaniously. {p 4 4 2} In other words, anytime an R code is executed, the R objects are available for further manipulation in Stata. R objects with {it:numeric}, {it:integer}, {it:character}, {it:logical}, {it:matrix}, {it:list}, and {it:NULL} classes are automatically returned to Stata as {help return:rclass}. {p 4 4 2} R objects with {it:data.frame} class can be automatically loaded from R to Stata using the {bf:st.load()} function (see below). {p 4 4 2} {bf:Rcall} uses the {bf:try} function to evaluate the R code and returns {bf:r(rc)} scalar which is an indicator for errors occuring in R. if {bf:r(rc)} equals zero, R has successfully executed the code. Otherwise, if {bf:r(rc)} equals one an error has occured and {bf:Rcall} will return the error message and break the execution. {title:Communication from R to Stata} {p 4 4 2} Stata automatically receives R objects as {help return:rclass} anytime the {opt R:call} is executed. If R is running interactively (i.e. without {bf:vanilla} subcommand), the previous objects still remain accessable to Stata, unless they are changed or erased from R. Moreover, the packages that you load from Stata in R remain loaded until you detach them. {p 4 4 2} Accessing R objects in Stata is simultanious which makes working with {opt R:call} convenient. For example a {it:numeric}, or {it:string} vector which is defined in R, can be accessed in Stata as simple as calling the name of that object withing {help rclass} i.e. {bf:r({it:objectname})}. {break} {p 4 4 2} A {it:numeric} object example: . R: a <- 100 . display r(a) 100 {p 4 4 2} Without the {bf:vanilla} subcommand, the defined object remains in the memory of R and consequently, returned to Stata anytime R is called. . R: a [1] 100 {p 4 4 2} A {it:string} object example: . R: str <- "Hello World" . display r(str) Hello World . R: str <- c("Hello", "World") . display r(str) "Hello" "World" {p 4 4 2} A {it:vector} example: . R: v <- c(1,2,3,4,5) . display r(v) 1 2 3 4 5 {p 4 4 2} A {it:matrix} example: . R: A = matrix(1:6, nrow=2, byrow = TRUE) . mat list r(A) r(A)[2,3] c1 c2 c3 r1 1 2 3 r2 4 5 6 {p 4 4 2} A {it:list} example: . R: mylist <- list(a=c(1:10)) . display r(mylist_a) 1 2 3 4 5 6 7 8 9 10 {p 4 4 2} A {it:logical} example: . R: l <- T . display r(l) TRUE {p 4 4 2} A {it:NULL} example: . R: n <- NULL . display r(n) NULL {p 4 4 2} Regarding communicating R data set to Stata automatically, see the {bf:st.load({it:dataframe})} function below. {title:Communication from Stata to R} {p 4 4 2} For an ideal reciprocation between Stata and R, Stata should also easily communicate variables to R. Local and global {help macro:macros} can be passed within R code, since Stata automatically interprets them while it passes the code to {opt R:call} command, as shown in the example below: . global a 99 . R: (a <- $a) [1] 99 {p 4 4 2} In order to pass a {help scalar} from Stata to R, you can use the {bf:st.scalar()} function as shown below: . scalar a = 50 . R: (a <- st.scalar(a)) [1] 50 {p 4 4 2} Similarly, Stata {help matrix:matrices} can be seamlessly passed to R using the {bf:st.matrix()} function as shown below: . matrix A = (1,2\3,4) . matrix B = (96,96\96,96) . R: C <- st.matrix(A) + st.matrix(B) . R: C [,1] [,2] [1,] 97 98 [2,] 99 100 {p 4 4 2} And of course, you can access the matrix from R in Stata as well: . mat list r(C) r(C)[2,2] c1 c2 r1 97 98 r2 99 100 {p 4 4 2} Passing variables from Stata to R is convenient, using the {bf:st.var({it:varname})} function. Therefore, any analysis can be executed in R simply by passing the variables required for the analysis from Stata to R: . sysuse auto, clear . R: dep <- st.var(price) . R: pre <- st.var(mpg) . R: lm(dep~pre) Call: lm(formula = dep ~ pre) Coefficients: (Intercept) pre 11267.3 -238.3 {p 4 4 2} The {opt R:call} package also allows to pass Stata data to R within {bf:st.data({it:{help filename}})} function. This function relies on the {bf:readstata13} package in R to load Stata data sets, without converting them to CSV or alike. The {bf:readstata13} package {browse "http://www.haghish.com/stata-blog/?p=21":is faster and more acurate then {bf:foreign} and {bf:haven} packages} and read Stata 13 and 14 datasets. This R package can be installed within Stata as follows: . R: install.packages("readstata13", repos="http://cran.uk.r-project.org") {p 4 4 2} Specify the relative or absolute path to the data set to transporting data from Stata to R. For example: . R: data <- st.data(/Applications/Stata/ado/base/a/auto.dta) . R: dim(data) {p 4 4 2} If the {it:filename} is not specified, the function passes the currently loaded data to R. . sysuse auto, clear . R: data <- st.data() . R: dim(data) [1] 74 12 {p 4 4 2} Finally, the data can be imported from R to Stata automatically, using the {bf:st.load({it:dataframe})} function. This function will automatically save a Stata data set from R and load it in Stata by clearing the current data set, if there is any. Naturally, you can have more control over converting variable types if you write a proper code in R for exporting Stata data sets. Nevertheless, the function should work just fine in most occasions: . clear . R: st.load(cars) . list in 1/2 {c TLC}{hline 14}{c TRC} {c |} speed dist {c |} {c LT}{hline 14}{c RT} 1. {c |} 4 2 {c |} 2. {c |} 4 10 {c |} {c BLC}{hline 14}{c BRC} {title:Remarks} {p 4 4 2} You should be careful with using Stata symbols in R. For example, the {bf:$} sign in Stata is preserved for global macros. To use this sign in R, you should place a backslash before it to pass it to R. For example: . R: head(cars\$speed) {p 4 4 2} Also, the object name in R can include a dot, for example: . R: a.name <- "anything" {p 4 4 2} The {opt R:call} package returns scalars and locals which can only include underscore in the names (e.g. a_name). {opt R:call} automatically converts dots to underscore in the name. In the example above, if you type {cmd:return list} in Stata, you would get a macro as follos: . return list r(a_name) : "anything" {p 4 4 2} To maximize the speed of calling R from Stata, detach the packages that are no longer needed and also, drop all the objects that are of no use for you. The more objects you keep in R memory, the more time needed to automatically communicate those objects between R and Stata. {title:Example} {p 4 4 2} Visit {browse "http://www.haghish.com/packages/Rcall.php":Rcall homepage} for more examples and documentation. {title:Author} {p 4 4 2} {bf:E. F. Haghish} {break} Center for Medical Biometry and Medical Informatics {break} University of Freiburg, Germany {break} {it:and} {break} Department of Mathematics and Computer Science {break} University of Southern Denmark {break} haghish@imbi.uni-freiburg.de {break} {p 4 4 2} {browse "www.haghish.com/packages/Rcall.php":Rcall Homepage} {break} Package Updates on {browse "http://www.twitter.com/Haghish":Twitter} {break} {hline} {p 4 4 2} This help file was dynamically produced by {help markdoc:MarkDoc Literate Programming package}