API Reference

This page documents the public API of rpy-bridge. For almost all use cases, users only need to work with a single class: RFunctionCaller.

For practical examples, see usage or the examples directory: rpy-bridge examples.

How it works internally

Internally, RFunctionCaller embeds an R session inside Python. Each sourced R script is loaded into its own isolated environment (namespace), preventing name collisions between scripts.

When call() is invoked:

  1. Python arguments are converted to R objects

  2. The requested R function is resolved (script, package, or base R)

  3. The function is executed inside the R session

  4. The return value is converted back into a Python object

These details are abstracted away so users can focus on calling R functions without managing R sessions, environments, or type conversion manually.

Overview

RFunctionCaller provides a unified interface for:

  • Loading one or more R scripts

  • Calling functions defined in those scripts

  • Calling base R and package functions

  • Inspecting available functions in loaded namespaces

  • Optionally activating a renv project

Typical usage looks like:

from rpy_bridge import RFunctionCaller

rfc = RFunctionCaller(scripts="my_script.R")
result = rfc.call("my_function", 1, 2)

RFunctionCaller

Initialization

rfc = RFunctionCaller(
    path_to_renv=None,
    scripts="my_script.R",
    packages=["dplyr"],
)

Parameters

  • path_to_renv Optional path to an R project that uses renv. This may point either to the project root or directly to the renv/ directory.

  • scripts One or more R scripts or directories containing .R files. Scripts are sourced and loaded into isolated namespaces.

  • packages Optional R packages to load (and install if missing), for example ["dplyr"].

Calling R Functions

The primary method users will interact with is call.

# Base R
rfc.call("sum", [1, 2, 3])

# Package function
rfc.call("dplyr::n_distinct", [1, 2, 2, 3])

# Function from a sourced R script
rfc.call("add_and_scale", 2, 3, scale=10)

Inspecting Loaded Functions

When working with larger scripts or multiple namespaces, it is often useful to inspect what functions are available.

rfc.list_namespaces()
rfc.print_function_tree()

Notes and Best Practices

  • Base R functions can be called directly (e.g. "sum", "mean").

  • Package functions should use package::function syntax.

  • Missing values (None, pd.NA) are mapped to R NA automatically.

  • Empty vectors, mixed types, and lists of DataFrames are supported.

  • For most workflows, users should rely on call() and print_function_tree() exclusively.

Examples

The following example scripts demonstrate real-world usage:

  • examples/basic_usage.py – Minimal usage patterns

  • examples/advanced_usage.py – Multiple scripts, packages, edge cases

  • examples/renv_usage.py – Using project-specific renv environments

View all examples on GitHub: https://github.com/vic-cheung/rpy-bridge/tree/main/examples