Metadata-Version: 2.4
Name: rpy-bridge
Version: 0.1.0
Summary: Bridge helpers for calling R from Python via rpy2
Author-email: Victoria Cheung <victoriakcheung@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Victoria Cheung
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        Acknowledgement: This project builds on work originally developed at
        Revolution Medicines and interfaces with the rpy2 project, which is licensed
        under the GNU General Public License version 2 or later.
        
Project-URL: Homepage, https://github.com/vic-cheung/rpy-bridge
Project-URL: Issue Tracker, https://github.com/vic-cheung/rpy-bridge/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: rpy2>=3.5
Requires-Dist: loguru>=0.7
Requires-Dist: ipykernel>=7.1.0
Dynamic: license-file

# rpy-bridge

Utilities for calling R code from Python using `rpy2`. It provides a small
wrapper that can (optionally) activate an `renv` project, source an R
script, call functions from that script, and post-process results into
well-typed pandas `DataFrame` objects.

This project was developed for bilingual teams where some functions are
authored in R and the primary consumer is a Python-centric developer. It
acts as an interoperability layer so a Python programmer can call and reuse
R functions (written and maintained by R authors) without reimplementing
that logic in Python.

## Installation

Prerequisites

- System R installed and available on `PATH` (rpy2 requires a working R
  installation).
- Python 3.12+

Installation

Install from PyPI or as an editable local package during development:

```bash
# From PyPI (recommended for consumers)
python3 -m pip install rpy-bridge

# During development (install editable from local source)
python3 -m pip install -e .
```

Required Python packages (the installer will pull these in):

- `rpy2` (GPLv2 or later)
- `pandas`
- `numpy`

## Usage

```python
from pathlib import Path

from rpy_bridge import RFunctionCaller

caller = RFunctionCaller(
    path_to_renv=Path("/path/to/project"),
    script_path=Path("/path/to/script.R"),
)

summary_df = caller.call("summarize_cohort", cohort_df)


## Examples

Basic — run a local R script

```python
from pathlib import Path
from rpy_bridge import RFunctionCaller

# If your project uses renv, pass the project directory (parent of renv/)
project_dir = Path("/path/to/your-r-project")
script = project_dir / "scripts" / "example.R"

# If you do not use renv, pass None for path_to_renv
caller = RFunctionCaller(path_to_renv=project_dir, script_path=script)
result = caller.call("some_function", 42, named_arg="value")
print(type(result))
```

Notes:

`path_to_renv` may be either the project directory (containing `renv/`) or
the `renv/` directory itself. When provided, `RFunctionCaller` will call
`renv::load()` so the R session uses the project's library versions. If
`path_to_renv` is `None`, `rpy-bridge` will use whatever R environment is
visible to the Python process (system R or an R environment you activated
before starting Python).

The intended workflow is:

- Clone or download the R script into your local filesystem (review the
  code if it came from a remote source).
- Construct an `RFunctionCaller` with `script_path` pointing to the local
  script and optionally `path_to_renv` to activate the project's R library.

This keeps network, token, and SSL concerns outside the package while
preserving an easy path for Python-first users to call R-written functions.

If you need to run an R script from a remote repository, clone or download
the script locally, review it, and then construct an `RFunctionCaller`
pointing at the local `script_path`. This keeps network, token, and SSL
concerns outside the package and avoids environment-specific failures.

```python
from rpy_bridge import RFunctionCaller

project_dir = Path("/path/to/cloned/repo")
script = project_dir / "scripts" / "analysis.R"

caller = RFunctionCaller(path_to_renv=None, script_path=script)
result = caller.call("analyze", some_arg=42)
```

## R Setup

If you plan to execute R code with `rpy-bridge`, use the helper scripts in
`examples/r-deps/` to prepare an R environment.

- On macOS (Homebrew) install system deps:

```bash
bash examples/r-deps/install_r_dev_deps_homebrew.sh
```

- Initialize a project `renv` (run in an R session):

```r
source("examples/r-deps/setup_env.R")
```

- Restore the environment on a new machine:

```r
renv::restore()
```

Review the scripts in `examples/r-deps/` before running; they install system
libraries and R packages and should be run from a trusted environment. For
CI, use `r-lib/actions/setup-r` to install R, then run the `Rscript` command
above to prepare the `renv` environment.

## Collaboration note

This repository provides example R setup scripts for teams working across
Python and R. Each project may require different R packages — check the
package list in `examples/r-deps/setup_env.R` and commit a `renv.lock` for
project-specific reproducibility.

Clone repositories containing R scripts locally or use your
preferred tooling to obtain scripts before execution.

## Licensing

- `rpy-bridge` is released under the MIT License © 2025 Victoria Cheung.
- The project depends on [`rpy2`](https://rpy2.github.io) which is licensed
  under the GNU General Public License v2 (or later). Distributing binaries that
  bundle `rpy2` must comply with the GPL terms. When you install `rpy-bridge`
  as a dependency, `rpy2` is resolved directly from its upstream maintainers.

### Thanks

This package was spun out of internal tooling at Revolution Medicines.
Many thanks to the team there for allowing the code to be open sourced.
