rpy-bridge 0.4.0__tar.gz → 0.5.0__tar.gz

rpy_bridge-0.5.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: rpy-bridge
+Version: 0.5.0
+Summary: Python-to-R interoperability engine with environment management, type-safe conversions, data normalization, and safe R function execution.
+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
+Keywords: python,r,rpy2,python-r,interoperability,data-science,statistics,bioinformatics
+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: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: loguru>=0.7
+Provides-Extra: r
+Requires-Dist: rpy2>=3.5; extra == "r"
+Provides-Extra: dev
+Requires-Dist: ipykernel>=7.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file
+
+# rpy-bridge
+
+**rpy-bridge** is a Python-controlled **R execution orchestrator** that enables
+Python code to run R functions, scripts, and packages with **reproducible
+filesystem and environment semantics**.
+
+It is built on top of `rpy2`, but unlike thin wrappers, rpy-bridge stabilizes how
+R code is executed when invoked from Python: project roots are inferred, `renv`
+environments can be activated out-of-tree, relative paths behave as expected,
+and return values are normalized for safe Python consumption.
+
+This makes rpy-bridge suitable for production pipelines, CI, and bilingual
+Python/R teams where R code must run reliably outside an interactive R session.
+
+**Latest release:** [`rpy-bridge` on PyPI](https://pypi.org/project/rpy-bridge/)
+
+---
+
+## What this is (and is not)
+
+rpy-bridge **is not a thin rpy2 wrapper**.
+
+Typical rpy2 usage assumes:
+- the Python working directory is the R project root
+- `renv` lives next to the executing script
+- relative paths resolve correctly by default
+- all R code executes in `globalenv()`
+
+These assumptions break quickly in real-world Python workflows.
+
+rpy-bridge instead provides a **controlled R runtime** with explicit guarantees
+around execution context, filesystem behavior, and environment activation.
+
+---
+
+## Core capabilities
+
+### 1. R execution orchestration
+
+- Embeds R via `rpy2` with deterministic startup behavior
+- Disables interactive and GUI-dependent hooks for headless execution
+- Loads R scripts into isolated namespaces (not `globalenv()`)
+
+### 2. Project root inference and path stability
+
+- Infers R project roots using markers such as:
+  `.git`, `.Rproj`, `renv.lock`, `DESCRIPTION`, `.here`
+- Executes R code from the inferred project root regardless of Python CWD
+- Preserves relative-path behavior expected by R scripts
+- Supports R code using `here::here()` or project-local data
+
+### 3. Out-of-tree `renv` activation
+
+- Activates `renv` projects located **outside** the calling Python directory
+- Sources `.Rprofile` and `.Renviron` to reproduce R startup semantics
+- Does not require R scripts and `renv` to live in the same directory
+
+### 4. Python ↔ R data conversion
+
+- Converts Python scalars, lists, dicts, and pandas objects into R equivalents
+- Converts R vectors, lists, and data.frames back into Python-native types
+- Handles nested structures, missing values, and mixed types robustly
+
+### 5. Data normalization and diagnostics
+
+- Post-processes R data.frames to fix dtype, timezone, and NA semantics
+- Normalizes column types for reliable Python-side comparison
+- Supports structured mismatch diagnostics between Python and R data
+
+### 6. Function invocation across scripts and packages
+
+- Calls functions defined in sourced R scripts, base R, or installed packages
+- Supports qualified function names (e.g. `stats::median`)
+- Executes functions within the active project and library context
+
+---
+
+## Calling base R functions and managing packages
+
+In addition to sourcing local R scripts, rpy-bridge supports calling functions
+from base R and installed packages directly from Python.
+
+Current support includes:
+
+- Calling base R functions without a local R script
+- Executing functions from installed R packages within the active environment
+
+Planned extensions (roadmap):
+
+- Programmatic installation of R packages into the active `renv` or system
+  environment when explicitly enabled
+- Declarative package requirements at the Python call site
+- Safe, opt-in package installation for CI and ephemeral environments
+
+Package installation is intentionally **not automatic by default** to preserve
+reproducibility and avoid side effects during execution.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- System R installed and available on `PATH`
+- Python 3.12+
+
+### From PyPI
+
+Install rpy-bridge with rpy2 for full R support:
+
+```bash
+python3 -m pip install rpy-bridge rpy2
+```
+
+Using `uv`:
+
+```bash
+uv add rpy-bridge rpy2
+```
+
+### Development install
+
+```bash
+python3 -m pip install -e .
+```
+
+or:
+
+```bash
+uv sync
+```
+
+### Required Python dependencies
+
+- `rpy2`
+- `pandas`
+- `numpy`
+
+---
+
+## Usage
+
+### Call a function from a local R script
+
+```python
+from pathlib import Path
+from rpy_bridge import RFunctionCaller
+
+project_dir = Path("/path/to/your-r-project")
+script = project_dir / "scripts" / "example.R"
+
+caller = RFunctionCaller(
+    path_to_renv=project_dir,
+    script_path=script,
+)
+
+result = caller.call("some_function", 42, named_arg="value")
+```
+
+### Call base R functions (no local script)
+
+```python
+from rpy_bridge import RFunctionCaller
+
+caller = RFunctionCaller(path_to_renv=None)
+
+samples = caller.call("stats::rnorm", 10, mean=0, sd=1)
+median_val = caller.call("stats::median", samples)
+```
+
+---
+
+## Round-trip Python ↔ R behavior
+
+rpy-bridge attempts to convert Python objects to R and back. Most objects used in
+scientific and ML pipelines round-trip cleanly, but some heterogeneous Python
+structures may be wrapped or slightly altered due to differences in R’s type
+system.
+
+| Python type                                    | Round-trip fidelity | Notes                                                                 |
+| ---------------------------------------------- | ------------------- | --------------------------------------------------------------------- |
+| `int`, `float`, `bool`, `str`                  | High                | Scalars convert directly                                              |
+| Homogeneous `list` of numbers/strings          | High                | Converted to atomic R vectors                                         |
+| Nested homogeneous lists                       | High                | Converted to nested R lists                                           |
+| `pandas.DataFrame` / `pd.Series`               | High                | Converted to `data.frame` and normalized on return                    |
+| Mixed-type `list` or `dict`                    | Partial             | May be wrapped in single-element vectors                              |
+| `None` / `pd.NA`                               | High                | Converted to R `NULL`                                                 |
+
+---
+
+## R setup helpers
+
+Helper scripts are provided in `examples/r-deps/` to prepare R environments.
+
+- Install system R dependencies (macOS / Homebrew):
+
+```bash
+bash examples/r-deps/install_r_dev_deps_homebrew.sh
+```
+
+- Initialize an `renv` project:
+
+```r
+source("examples/r-deps/setup_env.R")
+```
+
+- Restore the environment on a new machine:
+
+```r
+renv::restore()
+```
+
+---
+
+## Who this is for
+
+rpy-bridge is designed for:
+
+- Python-first pipelines that rely on mature R code
+- Teams where R logic must remain authoritative
+- CI or production systems that cannot rely on interactive R sessions
+- Multi-repo or multi-directory projects with non-trivial filesystem layouts
+
+It is **not** intended as a convenience wrapper for exploratory R usage.
+
+---
+
+## Licensing
+
+- rpy-bridge is released under the MIT License © 2025 Victoria Cheung
+- Depends on [`rpy2`](https://rpy2.github.io), licensed under the GNU GPL (v2 or later)
+
+---
+
+## Acknowledgements
+
+This package was spun out of internal tooling I wrote at Revolution Medicines.
+Thanks to the team there for supporting its open-source release.

rpy_bridge-0.5.0/README.md

@@ -0,0 +1,238 @@
+# rpy-bridge
+
+**rpy-bridge** is a Python-controlled **R execution orchestrator** that enables
+Python code to run R functions, scripts, and packages with **reproducible
+filesystem and environment semantics**.
+
+It is built on top of `rpy2`, but unlike thin wrappers, rpy-bridge stabilizes how
+R code is executed when invoked from Python: project roots are inferred, `renv`
+environments can be activated out-of-tree, relative paths behave as expected,
+and return values are normalized for safe Python consumption.
+
+This makes rpy-bridge suitable for production pipelines, CI, and bilingual
+Python/R teams where R code must run reliably outside an interactive R session.
+
+**Latest release:** [`rpy-bridge` on PyPI](https://pypi.org/project/rpy-bridge/)
+
+---
+
+## What this is (and is not)
+
+rpy-bridge **is not a thin rpy2 wrapper**.
+
+Typical rpy2 usage assumes:
+- the Python working directory is the R project root
+- `renv` lives next to the executing script
+- relative paths resolve correctly by default
+- all R code executes in `globalenv()`
+
+These assumptions break quickly in real-world Python workflows.
+
+rpy-bridge instead provides a **controlled R runtime** with explicit guarantees
+around execution context, filesystem behavior, and environment activation.
+
+---
+
+## Core capabilities
+
+### 1. R execution orchestration
+
+- Embeds R via `rpy2` with deterministic startup behavior
+- Disables interactive and GUI-dependent hooks for headless execution
+- Loads R scripts into isolated namespaces (not `globalenv()`)
+
+### 2. Project root inference and path stability
+
+- Infers R project roots using markers such as:
+  `.git`, `.Rproj`, `renv.lock`, `DESCRIPTION`, `.here`
+- Executes R code from the inferred project root regardless of Python CWD
+- Preserves relative-path behavior expected by R scripts
+- Supports R code using `here::here()` or project-local data
+
+### 3. Out-of-tree `renv` activation
+
+- Activates `renv` projects located **outside** the calling Python directory
+- Sources `.Rprofile` and `.Renviron` to reproduce R startup semantics
+- Does not require R scripts and `renv` to live in the same directory
+
+### 4. Python ↔ R data conversion
+
+- Converts Python scalars, lists, dicts, and pandas objects into R equivalents
+- Converts R vectors, lists, and data.frames back into Python-native types
+- Handles nested structures, missing values, and mixed types robustly
+
+### 5. Data normalization and diagnostics
+
+- Post-processes R data.frames to fix dtype, timezone, and NA semantics
+- Normalizes column types for reliable Python-side comparison
+- Supports structured mismatch diagnostics between Python and R data
+
+### 6. Function invocation across scripts and packages
+
+- Calls functions defined in sourced R scripts, base R, or installed packages
+- Supports qualified function names (e.g. `stats::median`)
+- Executes functions within the active project and library context
+
+---
+
+## Calling base R functions and managing packages
+
+In addition to sourcing local R scripts, rpy-bridge supports calling functions
+from base R and installed packages directly from Python.
+
+Current support includes:
+
+- Calling base R functions without a local R script
+- Executing functions from installed R packages within the active environment
+
+Planned extensions (roadmap):
+
+- Programmatic installation of R packages into the active `renv` or system
+  environment when explicitly enabled
+- Declarative package requirements at the Python call site
+- Safe, opt-in package installation for CI and ephemeral environments
+
+Package installation is intentionally **not automatic by default** to preserve
+reproducibility and avoid side effects during execution.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- System R installed and available on `PATH`
+- Python 3.12+
+
+### From PyPI
+
+Install rpy-bridge with rpy2 for full R support:
+
+```bash
+python3 -m pip install rpy-bridge rpy2
+```
+
+Using `uv`:
+
+```bash
+uv add rpy-bridge rpy2
+```
+
+### Development install
+
+```bash
+python3 -m pip install -e .
+```
+
+or:
+
+```bash
+uv sync
+```
+
+### Required Python dependencies
+
+- `rpy2`
+- `pandas`
+- `numpy`
+
+---
+
+## Usage
+
+### Call a function from a local R script
+
+```python
+from pathlib import Path
+from rpy_bridge import RFunctionCaller
+
+project_dir = Path("/path/to/your-r-project")
+script = project_dir / "scripts" / "example.R"
+
+caller = RFunctionCaller(
+    path_to_renv=project_dir,
+    script_path=script,
+)
+
+result = caller.call("some_function", 42, named_arg="value")
+```
+
+### Call base R functions (no local script)
+
+```python
+from rpy_bridge import RFunctionCaller
+
+caller = RFunctionCaller(path_to_renv=None)
+
+samples = caller.call("stats::rnorm", 10, mean=0, sd=1)
+median_val = caller.call("stats::median", samples)
+```
+
+---
+
+## Round-trip Python ↔ R behavior
+
+rpy-bridge attempts to convert Python objects to R and back. Most objects used in
+scientific and ML pipelines round-trip cleanly, but some heterogeneous Python
+structures may be wrapped or slightly altered due to differences in R’s type
+system.
+
+| Python type                                    | Round-trip fidelity | Notes                                                                 |
+| ---------------------------------------------- | ------------------- | --------------------------------------------------------------------- |
+| `int`, `float`, `bool`, `str`                  | High                | Scalars convert directly                                              |
+| Homogeneous `list` of numbers/strings          | High                | Converted to atomic R vectors                                         |
+| Nested homogeneous lists                       | High                | Converted to nested R lists                                           |
+| `pandas.DataFrame` / `pd.Series`               | High                | Converted to `data.frame` and normalized on return                    |
+| Mixed-type `list` or `dict`                    | Partial             | May be wrapped in single-element vectors                              |
+| `None` / `pd.NA`                               | High                | Converted to R `NULL`                                                 |
+
+---
+
+## R setup helpers
+
+Helper scripts are provided in `examples/r-deps/` to prepare R environments.
+
+- Install system R dependencies (macOS / Homebrew):
+
+```bash
+bash examples/r-deps/install_r_dev_deps_homebrew.sh
+```
+
+- Initialize an `renv` project:
+
+```r
+source("examples/r-deps/setup_env.R")
+```
+
+- Restore the environment on a new machine:
+
+```r
+renv::restore()
+```
+
+---
+
+## Who this is for
+
+rpy-bridge is designed for:
+
+- Python-first pipelines that rely on mature R code
+- Teams where R logic must remain authoritative
+- CI or production systems that cannot rely on interactive R sessions
+- Multi-repo or multi-directory projects with non-trivial filesystem layouts
+
+It is **not** intended as a convenience wrapper for exploratory R usage.
+
+---
+
+## Licensing
+
+- rpy-bridge is released under the MIT License © 2025 Victoria Cheung
+- Depends on [`rpy2`](https://rpy2.github.io), licensed under the GNU GPL (v2 or later)
+
+---
+
+## Acknowledgements
+
+This package was spun out of internal tooling I wrote at Revolution Medicines.
+Thanks to the team there for supporting its open-source release.

{rpy_bridge-0.4.0 → rpy_bridge-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rpy-bridge"
-version = "0.4.0"
+version = "0.5.0"
 description = "Python-to-R interoperability engine with environment management, type-safe conversions, data normalization, and safe R function execution."
 readme = "README.md"
 license = { file = "LICENSE" }

rpy_bridge-0.5.0/src/rpy_bridge/__init__.py

@@ -0,0 +1,14 @@
+"""
+Public API for the rpy-bridge package.
+
+`RFunctionCaller` is the primary entry point for loading R scripts and calling
+functions. Other helpers are re-exported for compatibility.
+"""
+
+from .core import RFunctionCaller
+from .renv import activate_renv
+
+__all__ = [
+    "activate_renv",
+    "RFunctionCaller",
+]

rpy_bridge-0.5.0/src/rpy_bridge/compare.py

@@ -0,0 +1,106 @@
+"""
+DataFrame comparison helpers used to validate parity between R and Python outputs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from .dataframe import fix_r_dataframe_types, fix_string_nans
+
+
+def normalize_dtypes(df1: pd.DataFrame, df2: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+    for col in df1.columns.intersection(df2.columns):
+        df1[col] = df1[col].replace("", pd.NA)
+        df2[col] = df2[col].replace("", pd.NA)
+        s1, s2 = df1[col], df2[col]
+        dtype1, dtype2 = s1.dtype, s2.dtype
+        if (pd.api.types.is_numeric_dtype(dtype1) and pd.api.types.is_object_dtype(dtype2)) or (
+            pd.api.types.is_object_dtype(dtype1) and pd.api.types.is_numeric_dtype(dtype2)
+        ):
+            try:
+                df1[col] = pd.to_numeric(s1, errors="coerce")
+                df2[col] = pd.to_numeric(s2, errors="coerce")
+                continue
+            except Exception:
+                pass
+        if pd.api.types.is_numeric_dtype(dtype1) and pd.api.types.is_numeric_dtype(dtype2):
+            df1[col] = df1[col].astype("float64")
+            df2[col] = df2[col].astype("float64")
+            continue
+        if pd.api.types.is_object_dtype(dtype1) or pd.api.types.is_object_dtype(dtype2):
+            df1[col] = df1[col].astype(str)
+            df2[col] = df2[col].astype(str)
+    return df1, df2
+
+
+def align_numeric_dtypes(df1: pd.DataFrame, df2: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+    for col in df1.columns.intersection(df2.columns):
+        s1, s2 = df1[col].replace("", pd.NA), df2[col].replace("", pd.NA)
+        try:
+            s1_num = pd.to_numeric(s1, errors="coerce")
+            s2_num = pd.to_numeric(s2, errors="coerce")
+            if not s1_num.isna().all() or not s2_num.isna().all():
+                df1[col] = s1_num.astype("float64")
+                df2[col] = s2_num.astype("float64")
+                continue
+        except Exception:
+            pass
+        df1[col], df2[col] = s1, s2
+    return df1, df2
+
+
+def compare_r_py_dataframes(df1: pd.DataFrame, df2: pd.DataFrame, float_tol: float = 1e-8) -> dict:
+    results: dict[str, Any] = {
+        "shape_mismatch": False,
+        "columns_mismatch": False,
+        "index_mismatch": False,
+        "numeric_diffs": {},
+        "non_numeric_diffs": {},
+    }
+    df2 = fix_r_dataframe_types(df2)
+    df1 = fix_string_nans(df1)
+    df2 = fix_string_nans(df2)
+    df1, df2 = normalize_dtypes(df1.copy(), df2.copy())
+    df1, df2 = align_numeric_dtypes(df1, df2)
+    if df1.shape != df2.shape:
+        results["shape_mismatch"] = True
+        print(f"[Warning] Shape mismatch: df1 {df1.shape} vs df2 {df2.shape}")
+    if set(df1.columns) != set(df2.columns):
+        results["columns_mismatch"] = True
+        print("[Warning] Column mismatch:")
+        print(f"  df1: {df1.columns}")
+        print(f"  df2: {df2.columns}")
+        common_cols = df1.columns.intersection(df2.columns)
+    else:
+        common_cols = df1.columns
+    df1_aligned, df2_aligned = df1.loc[:, common_cols], df2.loc[:, common_cols]
+    for col in common_cols:
+        col_py, col_r = df1_aligned[col], df2_aligned[col]
+        if pd.api.types.is_numeric_dtype(col_py) and pd.api.types.is_numeric_dtype(col_r):
+            col_py, col_r = col_py.align(col_r)
+            close = np.isclose(
+                col_py.fillna(np.nan),
+                col_r.fillna(np.nan),
+                atol=float_tol,
+                equal_nan=True,
+            )
+            if not close.all():
+                results["numeric_diffs"][col] = pd.DataFrame(
+                    {"df1": col_py[~close], "df2": col_r[~close]}
+                )
+        else:
+            unequal = ~col_py.eq(col_r)
+            both_na = col_py.isna() & col_r.isna()
+            unequal = unequal & ~both_na
+            if unequal.any():
+                results["non_numeric_diffs"][col] = pd.DataFrame(
+                    {"df1": col_py[unequal], "df2": col_r[unequal]}
+                )
+    return results
+
+
+__all__ = ["normalize_dtypes", "align_numeric_dtypes", "compare_r_py_dataframes"]