Metadata-Version: 2.4
Name: rpynative
Version: 0.1.4
Summary: Use R packages natively in Python, no R knowledge required.
Author-email: DevWebWacky <uwakmfon31@gmail.com>
Maintainer-email: DevWebWacky <uwakmfon31@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DevWebWacky/rpynative
Project-URL: Repository, https://github.com/DevWebWacky/rpynative
Project-URL: Issues, https://github.com/DevWebWacky/rpynative/issues
Keywords: r,rpy2,interoperability,statistics,data-science,cran,bridge
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rpy2>=3.6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/DevWebWacky/rpynative/main/logo.png" alt="rpynative logo" width="160">
</p>

<h1 align="center">rpynative</h1>

<p align="center">
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/v/rpynative" alt="PyPI Version"></a>
  <a href="https://pepy.tech/project/rpynative"><img src="https://static.pepy.tech/badge/rpynative" alt="Total Downloads"></a>
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/pyversions/rpynative" alt="Python Versions"></a>
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/l/rpynative" alt="License"></a>
</p>

**Use R packages natively in Python, no R knowledge required.**

`rpynative` lets Python developers load and use R packages as if they were normal Python packages. No R syntax, no manual object conversion, and unlike other R-Python bridges, `rpynative` supports real IDE autocomplete and rich Jupyter/Colab display for R functions.

> **Requires R to be installed on your system.** `rpynative` is not a pure-Python package — it's built on [rpy2](https://rpy2.github.io/), meaning the real chain is:
>
> `Python → rpynative → rpy2 → R`
>
> `pip install rpynative` will succeed even without R installed, but using it will fail until R is available on your system. See [Requirements](#requirements) below before you start.

## Why not just use rpy2?

`rpynative` is built on top of [rpy2](https://rpy2.github.io/), rpy2 is the engine, `rpynative` is what a Python-only developer actually experiences using it. rpy2 exposes R concepts directly (R vectors, manual converter contexts, raw R objects), it's a bridge for people who already know R. `rpynative` is built for people who don't, and want R's tools to feel like native Python.

Specifically, `rpynative` adds:

- **Zero R knowledge required**: pass plain Python lists/DataFrames, get back plain Python dicts/DataFrames
- **Auto-install**: missing R packages are installed from CRAN automatically
- **Preserved native reporting**: R's own nicely formatted print output is captured and shown, not just raw data
- **Object chaining and generic dispatch handled transparently**: things like `ggplot2`'s `+` syntax, or `predict()` working across any model type, just work
- **Auto-generated IDE stubs**: real autocomplete and parameter hints, generated automatically the first time you load a package
- **Rich Jupyter/Colab display**: R plots render as real inline images, statistical reports render as formatted output
- **Round-tripping of complex objects**: trained models, plots, and other R objects can be passed back into other R functions without losing their identity
- **Broad R object support**: S3, S4, matrices (as numpy arrays), environments, and Reference Classes (R5) all convert to clean Python types

## Example

```python
import rpynative

stats = rpynative.load("stats")
result = stats.mean([2, 4, 6, 8, 10])
print(result)  # 6.0
```

### Real statistical reports, not raw R objects

```python
statease = rpynative.load("statease")
result = statease.ttest_interpret([88, 92, 79, 85, 90], [70, 65, 72, 68, 74])

print(result)
# -- statease T-Test Report ----------------------------------------
#   Test         : Independent Samples T-Test
#   ...

print(result['p_val']) 
```

### Formulas, DataFrames, matrices, S4 objects, and environments

```python
import pandas as pd

data = pd.DataFrame({"score": [...], "group": [...]})
result = statease.anova_interpret("score ~ group", data=data)
print(result)
```

### Visual/plotting packages — with live rendering in Jupyter/Colab

```python
ggplot2 = rpynative.load("ggplot2")

plot = ggplot2.ggplot(data, ggplot2.aes(x="x", y="y")) + ggplot2.geom_point()
plot  # renders inline automatically in Jupyter/Colab

ggplot2.ggsave("plot.png", plot=plot)  # or save to a file
```

### Real machine learning workflows

```python
randomForest = rpynative.load("randomForest")

model = randomForest.randomForest("outcome ~ feature1 + feature2", data=data)
predictions = randomForest.predict(model, new_data)
```

### IDE autocomplete for R functions

Stubs are generated automatically the first time you load a package. To get full autocomplete in your editor:

```python
from rpynative.core import load_typed
from rpynative.stubs.statease import StateaseStub

statease = load_typed("statease", StateaseStub)
statease.
```

## Features

- Load any R package with one line or auto-installs it from CRAN if missing
- Automatic conversion: lists, numbers, pandas DataFrames, R formulas, matrices (as numpy arrays), S4 objects, environments, and Reference Classes (all as dicts)
- Rich report output preserved alongside clean programmatic access
- Object-chaining support (`+` operator) for packages like `ggplot2`
- Generic function dispatch (`predict`, `summary`, etc.) works across any model type
- Built-in R datasets accessible directly as pandas DataFrames
- Auto-generated IDE stubs — created automatically on `load()`, no manual step needed
- Rich Jupyter/Colab display, plots render as inline images, reports as formatted output
- Clean Python errors instead of raw R tracebacks

## Requirements

- Python 3.9+
- **R installed and available on your system**: download from [r-project.org](https://www.r-project.org/) if you don't have it
- R must be discoverable on your system PATH (on Windows, this sometimes requires adding R's `bin` folder to PATH manually after installing R, see [R's Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) if `R --version` doesn't work in your terminal)

Individual R packages (like `stats`, `ggplot2`, etc.) do **not** need to be pre-installed — `rpynative` installs them automatically from CRAN the first time you load them.

## Installation

```bash
pip install rpynative
```

Then verify your R installation is discoverable:

```bash
python -c "import rpynative; v = rpynative.load('base').getRversion(); print('R version:', '.'.join(str(x) for x in v))"
```

If this raises an error instead of printing your R version, `rpynative` is installed correctly, but R itself isn't discoverable yet, check the PATH note above.

### Using rpynative in Google Colab

Colab sometimes ships with a broken or conflicting pre-installed `rpy2`, causing errors like `ModuleNotFoundError: No module named 'rpy2.robjects.packages'` even after installing `rpynative` successfully. If you hit this, run:

```python
!pip uninstall -y rpy2 rpy2-rinterface rpy2-robjects
!pip install --force-reinstall --no-cache-dir rpy2
!pip install rpynative
```

Then **restart the runtime** (Runtime → Restart session) before importing `rpynative`. This is a one-time fix per Colab session/instance.

### Using rpynative in JupyterLab

Unlike Google Colab, JupyterLab does not come with R pre-installed, you will need to install R yourself first. Two common options:

**Option A: Install R directly (if not using Anaconda/conda)**

Download and install R from [r-project.org](https://www.r-project.org/), then make sure it's discoverable on your system PATH (see [Requirements](#requirements) above).

**Option B: Install R via conda (if you manage your JupyterLab environment with Anaconda/Miniconda)**

```bash
conda install -c conda-forge r-base
```
Note: you do **not** need `IRkernel` for `rpynative` — `IRkernel` is for running R code natively in Jupyter cells (an R kernel), which is a different use case. `rpynative` works entirely from a normal **Python** kernel; it calls R in the background for you.

Once R is installed either way, install `rpynative` as normal:

```bash
pip install rpynative
```

## How it works

Under the hood, `rpynative` uses [rpy2](https://rpy2.github.io/) to talk to R, but wraps it in a layer that:
1. Automatically converts Python arguments into R-friendly types
2. Runs the R function inside R itself, preserving its native object class
3. Captures R's own pretty-printed report text
4. Converts the result into a clean Python dict/DataFrame, while keeping the original R object available for chaining into other R calls

This means R's own formatting, object systems (S3, S4, environments, Reference Classes), and object-chaining patterns (like `ggplot2`'s `+` syntax) work correctly, without the user ever writing R code directly.

## Known limitations

- Not yet tested against every R object type across all ~20,000 CRAN packages — common types are covered and tested; more exotic types may surface new edge cases
- Windows, macOS, and Linux should all work (R + rpy2 support all three), but development and testing so far has been primarily on Windows and Google Colab

See [CHANGELOG.md](CHANGELOG.md) for a full history of changes.

## Status

Actively developed. Core engine, report handling, plotting support, matrix/S4/environment support, IDE autocomplete, and Jupyter/Colab rendering are all working and tested against real published R packages, including real machine learning workflows.

## Author

Built by [DevWebWacky](https://github.com/DevWebWacky), also the author of [triageR](https://cran.r-project.org/package=triageR), and [statease](https://cran.r-project.org/package=statease), the R package used throughout development and testing.

## License

MIT
