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.

rpy2.robjects.help.pages(topic)

Get help pages corresponding to a given topic.

Package documentation

The documentation for a package is represented with the class Package.

class rpy2.robjects.help.Package(package_name, package_path=None)

Bases: object

The R documentation page (aka help) for a package.

fetch(alias: str) → Page

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)

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.

arguments() → List[Item]

Get the arguments and descriptions as a list of Item objects.

description() → str

Get the description of the entry

details() → str

Get the section Details for the documentation entry.

items()

iterator through the sections names and content in the documentation Page.

iteritems()

iterator through the sections names and content in the documentation Page. (deprecated, use items())

property sections

Sections in the in help page, as a dict.

seealso() → str

Get the other documentation entries recommended

title() → str

Get the title

to_docstring(section_names: Tuple[str, ...] | None = None) → str

section_names: list of section names to consider. If None all sections are used.

Returns a string that can be used as a Python docstring.

usage() → str

Get the usage for the object

value() → str

Get the value returned

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