Ticket #839: sage-839-referee1.patch

File sage-839-referee1.patch, 44.9 KB (added by was, 13 years ago)
  • sage/interfaces/expect.py

    # HG changeset patch
    # User William Stein <wstein@gmail.com>
    # Date 1208668384 25200
    # Node ID e53b80ecaab12380cd2055a5600cf4ccce8c40e1
    # Parent  dff3e5df5ef8ff029535a01cc30ef1f2e45dd6f0
    Refereeing trac #839 -- made a ton of little changes polishing up the documentation and hopefully increasing robustness.
    
    diff -r dff3e5df5ef8 -r e53b80ecaab1 sage/interfaces/expect.py
    a b class Expect(ParentWithBase): 
    283283#            os.makedirs(T)
    284284#        return T + str(x)
    285285
    286     def name(self):
     286    def name(self, new_name=None):
    287287        return self.__name
    288288
    289289    def path(self):
  • sage/interfaces/r.py

    diff -r dff3e5df5ef8 -r e53b80ecaab1 sage/interfaces/r.py
    a b AUTHORS: 
    204204
    205205from keyword import iskeyword
    206206from expect import Expect, ExpectElement, ExpectFunction, FunctionElement
    207 from sage.misc.misc import DOT_SAGE
     207from sage.misc.misc import DOT_SAGE, UNAME
     208from sage.misc.latex import LatexExpr
    208209import pexpect
    209210from random import randrange
    210211import re
    211212import sage.rings.integer
    212213
    213214COMMANDS_CACHE = '%s/r_commandlist.sobj'%DOT_SAGE
    214 PROMPT = 'ObFuSc4t3dpR0mp7> '
     215PROMPT = '__SAGE__R__PROMPT__> '
    215216prompt_re = re.compile("^>", re.M)
    216217
    217218#there is a mirror network, but lets take #1 for now
    RBaseCommands = ['c', "NULL", "NA", "Tru 
    223224RBaseCommands = ['c', "NULL", "NA", "True", "False", "Inf", "NaN"]
    224225
    225226class R(Expect):
    226     """
    227     R is a comprehensive collection of methods for statistics,
    228     modelling, bioinformatics, data analysis and much more.
    229     Coninues here: http://www.r-project.org/about.html
    230 
    231     Resources:
    232      * http://r-project.org/ provides more information about R.
    233      * http://rseek.org/ R's own search engine.
    234 
    235     EXAMPLES:
    236          sage: r.summary(r.c(1,2,3,111,2,3,2,3,2,5,4))
    237          Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
    238          1.00    2.00    3.00   12.55    3.50  111.00
    239 
    240     """
    241227    def __init__(self,
    242228                 maxread=100000, script_subdirectory=None,
    243229                 server_tmpdir = None,
    class R(Expect): 
    245231                 server=None,
    246232                 init_list_length=1024):
    247233        """
     234        An interface to the R interpreter.
     235       
     236        R is a comprehensive collection of methods for statistics,
     237        modelling, bioinformatics, data analysis and much more.
     238        For more details, see http://www.r-project.org/about.html
     239
     240        Resources:
     241         * http://r-project.org/ provides more information about R.
     242         * http://rseek.org/ R's own search engine.
     243
     244        EXAMPLES:
     245             sage: r.summary(r.c(1,2,3,111,2,3,2,3,2,5,4))
     246             Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
     247             1.00    2.00    3.00   12.55    3.50  111.00
     248
    248249        TESTS:
    249250            sage: r == loads(dumps(r))
    250251            True
    251 
    252252        """
    253253        Expect.__init__(self,
    254254
    class R(Expect): 
    294294    def _start(self):
    295295        """
    296296        Start up the R interpreter and sets the initial prompt and options.
     297
     298        This is called the first time the R interface is actually used.
     299
     300        EXAMPLES:
     301            sage: r = R()
     302            sage: r._start()       
    297303        """
    298304        Expect._start(self)
    299305
    class R(Expect): 
    318324        to call r.dev_off() in the same cell as you opened the device on in order
    319325        to get the plot to appear.
    320326
    321 
    322327        EXAMPLES:
    323328            sage: filename = tmp_filename() + '.png'
    324329            sage: r.png(file='"%s"'%filename)
    class R(Expect): 
    331336                null device
    332337                          1
    333338            sage: import os; os.unlink(filename)
    334 
    335339        """
    336340        from sage.server.support import EMBEDDED_MODE
    337341        if EMBEDDED_MODE:
    class R(Expect): 
    354358             'package:methods',
    355359             'Autoloads',
    356360             'package:base']
    357 
    358361        """
    359362        pl = []
    360363        l = "".join(l.split("\n"))
    class R(Expect): 
    365368
    366369    def install_packages(self, package_name):
    367370        """
    368         Returns help on how to install R packages in Sage's R installation.
     371        Install an R package into Sage's R installation.
    369372
    370373        EXAMPLES:
    371             sage: r.install_packages('Hmisc') #optional requires internet random
    372             ...
     374            sage: r.install_package('Hmisc')       # optional requires internet
     375            [1] 4 5 6
     376        """
     377        if UNAME == "Darwin":
     378            warn = "** You are using OS X.  Unfortunately, the R optional package system currently doesn't support OS X very well.  We are working on this. **"
     379        else:
     380            warn = None
     381        if warn is not None: print warn
    373382
    374         """
    375         s = r.eval('install.packages("%s")'%package_name)
    376         print s
     383        cmd = """options(repos="%s"); install.packages("%s")"""%(RRepositoryURL, package_name)
     384        os.system("time echo '%s' | R --vanilla"%cmd)
     385        print "Please restart Sage or restart the the R interface (via r.restart()) in order to use '%s'."%package_name
     386       
     387        if warn is not None: print warn
     388        #s = r.eval('install.packages("%s")'%package_name)
     389        #print s
    377390
    378391    def __repr__(self):
    379392        """
     393        Return string representation of this R interface.
     394       
    380395        EXAMPLES:
    381396            sage: r.__repr__()
    382397            'R Interpreter'
    class R(Expect): 
    385400
    386401    def __reduce__(self):
    387402        """
     403        Used in serializing an R interface.
     404       
    388405        EXAMPLES:
    389406            sage: rlr, t = r.__reduce__()
    390407            sage: rlr(*t)
    class R(Expect): 
    394411   
    395412    def __getattr__(self, attrname):
    396413        """
     414        Called when you get an attribute of the R interface.  This
     415        manufactures an R function, which is a Python function that
     416        can then be called with various inputs.
     417       
    397418        EXAMPLES:
    398419            sage: c = r.c; c
    399420            c
    class R(Expect): 
    407428
    408429    def _quit_string(self):
    409430        """
     431        Return the string that when typed into R causes the R
     432        interpreter to exit.
     433       
    410434        EXMAPLES:
    411435            sage: r._quit_string()
    412436            'quit(save="no")'
    class R(Expect): 
    444468        """
    445469        EXAMPLES:
    446470            sage: print r._install_hints()
    447             R is currently installed with Sage.
    448            
     471            R is currently installed with Sage.           
    449472        """
    450473        return "R is currently installed with Sage.\n"
    451474
    452475    def _source(self, s):
    453476        """
    454         Returns the source code of a R function as a string.
     477        Returns the source code of an R function as a string.
    455478
    456479        INPUT:
    457480             s -- the name of the function as a string
    class R(Expect): 
    460483            sage: print r._source("print.anova")
    461484            function (x, digits = max(getOption("digits") - 2, 3), signif.stars = getOption("show.signif.stars"),
    462485            ...
    463 
    464486        """
    465487        if s[-2:] == "()":
    466488            s = s[-2:]
    class R(Expect): 
    468490
    469491    def source(self, s):
    470492        """
    471         Display the R source (if possible) about s.
     493        Display the R source (if possible) about the function named s.
    472494       
     495        INPUT:
     496            s -- a string representing the function whose source code you want to see
     497        OUTPUT:
     498            string -- source code
     499           
    473500        EXAMPLES:
    474501            sage: print r.source("print.anova")
    475502            function (x, digits = max(getOption("digits") - 2, 3), signif.stars = getOption("show.signif.stars"),
    476503            ...
    477        
    478         INPUT:
    479             s -- a string representing the function whose source code you
    480                  want
    481504        """
    482505        return self._source(s)
    483506
    484507    def version(self):
    485508        """
    486509        Returns the version of R currently running.
     510
     511        OUTPUT:
     512            tuple of ints; string
    487513
    488514        EXAMPLES:
    489515            sage: r.version()
    class R(Expect): 
    501527       
    502528        return ( (major,) + minor, version_string )
    503529
    504     def library(self,l):
     530    def library(self, library_name):
    505531        """
    506         Loads a library into the R interpreter.
     532        Load the library library_name into the R interpreter.
     533
     534        This function raises an ImportError if the given library
     535        is not known.
     536
     537        INPUT:
     538            library_name -- string
    507539
    508540        EXAMPLES:
    509541            sage: r.library('grid')
    510542            sage: 'grid' in r.eval('(.packages())')
    511543            True
     544            sage: r.library('foobar')
     545            Traceback (most recent call last):
     546            ...
     547            ImportError: there is no package called 'foobar'
    512548        """
    513         success = self.eval('require("%s")'%l)
    514         if not success:
    515             print "Could not load library %s"%l
     549        ret = self.eval('require("%s")'%library_name)
     550        if 'there is no package' in ret:
     551            raise ImportError, "there is no package called '%s'"%library_name
    516552        else:
    517553            try:
    518                 #we need to rebuild keywords!
     554                # We need to rebuild keywords!
    519555                del self.__trait_names
    520556            except AttributeError:
    521557                pass
    522             self.trait_names(verbose=False)
     558            self.trait_names(verbose=False, use_disk_cache=False)
    523559
    524560    require = library #overwrites require
    525561
    526562    def available_packages(self):
    527563        """
    528         Returns a list of available packages where each entry in the list is of
    529         the form ["package name", "version"].
     564        Returns a list of all available R package names.
     565
     566        This list is not necessarily sorted.
     567
     568        OUTPUT:
     569            list of strings
    530570
    531571        NOTE:
    532572            This requires an internet connection. The CRAN server is
    533573            that is checked is defined at the top of sage/interfaces/r.py.
    534574
    535575        EXAMPLES:
    536             sage: ap = r.available_packages() #optional requires internet connection
    537             sage: ap[:3] #optional
    538             [['ADaCGH', '1.0'], ['AIS', '0.2-11'], ['AMORE', '1.2-3']]
    539 
     576            sage: ap = r.available_packages()   # optional requires internet connection
     577            sage: ap[:3]                        # optional
     578            ['aaMI', 'abind', 'AcceptanceSampling']
    540579        """
    541580        p = self.new('available.packages("%s/src/contrib")'%RRepositoryURL)
    542         if p:
    543             p = p._sage_()
    544             s = p['_Dim'][0]
    545             l = [[p['DATA'][i],p['DATA'][s+1+i]] for i in xrange(0,s)]
    546             return l
    547         else:
    548             return []
     581        s = str(p).splitlines()[1:]
     582        v = [x.split()[0].strip("'") for x in s]
     583        return v
     584        # The following was more structural, but breaks on my machine.  (stein)
     585##         p = p._sage_()
     586##         s = p['_Dim'][0]
     587##         l = [[p['DATA'][i],p['DATA'][s+1+i]] for i in xrange(0,s)]
     588##         return l
    549589
    550590    def _object_class(self):
    551591        """
     592        Return the underlying class of elements of the R interface object.
     593
     594        OUTPUT:
     595            a Python class
     596       
    552597        EXAMPLES:
    553598            sage: r._object_class()
    554599            <class 'sage.interfaces.r.RElement'>
    class R(Expect): 
    557602
    558603    def _true_symbol(self):
    559604        """
     605        Return the symbol that represents True in R.
     606
     607        OUTPUT:
     608            string
     609
    560610        EXAMPLES:
    561611            sage: r._true_symbol()
    562612            '[1] TRUE'
     613
     614        This is used behinds the scenes to implement comparison:
     615            sage: r('1') == r('1')
     616            [1] TRUE
     617            sage: r('1') == r('2')
     618            [1] FALSE
    563619        """
    564620        # return the string rep of truth, i.e., what the system outputs
    565621        # when you type 1==1.
    class R(Expect): 
    567623
    568624    def _false_symbol(self):
    569625        """
     626        Return the symbol that represents True in R.
     627
     628        OUTPUT:
     629            string
     630
    570631        EXAMPLES:
    571632            sage: r._false_symbol()
    572633            '[1] FALSE'
    573634        """
    574         # return the string rep of truth, i.e., what the system outputs
     635        # return the string rep of false, i.e., what the system outputs
    575636        # when you type 1==2.
    576637        return "[1] FALSE"
    577638       
    class R(Expect): 
    586647
    587648    def help(self, command):
    588649        """
    589         Returns help on for a given command.
     650        Returns help string for a given command.
     651
     652        INPUT:
     653            command -- a string
     654
     655        OUTPUT:
     656            HelpExpression -- a subclass of string whose __repr__
     657                              method is __str__, so it prints nicely
    590658
    591659        EXAMPLES:
    592             sage: s = r.help('print.anova').split("\n")
    593             sage: print "\n".join(s[:8])
     660            sage: r.help('print.anova')
    594661            anova                 package:stats                 R Documentation
    595662            ...
    596                  Compute analysis of variance (or deviance) tables for one or more
    597                  fitted model objects.
     663                 'coefficients', 'effects', 'fitted.values', 'residuals',
     664                 'summary', 'drop1', 'add1'.
     665
     666        NOTE:
     667            This is similar to typing r.command?.
    598668        """
    599         return self.eval('help("%s")'%command) #?cmd is only an unsafe shortcut
     669        s = self.eval('help("%s")'%command)     # ?cmd is only an unsafe shortcut
     670        return HelpExpression(s.strip())
    600671
    601672    def _assign_symbol(self):
    602673        """
     674        Return the symbol used in R for assignment, which is ' <- '.
     675
     676        OUTPUT:
     677            string
     678       
    603679        EXAMPLES:
    604680            sage: r._assign_symbol()
    605681            ' <- '
    class R(Expect): 
    608684
    609685    def _left_list_delim(self):
    610686        """
     687        Return the left delimiter for lists in R, which is 'c('
     688
     689        OUTPUT:
     690            string
     691       
    611692        EXAMPLES:
    612693            sage: r._left_list_delim()
    613694            'c('
    class R(Expect): 
    616697
    617698    def _right_list_delim(self):
    618699        """
     700        Return the right delimiter for lists in R, which is 'c('
     701
     702        OUTPUT:
     703            string
     704       
    619705        EXAMPLES:
    620706            sage: r._right_list_delim()
    621707            ')'
    class R(Expect): 
    624710
    625711    def console(self):
    626712        """
    627         Runs the R console.
     713        Runs the R console as a separate new R process.
     714
     715        sage: r.console()                    # not tested
     716            R version 2.6.1 (2007-11-26)
     717            Copyright (C) 2007 The R Foundation for Statistical Computing
     718            ISBN 3-900051-07-0
     719            ...
    628720        """
    629721        r_console()
    630722
    631723    def function_call(self, function, args=None, kwargs=None):
    632724        """
     725        Return the result of calling an R function, with given args and keyword args.
     726
     727        OUTPUT:
     728            RElement -- an object in R
     729       
    633730        EXAMPLES:
    634731            sage: r.function_call('length', args=[ [1,2,3] ])
    635732            [1] 3
    636    
    637733        """
    638734        if args is None:
    639735            args = []
    class R(Expect): 
    659755        return self.new("%s(%s)"%(function, ",".join([s.name() for s in args] + [self._sage_to_r_name(key)+'='+kwargs[key].name() for key in kwargs ] )))
    660756
    661757    def call(self, function_name, *args, **kwargs):
    662         """
     758        r"""
     759        This is an alias for \code{self.function_call}.
     760       
    663761        EXAMPLES:
    664762            sage: r.call('length', [1,2,3])
    665763            [1] 3
    class R(Expect): 
    671769        Returns an element belonging to the R interpreter.  This is used
    672770        behind the scenes when doing things like comparisons, etc.
    673771
     772        OUTPUT:
     773            RElement -- an R element.
     774
    674775        EXAMPLES:
    675776            sage: r._an_element_impl()
    676777            [1] 0
    class R(Expect): 
    681782   
    682783    def set(self, var, value):
    683784        """
    684         Set the variable var to the given value.
     785        Set the variable var in R to what the string value evaluates to in R.
     786
     787        INPUT:
     788            var -- a string
     789            value -- a string
    685790
    686791        EXAMPLES:
    687             sage: r.set('a', 2)
     792            sage: r.set('a', '2 + 3')
    688793            sage: r.get('a')
    689             '[1] 2'
     794            '[1] 5'
    690795        """
    691796        cmd = '%s <- %s'%(var,value)
    692797        out = self.eval(cmd)
    class R(Expect): 
    695800
    696801    def get(self, var):
    697802        """
    698         Returns the value of the variable var.
     803        Returns the string representation of the variable var.
     804
     805        INPUT:
     806            var -- a string
     807
     808        OUTPUT:
     809            string
    699810
    700811        EXAMPLES:
    701812            sage: r.set('a', 2)
    class R(Expect): 
    710821        """
    711822        Returns the NA in R.
    712823
     824        OUTPUT:
     825            RElement -- an element of R
     826
    713827        EXAMPLES:
    714828            sage: r.na()
    715829            [1] NA
    class R(Expect): 
    718832   
    719833    def completions(self, s):
    720834        """
    721         Return all commands that complete the command starting with the
     835        Return all commands names that complete the command starting with the
    722836        string s.   This is like typing s[Ctrl-T] in the R interpreter.
     837
     838        INPUT:
     839            s -- string
     840
     841        OUTPUT:
     842            list -- a list of strings
    723843
    724844        EXAMPLES:
    725845            sage: r.completions('tes')
    class R(Expect): 
    730850    def _commands(self):
    731851        """
    732852        Return list of all commands defined in R.
     853
     854        OUTPUT:
     855            list -- a sorted list of strings
    733856
    734857        EXAMPLES:
    735858            sage: l = r._commands()
    class R(Expect): 
    772895   
    773896    def trait_names(self, verbose=True, use_disk_cache=True):
    774897        """
     898        Return list of all R functions.
     899
     900        INPUT:
     901            verbose -- bool (default: True); if True, display debugging information
     902            use_disk_cache -- bool (default: True); if True, use the disk cache of
     903                              trait names to save time.
     904        OUTPUT:
     905            list -- list of string
     906           
    775907        EXAMPLES:
    776908            sage: t = r.trait_names(verbose=False)
    777909            sage: len(t) > 200
    class R(Expect): 
    787919                    return self.__trait_names
    788920                except IOError:
    789921                    pass
    790             if verbose:
     922            if verbose and use_disk_cache:
    791923                print "\nBuilding R command completion list (this takes"
    792924                print "a few seconds only the first time you do it)."
    793925                print "To force rebuild later, delete %s."%COMMANDS_CACHE
    794926            v = self._commands()
    795927            self.__trait_names = v
    796             if len(v) > 200:
     928            if len(v) > 200 and use_disk_cache:
    797929                sage.misc.persist.save(v, COMMANDS_CACHE)
    798930            return v
    799931
    800932    def _sendstr(self, str):
     933        """
     934        Send a string to the pexpect R interface, autorestarting the
     935        expect interface if anything goes wrong.
     936       
     937        INPUT:
     938           str -- a string
     939
     940        EXAMPLES:
     941            sage: r._sendstr('a <- 10;\n')
     942            sage: r.eval('a')
     943            '[1] 10'
     944        """
    801945        if self._expect is None:
    802946            self._start()
    803947        try:
    class R(Expect): 
    818962
    819963        This way, even if you somehow left R in a busy state
    820964        computing, calling _synchronize gets everything fixed.
     965
     966        EXAMPLES:
     967        We observe nothing, just as it should be:
     968            sage: r._synchronize()
    821969        """
    822970        if self._expect is None:
    823971            return
    class R(Expect): 
    837985            self.quit()
    838986           
    839987    def _expect_expr(self, expr=None, timeout=None):
     988        r"""
     989        Wait for a given expression expr (which could be a regular
     990        expression or list of regular expressions) to appear in the
     991        output for at most timeout seconds.
     992
     993        Use \code{r._expect.before} to see what was put in the output
     994        stream before the expression.
     995       
     996        INPUT:
     997            expr -- None or a string or list of strings (default: None)
     998            timeout -- None or a number (default: None)
     999
     1000        EXAMPLES:
     1001            sage: r._sendstr('abc <- 10 +15;\n')
     1002
     1003        Here an exception is raised because 25 hasn't appeared yet in the
     1004        output stream.  The key thing is that this doesn't lock, but instead
     1005        quickly raises an exception.
     1006            sage: t = walltime()
     1007            sage: try: r._expect_expr('25', timeout=0.5)
     1008            ... except: print "Didn't get expression"
     1009            Didn't get expression
     1010
     1011        A quick consistency check on the time that the above took:
     1012            sage: w = walltime(t); w > 0.4 and w < 10
     1013            True
     1014
     1015        We tell R to print abc, which equals 25.
     1016            sage: r._sendstr('abc;\n')
     1017
     1018        Now 25 is in the output stream, so we can wait for it.
     1019            sage: r._expect_expr('25')
     1020
     1021        This gives us everything before the 25.
     1022            sage: r._expect.before
     1023            'abc;\r\n[1] '       
     1024        """
    8401025        if expr is None:
    8411026            expr = self._prompt_wait
    8421027        if self._expect is None:
    class R(Expect): 
    8701055
    8711056    def plot(self, *args, **kwargs):
    8721057        """
    873         R's plot function.
    874 
    875         We have to define this to override the plot function defined in the
    876         superclass.
     1058        The R plot function.  Type r.help('plot') for much more extensive
     1059        documentatin about this function.  See the examples below for how
     1060        to use it to write output to a FILE.
    8771061
    8781062        EXAMPLES:
    8791063            sage: filename = tmp_filename() + '.png'
    class R(Expect): 
    8881072                          1
    8891073            sage: import os; os.unlink(filename)
    8901074        """
     1075        # We have to define this to override the plot function defined in the
     1076        # superclass.
    8911077        return RFunction(self, 'plot')(*args, **kwargs)
    8921078
    8931079    def _strip_prompt(self, code):
    8941080        """
    8951081        Remove the standard R prompt from the beginning of lines in code.
     1082
     1083        INPUT:
     1084            code -- a string
     1085        OUTPUT:
     1086            a string
    8961087
    8971088        EXAMPLES:
    8981089            sage: s = '> a <- 2\n> b <- 3'
    class R(Expect): 
    9091100        EXAMPLES:
    9101101            sage: r.eval('1+1')
    9111102            '[1] 2'
     1103
     1104        You must give r.eval at least one input:
     1105            sage: r.eval()
     1106            Traceback (most recent call last):
     1107            ...
     1108            TypeError: R eval takes at least one argument
    9121109        """
    9131110        # TODO split code at ";" outside of quotes and send them as individual
    914         #      lines withouth ";".
     1111        #      lines without ";".
    9151112        if len(args) == 0:
    916             return "You called R with no arguments! e.g. try eval('1+1') or eval('matrix(seq(1,9),3)')."
     1113            raise TypeError, "R eval takes at least one argument"
    9171114        else:
    9181115            code = args[0]
    9191116            ret = Expect.eval(self, code, synchronize=True, *args,**kwargs)
    9201117            return ret
    9211118
    922    
    923     #####################
    9241119    def _r_to_sage_name(self, s):
    9251120        """
    9261121        Returns a Sage/Python identifier from an R one.  This involves
    9271122        replacing periods with underscores, <- with __, and prepending
    9281123        _ in front of Python keywords.
     1124
     1125        INPUT:
     1126            s -- a string
     1127        OUTPUT:
     1128            a string
    9291129       
    9301130        EXAMPLES:
    9311131            sage: f = r._r_to_sage_name
    class R(Expect): 
    9451145        return s
    9461146
    9471147    def _sage_to_r_name(self, s):
    948         """
     1148        r"""
     1149        The reverse of \code{_r_to_sage_name}.  See the docs for that method.
     1150       
    9491151        EXAMPLES:
    9501152            sage: f = r._sage_to_r_name
    9511153            sage: f('t_test')
    class R(Expect): 
    9541156            'attr<-'
    9551157            sage: f('parent_env__')
    9561158            'parent.env<-'
     1159            sage: r._r_to_sage_name(f('parent_env__'))
     1160            'parent_env__'
    9571161            sage: f('class_')
    9581162            'class'
    9591163        """
    class R(Expect): 
    9661170
    9671171    def __getitem__(self, s):
    9681172        """
    969         Returns the RFunction s.
     1173        Returns the RFunction with name s.
     1174
     1175        INPUT:
     1176            s -- a string
     1177        OUTPUT:
     1178            RFunction -- the R function that in R has name s
    9701179
    9711180        EXAMPLES:
    9721181            sage: r['as.data.frame']
    rel_re_integer = re.compile('([^\d])([\d 
    9831192rel_re_integer = re.compile('([^\d])([\d]+)L')
    9841193rel_re_terms = re.compile('terms\s*=\s*(.*?),')
    9851194rel_re_call = re.compile('call\s*=\s*(.*?)\),')
    986 
    987 
    9881195   
    9891196class RElement(ExpectElement):
     1197    def __reduce__(self):
     1198        """
     1199        EXAMPLES:
     1200            sage: a = r([1,2,3])
     1201            sage: dumps(a)
     1202            Traceback (most recent call last):
     1203            ...
     1204            NotImplementedError: pickling of R elements is not yet supported
     1205        """
     1206        raise NotImplementedError, "pickling of R elements is not yet supported"
     1207       
    9901208    def trait_names(self):
    9911209        """
     1210        Return a list of all methods of this object.
     1211
     1212        NOTE: Current returns all R commands.
     1213
    9921214        EXAMPLES:
    9931215            sage: a = r([1,2,3])
    9941216            sage: t = a.trait_names()
    class RElement(ExpectElement): 
    10001222
    10011223    def tilde(self, x):
    10021224        """
     1225        The tilde regression operator in R.
     1226       
    10031227        EXAMPLES:
    10041228            sage: x = r([1,2,3,4,5])
    10051229            sage: y = r([3,5,7,9,11])
    class RElement(ExpectElement): 
    10161240
    10171241    def __len__(self):
    10181242        """
     1243        Return the length of this object.
     1244
     1245        OUTPUT:
     1246            integer
     1247           
    10191248        EXAMPLES:
    10201249            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    10211250            sage: len(x)
    class RElement(ExpectElement): 
    10251254   
    10261255    def __getattr__(self, attrname):
    10271256        """
     1257        Return attribute of this object, which is an R function with this object
     1258        as the first input.
     1259
     1260        INPUT:
     1261            attrname -- string
     1262
     1263        OUTPUT:
     1264            RFunctionElement
     1265       
    10281266        EXAMPLES:
    10291267            sage: x = r([1,2,3])
    10301268            sage: length = x.length
    class RElement(ExpectElement): 
    10321270            <class 'sage.interfaces.r.RFunctionElement'>
    10331271            sage: length()
    10341272            [1] 3
    1035 
    10361273        """
    10371274        self._check_valid()
    10381275        if attrname[:1] == "_":
    class RElement(ExpectElement): 
    10411278
    10421279    def __getitem__(self, n):
    10431280        """
     1281        Return n-th element of self.
     1282       
     1283        INPUT:
     1284            n -- an integer
     1285        OUTPUT:
     1286            RElement
     1287           
    10441288        EXAMPLES:
    10451289            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    10461290            sage: x[0]
    class RElement(ExpectElement): 
    10551299            [1] 10.4  5.6  6.4 21.7
    10561300            sage: x[4]
    10571301            [1] 6.4
    1058 
    10591302        """
    10601303        P = self._check_valid()
    10611304        if isinstance(n, basestring):
    class RElement(ExpectElement): 
    10681311
    10691312    def __nonzero__(self):
    10701313        """
    1071         bool(self) will only return True if self == 0 contains
    1072         a FALSE.
     1314        Implements bool(self).
     1315       
     1316        NOTE: bool(self) will only return True if self == 0 contains a FALSE in its representation.
    10731317
    10741318        EXAMPLES:
    10751319            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    class RElement(ExpectElement): 
    10821326            False
    10831327            sage: bool(r(1))
    10841328            True
    1085 
    10861329        """
    10871330        return "FALSE" in repr(self==0)
    10881331   
    10891332    def _comparison(self, other, symbol):
    10901333        """
     1334        Used to implement comparison of two objects.
     1335       
     1336        INPUT:
     1337            other -- RElement
     1338            symbol -- string
     1339
     1340        OUTPUT:
     1341            RElement -- output is an R element; not a bool!
     1342           
    10911343        TESTS:
    10921344            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    10931345            sage: x._comparison(10.4, "==")
    10941346            [1] TRUE FALSE FALSE FALSE FALSE
    1095 
    10961347        """
    10971348        P = self.parent()
    10981349        other = P(other)
    class RElement(ExpectElement): 
    11001351   
    11011352    def __eq__(self, other):
    11021353        """
    1103         TESTS:
     1354        Equality testing term by term.
     1355
     1356        INPUT:
     1357            other -- RElement
     1358        OUTPUT:
     1359            RElement -- an R element; not a bool!       
     1360       
     1361        EXAMPLES:
     1362        Notice that comparison is term by term and returns an R element.
    11041363            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11051364            sage: x == 10.4
    11061365            [1] TRUE FALSE FALSE FALSE FALSE
    class RElement(ExpectElement): 
    11091368   
    11101369    def __lt__(self, other):
    11111370        """
    1112         TESTS:
     1371        Less than testing term by term.
     1372
     1373        INPUT:
     1374            other -- RElement
     1375        OUTPUT:
     1376            RElement -- an R element; not a bool!
     1377       
     1378        EXAMPLES:
     1379        Notice that comparison is term by term and returns an R element.
    11131380            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11141381            sage: x < 7
    11151382            [1] FALSE  TRUE  TRUE  TRUE FALSE
    1116 
    11171383        """
    11181384        return self._comparison(other, "<")
    11191385   
    11201386    def __gt__(self, other):
    11211387        """
    1122         TESTS:
     1388        Greater than testing term by term.
     1389
     1390        INPUT:
     1391            other -- RElement
     1392        OUTPUT:
     1393            RElement -- an R element; not a bool!       
     1394       
     1395        EXAMPLES:
     1396        Notice that comparison is term by term and returns an R element.
    11231397            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11241398            sage: x > 8
    11251399            [1] TRUE FALSE FALSE FALSE  TRUE
    1126 
    11271400        """
    11281401        return self._comparison(other, ">")
    11291402   
    11301403    def __le__(self, other):
    11311404        """
    1132         TESTS:
     1405        Less than or equal testing term by term.
     1406       
     1407        INPUT:
     1408            other -- RElement
     1409        OUTPUT:
     1410            RElement -- an R element; not a bool!       
     1411
     1412        EXAMPLES:
    11331413            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11341414            sage: x <= 10.4
    11351415            [1] TRUE  TRUE  TRUE  TRUE FALSE
    1136 
    11371416        """
    11381417        return self._comparison(other, "<=")
    11391418   
    11401419    def __ge__(self, other):
    11411420        """
    1142         TESTS:
     1421        Greater than or equal testing term by term.
     1422       
     1423        INPUT:
     1424            other -- RElement
     1425        OUTPUT:
     1426            RElement -- an R element; not a bool!       
     1427
     1428        EXAMPLES:
    11431429            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11441430            sage: x >= 10.4
    11451431            [1] TRUE FALSE FALSE FALSE  TRUE
    1146 
    11471432        """
    11481433        return self._comparison(other, ">=")
    11491434   
    11501435    def __ne__(self, other):
    11511436        """
    1152         TESTS:
     1437        Not equal testing term by term.
     1438       
     1439        INPUT:
     1440            other -- RElement
     1441        OUTPUT:
     1442            RElement -- an R element; not a bool!       
     1443
     1444        EXAMPLES:
    11531445            sage: x = r([10.4,5.6,3.1,6.4,21.7])
    11541446            sage: x != 10.4
    11551447            [1] FALSE  TRUE  TRUE  TRUE  TRUE
    class RElement(ExpectElement): 
    11581450        return self._comparison(other, "!=")
    11591451   
    11601452    def __cmp__(self, other):
    1161         """
     1453        r"""
     1454        Return 0, 1, or -1 depending on how self and other compare.
     1455
     1456        This is \emph{not} called by the comparison operators, which
     1457        do term-by-term comparison and return R elements.
     1458
     1459        INPUT:
     1460            self, other -- R elements
     1461        OUTPUT:
     1462            0, 1, or -1
     1463       
    11621464        EXAMPLES:
    11631465            sage: one = r(1)
    11641466            sage: two = r(2)
    class RElement(ExpectElement): 
    11861488        """
    11871489        Implements the notation self . other.
    11881490
     1491        INPUT:
     1492            self, other -- R elements
     1493        OUTPUT:
     1494            R element
     1495
    11891496        EXAMPLES:
    11901497            sage: c = r.c(1,2,3,4)
    11911498            sage: c.dot_product(c.t())
    class RElement(ExpectElement): 
    12021509        """
    12031510        P = self._check_valid()
    12041511        Q = P(other)
    1205         #the R operator is %*% for matrix multiplication
     1512        # the R operator is %*% for matrix multiplication
    12061513        return P('%s %%*%% %s'%(self.name(), Q.name()))
    1207 
    12081514
    12091515    def _subs_dots(self, x):
    12101516        """
     1517        Replace dots by underscores; used internally to implement
     1518        conversation from R expression to Sage objects.
     1519       
     1520        INPUT:
     1521            x -- regular expression match: <type '_sre.SRE_Match'>
     1522        OUTPUT:
     1523            string
     1524           
    12111525        EXAMPLES:
    12121526            sage: import re
    12131527            sage: a = r([1,2,3])
    class RElement(ExpectElement): 
    12191533
    12201534    def _subs_xrange(self, x):
    12211535        """
     1536        Change endpoints of xranges.  This is used internally in the
     1537        code for converting R expressions to Sage objects.
     1538       
     1539        INPUT:
     1540            x -- regular expression match: <type '_sre.SRE_Match'>
     1541        OUTPUT:
     1542            string
     1543           
    12221544        EXAMPLES:
    12231545            sage: import re
    12241546            sage: a = r([1,2,3])
    class RElement(ExpectElement): 
    12331555    def _subs_integer(self, x):
    12341556        """
    12351557        Replaces strings like 'dL' with 'Integer(d)' where d is some
    1236         integer.
     1558        integer.  This is used internally in the code for converting R
     1559        expressions to Sage objects.
    12371560       
    12381561        EXAMPLES:
    12391562            sage: import re
    class RElement(ExpectElement): 
    12491572
    12501573    def _convert_nested_r_list(self, exp):
    12511574        """
    1252         Converts a string representing a (possibly) nested
    1253         list in R to a (possibly) nested Python list.
     1575        Converts a string representing a (possibly) nested list in R
     1576        to a (possibly) nested Python list.  This is used internally
     1577        in the code for converting R expressions to Sage objects.
     1578
     1579        INPUT:
     1580            exp -- a string
     1581        OUTPUT
     1582            a string
    12541583
    12551584        EXAMPLES:
    12561585            sage: a = r([1,2,3])
    class RElement(ExpectElement): 
    12861615       
    12871616    def _r_list(self, *args, **kwargs):
    12881617        """
     1618        This is used internally in the code for converting R
     1619        expressions to Sage objects.
     1620       
    12891621        EXAMPLES:
    12901622            sage: a = r([1,2,3])
    12911623            sage: list(sorted(a._r_list(1,2,3,k=5).items()))
    class RElement(ExpectElement): 
    13001632
    13011633    def _r_structure(self, __DATA__, **kwargs):
    13021634        """
     1635        This is used internally in the code for converting R
     1636        expressions to Sage objects.
     1637
    13031638        EXAMPLES:
    13041639            sage: a = r([1,2,3])
    13051640            sage: d = a._r_structure('data', a=1, b=2)
    class RElement(ExpectElement): 
    13301665        return d
    13311666       
    13321667    def _sage_(self):
    1333         """
     1668        r"""
    13341669        Returns Sage representation of the R object.
    1335         R objects are basic C structures, of different kind,
    1336         that can be stacked together.
    1337         This is similar to Python lists with variable objects,
    1338         including lists in lists.
    1339         If R lists have names, they are translated to a Python
    1340         dictionary, anonymous list entries are called #{number}
    13411670
     1671        R objects are basic C structures, of different kind, that can
     1672        be stacked together.  This is similar to Python lists with
     1673        variable objects, including lists of lists.  If R lists have
     1674        names, they are translated to a Python dictionary, with anonymous
     1675        list entries called \#\{number\}.
     1676
     1677        OUTPUT:
     1678            object -- Python object
    13421679
    13431680        EXAMPLES:
    13441681            sage: rs = r.summary(r.c(1,4,3,4,3,2,5,1))
    class RElement(ExpectElement): 
    13471684            [('DATA', [1, 1.75, 3, 2.875, 4, 5]),
    13481685             ('_Names', ['Min.', '1st Qu.', 'Median', 'Mean', '3rd Qu.', 'Max.']),
    13491686             ('_r_class', 'table')]
    1350 
    13511687        """
    13521688        self._check_valid()
    13531689        P = self.parent()
    13541690
    1355         #thats the core of the trick: using dput
     1691        # This is the core of the trick: using dput
    13561692        # dput prints out the internal structure of R's data elements
    13571693        # options via .deparseOpts(control=...)
    1358         # TODO dput also works with a file, if things get huge!
     1694        # TODO: dput also works with a file, if things get huge!
     1695        # [[However, using a file for output often isn't necessary
     1696        # since pipe buffering works pretty well for output.
     1697        # That said, benchmark this.  -- William Stein]]
    13591698        exp = P.eval('dput(%s)'%self.name())
    1360        
    13611699
    1362         # preprocess expression
     1700        # Preprocess expression
    13631701        # example what this could be:
    13641702        # structure(list(statistic = structure(0.233549683248457, .Names = "t"),
    13651703        # parameter = structure(5.58461538461538, .Names = "df"), p.value = 0.823657802106985,
    class RElement(ExpectElement): 
    13981736        exp = re.sub(' structure\(', ' _r_structure(', exp)
    13991737        exp = re.sub('^structure\(', '_r_structure(', exp) #special case
    14001738
    1401         #Change 'list' to '_r_list'
     1739        # Change 'list' to '_r_list'
    14021740        exp = re.sub(' list\(', ' _r_list(', exp)
    14031741        exp = re.sub('\(list\(', '(_r_list(', exp)
    14041742       
    1405         #Change 'a:b' to 'xrange(a,b+1)'
     1743        # Change 'a:b' to 'xrange(a,b+1)'
    14061744        exp = rel_re_xrange.sub(self._subs_xrange, exp)
    14071745
    1408         #Change 'dL' to 'Integer(d)'
     1746        # Change 'dL' to 'Integer(d)'
    14091747        exp = rel_re_integer.sub(self._subs_integer, exp)
    14101748
    1411         #Wrap the right hand side of terms = ... in quotes since it
    1412         #has a ~ in it.
     1749        # Wrap the right hand side of terms = ... in quotes since it
     1750        # has a ~ in it.
    14131751        exp = rel_re_terms.sub(r'terms = "\1",', exp)
    14141752
    14151753
    1416         #Change call = ..., to call = "...",
     1754        # Change call = ..., to call = "...",
    14171755        exp = rel_re_call.sub(r'call = "\1",', exp)       
    14181756
    14191757        # seems to work for
    class RElement(ExpectElement): 
    14321770
    14331771        exp = self._convert_nested_r_list(exp)
    14341772
    1435         #Set up the globals
     1773        # Set up the globals
    14361774        globs = {'NA':None, 'NULL':None, 'FALSE':False, 'TRUE':True,
    14371775                 '_r_list':self._r_list, '_r_structure':self._r_structure,
    14381776                 'Integer':sage.rings.integer.Integer,
    class RElement(ExpectElement): 
    14421780       
    14431781
    14441782    def _latex_(self):
    1445         """
     1783        r"""
    14461784        Return LaTeX representation of this R object.
    14471785
    1448         This calls the tex command in R
     1786        This calls the \code{latex} command in R.
     1787
     1788        OUTPUT:
     1789           a latex expression (basically a string)
    14491790       
    14501791        EXAMPLES:
    1451             sage: latex(r(2))  #optional requires the Hmisc R package
     1792            sage: latex(r(2))  # optional requires the Hmisc R package
    14521793            2
    14531794        """
    14541795        self._check_valid()
    14551796        P = self.parent()
    14561797        # latex is in Hmisc, this is currently not part of Sage's R!!!
    1457         if P.library('Hmisc'):
    1458             #s = P._eval_line('latex(%s, file="");'%self.name(), reformat=False)
    1459             s = P.eval('latex(%s, file="");'%self.name())
    1460             return s
     1798        try:
     1799            P.library('Hmisc')
     1800        except ImportError:
     1801            raise RuntimeError, "The R package 'Hmisc' is required for R to LaTeX conversion, but it is not available."
     1802        return LatexExpr(P.eval('latex(%s, file="");'%self.name()))
    14611803
    1462         raise RuntimeError, "The R package 'Hmisc' is required for R to LaTeX conversion, but it is not available."
     1804
    14631805
    14641806class RFunctionElement(FunctionElement):
     1807    def __reduce__(self):
     1808        """
     1809        EXAMPLES:
     1810            sage: a = r([1,2,3])
     1811            sage: a.mean
     1812            mean
     1813            sage: dumps(a.mean)
     1814            Traceback (most recent call last):
     1815            ...
     1816            NotImplementedError: pickling of R element methods is not yet supported
     1817        """
     1818        raise NotImplementedError, "pickling of R element methods is not yet supported"
     1819   
    14651820    def _sage_doc_(self):
    14661821        """
    1467         Returns the help for self.
     1822        Returns the help for self as a string.
    14681823
    14691824        EXAMPLES:
    14701825            sage: a = r([1,2,3])
    class RFunctionElement(FunctionElement): 
    14731828            length                 package:base                 R Documentation
    14741829            ...
    14751830            <BLANKLINE>
    1476 
    14771831        """
    14781832        M = self._obj.parent()
    14791833        return M.help(self._name)
    14801834
    14811835    def _sage_src_(self):
    14821836        """
    1483         Returns the source of self.
     1837        Returns the source code of self.
    14841838       
    14851839        EXAMPLES:
    14861840            sage: a = r([1,2,3])
    14871841            sage: length = a.length
    14881842            sage: print length._sage_src_()
    14891843            function (x)  .Primitive("length")
    1490 
    14911844        """
    14921845        M = self._obj.parent()
    14931846        return M.source(self._name)
    class RFunctionElement(FunctionElement): 
    14991852            sage: length = a.length
    15001853            sage: length()
    15011854            [1] 3
    1502 
    15031855        """
    15041856        return self._obj.parent().function_call(self._name, args=[self._obj] + list(args), kwargs=kwargs)
    15051857   
    class RFunction(ExpectFunction): 
    15071859class RFunction(ExpectFunction):
    15081860    def __init__(self, parent, name, r_name=None):
    15091861        """
     1862        A Function in the R interface.
     1863
     1864        INPUT:
     1865            parent -- the R interface
     1866            name -- the name of the function for Python
     1867            r_name -- the name of the function in R itself (which can have dots in it)
     1868       
    15101869        EXAMPLES:
    15111870            sage: length = r.length
    15121871            sage: type(length)
    class RFunction(ExpectFunction): 
    15191878            self._name = name
    15201879        else:
    15211880            self._name = parent._sage_to_r_name(name)
     1881
     1882    def __cmp__(self, other):
     1883        """
     1884        EXAMPLES:
     1885            sage: r.mean == loads(dumps(r.mean))
     1886            True
     1887            sage: r.mean == r.lr
     1888            False
     1889        """
     1890        if not isinstance(other, RFunction):
     1891            return cmp(type(self), type(other))
     1892        return cmp(self._name, other._name)
    15221893       
    15231894    def _sage_doc_(self):
    15241895        """
    class RFunction(ExpectFunction): 
    15301901            length                 package:base                 R Documentation
    15311902            ...
    15321903            <BLANKLINE>
    1533 
    15341904        """
    15351905        M = self._parent
    15361906        return M.help(self._name)
    class RFunction(ExpectFunction): 
    15591929                                         
    15601930def is_RElement(x):
    15611931    """
     1932    Return True if x is an element in an R interface.
     1933
     1934    INPUT:
     1935        x -- object
     1936    OUTPUT:
     1937        bool
     1938       
    15621939    EXAMPLES:
    15631940        sage: is_RElement(2)
    15641941        False
    def is_RElement(x): 
    15671944    """
    15681945    return isinstance(x, RElement)
    15691946
    1570 # An instance
     1947# An instance of R
    15711948r = R()
    15721949
    15731950def reduce_load_R():
    15741951    """
     1952    Used for reconstructing a copy of the R interpreter from a pickle.
     1953   
    15751954    EXAMPLES:
    15761955        sage: from sage.interfaces.r import reduce_load_R
    15771956        sage: reduce_load_R()
    def reduce_load_R(): 
    15811960
    15821961import os
    15831962def r_console():
     1963    """
     1964    Spawn a new R command-line session.
     1965
     1966    EXAMPLES:
     1967        sage: r.console()                    # not tested
     1968            R version 2.6.1 (2007-11-26)
     1969            Copyright (C) 2007 The R Foundation for Statistical Computing
     1970            ISBN 3-900051-07-0
     1971            ...
     1972    """
    15841973    # This will only spawn local processes
    15851974    os.system('R --vanilla')
    15861975
    def r_version(): 
    15891978    EXAMPLES:
    15901979        sage: r.version()
    15911980        ((2, 6, 1), 'R version 2.6.1 (2007-11-26)')
    1592        
    15931981    """
    15941982    return r.version()
     1983
     1984class HelpExpression(str):
     1985    """
     1986    Used to improve printing of output of r.help.
     1987    """
     1988    def __repr__(self):
     1989        """
     1990        Return string representatin of self.
     1991
     1992        OUTPUT:
     1993            string
     1994
     1995        EXAMPLES:
     1996            sage: a = sage.interfaces.r.HelpExpression("This\nis\nR!")
     1997            sage: type(a)
     1998            <class 'sage.interfaces.r.HelpExpression'>
     1999            sage: a
     2000            This
     2001            is
     2002            R!
     2003        """
     2004        return self.__str__()
     2005   
  • sage/stats/r.py

    diff -r dff3e5df5ef8 -r e53b80ecaab1 sage/stats/r.py
    a b from sage.interfaces.r import R, RElemen 
     1##########################################################################
     2#
     3#       Copyright (C) 2007 William Stein <wstein@gmail.com>
     4#                     2007 Mike Hansen   <mhansen@gmail.com>
     5#                     2008 Harald Schilly <harald.schilly@gmail.com>
     6#
     7#  Distributed under the terms of the GNU General Public License (GPL)
     8#
     9#                  http://www.gnu.org/licenses/
     10#
     11##########################################################################
     12
    113from sage.interfaces.r import R, RElement
    214
    3 #my own copy
     15# my own copy of an R interface
    416myR = R()
    517
    618def ttest(x,y,conf_level = 0.95, **kw):
  • sage/structure/sage_object.pyx

    diff -r dff3e5df5ef8 -r e53b80ecaab1 sage/structure/sage_object.pyx
    a b cdef class SageObject: 
    364364        return self._interface_init_()
    365365
    366366    def _r_init_(self):
     367        """
     368        Return default string expression that evaluates in R to this
     369        object.
     370
     371        OUTPUT:
     372            string
     373
     374        EXAMPLES:
     375            sage: a = 2/3
     376            sage: a._r_init_()
     377            '2/3'
     378        """
    367379        return self._interface_init_()
    368380
    369381    def _singular_(self, G=None, have_ring=False):