Metadata-Version: 2.4
Name: rds2py
Version: 0.9.0
Summary: Parse and construct Python representations for datasets stored in RDS files
Home-page: https://github.com/biocpy/rds2py
Author: jkanche
Author-email: jayaram.kancherla@gmail.com
License: MIT
Project-URL: Documentation, https://biocpy.github.io/rds2py/
Project-URL: Source, https://github.com/biocpy/rds2py
Platform: Mac
Platform: Linux
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
License-File: LICENSE.txt
Requires-Dist: importlib-metadata; python_version < "3.8"
Requires-Dist: numpy
Requires-Dist: biocutils>=0.1.5
Provides-Extra: optional
Requires-Dist: hdf5array; extra == "optional"
Requires-Dist: scipy; extra == "optional"
Requires-Dist: biocframe; extra == "optional"
Requires-Dist: genomicranges>=0.8.4; extra == "optional"
Requires-Dist: summarizedexperiment>=0.6.5; extra == "optional"
Requires-Dist: singlecellexperiment>=0.6.2; extra == "optional"
Requires-Dist: multiassayexperiment>=0.6.0; extra == "optional"
Requires-Dist: compressed_lists>=0.4.4; extra == "optional"
Requires-Dist: biocutils>=0.3.4; extra == "optional"
Requires-Dist: compressed_lists; extra == "optional"
Provides-Extra: testing
Requires-Dist: setuptools; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: hdf5array; extra == "testing"
Requires-Dist: scipy; extra == "testing"
Requires-Dist: biocframe; extra == "testing"
Requires-Dist: genomicranges>=0.8.4; extra == "testing"
Requires-Dist: summarizedexperiment>=0.6.5; extra == "testing"
Requires-Dist: singlecellexperiment>=0.6.2; extra == "testing"
Requires-Dist: multiassayexperiment>=0.6.0; extra == "testing"
Requires-Dist: compressed_lists>=0.4.4; extra == "testing"
Requires-Dist: biocutils>=0.3.4; extra == "testing"
Requires-Dist: compressed_lists; extra == "testing"
Dynamic: license-file

[![Project generated with PyScaffold](https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold)](https://pyscaffold.org/)
[![PyPI-Server](https://img.shields.io/pypi/v/rds2py.svg)](https://pypi.org/project/rds2py/)
![Unit tests](https://github.com/BiocPy/rds2py/actions/workflows/run-tests.yml/badge.svg)

# rds2py

Parse and construct Python representations for datasets stored in **RDS or RData** files. `rds2py` supports various base classes from R, and Bioconductor's `SummarizedExperiment` and `SingleCellExperiment` S4 classes. **_For more details, check out [rds2cpp library](https://github.com/LTLA/rds2cpp)._**

## Installation

Package is published to [PyPI](https://pypi.org/project/rds2py/)

```shell
pip install rds2py

# or install optional dependencies
pip install rds2py[optional]
```

By default, the package does not install packages to convert python representations to BiocPy classes. Please consider installing all optional dependencies.

## Usage

> [!NOTE]
>
> If you do not have an RDS object handy, feel free to download one from [single-cell-test-files](https://github.com/jkanche/random-test-files/releases).

```python
from rds2py import read_rds, read_rda
r_obj = read_rds("path/to/file.rds") # or read_rda("path/to/file.rda")
```

The returned `r_obj` either returns an appropriate Python class if a parser is already implemented or returns the dictionary containing the data from the RDS file.

### Write-your-own-reader

Reading RDS or RData files as dictionary representations allows users to write their own custom readers into appropriate Python representations.

```python
from rds2py import parse_rds, parse_rda

robject = parse_rds("path/to/file.rds") # or use parse_rda for rdata files
print(robject)
```

If you know this RDS file contains an `GenomicRanges` object, you can use the built-in reader or write your own reader to convert this dictionary.

```python
from rds2py.read_granges import read_genomic_ranges

gr = read_genomic_ranges(robject)
print(gr)
```

## Type Conversion Reference

| R Type     | Python/NumPy Type                    |
| ---------- | ------------------------------------ |
| numeric    | numpy.ndarray (float64)              |
| integer    | numpy.ndarray (int32)                |
| character  | list of str                          |
| logical    | numpy.ndarray (bool)                 |
| factor     | list                                 |
| data.frame | BiocFrame                            |
| matrix     | numpy.ndarray or scipy.sparse matrix |
| dgCMatrix  | scipy.sparse.csc_matrix              |
| dgRMatrix  | scipy.sparse.csr_matrix              |

and integration with BiocPy ecosystem for Bioconductor classes
  - SummarizedExperiment
  - RangedSummarizedExperiment
  - SingleCellExperiment
  - GenomicRanges
  - MultiAssayExperiment

## Developer Notes

This project uses pybind11 to provide bindings to the rds2cpp library. Please make sure necessary C++ compiler is installed on your system.

<!-- pyscaffold-notes -->

## Note

This project has been set up using PyScaffold 4.5. For details and usage
information on PyScaffold see https://pyscaffold.org/.
