PypeR

					
		              PypeR (PYthon-piPE-R)

PypeR is free software subjected to the GPL license 3.0. and comes with
ABSOLUTELY NO WARRANT. 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. 

Please refer to http://bioinfo.ihb.ac.cn/softwares/PypeR/ for bug fixes.

******************************************************************************

Requirements:
	Python 2.3 or later. 
	PypeR can run with different Python implementations: 
		Python 2.X.X
		Python 3.X.X
		Jython
		IronPython

******************************************************************************

For installation:
	# python setup.py install
	  or
	# easy_install PypeR
	  or
	# pip install PypeR

To upgrade to the newest version:
	# python setup.py install
	  or
	# easy_install --upgrade PypeR
	  or
	# pip install --upgrade PypeR

******************************************************************************

Known issues:
	1. Problem: cannot run with IronPython on mono.
	   Platform: tested on Ubuntu-10.04, mono 2.4.4, IronPython 2.6 Beta 2
		   DEBUG (2.6.0.20) on .NET 2.0.50727.1433
	   Behavior: report "TypeError: Cannot cast from source type to desination type."
	   Reason: This happens when call a function found in the dict "str_func",
		   e.g. "str_func[type(obj)](obj)".  Most likely it is caused by a bug
		   of IronPython (or mono?). 
	   Solution: It is possible to use IF...ELIF...ESLE to replace the dict
		   "str_func". However it will make the function "Str4R" much longer
		   than it is now.

******************************************************************************

For Help:
	Please see the documents of the module, class, and methods

For example:
	The script "test.py" covers all the typical uses of PypeR

Citation:
	@article{Xia:McClelland:Wang:2010:JSSOBK:v35c02,
	  author =	"Xiao-Qin Xia and Michael McClelland and Yipeng Wang",
	  title =	"PypeR, A Python Package for Using R in Python",
	  journal =	"Journal of Statistical Software, Code Snippets",
	  volume =	"35",
	  number =	"2",
	  pages =	"1--8",
	  day =  	"30",
	  month =	"7",
	  year = 	"2010",
	  CODEN =	"JSSOBK",
	  ISSN = 	"1548-7660",
	  bibdate =	"2010-03-23",
	  URL =  	"http://www.jstatsoft.org/v35/c02",
	  accepted =	"2010-03-23",
	  acknowledgement = "",
	  keywords =	"",
	  submitted =	"2009-10-23",
	}


******************************************************************************

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.

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

    2. Call the instance as a function
        The instance is callable. If called as a function, it behaves just
        same as its "run" method.

    3. 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".

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

******************************************************************************

FAQs:

1.	Q: I got error message when trying to use PypeR:
		>>> from pyper import *
		>>> r = R()

		Traceback (most recent call last):
		......
		"WindowsError: [Error 2] The system cannot find the file specified"
		>>>

	A: Usually this means PypeR cannot find the R program on Windows. There is
		two ways to tell PypeR where R is. E.g., R is installed at 
		"C:\Program Files\R\R-2.11.1".

		method 1 - initialize R with full path:
			>>>  r = R(RCMD="C:\\Program Files\\R\\R-2.11.1\\bin\\R")

		method 2 - add "C:\\Program Files\\R\\R-2.11.1\\bin" into the PATH
			environmental variable:

			(1) Right click "My Computer" on Windows XP (or "Computer" on
				Windows 7), either on your desktop or in your start menu.
			(2) Click "Properties"
			(3) In Windows 7, click "Advanced System Settings" on the left.
			(4) In the "Advanced" tab, click the "Environment Variables" button.
			(5) Double-click the PATH variable, and add your R path to the list.
				Entries are separated by semicolons.  For example:
				%WinDir%\System32;C:\Program Files\R\R-2.11.1\bin

2.	Q: What is the differences between r("myvar"), r["myvar"], r.myvar,
		r.get("myvar", "a wild value"), and r.assign("myvar", "a new value")?

	A: These forms serve for different purpose:
		(1) r("myvar")
			Here "myvar" is a R variable name or a complex R expression. This
			equals to type myvar on the R terminal. The information displayed
			on the terminal will be returned as a Python string.

		(2) r["myvar"] 
			This form can be used to get values from R, or set value for a R
			variable. 

			If it is used to get value from R, "myvar" can be a R variable name
			or a complex R expression, and this will return the value of
			"myvar" instead of the output on STDOUT. 

			To set value for the R variable, the form is:
				r["myvar"] = "something"
			here "myvar" should be valid R variable name.

		(3) r.myvar
			This form is similar to r["myvar"], but diffs in two aspects:
			a) myvar have to following Python's name convention too.
			b) IMPORTANT: if myvar is a attribute of the python object r, it
				will override (shield) the variable myvar in R!

		(4) r.get("myvar", "a wild value")
			This form is similar to r["myvar"], but it can only be used to get
			values from R. If there is no variable "myvar" in R, the value "a
			wild value" will be returned

		(5) r.assign("myvar", "a new value") 
			This form is used to assign value ("a new value") to a R variable
			("myvar"). Here "myvar" should be a valid R variable name.

3.	Q: How can I get a named list in R returned as a dict, - just as been done
		in RPy?

	A: Due to named R list allows replicated names, while Python dictionary
		does not, conversion of R named list to Python dictionary may lead to
		lost of data. That is why PypeR return a list of tuples (name, value)
		for R named list. However it is possible to get dictionary returned
		since PypeR 1.0.2:
			method 1:
				>>> r.get("myvar", use_dict=True)
			method 2:
				>>> r.use_dict = True
				>>> r.myvar
		If this failed, please update your PypeR with the newest version.