rdata

|build-status| |docs| |coverage| |repostatus| |versions| |pypi| |conda| |zenodo| |pyOpenSci|

Read R datasets from Python.

.. Github does not support include in README for dubious security reasons, so we copy-paste instead. Also Github does not understand Sphinx directives. .. include:: docs/index.rst .. include:: docs/simpleusage.rst

The package rdata offers a lightweight way to import R datasets/objects stored in the ".rda" and ".rds" formats into Python. Its main advantages are:

• It is a pure Python implementation, with no dependencies on the R language or related libraries. Thus, it can be used anywhere where Python is supported, including the web using Pyodide <https://pyodide.org/>__.
• It attempt to support all R objects that can be meaningfully translated. As opposed to other solutions, you are no limited to import dataframes or data with a particular structure.
• It allows users to easily customize the conversion of R classes to Python ones. Does your data use custom R classes? Worry no longer, as it is possible to define custom conversions to the Python classes of your choosing.
• It has a permissive license (MIT). As opposed to other packages that depend on R libraries and thus need to adhere to the GPL license, you can use rdata as a dependency on MIT, BSD or even closed source projects.

Installation

rdata is on PyPi and can be installed using :code:pip:

.. code::

pip install rdata

It is also available for :code:conda using the :code:conda-forge channel:

.. code::

conda install -c conda-forge rdata

Installing the develop version

The current version from the develop branch can be installed as

.. code::

pip install git+https://github.com/vnmabus/rdata.git@develop

Documentation

The documentation of rdata is in ReadTheDocs <https://rdata.readthedocs.io/>__.

Examples

Examples of use are available in ReadTheDocs <https://rdata.readthedocs.io/en/stable/auto_examples/>__.

Simple usage

Read a R dataset

The common way of reading an R dataset is the following one:

.. code:: python

import rdata

converted = rdata.read_rda(rdata.TESTDATA_PATH / "test_vector.rda")
converted

which results in

.. code::

{'test_vector': array([1., 2., 3.])}

Under the hood, this is equivalent to the following code:

.. code:: python

import rdata

parsed = rdata.parser.parse_file(rdata.TESTDATA_PATH / "test_vector.rda")
converted = rdata.conversion.convert(parsed)
converted

This consists on two steps:

#. First, the file is parsed using the function rdata.parser.parse_file <https://rdata.readthedocs.io/en/latest/modules/rdata.parser.parse_file.html>. This provides a literal description of the file contents as a hierarchy of Python objects representing the basic R objects. This step is unambiguous and always the same. #. Then, each object must be converted to an appropriate Python object. In this step there are several choices on which Python type is the most appropriate as the conversion for a given R object. Thus, we provide a default rdata.conversion.convert <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.convert.html> routine, which tries to select Python objects that preserve most information of the original R object. For custom R classes, it is also possible to specify conversion routines to Python objects.

Convert custom R classes

The basic convert <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.convert.html>__ routine only constructs a SimpleConverter <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.SimpleConverter.html>__ object and calls its convert <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.SimpleConverter.html#rdata.conversion.SimpleConverter.convert>__ method. All arguments of convert <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.convert.html>__ are directly passed to the SimpleConverter <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.SimpleConverter.html>__ initialization method.

It is possible, although not trivial, to make a custom Converter <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.Converter.html>__ object to change the way in which the basic R objects are transformed to Python objects. However, a more common situation is that one does not want to change how basic R objects are converted, but instead wants to provide conversions for specific R classes. This can be done by passing a dictionary to the SimpleConverter <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.SimpleConverter.html>__ initialization method, containing as keys the names of R classes and as values, callables that convert a R object of that class to a Python object. By default, the dictionary used is DEFAULT_CLASS_MAP <https://rdata.readthedocs.io/en/latest/modules/rdata.conversion.DEFAULT_CLASS_MAP.html>, which can convert commonly used R classes such as data.frame <https://www.rdocumentation.org/packages/base/topics/data.frame> and factor <https://www.rdocumentation.org/packages/base/topics/factor>__.

As an example, here is how we would implement a conversion routine for the factor class to bytes <https://docs.python.org/3/library/stdtypes.html#bytes>__ objects, instead of the default conversion to Pandas Categorical <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Categorical.html#pandas.Categorical>__ objects:

.. code:: python

import rdata

def factor_constructor(obj, attrs):
    values = [bytes(attrs['levels'][i - 1], 'utf8')
              if i >= 0 else None for i in obj]

    return values

new_dict = {
    **rdata.conversion.DEFAULT_CLASS_MAP,
    "factor": factor_constructor
}

converted = rdata.read_rda(
    rdata.TESTDATA_PATH / "test_dataframe.rda",
    constructor_dict=new_dict,
)
converted

which has the following result:

.. code::

{'test_dataframe':   class  value
    1     b'a'      1
    2     b'b'      2
    3     b'b'      3}

Additional examples

Additional examples illustrating the functionalities of this package can be found in the ReadTheDocs documentation <https://rdata.readthedocs.io/en/latest/auto_examples/index.html>__.

.. |build-status| image:: https://github.com/vnmabus/rdata/actions/workflows/main.yml/badge.svg?branch=master :alt: build status :scale: 100% :target: https://github.com/vnmabus/rdata/actions/workflows/main.yml

.. |docs| image:: https://readthedocs.org/projects/rdata/badge/?version=latest :alt: Documentation Status :scale: 100% :target: https://rdata.readthedocs.io/en/latest/?badge=latest

.. |coverage| image:: http://codecov.io/github/vnmabus/rdata/coverage.svg?branch=develop :alt: Coverage Status :scale: 100% :target: https://codecov.io/gh/vnmabus/rdata/branch/develop

.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed. :target: https://www.repostatus.org/#active

.. |versions| image:: https://img.shields.io/pypi/pyversions/rdata :alt: PyPI - Python Version :scale: 100%

.. |pypi| image:: https://badge.fury.io/py/rdata.svg :alt: Pypi version :scale: 100% :target: https://pypi.python.org/pypi/rdata/

.. |conda| image:: https://anaconda.org/conda-forge/rdata/badges/version.svg :alt: Conda version :scale: 100% :target: https://anaconda.org/conda-forge/rdata

.. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6382237.svg :alt: Zenodo DOI :scale: 100% :target: https://doi.org/10.5281/zenodo.6382237

.. |pyOpenSci| image:: https://tinyurl.com/y22nb8up :alt: pyOpenSci: Peer reviewed :scale: 100% :target: https://github.com/pyOpenSci/software-submission/issues/144