Metadata-Version: 2.4
Name: CausalScience
Version: 0.1.0a14
Summary: Graph-based causal identification, mean estimation, and qualified UCA inference
Author: Yonghan Jung
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-MIT.txt
License-File: LICENSING.md
License-File: src/causalscience/ENGINE_LICENSE.txt
License-File: src/causalscience/ENGINE_SOURCES.json
Requires-Dist: numpy<3,>=1.24
Requires-Dist: pandas<4,>=2
Requires-Dist: networkx<4,>=2.8
Requires-Dist: scipy<2,>=1.10
Requires-Dist: scikit-learn<2,>=1.2
Requires-Dist: xgboost<4,>=2
Requires-Dist: osqp<2,>=0.6
Requires-Dist: tabulate<1,>=0.9
Requires-Dist: pyperclip<2,>=1.8
Requires-Dist: dill<0.5,>=0.3
Provides-Extra: plot
Requires-Dist: matplotlib<4,>=3.8; extra == "plot"
Requires-Dist: pyvis<1,>=0.3; extra == "plot"
Requires-Dist: plotly<7,>=5; extra == "plot"
Dynamic: license-file

# CausalScience

CausalScience provides structural causal model (SCM) simulation, graph-based
identification and causal-effect estimation. This source prepares the
**0.1.0a14 release candidate** with 22 public exports, including `estimate_capo`
and CSCM_capo Simpson support. Both source and installed imports use
`causalscience`; runtime files are under `src/causalscience/`.

The GitHub repository and local checkout directory are named CausalScience.
Historical snapshots and the CausalEngine Noncommercial License retain their original names.

<a id="cscm-quickstart"></a>
<a id="graphs-and-data"></a>
<a id="graph-free-point-estimators-010a13"></a>

## Choose your task

| What you have or need | Start here |
|---|---|
| Observed data and an assumed back-door/front-door/sequential formula | [Graph-free estimators](docs/graphless-estimators.md): `estimate_bd`, `estimate_sbd`, `estimate_fd`, `estimate_uca` |
| A causal graph and observed data | [Identify and estimate](docs/internal-library.md#identify-and-estimate-a-mean): `identify_query`, `fit_query_mean` |
| Simulated tasks and conditional average potential outcome (CAPO) targets | [Generators and truth](docs/internal-library.md#scm-generation-and-truth): `BDSCM`, `CSCM`, `CSCM_capo` |
| Average treatment effect (ATE) or conditional average treatment effect (CATE) | [Paired effects](docs/internal-library.md#ate-and-cate): `estimate_ate`, `estimate_cate` |
| Learn conditional outcome means for each treatment arm | [CAPO prediction](docs/internal-library.md#capo-prediction-unreleased-source-api): a14 candidate `estimate_capo` |
| Code to change | [Implementation map](docs/internal-library.md#implementation-map) or [Wiki](docs/wiki/README.md) |

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

<a id="internal-lab-use"></a>
<a id="causalengine-package-installation"></a>

## Install

Python 3.11+ is required. To install or update the latest **published** release:

```bash
python -m pip install --upgrade causalscience
python -m causalscience.demo
```

Check `python -c "import causalscience; print(causalscience.__version__)"` before
using version-specific features. Public a13 does not contain the new CAPO API or
CSCM_capo Simpson extension. For the a14 candidate, install its reviewed wheel
or this checkout in a project environment:

```bash
python -m pip install /path/to/causalscience-0.1.0a14-py3-none-any.whl
# Alternatively, from this source checkout:
python -m pip install .
```

Both routes use `import causalscience`. See [installation](docs/installation.md)
for environment setup and editable development. Candidate preparation does not
itself publish a release to PyPI.

## 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.

```python
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.

<a id="code-structure-wiki"></a>
<a id="indexed-tian-identification-and-finite-kpp-compilation"></a>
<a id="tutorials"></a>
<a id="references"></a>
<a id="documentation-and-maintained-tutorial"></a>

## CAPO estimator in the a14 candidate

`estimate_capo` learns one treatment regime's conditional expected outcome.
Call it for actions 0 and 1 to obtain separate CAPO predictors. This API requires
the a14 candidate or later and `from causalscience import estimate_capo`; it is
**not included in public `0.1.0a13`**. See the
[complete source example and target definitions](docs/graphless-estimators.md#conditional-potential-outcome-prediction-unreleased-source-api).
The existing public six-API tutorial retains its original scope.

## Read more

- [Document](docs/internal-library.md): workflows, assumptions, API contracts and implementation map.
- [Six-API tutorial](tutorials/current-workflow.md): four graph-free means plus paired ATE/CATE.
- [Wiki](docs/wiki/README.md): detailed modules and method routes.
- [Indexed compiler reference](docs/indexed-identification.md): lower-level symbolic/finite tools.
- [Whole-call benchmark](docs/estimator-benchmark.md) and [shared-fit component pilot](docs/uca-benchmark.md): different timing scopes.
- [Historical validation](docs/validation-history.md): dated version-specific checks.

Browser editions: [Document](https://causalscience.ai/docs/causalengine/),
[Wiki](https://causalscience.ai/docs/causalengine/wiki/),
[Tutorial](https://causalscience.ai/docs/causalengine/tutorial/).

<a id="current-module-map"></a>

## Repository layout

| Directory | Responsibility |
|---|---|
| `src/causalscience/` | Single canonical runtime: public APIs, SCMs, criteria, score engine and HTML tool |
| `tests/` / `tests/checkout/` | Installed contracts / source and developer-tool regressions |
| `tutorials/` | Maintained walkthrough, demos, benchmarks and named SCM examples; notebooks are labeled historical |
| `docs/` | User guide, Wiki, assumptions, benchmarks and provenance |
| `experimental/backdoor_scm/` | Separate research component, outside the public distribution |
| `archived/` | Preserved historical material |

<a id="source-development-and-compatibility"></a>

Source developers install the checkout with `python -m pip install .`, or
`python -m pip install --no-deps --no-build-isolation -e .` after dependencies are
installed. Source and installed packages use `import causalscience` and `python -m causalscience.demo`.
Source checks use `PYTHONPATH=src python -B -m unittest discover -s tests/checkout -v`.
Old `causalengine.*` and flat imports such as `import SCM` are not aliases; use `causalscience.*` imports.
The [compatibility notes](docs/internal-library.md#source-development-and-compatibility)
cover external research scripts and frozen snapshots.

<a id="qualified-score-inference"></a>
<a id="engine-snapshots-and-license-scope"></a>
<a id="status-and-limitations"></a>

## 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](docs/internal-library.md#limitations).

[LICENSE](LICENSE) is the CausalEngine Noncommercial License 1.0.
[LICENSING.md](LICENSING.md) preserves prior MIT grants and separate rights.
[Engine provenance](src/causalscience/ENGINE_SOURCES.json) records current canonical
hashes and earlier snapshots.
