Metadata-Version: 2.4
Name: CausalScience
Version: 0.1.0a13
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 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/`**.

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

Use Python 3.11 or later in your project environment:

```bash
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](docs/installation.md) 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.

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

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

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](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.
