### Navigation

- index
- modules |
- next |
- previous |
- Interpreter Interfaces »

# Interface to R

The following examples try to follow “An Introduction to R” which can be found at http://cran.r-project.org/doc/manuals/R-intro.html .

EXAMPLES:

Simple manipulations; numbers and vectors

The simplest data structure in R is the numeric vector which consists of an ordered collection of numbers. To create a vector named \(x\) using the R interface in Sage, you pass the R interpreter object a list or tuple of numbers:

    sage: x = r([10.4,5.6,3.1,6.4,21.7]); x
    [1] 10.4  5.6  3.1  6.4 21.7

You can invert elements of a vector x in R by using the invert operator or by doing 1/x:

    sage: ~x
    [1] 0.09615385 0.17857143 0.32258065 0.15625000 0.04608295
    sage: 1/x
    [1] 0.09615385 0.17857143 0.32258065 0.15625000 0.04608295

The following assignment creates a vector \(y\) with 11 entries which consists of two copies of \(x\) with a 0 in between:

    sage: y = r([x,0,x]); y
    [1] 10.4  5.6  3.1  6.4 21.7  0.0 10.4  5.6  3.1  6.4 21.7

Vector Arithmetic

The following command generates a new vector \(v\) of length 11 constructed by adding together (element by element) \(2x\) repeated 2.2 times, \(y\) repeated just once, and 1 repeated 11 times:

    sage: v = 2*x+y+1; v
    [1] 32.2 17.8 10.3 20.2 66.1 21.8 22.6 12.8 16.9 50.8 43.5

One can compute the sum of the elements of an R vector in the following two ways:

    sage: sum(x)
    [1] 47.2
    sage: x.sum()
    [1] 47.2

One can calculate the sample variance of a list of numbers:

    sage: ((x-x.mean())^2/(x.length()-1)).sum()
    [1] 53.853
    sage: x.var()
    [1] 53.853

    sage: x.sort()
    [1] 3.1  5.6  6.4 10.4 21.7
    sage: x.min()
    [1] 3.1
    sage: x.max()
    [1] 21.7
    sage: x
    [1] 10.4  5.6  3.1  6.4 21.7

    sage: r(-17).sqrt()
    [1] NaN
    sage: r('-17+0i').sqrt()
    [1] 0+4.123106i

Generating an arithmetic sequence:

    sage: r('1:10')
    [1] 1  2  3  4  5  6  7  8  9 10

Because `from` is a keyword in Python, it can’t be used as a keyword argument. Instead, `from_` can be passed, and R will recognize it as the correct thing:

    sage: r.seq(length=10, from_=-1, by=.2)
    [1] -1.0 -0.8 -0.6 -0.4 -0.2  0.0  0.2  0.4  0.6  0.8

    sage: x = r([10.4,5.6,3.1,6.4,21.7]);
    sage: x.rep(2)
    [1] 10.4  5.6  3.1  6.4 21.7 10.4  5.6  3.1  6.4 21.7
    sage: x.rep(times=2)
    [1] 10.4  5.6  3.1  6.4 21.7 10.4  5.6  3.1  6.4 21.7
    sage: x.rep(each=2)
    [1] 10.4 10.4  5.6  5.6  3.1  3.1  6.4  6.4 21.7 21.7

Missing Values:

    sage: na = r('NA')
    sage: z = r([1,2,3,na])
    sage: z
    [1]  1  2  3 NA
    sage: ind = r.is_na(z)
    sage: ind
    [1] FALSE FALSE FALSE  TRUE
    sage: zero = r(0)
    sage: zero / zero
    [1] NaN
    sage: inf = r('Inf')
    sage: inf-inf
    [1] NaN
    sage: r.is_na(inf)
    [1] FALSE
    sage: r.is_na(inf-inf)
    [1] TRUE
    sage: r.is_na(zero/zero)
    [1] TRUE
    sage: r.is_na(na)
    [1] TRUE
    sage: r.is_nan(inf-inf)
    [1] TRUE
    sage: r.is_nan(zero/zero)
    [1] TRUE
    sage: r.is_nan(na)
    [1] FALSE

Character Vectors:

    sage: labs = r.paste('c("X","Y")', '1:10', sep='""'); labs
    [1] "X1"  "Y2"  "X3"  "Y4"  "X5"  "Y6"  "X7"  "Y8"  "X9"  "Y10"

