CausalScience

CausalScience is a functional distribution of the CausalEngine library from source commit 4bdf0bc38445b31a50cd384f7cbf766af23b2a23.

Install with python -m pip install CausalScience and import with import causalscience. For example: from causalscience import CSCM, estimate_uca. This alpha release is version 0.1.0a13 and requires Python 3.11 or later.

The upstream CausalEngine repository and license notices retain their original names. Upstream documentation may use causalengine; use causalscience as the import and module-command prefix for this distribution.

CausalEngine is a Python library for structural causal model (SCM) simulation, graph-based identification, and causal-effect estimation. It is an alpha research package (0.1.0a13). Public imports use causalscience; all runtime source is in src/causalscience/.

Choose your task

A graph-free estimator executes your chosen identifying formula. It does not infer or verify a causal graph from the data.

Install

Use Python 3.11 or later in your project environment:

python -m pip install CausalScience
python -m causalscience.demo

Optional source-checkout installation requires access to the upstream repository; from this distribution's source archive or prepared checkout, use python -m pip install ..

The installed demo runs from any directory. For source development, use python -m pip install --no-deps --no-build-isolation -e . once the declared dependencies are installed. See installation for virtual environments, reproducible older pins and wheel delivery.

One complete example

This binary synthetic example estimates the mean under action A=1. It is not an ATE; the adjustment assumption is supplied by the caller.

import numpy as np
import pandas as pd
from causalscience import estimate_bd

rng = np.random.default_rng(11)
c = rng.binomial(1, .5, 1200)
a = rng.binomial(1, .2 + .5*c)
y = rng.binomial(1, .1 + .3*c + .4*a)
data = pd.DataFrame(dict(C=c, A=a, Y=y))
fit = estimate_bd(data, treatment="A", outcome="Y", adjustment=["C"],
    action=1, schema={name: "binary" for name in data}, num_boost_round=30)
assert fit["estimation_status"] == "ACCEPT"
assert fit["graph_verification"] == "not_run"
assert fit["causal_interval"] is None
print(fit["estimate"])

Defaults use Unified Covariate Adjustment (UCA) full scores with XGBoost backward regressions and separate normalized minimum-L2 weights. Graph-based default fitting checks the Fixed-partition Multilinearity Criterion (FMC), then the Multilinearity Criterion (MC) if needed; graph-free fitting uses the supplied functional. Always inspect status and diagnostics. Successful fitting does not verify overlap, causal assumptions, population consistency or causal confidence-interval coverage.

Read more

• Document: workflows, assumptions, API contracts and implementation map.
• Six-API tutorial: four graph-free means plus paired ATE/CATE.
• Wiki: detailed modules and method routes.
• Indexed compiler reference: lower-level symbolic/finite tools.
• Whole-call benchmark and shared-fit component pilot: different timing scopes.
• Historical validation: dated version-specific checks.

Browser editions: Document, Wiki, Tutorial.

Repository layout

After installing this distribution, run its adapted public API checks with python -B -m unittest discover -s tests -p test_public_api.py -v from the source archive root. Other upstream tests and tutorials retain their original namespace and need namespace adaptation before running against this distribution. Old flat imports such as import SCM are retired; use causalscience.* imports. The compatibility notes cover external research scripts and frozen snapshots.

Boundaries and license

Default full-score execution supports declared discrete actions; continuous fixed-point actions and unsupported compiler/design cases are declined. CATE requires a supported baseline anchor and learning assumptions; it returns predictions, not automatic pointwise causal intervals. CSCM_capo has fast direct truth lookup but conditional centering can make mixed-X generation expensive. See limitations.

LICENSE is the CausalEngine Noncommercial License 1.0. LICENSING.md preserves prior MIT grants and separate rights. Engine provenance records current canonical hashes and earlier snapshots.