emzed.r_connect.pyper module¶
This module is based on version 1.1.1 of
PypeR (PYthon-piPE-R)
This package provides a light-weight interface to use R in Python by pipe. It can be used on multiple platforms since it is written in pure python.
- Prerequisites:
Python 2.3 or later is required.
- Usage:
The usage of this packages is very simple. Examples are presented in the file “test.py” in the distribution package.
PypeR provide a class “R” to wrap the R language. An instance of the R class is used to manage an R process. Different instances can use different R installations. On POSIX systems (including the Cygwin environment on Windows), it is even possible to use an R installed on a remote computer.
Basicly, there are four ways to use an instance of the R class.
- Use the methods of the instance
- methods include:
- run:This method is used to pass an R command string to the R process,
the return value is a string - the standard output from R. Note that the return value usually includes the R expression (a series of R codes) themselves and the output of the R expression. If the real result value is wanted, use the function “get” instead.
assign: Assign a value to an R variable. No return value. get: Get the result of an R expression. remove: Remove a R variable.
- Call the instance as a function
The instance is callable. If called as a function, it behaves just same as its “run” method.
- Use the instance as a Python dictionary
The instance can mimic some operations on a python dictionary, typically, to assign values to R variables, to retrieve values for any R expression, or delete an R variable. These two operations do same jobs as the methods “assign”, “get”, and “remove”.
- Access R variables as if they are the attributes of the instance.
If the variable name cannot be found in the instance or its class, the instance will try to get/set/remove it in R. This way is similar to 3, but with more limitations, e.g., the R variable name cannot contain any DOT (.)
Considering that any code block in R is an expression, the “get” method (or the form of retrieving values from a dictionary) can be used to run a number of R commands with the final result returned.
Note that PypeR do NOT validate/convert a variable name when pass it to R. If a variable name with a leading underscore (“_”), although it legal in python, is passed to R, an RError will be raised.
- Conversions:
- Python -> R
None -> NULL, NaN -> NaN, Inf -> Inf
- R -> Python (numpy)
NULL -> None, NA -> None, NaN -> None (NaN), Inf -> None (Inf)
- DEBUG model:
Since the child process (R) can be easily killed by any ocassional error in the codes passed to it, PypeR is set to “DEBUG” model by default. This means that any code blocks send to R will be wrapped in the function “try()”, which will prevent R from crashing. To disable the “DEBUG” model, the user can simple set the variable “_DEBUG_MODE” in the R class or in its instance to False.
To model the behavior of the “get” method of a Python dictionary, the method “get” allows wild values for variables that does not exists in R. Then the R expression will always be wrapped in “try()” to avoid R crashing if the method “get” is called.
- class emzed.r_connect.pyper.R(RCMD='R', max_len=1000, use_numpy=True, use_pandas=True, use_dict=None, host='localhost', user=None, ssh='ssh', return_err=True)[source]¶
Bases:
objectA Python class to enclose an R process.
- assign(obj, val)¶
Assign a value (val) to an R variable (obj).
obj: a string - the name of an R variable val: a python object - the value to be passed to an R object
- get(obj, default=None, use_dict=None)[source]¶
obj: a string - the name of an R variable, or an R expression default: a python object - the value to be returned if failed to get data from R use_dict: named list will be returned a dict if use_dict is True,
otherwise it will be a list of tuples (name, value). If use_dict is None, the value of self.use_dict will be used instead.
- remove(obj)¶
- run(CMDS=[], use_try=None)¶
Run a (list of) R command(s), and return the output message from the STDOUT of R.
CMDS: an R command string or a list of R commands
- emzed.r_connect.pyper.Str4R(obj)[source]¶
convert a Python basic object into an R object in the form of string.
- emzed.r_connect.pyper.runR(CMDS, Robj='R', max_len=1000, use_numpy=True, use_pandas=True, use_dict=None, host='localhost', user=None, ssh='ssh')[source]¶
Run a (list of) R command(s), and return the output from the STDOUT.
CMDS: a R command string or a list of R commands. Robj: can be a shell command (like /usr/bin/R), or the R class. max_len: define the upper limitation for the length of command string. A
command string will be passed to R by a temporary file if it is longer than this value.
- use_numpy: Used as a boolean value. A False value will disable numpy even
if it has been imported.
- use_pandas: Used as a boolean value. A False value will disable pandas even
if it has been imported.
- use_dict: named list will be returned a dict if use_dict is True, otherwise
it will be a list of tuples (name, value).
- host: The computer name (or IP) on which the R interpreter is
installed. The value “localhost” means that the R locates on the the localhost computer. On POSIX systems (including Cygwin environment on Windows), it is possible to use R on a remote computer if the command “ssh” works. To do that, the user need set this value, and perhaps the parameter “user”.
- user: The user name on the remote computer. This value need to be set
only if the user name is different on the remote computer. In interactive environment, the password can be input by the user if prompted. If running in a program, the user need to be able to login without typing password!
ssh: The program to login to remote computer.