Index vectors; selecting and modifying subsets of a data set:

    sage: na = r('NA')
    sage: x = r([10.4,5.6,3.1,6.4,21.7,na]); x
    [1] 10.4  5.6  3.1  6.4 21.7   NA
    sage: x['!is.na(self)']
    [1] 10.4  5.6  3.1  6.4 21.7

    sage: x = r([10.4,5.6,3.1,6.4,21.7,na]); x
    [1] 10.4  5.6  3.1  6.4 21.7   NA
    sage: (x+1)['(!is.na(self)) & self>0']
    [1] 11.4  6.6  4.1  7.4 22.7
    sage: x = r([10.4,-2,3.1,-0.5,21.7,na]); x
    [1] 10.4 -2.0  3.1 -0.5 21.7   NA
    sage: (x+1)['(!is.na(self)) & self>0']
    [1] 11.4  4.1  0.5 22.7

Distributions:

    sage: r.options(width="60");
    $width
    [1] 100

    sage: rr = r.dnorm(r.seq(-3,3,0.1))
    sage: rr
     [1] 0.004431848 0.005952532 0.007915452 0.010420935
     [5] 0.013582969 0.017528300 0.022394530 0.028327038
     [9] 0.035474593 0.043983596 0.053990967 0.065615815
    [13] 0.078950158 0.094049077 0.110920835 0.129517596
    [17] 0.149727466 0.171368592 0.194186055 0.217852177
    [21] 0.241970725 0.266085250 0.289691553 0.312253933
    [25] 0.333224603 0.352065327 0.368270140 0.381387815
    [29] 0.391042694 0.396952547 0.398942280 0.396952547
    [33] 0.391042694 0.381387815 0.368270140 0.352065327
    [37] 0.333224603 0.312253933 0.289691553 0.266085250
    [41] 0.241970725 0.217852177 0.194186055 0.171368592
    [45] 0.149727466 0.129517596 0.110920835 0.094049077
    [49] 0.078950158 0.065615815 0.053990967 0.043983596
    [53] 0.035474593 0.028327038 0.022394530 0.017528300
    [57] 0.013582969 0.010420935 0.007915452 0.005952532
    [61] 0.004431848

Convert R Data Structures to Python/Sage:

    sage: rr = r.dnorm(r.seq(-3,3,0.1))
    sage: sum(rr._sage_())
    9.9772125168981...

Or you get a dictionary to be able to access all the information:

    sage: rs = r.summary(r.c(1,4,3,4,3,2,5,1))
    sage: rs
       Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
      1.000   1.750   3.000   2.875   4.000   5.000
      sage: d = rs._sage_()
      sage: d['DATA']
      [1, 1.75, 3, 2.875, 4, 5]
      sage: d['_Names']
      ['Min.', '1st Qu.', 'Median', 'Mean', '3rd Qu.', 'Max.']
      sage: d['_r_class']
      ['summaryDefault', 'table']

It is also possible to access the plotting capabilities of R through Sage. For more information see the documentation of r.plot() or r.png().

AUTHORS:

- Mike Hansen (2007-11-01)
- William Stein (2008-04-19)
- Harald Schilly (2008-03-20)
- Mike Hansen (2008-04-19)

class `sage.interfaces.r.``HelpExpression`

  Bases: `str`

  Used to improve printing of output of r.help.

