R bindings for the fastcit-core Rust library: data-bound conditional-independence (CI) tests with one uniform surface. Bind a data.frame once, then run any number of X ⟂ Y | Z queries against it. See the repository README for the cross-language story.

Install

Requires Rust 1.85 or newer (rustup). From the repository root:

# install.packages("devtools")
devtools::install("crates/ci-r")

Benchmarking note: devtools::load_all() / rextendr::document() compile a debug build. For benchmarks, install a release build: NOT_CRAN=true R CMD INSTALL crates/ci-r and library(fastcit).

Quick start

library(fastcit)

set.seed(0)
df <- data.frame(
  A = sample(0:1, 500, TRUE), B = sample(0:2, 500, TRUE),   # integer -> discrete
  X = rnorm(500), Y = rnorm(500), Z = rnorm(500)            # double  -> continuous
)

data <- dataset(df)        # bind once; factor/character columns are coded for you

chi <- chi_squared(data)                    # Yates' correction on by default
res <- run_test(chi, "A", "B")              # list(statistic, p_value, dof, effect_size)
is_independent(chi, "A", "B", significance_level = 0.05)

fz <- fisher_z(data)                        # the pcalg/causal-learn standard test
run_test(fz, "X", "Y", c("Z"))              # res$dof is NULL for continuous tests

Column kinds are inferred: integer/logical/factor/character columns are discrete, double columns continuous. Missing values are rejected when the dataset is bound — na.omit(df) (or impute) first. Every factory also accepts a raw data.frame directly (chi_squared(df)).

Available tests

Factory Data Config Independent when
chi_squared(data, yates = TRUE) discrete yates p >= alpha
log_likelihood(data, yates = TRUE) discrete yates p >= alpha
cressie_read(data, yates = TRUE) discrete yates p >= alpha
freeman_tukey(data, yates = TRUE) discrete yates p >= alpha
modified_likelihood(data, yates = TRUE) discrete yates p >= alpha
pearson_correlation(data) continuous — p >= alpha
fisher_z(data) continuous — p >= alpha
gcm(data) continuous — p >= alpha
pillai(data) mixed — p >= alpha
pearson_equivalence(data, delta_threshold = 0.1) continuous delta_threshold p < alpha (TOST)
hsic(data, kernel = NULL, bandwidth = "heuristic", null_dist = "gamma", n_permutations = 100L, seed = 0) continuous kernel, bandwidth, null p >= alpha (no z)
kci(data, kernel = NULL, bandwidth = "heuristic", epsilon = 1e-3) continuous kernel, bandwidth, epsilon p >= alpha

Kernel tests take kernel = NULL (default RBF), one rbf_kernel(length_scale) / linear_kernel(), or a named list of them keyed by column:

df <- data.frame(X = rnorm(100), Y = rnorm(100), Z = rnorm(100))
run_test(hsic(df, kernel = rbf_kernel(2)), "X", "Y")
run_test(kci(df, kernel = list(X = linear_kernel())), "X", "Y", "Z")

gcm() and pillai() use linear residualization (pgmpy’s Pillai default is a random forest); in pillai() conditioning variables are one-hot encoded minus one level and a categorical X/Y becomes K - 1 level indicators fitted with a linear probability model. Degenerate inputs raise errors instead of NaN. Conditioning sets whose columns are linearly dependent (duplicate or nested categorical variables, a constant column) raise a degenerate-data error, whereas pgmpy fits them by least squares. When Z is not empty and n - columns == max(p, q), pillai() returns p = 0 (“dependent”), as pgmpy does. When n - columns < max(p, q), it raises an error. gcm() is continuous-only; pillai() accepts mixed factor and numeric columns.

is_independent() applies each test’s own decision rule, so the caller never writes it — including the equivalence test’s inverted rule.

Integration

# pcalg: any test adapts to the indepTest(x, y, S, suffStat) callback shape.
indepTest <- as_pcalg(fisher_z(dataset(df)))
# pcalg::pc(suffStat = list(), indepTest = indepTest, labels = colnames(df), alpha = 0.05)

# base-R / bnlearn-style: an htest object.
ci_test(chi, "A", "B")

Testing

rextendr::document("crates/ci-r")   # recompile + regenerate wrappers
devtools::test("crates/ci-r")       # includes the shared 80-case golden fixture
archive <- devtools::build("crates/ci-r", manual = FALSE, vignettes = FALSE)
devtools::check_built(archive, args = "--no-manual", error_on = "warning")

The source package includes locked, vendored Rust dependencies plus synchronized copies of fastcit-core and the golden fixture. From the repository root, refresh and verify those project-owned copies with:

python crates/ci-r/tools/sync_package_assets.py --sync
python crates/ci-r/tools/sync_package_assets.py --check