COREX Documentation

📖 Overview

"Causality is not assumed, inferred, or interpreted — it is survived or rejected under systematic perturbation tests."

COREX is a deterministic, graph-free, model-agnostic computational framework that treats causality as an empirically testable robustness property rather than an assumed structural characteristic. The framework implements a four-axis evaluation pipeline — Statistical Stability, Representation Invariance, Intervention Consistency, and Domain Robustness — and fuses their outputs through a weighted scoring function to produce a calibrated causal classification.

Contemporary machine learning systems routinely exploit shortcut correlations embedded in training distributions — associations that collapse the moment data distribution shifts, feature encodings change, or interventions are applied. COREX provides a principled audit pipeline to classify any observed X → Y relationship as CAUSAL, SPURIOUS, or REPRESENTATION ARTIFACT.

🏗️ 4-Module Architecture

Module 01 — Statistical Stability (S)

Tests whether P(Y|X) remains invariant across independently drawn subpopulations of the data. Performs random stratified partitioning into k folds, estimates conditional distributions using kernel density estimation, and computes pairwise KL divergence across fold estimates.

S = 1 - mean_{i≠j} KL[P(Y|X, D_i) ‖ P(Y|X, D_j)]

Module 02 — Representation Invariance (R)

Evaluates whether the observed relationship persists when the feature representation of X is subjected to a structured family of transformations: linear projections, nonlinear embeddings, Gaussian noise injection, feature dropout, and PCA compression.

R = 1 - (1/|Φ|) Σ_φ ||P(Y|X) - P(Y|φ(X))||₁

Module 03 — Intervention Consistency (I)

Simulates causal interventions by applying controlled perturbations to X and observing the consistency of the downstream effect on Y. Uses propensity-score matched observational comparisons and synthetic counterfactual generation.

I = Consistency(do(X=x₁)→Y₁, do(X=x₂)→Y₂)

Module 04 — Domain Robustness (D)

Evaluates whether the predictive relationship generalizes across environments with distinct data-generating distributions. Constructs pseudo-environments through clustering in covariate space and assesses stability via coefficient of variation.

D = 1 - CV(P(Y|X, e)) over e ∈ E

📐 Core Equations

📊 COREX Scoring Function

COREX = w₁·S + w₂·R + w₃·I + w₄·D

Decision Thresholds

📦 Installation

pip install corex

# From source
git clone https://github.com/gitdeeper12/COREX.git
cd COREX
pip install -e .

Core Dependencies: numpy, scipy

🔧 API Reference

from corex import CausalEvaluator

# Initialize evaluator
evaluator = CausalEvaluator()

# Evaluate relationship between X and Y
result = evaluator.evaluate(X, y)

# Access results
print(result.label)         # "CAUSAL" | "SPURIOUS" | "REPRESENTATION_ARTIFACT"
print(result.corex_score)   # float in [0, 1]
print(result.breakdown)     # {"S": 0.91, "R": 0.88, "I": 0.85, "D": 0.90}

Parameters

🧩 Core Modules

📊 Validation Summary

👤 Author

📝 Citation

"Causality is not assumed — it is survived."