class `sage.interfaces.r.``R`(maxread=100000, script_subdirectory=None, server_tmpdir=None, logfile=None, server=None, init_list_length=1024)

  Bases: `sage.interfaces.expect.Expect`

  An interface to the R interpreter.

  R is a comprehensive collection of methods for statistics, modelling, bioinformatics, data analysis and much more. For more details, see http://www.r-project.org/about.html

  Resources:

  - http://r-project.org/ provides more information about R.
  - http://rseek.org/ R’s own search engine.

  EXAMPLES:

      sage: r.summary(r.c(1,2,3,111,2,3,2,3,2,5,4))
      Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
      1.00    2.00    3.00   12.55    3.50  111.00

  TESTS:

      sage: r == loads(dumps(r))
      True

  `available_packages`()

    Returns a list of all available R package names.

    This list is not necessarily sorted.

    OUTPUT: list of strings

    Note

    This requires an internet connection. The CRAN server is that is checked is defined at the top of sage/interfaces/r.py.

    EXAMPLES:

        sage: ap = r.available_packages()   # optional - internet
        sage: len(ap) > 20                  #optional
        True

  `call`(function_name, *args, **kwds)

    This is an alias for `function_call()`.

    EXAMPLES:

        sage: r.call('length', [1,2,3])
        [1] 3

  `chdir`(dir)

    Changes the working directory to `dir`

    INPUT:

    - `dir` – the directory to change to.

    EXAMPLES:

        sage: import tempfile
        sage: tmpdir = tempfile.mkdtemp()
        sage: r.chdir(tmpdir)

    Check that `tmpdir` and `r.getwd()` refer to the same directory. We need to use `realpath()` in case `$TMPDIR` (by default `/tmp`) is a symbolic link (see trac ticket #10264).

        sage: os.path.realpath(tmpdir) == sageobj(r.getwd())  # known bug (:trac:`9970`)
        True

  `completions`(s)

    Return all commands names that complete the command starting with the string s. This is like typing s[Ctrl-T] in the R interpreter.

    INPUT:

    - s – string

    OUTPUT: list – a list of strings

    EXAMPLES:

        sage: dummy = r.trait_names(use_disk_cache=False)    #clean doctest
        sage: r.completions('tes')
        ['testInheritedMethods', 'testPlatformEquivalence', 'testVirtual']

  `console`()

    Runs the R console as a separate new R process.

    EXAMPLES:

        sage: r.console()                    # not tested
            R version 2.6.1 (2007-11-26)
            Copyright (C) 2007 The R Foundation for Statistical Computing
            ISBN 3-900051-07-0
            ...

  `convert_r_list`(l)

    Converts an R list to a Python list.

    EXAMPLES:

        sage: s = 'c(".GlobalEnv", "package:stats", "package:graphics", "package:grDevices", \n"package:utils", "package:datasets", "package:methods", "Autoloads", \n"package:base")'
        sage: r.convert_r_list(s)
        ['.GlobalEnv',
         'package:stats',
         'package:graphics',
         'package:grDevices',
         'package:utils',
         'package:datasets',
         'package:methods',
         'Autoloads',
         'package:base']

  `eval`(code, globals=None, locals=None, synchronize=True, *args, **kwds)

    Evaluates a command inside the R interpreter and returns the output as a string.

    EXAMPLES:

        sage: r.eval('1+1')
        '[1] 2'

  `function_call`(function, args=None, kwds=None)

    Return the result of calling an R function, with given args and keyword args.

    OUTPUT: RElement – an object in R

    EXAMPLES:

        sage: r.function_call('length', args=[ [1,2,3] ])
        [1] 3

  `get`(var)

    Returns the string representation of the variable var.

    INPUT:

    - var – a string

    OUTPUT: string

    EXAMPLES:

        sage: r.set('a', 2)
        sage: r.get('a')
        '[1] 2'

  `help`(command)

    Returns help string for a given command.

    INPUT: - command – a string

    OUTPUT: HelpExpression – a subclass of string whose __repr__ method is __str__, so it prints nicely

    EXAMPLES:

        sage: r.help('c')
        c                     package:base                     R Documentation
        ...

        .. note::

        This is similar to typing r.command?.

  `install_packages`(package_name)

    Install an R package into Sage’s R installation.

    EXAMPLES:

        sage: r.install_packages('aaMI')       # not tested
        ...
        R is free software and comes with ABSOLUTELY NO WARRANTY.
        You are welcome to redistribute it under certain conditions.
        Type 'license()' or 'licence()' for distribution details.
        ...
        Please restart Sage in order to use 'aaMI'.

  `library`(library_name)

    Load the library library_name into the R interpreter.

    This function raises an ImportError if the given library is not known.

    INPUT:

    - library_name – string

    EXAMPLES:

        sage: r.library('grid')
        sage: 'grid' in r.eval('(.packages())')
        True
        sage: r.library('foobar')
        Traceback (most recent call last):
        ...
        ImportError: ...

  `na`()

    Returns the NA in R.

    OUTPUT: RElement – an element of R

    EXAMPLES:

        sage: r.na()
        [1] NA

  `plot`(*args, **kwds)

    The R plot function. Type r.help(‘plot’) for much more extensive documentation about this function. See also below for a brief introduction to more plotting with R.

    If one simply wants to view an R graphic, using this function is is sufficient (because it calls dev.off() to turn off the device).

    However, if one wants to save the graphic to a specific file, it should be used as in the example below to write the output.

    EXAMPLES:

    This example saves a plot to the standard R output, usually a filename like `Rplot001.png` - from the command line, in the current directory, and in the cell directory in the notebook:

        sage: d=r.setwd('"%s"'%SAGE_TMP)    # for doctesting only; ignore if you are trying this;
        sage: r.plot("1:10")                # optional -- rgraphics
        null device
                  1

    To save to a specific file name, one should use `png()` to set the output device to that file. If this is done in the notebook, it must be done in the same cell as the plot itself:

        sage: filename = tmp_filename() + '.png'
        sage: r.png(filename='"%s"'%filename) # Note the double quotes in single quotes!; optional -- rgraphics
        NULL
        sage: x = r([1,2,3])
        sage: y = r([4,5,6])
        sage: r.plot(x,y)         # optional -- rgraphics
        null device
                  1
        sage: import os; os.unlink(filename) # For doctesting, we remove the file; optional -- rgraphics

    Please note that for more extensive use of R’s plotting capabilities (such as the lattices package), it is advisable to either use an interactive plotting device or to use the notebook. The following examples are not tested, because they differ depending on operating system:

        sage: r.X11() # not tested - opens interactive device on systems with X11 support
        sage: r.quartz() # not tested - opens interactive device on OSX
        sage: r.hist("rnorm(100)") # not tested - makes a plot
        sage: r.library("lattice") # not tested - loads R lattice plotting package
        sage: r.histogram(x = "~ wt | cyl", data="mtcars") # not tested - makes a lattice plot
        sage: r.dev_off() # not tested, turns off the interactive viewer

    In the notebook, one can use r.png() to open the device, but would need to use the following since R lattice graphics do not automatically print away from the command line:

        sage: filename = tmp_filename() + '.png' # Not needed in notebook, used for doctesting
        sage: r.png(filename='"%s"'%filename) # filename not needed in notebook, used for doctesting; optional -- rgraphics
        NULL
        sage: r.library("lattice")
        sage: r("print(histogram(~wt | cyl, data=mtcars))") # plot should appear; optional -- rgraphics
        sage: import os; os.unlink(filename) # We remove the file for doctesting, not needed in notebook; optional -- rgraphics

  `png`(*args, **kwds)

    Creates an R PNG device.

    This should primarily be used to save an R graphic to a custom file. Note that when using this in the notebook, one must plot in the same cell that one creates the device. See r.plot() documentation for more information about plotting via R in Sage.

    These examples won’t work on the many platforms where R still gets built without graphics support.

    EXAMPLES:

        sage: filename = tmp_filename() + '.png'
        sage: r.png(filename='"%s"'%filename)             # optional -- rgraphics
        NULL
        sage: x = r([1,2,3])
        sage: y = r([4,5,6])
        sage: r.plot(x,y) # This saves to filename, but is not viewable from command line; optional -- rgraphics
        null device
                  1
        sage: import os; os.unlink(filename) # We remove the file for doctesting; optional -- rgraphics

    We want to make sure that we actually can view R graphics, which happens differently on different platforms:

        sage: s = r.eval('capabilities("png")') # Should be on Linux and Solaris
        sage: t = r.eval('capabilities("aqua")') # Should be on all supported Mac versions
        sage: "TRUE" in s+t                      # optional -- rgraphics
        True

  `read`(filename)

    Read filename into the R interpreter by calling R’s source function on a read-only file connection.

    EXAMPLES:

        sage: filename = tmp_filename()
        sage: f = open(filename, 'w')
        sage: f.write('a <- 2+2\n')
        sage: f.close()
        sage: r.read(filename)
        sage: r.get('a')
        '[1] 4'

  `require`(library_name)

    Load the library library_name into the R interpreter.

    This function raises an ImportError if the given library is not known.

    INPUT:

    - library_name – string

    EXAMPLES:

        sage: r.library('grid')
        sage: 'grid' in r.eval('(.packages())')
        True
        sage: r.library('foobar')
        Traceback (most recent call last):
        ...
        ImportError: ...

  `set`(var, value)

    Set the variable var in R to what the string value evaluates to in R.

    INPUT:

    - var – a string
    - value – a string

    EXAMPLES:

        sage: r.set('a', '2 + 3')
        sage: r.get('a')
        '[1] 5'

  `source`(s)

    Display the R source (if possible) about the function named s.

    INPUT:

    - s – a string representing the function whose source code you want to see

    OUTPUT: string – source code

    EXAMPLES:

        sage: print r.source("c")
        function (..., recursive = FALSE)  .Primitive("c")

  `trait_names`(verbose=True, use_disk_cache=True)

    Return list of all R functions.

    INPUT:

    - verbose – bool (default: True); if True, display debugging information
    - use_disk_cache – bool (default: True); if True, use the disk cache of trait names to save time.

    OUTPUT: list – list of string

    EXAMPLES:

        sage: t = r.trait_names(verbose=False)
        sage: len(t) > 200
        True

  `version`()

    Return the version of R currently running.

    OUTPUT: tuple of ints; string

    EXAMPLES:

        sage: r.version() # not tested
        ((3, 0, 1), 'R version 3.0.1 (2013-05-16)')
        sage: rint, rstr = r.version()
        sage: rint[0] >= 3
        True
        sage: rstr.startswith('R version')
        True

class `sage.interfaces.r.``RElement`(parent, value, is_name=False, name=None)

  Bases: `sage.interfaces.expect.ExpectElement`

  `dot_product`(other)

    Implements the notation self . other.

    INPUT:

    - self, other – R elements

    OUTPUT: R element

    EXAMPLES:

        sage: c = r.c(1,2,3,4)
        sage: c.dot_product(c.t())
             [,1] [,2] [,3] [,4]
        [1,]    1    2    3    4
        [2,]    2    4    6    8
        [3,]    3    6    9   12
        [4,]    4    8   12   16

        sage: v = r([3,-1,8])
        sage: v.dot_product(v)
             [,1]
        [1,]   74

  `stat_model`(x)

    The tilde regression operator in R.

    EXAMPLES:

        sage: x = r([1,2,3,4,5])
        sage: y = r([3,5,7,9,11])
        sage: a = r.lm( y.tilde(x) ) # lm( y ~ x )
        sage: d = a._sage_()
        sage: d['DATA']['coefficients']['DATA'][1]
        2

  `tilde`(x)

    The tilde regression operator in R.

    EXAMPLES:

        sage: x = r([1,2,3,4,5])
        sage: y = r([3,5,7,9,11])
        sage: a = r.lm( y.tilde(x) ) # lm( y ~ x )
        sage: d = a._sage_()
        sage: d['DATA']['coefficients']['DATA'][1]
        2

  `trait_names`()

    Return a list of all methods of this object.

    Note

    Currently returns all R commands.

    EXAMPLES:

        sage: a = r([1,2,3])
        sage: t = a.trait_names()
        sage: len(t) > 200
        True

class `sage.interfaces.r.``RFunction`(parent, name, r_name=None)

  Bases: `sage.interfaces.expect.ExpectFunction`

  A Function in the R interface.

  INPUT:

  - parent – the R interface
  - name – the name of the function for Python
  - r_name – the name of the function in R itself (which can have dots in it)

  EXAMPLES:

      sage: length = r.length
      sage: type(length)
      <class 'sage.interfaces.r.RFunction'>
      sage: loads(dumps(length))
      length

class `sage.interfaces.r.``RFunctionElement`(obj, name)

  Bases: `sage.interfaces.expect.FunctionElement`

`sage.interfaces.r.``is_RElement`(x)

  Return True if x is an element in an R interface.

  INPUT:

  - x – object

  OUTPUT: bool

  EXAMPLES:

      sage: from sage.interfaces.r import is_RElement
      sage: is_RElement(2)
      False
      sage: is_RElement(r(2))
      True

`sage.interfaces.r.``r_console`()

  Spawn a new R command-line session.

  EXAMPLES:

      sage: r.console()                    # not tested
          R version 2.6.1 (2007-11-26)
          Copyright (C) 2007 The R Foundation for Statistical Computing
          ISBN 3-900051-07-0
          ...

`sage.interfaces.r.``r_version`()

  Return the R version.

  EXAMPLES:

      sage: r_version() # not tested
      ((3, 0, 1), 'R version 3.0.1 (2013-05-16)')
      sage: rint, rstr = r_version()
      sage: rint[0] >= 3
      True
      sage: rstr.startswith('R version')
      True

`sage.interfaces.r.``reduce_load_R`()

  Used for reconstructing a copy of the R interpreter from a pickle.

  EXAMPLES:

      sage: from sage.interfaces.r import reduce_load_R
      sage: reduce_load_R()
      R Interpreter

### Navigation

- index
- modules |
- next |
- previous |
- Interpreter Interfaces »