R help¶
R has a documentation system that ensures that documentation for code distributed as packages is installed when packages are installed. This documentation can be called and searched from R itself.
Unlike Python docstrings, where the documentation string
can be found in the special attribute __doc__
,
the R documentation lives outside objects in documentation pages.
Each documentation page is associated at minimum one alias, aliases often
corresponding to the name of an R object defined in a package
(function, dataset, etc…).
For example, querying documentation for the R function sum becomes a matter of finding which documentation page has the alias sum, and retrieve that page.
Querying on aliases¶
When working with R, a frequent use case for using the documention is to query on an alias (a function name, a dataset, or a class name) and retrieve the associated documentation.
While the R packaging system will make checks that any given alias is associated with only one page within the same package, it is well possible to have several packages defining a documentation page for the same alias.
With rpy2’s interface to the help system, an easy way to retrive
pages associated with an alias is to
use the function pages()
, which returns a tuple
of Page
instances.
Package documentation¶
The documentation for a package is represented with the class
Package
.
-
class
rpy2.robjects.help.
Package
(package_name, package_path = None)[source]¶ Bases:
object
The R documentation page (aka help) for a package.
-
fetch
(alias)[source]¶ Fetch the documentation page associated with a given alias.
For S4 classes, the class name is often suffixed with ‘-class’. For example, the alias to the documentation for the class AnnotatedDataFrame in the package Biobase is ‘AnnotatedDataFrame-class’.
-
property
name
¶ Name of the package as known by R
-
property
package_path
¶ Path to the installed R package
-
>>> import rpy2.robjects.help as rh
>>> base_help = rh.Package('base')
>>> base_help.fetch('sum')
Documentation page¶
A documentation page is represented as an instance of
class Page
.
-
class
rpy2.robjects.help.
Page
(struct_rdb)[source]¶ Bases:
object
An R documentation page. The original R structure is a nested sequence of components, corresponding to the latex-like .Rd file
An help page is divided into sections, the names for the sections are the keys for the dict attribute ‘sections’, and a given section can be extracted with the square-bracket operator.
In R, the S3 class ‘Rd’ is the closest entity to this class.
-
property
sections
¶ Sections in the in help page, as a dict.
-
property
>>> hp = base_help.fetch('sum')
>>> hp.sections.keys()
('title', 'name', 'alias', 'keyword', 'description', 'usage', 'arguments', 'deta
ils', 'value', 'section', 'references', 'seealso')
Note
>>> print(''.join(hp.to_docstring(('details',))))
details
-------
This is a generic function: methods can be defined for it
directly or via the Summary group generic.
For this to work properly, the arguments should be
unnamed, and dispatch is on the first argument.
If na.rm is FALSE an NA
value in any of the arguments will cause
a value of NA to be returned, otherwise
NA values are ignored.
Logical true values are regarded as one, false values as zero.
For historical reasons, NULL is accepted and treated as if it
were integer(0) .