R Language Integration¶
The causaliq_core.r module provides subprocess-based access to R packages
from Python. It was introduced in v0.8.0 as the shared R foundation used by
causaliq-discovery and other CausalIQ packages that interact with R.
Design Rationale¶
Why subprocess instead of rpy2?¶
The previous approach used rpy2, a C-extension that embeds the R runtime in the Python process. This caused several practical problems:
| Problem | rpy2 | subprocess |
|---|---|---|
| Windows install | Requires Rtools + make | Plain CRAN R sufficient |
| CI setup | Complex linker configuration | Install R, done |
| Isolation | Shared process memory | Separate R process |
| Debugging | Opaque C-level errors | Full R stderr captured |
| Version coupling | rpy2 version tied to R version | Any R version works |
The subprocess approach runs Rscript --vanilla - and pipes R code through
stdin. Stdout is returned as a string and parsed in Python. This is simpler,
more portable, and easier to test.
Architecture¶
Module Structure¶
causaliq_core/r/
├── __init__.py # Exports run_r_script
├── session.py # _find_rscript(), run_r_script()
├── availability.py # is_r_available(), is_r_package_available()
├── convert.py # write_r_datafile(), datafile_to_r_code(),
│ # data_to_r_dataframe(), r_arcs_to_edges()
├── bnlearn.py # bnlearn_cpdag(), bnlearn_compare(), bnlearn_import()
└── exceptions.py # RNotAvailableError, RPackageNotAvailableError,
# RRuntimeError
Call Flow¶
Python caller
│
├─ is_r_available() # guard check — returns bool, never raises
│
├─ write_r_datafile(...) # serialise Python data → temporary CSV
├─ datafile_to_r_code(...) # → R code string that reads the datafile
│
└─ run_r_script(script)
│
├─ _find_rscript() # PATH → R_HOME fallback
│
└─ subprocess.run(
["Rscript", "--vanilla", "-"],
input=script, # R code piped via stdin
capture_output=True,
text=True,
timeout=timeout
)
│
├─ stdout → parsed by caller (arcs, metrics, BN fields)
└─ stderr → included in RRuntimeError on non-zero exit
Session Management¶
Rscript Discovery¶
_find_rscript() locates the Rscript executable using a two-stage search:
- PATH search —
shutil.which("Rscript")covers the common case where R is on the system PATH. - R_HOME fallback — if the
R_HOMEenvironment variable is set, platform-specific candidate paths under it are checked withos.path.isfile. This handles installations where R is present but not on PATH (common in some CI environments).
The function returns None if Rscript cannot be found; callers that need to
raise do so explicitly.
Script Execution¶
run_r_script(script, timeout=60) provides the single execution primitive:
- The R script is passed via stdin (
--vanilla -). This avoids creating temporary files and makes the call parallel-safe. --vanilladisables R's.Rprofileand.Rhistoryso results are reproducible regardless of the user's R configuration.RNotAvailableErroris raised when_find_rscript()returnsNone.RRuntimeErroris raised on non-zero exit, with stderr included in the message.
Data Exchange¶
Results flow from R to Python as plain text on stdout. There are no binary formats, no shared memory, and no long-lived state in R.
Python → R: sample data¶
Sample data is handed to R as a temporary CSV datafile, never as generated R source literals:
| Function | Purpose |
|---|---|
write_r_datafile(sample, columns, path) |
write the sample to a CSV datafile |
datafile_to_r_code(path, columns, node_types, varname) |
return the read.csv line that loads it |
datafile_to_r_code maps node types to R column classes, so continuous
nodes are read as numeric vectors and categorical nodes as factor
vectors. Column names are kept verbatim (check.names = FALSE) so the node
names R reports back match those held in Python.
Writing a datafile matters for performance. Serialising a sample as inline R
literals (c(1.2, 3.4, ...)) makes the R parser build one length-1 vector per
value, and parsing cost grows faster than the sample size: an 8-variable
discrete sample takes 0.04 s to read at 1,000 rows but 54 s at 100,000 rows.
read.csv parses the same data in 0.2 s at 100,000 rows and 1.3 s at
1,000,000 rows. data_to_r_dataframe remains available for small samples and
documentation examples, but is not used for learning runs.
R → Python: text parsing¶
R scripts write results to stdout as delimited text:
| Use case | Format | Parsed by |
|---|---|---|
| Graph arcs | from\tto per line |
r_arcs_to_edges() |
| Structural metrics | tp\tfp\tfn\tshd single line |
bnlearn_compare() |
| BN parameters | NODE\t…, PARENTS\t…, COEF\t…, SD\t… blocks |
_parse_bn_output() |
bnlearn Utilities¶
CPDAG Conversion (bnlearn_cpdag)¶
Converts a PDAG to a CPDAG using bnlearn's cpdag() function. This
provides a reference implementation for testing CausalIQ's native
pdag_to_cpdag against bnlearn's.
The function:
- Builds an
empty.graphin R with the PDAG's nodes - Adds arcs and edges via
set.arcandset.edge - Calls
cpdag()and prints arcs as tab-separated pairs - Parses the output with
r_arcs_to_edges
Structural Comparison (bnlearn_compare)¶
Wraps bnlearn's compare() and shd() functions to compute four structural
metrics between a learned graph and a reference:
- tp — true positives (correct edges)
- fp — false positives (extra edges)
- fn — false negatives (missing edges)
- shd — Structural Hamming Distance
BN Import (bnlearn_import)¶
Loads a fitted bnlearn BN from an .rda file and converts it to a
causaliq_core.bn.BN object. The R script extracts node names, parent
lists, regression coefficients, and standard deviations, then writes them to
stdout as tagged lines. Python parses these lines into LinGauss
conditional distributions and assembles the BN.
Error Handling¶
Three exception types cover the error surface:
RNotAvailableError # Rscript not found on this system
RPackageNotAvailableError # required R package not installed
RRuntimeError # R process exited with non-zero code
All three inherit from Python's built-in Exception. Callers that want to
handle R absence gracefully should use is_r_available() or
is_r_package_available() as guards rather than catching exceptions.
Testing Strategy¶
Unit Tests¶
All r-module functions are covered by unit tests that monkeypatch
subprocess.run. This means:
- The full Python logic (argument building, output parsing, error wrapping) is covered without R being installed.
- Tests run in CI on all Python versions without any R dependency.
Integration Tests (r_integration marker)¶
Tests marked r_integration call real R. They are:
- Skipped automatically when
is_r_available()returnsFalse - Excluded from the main CI pipeline (run only in the dedicated
r-integration.ymlworkflow) - Excluded from the 100% coverage requirement
The r_integration marker pattern will be reused for future external-tool
integrations (e.g. java_integration for Tetrad).
To run integration tests locally (requires R and bnlearn):
Prerequisites¶
Only a standard CRAN R installation is required. No additional Python
packages, no Rtools, no make:
Install bnlearn from within R:
Verify that R is available: