rpy-bridge 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

rpy_bridge-0.3.1.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: rpy-bridge
+Version: 0.3.1
+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
+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: 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-to-R a robust interoperability engine that combines environment management, type-safe conversions, data normalization, and safe function execution to make Python-R collaboration seamless.
+
+It enables Python developers to call R functions, scripts, and packages safely while preserving type fidelity and project-specific R environments. This is ideal for bilingual teams where R authors maintain core logic, and Python-centric users need reliable access without rewriting code.
+
+**Latest release:** [`rpy-bridge` on PyPI](https://pypi.org/project/rpy-bridge/)
+
+---
+
+## Key layers and capabilities
+
+### 1. Lazy and robust R integration
+
+- Automatically detects or sets R_HOME and ensures rpy2 is installed.
+- Configures platform-specific dynamic library paths for macOS/Linux.
+
+### 2. Environment management
+
+- Activates renv projects and loads project-specific libraries if it exists, otherwise use current environemnt.
+- Sources .Renviron and .Rprofile files to replicate the R project environment in Python.
+
+### 3. Python ↔ R type conversion
+
+- Converts Python scalars, lists, dicts, and pandas DataFrames into appropriate R objects.
+- Converts R atomic vectors, ListVector/NamedList, and data.frames back into Python-native objects.
+- Handles nested structures, mixed types, and missing values robustly (NA_* → None/pd.NA).
+
+### 4. Data hygiene and normalization
+
+- Post-processes R DataFrames: fixes dtypes, numeric/date conversions, and timezone issues.
+- Normalizes and aligns column types for accurate Python comparisons.
+- Supports comparing Python and R DataFrames with mismatch diagnostics.
+
+### 5. Function calling
+
+- Calls functions from R scripts, base R, or installed packages safely.
+- Automatically converts arguments and return values, including keyword arguments.
+- Supports mixed data types, nested structures, and DataFrames seamlessly.
+
+### 6. Python-first workflow for R code
+
+- Enables Python developers to reuse R functions without needing deep R knowledge.
+- Keeps network, token, and SSL concerns outside the package when sourcing scripts locally.
+- Designed for reproducibility and safe execution in CI or cross-platform environments.
+
+---
+
+## Installation
+
+**Prerequisites**
+
+- System R installed and available on `PATH` (rpy2 requires a working R installation).
+- Python 3.12+
+
+**From PyPI:**
+
+```bash
+python3 -m pip install rpy-bridge
+```
+
+or using `uv`:
+
+```bash
+uv add rpy-bridge
+```
+
+**During development (editable install):**
+
+```bash
+python3 -m pip install -e .
+```
+
+or using `uv`:
+
+```bash
+uv sync
+```
+
+**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)
+```
+
+---
+
+## Round-trip Python ↔ R behavior
+
+`rpy-bridge` attempts to convert Python objects to R and back. Most objects used in scientific/ML pipelines round-trip cleanly, but some heterogeneous Python structures may be wrapped or slightly altered. This is normal due to R's type system.
+
+| Python type                                    | Round-trip fidelity | Notes                                                                 |
+| ---------------------------------------------- | ------------------- | --------------------------------------------------------------------- |
+| `int`, `float`, `bool`, `str`                  | ✅ High              | Scalars convert directly                                              |
+| Homogeneous `list` of numbers/strings/booleans | ✅ High              | Converted to atomic R vectors                                         |
+| Nested lists of homogeneous types              | ✅ High              | Converted to nested R `ListVector`                                    |
+| `pandas.DataFrame` / `pd.Series`               | ✅ High              | Converted to `data.frame` / R vector, post-processed back             |
+| Mixed-type `list` or heterogeneous `dict`      | ⚠️ Partial          | Elements wrapped in single-element vectors; round-trip may alter type |
+| Python `None` / `pd.NA`                        | ✅ High              | Converted to R `NULL`                                                 |
+
+# Guidance
+
+- Typical workflows (DataFrames, numeric arrays, series, homogeneous lists) are fully supported.
+- Rare or highly heterogeneous Python objects may not round-trip perfectly.
+- Round-trip fidelity is mainly a “nice-to-have” for debugging. For production pipelines, it’s safe to focus on supported types.
+
+---
+
+## Examples
+
+### Basic — run 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")
+print(type(result))
+```
+
+### Call installed R packages (no local script)
+
+```python
+from rpy_bridge import RFunctionCaller
+
+caller = RFunctionCaller(path_to_renv=None, packages=["stats"])
+samples = caller.call("rnorm", 5, mean=10)
+print(type(samples))  # typically a numpy.ndarray
+
+median_val = caller.call("stats::median", samples)
+print(median_val)
+```
+
+---
+
+## 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()
+```
+
+---
+
+## 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).
+
+### 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.

rpy_bridge-0.3.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+rpy_bridge/__init__.py,sha256=fXINFO0OFsSkxNccFPlSPIVsye5WGLVzu6Puf7o1Ao4,829
+rpy_bridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rpy_bridge/rpy2_utils.py,sha256=D8hCv9axFbHGM71NFNO6E4oZIIBA5fBioOvzLDEVAHM,27842
+rpy_bridge-0.3.1.dist-info/licenses/LICENSE,sha256=JwbWVcSfeoLfZ2M_ZiyygKVDvhBDW3zbqTWwXOJwmrA,1276
+rpy_bridge-0.3.1.dist-info/METADATA,sha256=LeJLe_ETz_1bJxnjHUG-LJg3U7fG7Mq6O8YHccNZiVg,9267
+rpy_bridge-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rpy_bridge-0.3.1.dist-info/top_level.txt,sha256=z9UZ77ZuUPoLqMDQEpP4btstsaM1IpXb9Cn9yBVaHmU,11
+rpy_bridge-0.3.1.dist-info/RECORD,,

rpy_bridge-0.1.0.dist-info/METADATA

@@ -1,205 +0,0 @@
-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.

rpy_bridge-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-rpy_bridge/__init__.py,sha256=56cw27pgg7ES9zl6-rwKz01Ky3MRvJX2dusBAjbGXM4,823
-rpy_bridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rpy_bridge/rpy2_utils.py,sha256=13BDM0577R4cjZ06CSH0Glv0xkA9ZbaTe4gS9eno_ko,20536
-rpy_bridge-0.1.0.dist-info/licenses/LICENSE,sha256=JwbWVcSfeoLfZ2M_ZiyygKVDvhBDW3zbqTWwXOJwmrA,1276
-rpy_bridge-0.1.0.dist-info/METADATA,sha256=t7wkdtOKNvB4Ty2oPajgoJiqw88FW0AgTdaSDca4Jew,7229
-rpy_bridge-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rpy_bridge-0.1.0.dist-info/top_level.txt,sha256=z9UZ77ZuUPoLqMDQEpP4btstsaM1IpXb9Cn9yBVaHmU,11
-rpy_bridge-0.1.0.dist-info/RECORD,,