Interfaces to R - Interpreter Interfaces

Skip to content
Back to top
View this page
Edit this page

# Interfaces to R

This is the reference to the Sagemath R interface, usable from any Sage program.

The %r interface creating an R cell in the sage notebook is described in the Notebook manual.

The %R and %%R interface creating an R line or an R cell in the Jupyter notebook are briefly described at the end of this page. This documentation will be expanded and placed in the Jupyter notebook manual when this manual exists.

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

    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

Python

    >>> from sage.all import *
    >>> x = r([RealNumber('10.4'),RealNumber('5.6'),RealNumber('3.1'),RealNumber('6.4'),RealNumber('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

    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

[Python]

    >>> from sage.all import *
    >>> ~x
    [1] 0.09615385 0.17857143 0.32258065 0.15625000 0.04608295
    >>> Integer(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

    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

Python

    >>> from sage.all import *
    >>> y = r([x,Integer(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

    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

[Python]

    >>> from sage.all import *
    >>> v = Integer(2)*x+y+Integer(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

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

Python

    >>> from sage.all import *
    >>> sum(x)
    [1] 47.2
    >>> x.sum()
    [1] 47.2

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

Sage

    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

[Python]

    >>> from sage.all import *
    >>> ((x-x.mean())**Integer(2)/(x.length()-Integer(1))).sum()
    [1] 53.853
    >>> x.var()
    [1] 53.853

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

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

Generating an arithmetic sequence:

Sage

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

Python

    >>> from sage.all import *
    >>> 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

    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

[Python]

    >>> from sage.all import *
    >>> r.seq(length=Integer(10), from_=-Integer(1), by=RealNumber('.2'))
    [1] -1.0 -0.8 -0.6 -0.4 -0.2  0.0  0.2  0.4  0.6  0.8

    >>> x = r([RealNumber('10.4'),RealNumber('5.6'),RealNumber('3.1'),RealNumber('6.4'),RealNumber('21.7')])
    >>> x.rep(Integer(2))
    [1] 10.4  5.6  3.1  6.4 21.7 10.4  5.6  3.1  6.4 21.7
    >>> x.rep(times=Integer(2))
    [1] 10.4  5.6  3.1  6.4 21.7 10.4  5.6  3.1  6.4 21.7
    >>> x.rep(each=Integer(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

    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

Python

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

Character Vectors:

Sage

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

[Python]

    >>> from sage.all import *
    >>> 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

    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

Python

    >>> from sage.all import *
    >>> na = r('NA')
    >>> x = r([RealNumber('10.4'),RealNumber('5.6'),RealNumber('3.1'),RealNumber('6.4'),RealNumber('21.7'),na]); x
    [1] 10.4  5.6  3.1  6.4 21.7   NA
    >>> x['!is.na(self)']
    [1] 10.4  5.6  3.1  6.4 21.7

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

Distributions:

Sage

    sage: r.options(width='60')
    $width
    [1] 80

    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

[Python]

    >>> from sage.all import *
    >>> r.options(width='60')
    $width
    [1] 80

    >>> rr = r.dnorm(r.seq(-Integer(3),Integer(3),RealNumber('0.1')))
    >>> 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

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

Python

    >>> from sage.all import *
    >>> rr = r.dnorm(r.seq(-Integer(3),Integer(3),RealNumber('0.1')))
    >>> sum(rr._sage_())
    9.9772125168981...

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

Sage

    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']

[Python]

    >>> from sage.all import *
    >>> rs = r.summary(r.c(Integer(1),Integer(4),Integer(3),Integer(4),Integer(3),Integer(2),Integer(5),Integer(1)))
    >>> rs
       Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
      1.000   1.750   3.000   2.875   4.000   5.000
    >>> d = rs._sage_()
    >>> d['DATA']
      [1, 1.75, 3, 2.875, 4, 5]
    >>> d['_Names']
      ['Min.', '1st Qu.', 'Median', 'Mean', '3rd Qu.', 'Max.']
    >>> 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().

THE JUPYTER NOTEBOOK INTERFACE (work in progress).

The %r interface described in the Sage notebook manual is not useful in the Jupyter notebook : it creates a inferior R interpreter which cannot be escaped.

The RPy2 library allows the creation of an R cell in the Jupyter notebook analogous to the %r escape in command line or %r cell in a Sage notebook.

The interface is loaded by a cell containing the sole code:

“%load_ext rpy2.ipython”

After execution of this code, the %R and %%R magics are available:

- %R allows the execution of a single line of R code. Data exchange is

    possible via the -i and -o options. Do “%R?” in a standalone cell to get the documentation.

- %%R allows the execution in R of the whole text of a cell, with

    similar options (do “%%R?” in a standalone cell for documentation).

A few important points must be noted:

- The R interpreter launched by this interface IS (currently) DIFFERENT from the R interpreter used br other r… functions.

- Data exchanged via the -i and -o options have a format DIFFERENT from the format used by the r… functions (RPy2 mostly uses arrays, and bugs the user to use the pandas Python package).

- R graphics are (beautifully) displayed in output cells, but are not directly importable. You have to save them as .png, .pdf or .svg files and import them in Sage for further use.

In its current incarnation, this interface is mostly useful to statisticians needing Sage for a few symbolic computations but mostly using R for applied work.

AUTHORS:

- Mike Hansen (2007-11-01)

- William Stein (2008-04-19)

- Harald Schilly (2008-03-20)

- Mike Hansen (2008-04-19)

- Emmanuel Charpentier (2015-12-12, RPy2 interface)

class sage.interfaces.r.HelpExpression

  Bases: `str`

  Used to improve printing of output of r.help.

class sage.interfaces.r.R(maxread=None, logfile=None, init_list_length=1024, seed=None)

  Bases: `ExtraTabCompletion`, `Interface`

  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

      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

  Python

      >>> from sage.all import *
      >>> r.summary(r.c(Integer(1),Integer(2),Integer(3),Integer(111),Integer(2),Integer(3),Integer(2),Integer(3),Integer(2),Integer(5),Integer(4)))
      Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
      1.00    2.00    3.00   12.55    3.50  111.00

  available_packages()

    Return 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

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

    Python

        >>> from sage.all import *
        >>> ap = r.available_packages()                   # optional - internet
        >>> len(ap) > Integer(20)                                  # optional - internet
        True

  call(function_name, *args, **kwds)

    This is an alias for `function_call()`.

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> r.call('length', [Integer(1),Integer(2),Integer(3)])
        [1] 3

  chdir(dir)

    Changes the working directory to `dir`.

    INPUT:

    - `dir` – the directory to change to

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> import tempfile
        >>> tmpdir = tempfile.mkdtemp()
        >>> 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 Issue #10264).

    Sage

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

    [Python]

        >>> from sage.all import *
        >>> os.path.realpath(tmpdir) == sageobj(r.getwd())  # known bug (issue #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 of strings

    EXAMPLES:

    Sage

        sage: dummy = r._tab_completion(use_disk_cache=False)  # clean doctest
        sage: 'testInheritedMethods' in r.completions('tes')
        True

    Python

        >>> from sage.all import *
        >>> dummy = r._tab_completion(use_disk_cache=False)  # clean doctest
        >>> 'testInheritedMethods' in r.completions('tes')
        True

  console()

    Run the R console as a separate new R process.

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> 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)

    Convert an R list to a Python list.

    EXAMPLES:

    Sage

        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']

    Python

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

  eval(code, *args, **kwds)

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

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> 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

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

    Python

        >>> from sage.all import *
        >>> r.function_call('length', args=[ [Integer(1),Integer(2),Integer(3)] ])
        [1] 3

  get(var)

    Return the string representation of the variable var.

    INPUT:

    - `var` – string

    OUTPUT: string

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> r.set('a', Integer(2))
        >>> r.get('a')
        '[1] 2'

  help(command)

    Return help string for a given command.

    INPUT:

    - `command` – string

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

    EXAMPLES:

    Sage

        sage: r.help('c')
        title
        -----

        Combine Values into a Vector or List

        name
        ----

        c
        ...

    Python

        >>> from sage.all import *
        >>> r.help('c')
        title
        -----
        <BLANKLINE>
        Combine Values into a Vector or List
        <BLANKLINE>
        name
        ----
        <BLANKLINE>
        c
        ...

  install_packages(package_name)

    Install an R package into Sage’s R installation.

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> 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

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

    Python

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

  na()

    Return the NA in R.

    OUTPUT: RElement; an element of R

    EXAMPLES:

    Sage

        sage: r.na()
        [1] NA

    Python

        >>> from sage.all import *
        >>> 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. We use a temporary directory in this example while doctesting this example, but you should use something persistent in your own code:

    Sage

        sage: from tempfile import TemporaryDirectory
        sage: with TemporaryDirectory() as d:               # optional - rgraphics
        ....:     _ = r.setwd(d)
        ....:     r.plot("1:10")
        null device
                  1

    Python

        >>> from sage.all import *
        >>> from tempfile import TemporaryDirectory
        >>> with TemporaryDirectory() as d:               # optional - rgraphics
        ...     _ = r.setwd(d)
        ...     r.plot("1:10")
        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

        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)                                   # optional - rgraphics
        null device
                  1
        sage: import os; os.unlink(filename)                # optional - rgraphics

    [Python]

        >>> from sage.all import *
        >>> filename = tmp_filename() + '.png'
        >>> r.png(filename='"%s"'%filename)               # optional - rgraphics
        NULL
        >>> x = r([Integer(1),Integer(2),Integer(3)])
        >>> y = r([Integer(4),Integer(5),Integer(6)])
        >>> r.plot(x,y)                                   # optional - rgraphics
        null device
                  1
        >>> import os; os.unlink(filename)                # 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

        sage: # not tested
        sage: r.X11()
        sage: r.quartz()
        sage: r.hist("rnorm(100)")
        sage: r.library("lattice")
        sage: r.histogram(x = '~ wt | cyl', data='mtcars')
        sage: r.dev_off()

    Python

        >>> from sage.all import *
        >>> # not tested
        >>> r.X11()
        >>> r.quartz()
        >>> r.hist("rnorm(100)")
        >>> r.library("lattice")
        >>> r.histogram(x = '~ wt | cyl', data='mtcars')
        >>> r.dev_off()

    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

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

    [Python]

        >>> from sage.all import *
        >>> filename = tmp_filename() + '.png'  # not needed in notebook, used for doctesting
        >>> r.png(filename='"%s"'%filename)               # optional - rgraphics
        NULL
        >>> r.library("lattice")
        >>> r("print(histogram(~wt | cyl, data=mtcars))")         # optional - rgraphics
        >>> import os; os.unlink(filename)                # optional - rgraphics

  png(*args, **kwds)

    Create 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

        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)                                   # optional - rgraphics
        null device
                  1
        sage: import os; os.unlink(filename)                # optional - rgraphics

    Python

        >>> from sage.all import *
        >>> filename = tmp_filename() + '.png'
        >>> r.png(filename='"%s"'%filename)               # optional - rgraphics
        NULL
        >>> x = r([Integer(1),Integer(2),Integer(3)])
        >>> y = r([Integer(4),Integer(5),Integer(6)])
        >>> r.plot(x,y)                                   # optional - rgraphics
        null device
                  1
        >>> import os; os.unlink(filename)                # optional - rgraphics

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

    Sage

        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

    [Python]

        >>> from sage.all import *
        >>> s = r.eval('capabilities("png")')   # should be on Linux and Solaris
        >>> t = r.eval('capabilities("aqua")')  # should be on all supported Mac versions
        >>> "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

        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'

    Python

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

  require(library_name)

    alias of `library()`.

  set(var, value)

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

    INPUT:

    - `var` – string

    - `value` – string

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> r.set('a', '2 + 3')
        >>> r.get('a')
        '[1] 5'

  set_seed(seed=None)

    Set the seed for R interpreter.

    The seed should be an integer.

    EXAMPLES:

    Sage

        sage: r = R()
        sage: r.set_seed(1)
        1
        sage: r.sample("1:10", 5) # random
        [1] 3 4 5 7 2

    Python

        >>> from sage.all import *
        >>> r = R()
        >>> r.set_seed(Integer(1))
        1
        >>> r.sample("1:10", Integer(5)) # random
        [1] 3 4 5 7 2

  source(s)

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

    INPUT:

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

    OUTPUT: string; source code

    EXAMPLES:

    Sage

        sage: print(r.source("c"))
        function (...)  .Primitive("c")

    Python

        >>> from sage.all import *
        >>> print(r.source("c"))
        function (...)  .Primitive("c")

  version()

    Return the version of R currently running.

    OUTPUT: tuple of ints; string

    EXAMPLES:

    Sage

        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

    Python

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

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

  Bases: `ExtraTabCompletion`, `InterfaceElement`

  dot_product(other)

    Implement the notation `self . other`.

    INPUT:

    - `self`, `other` – R elements

    OUTPUT: R element

    EXAMPLES:

    Sage

        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

    Python

        >>> from sage.all import *
        >>> c = r.c(Integer(1),Integer(2),Integer(3),Integer(4))
        >>> 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

        >>> v = r([Integer(3),-Integer(1),Integer(8)])
        >>> v.dot_product(v)
             [,1]
        [1,]   74

  is_string()

    Tell whether this element is a string.

    EXAMPLES:

    Sage

        sage: r('"abc"').is_string()
        True
        sage: r([1,2,3]).is_string()
        False

    Python

        >>> from sage.all import *
        >>> r('"abc"').is_string()
        True
        >>> r([Integer(1),Integer(2),Integer(3)]).is_string()
        False

  stat_model(x)

    alias of `tilde()`.

  tilde(x)

    The tilde regression operator in R.

    EXAMPLES:

    Sage

        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

    Python

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

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

  Bases: `InterfaceFunction`

  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

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

  Python

      >>> from sage.all import *
      >>> length = r.length
      >>> type(length)
      <class 'sage.interfaces.r.RFunction'>
      >>> loads(dumps(length))
      length

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

  Bases: `InterfaceFunctionElement`

sage.interfaces.r.r_console()

  Spawn a new R command-line session.

  EXAMPLES:

  Sage

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

  Python

      >>> from sage.all import *
      >>> 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

      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

  Python

      >>> from sage.all import *
      >>> r_version()                       # not tested
      ((3, 0, 1), 'R version 3.0.1 (2013-05-16)')
      >>> rint, rstr = r_version()
      >>> rint[Integer(0)] >= Integer(3)
      True
      >>> 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

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

  Python

      >>> from sage.all import *
      >>> from sage.interfaces.r import reduce_load_R
      >>> reduce_load_R()
      R Interpreter