Metadata-Version: 2.4
Name: dagsampler
Version: 0.4.0
Summary: Configurable causal DAG simulator for synthetic mixed-type data and CI test benchmarks
Author: Pavel Averin
License-Expression: MIT
Project-URL: Homepage, https://github.com/averinpa/constraint-based-causal-discovery-suite
Project-URL: Documentation, https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/
Project-URL: Issues, https://github.com/averinpa/constraint-based-causal-discovery-suite/issues
Project-URL: Source, https://github.com/averinpa/constraint-based-causal-discovery-suite/tree/main/dagsampler
Project-URL: Changelog, https://github.com/averinpa/dagsampler/blob/main/CHANGELOG.md
Keywords: causal-inference,causal-discovery,conditional-independence,dag,simulation,synthetic-data,benchmarks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.3
Requires-Dist: networkx>=2.6
Requires-Dist: scipy>=1.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ipykernel>=6.29.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo>=2024.1; extra == "docs"
Requires-Dist: myst-parser>=2; extra == "docs"
Requires-Dist: sphinx-autoapi>=3; extra == "docs"
Requires-Dist: linkify-it-py>=2; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0; extra == "examples"
Requires-Dist: matplotlib>=3.7; extra == "examples"
Dynamic: license-file

# dagsampler

> [!IMPORTANT]
> **This repository is archived.** `dagsampler` has moved to the
> [constraint-based-causal-discovery-suite](https://github.com/averinpa/constraint-based-causal-discovery-suite)
> umbrella, where it lives at
> [`dagsampler/`](https://github.com/averinpa/constraint-based-causal-discovery-suite/tree/main/dagsampler).
>
> The PyPI package name **`dagsampler`** is unchanged — `pip install
> dagsampler` continues to work, with future releases (0.2.0+)
> published from the suite repo. This archive is kept read-only for
> historical reference; the v0.1.0 source remains here at the last
> commit before the move.

[![PyPI version](https://img.shields.io/pypi/v/dagsampler.svg)](https://pypi.org/project/dagsampler/)
[![Python versions](https://img.shields.io/pypi/pyversions/dagsampler.svg)](https://pypi.org/project/dagsampler/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-averinpa.github.io-blue.svg)](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/)

Configurable causal DAG simulator for synthetic mixed-type data and CI test benchmarks.

[Documentation](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/) · [Changelog](CHANGELOG.md)

## What it provides

- `CausalDataGenerator` class for configurable simulation
- Support for `custom` and `random` DAGs
- Mixed continuous/binary/categorical nodes (configurable categorical cardinality)
- Structural forms: `linear`, `polynomial`, `interaction`, `sigmoid`, `cos`, `sin`, `stratum_means`
- Optional element-wise `post_transform` (`tanh`, `sin`, `cos`, `exp_neg_abs`, `sqrt_abs`, `relu`, `sign`)
- Cross-type mechanisms:
  - continuous -> categorical (`categorical_model.name = "threshold"`), with an opt-in standardized (design-A) threshold mode (`threshold_standardized`) that discretizes a unit-variance linear-Gaussian latent at equal-probability cutpoints
  - categorical -> continuous (`functional_form.name = "stratum_means"`, including mixed-parent cases with `metric_weights`)
- Opt-in spread-controlled softmax/logistic weights (`softmax_weight_mode = "spread"`) for a detectable, balance-preserving logit contrast (default `"gaussian"` preserves legacy behaviour)
- Noise models:
  - additive (`gaussian`, `student_t`, `gamma`, `exponential`, `laplace`, `cauchy`, `uniform`)
  - multiplicative (`gaussian`, `student_t`, `gamma`, `exponential`)
  - heteroskedastic (`abs_first_parent`, `abs_parent_plus_const`, `mean_abs_plus_const`); base distribution selectable via `dist` (`gaussian` default, `student_t`, `laplace`, `uniform`, `gamma`, `exponential`)
  - shape / tail-shape (`skew_first_parent`, `skew_tanh_first_parent`, `skew_mean_parents`) — a parent drives the noise skewness with mean and variance held fixed (a higher-moment edge)
- Random weight sampling controls (including exclusion band around zero)
- `force_uniform_marginals` for balanced exogenous binary / categorical draws
- Template helpers (`chain_config`, `fork_config`, `collider_config`, `independence_config`)
- Reproducibility via `seed_structure` and `seed_data` (or single `seed`)
- Optional d-separation CI oracle output (`store_ci_oracle=true`)

## Installation

From PyPI:

```bash
pip install dagsampler
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv venv
source .venv/bin/activate
uv pip install dagsampler
```

From GitHub (latest `main`):

```bash
uv pip install "dagsampler @ git+https://github.com/averinpa/dagsampler.git"
```

## Quick start (Python API)

```python
from dagsampler import CausalDataGenerator

config = {
    "simulation_params": {"n_samples": 200, "seed": 42},
    "graph_params": {
        "type": "custom",
        "nodes": ["X", "Y", "Z1"],
        "edges": [["X", "Z1"], ["Y", "Z1"]],
    },
}

result = CausalDataGenerator(config).simulate()
data = result["data"]
dag = result["dag"]
params = result["parametrization"]
```

## CLI

The package exposes `dagsampler-generate`.

```bash
dagsampler-generate \
  --config config.json \
  --output dataset.csv \
  --params-out params.json \
  --edges-out edges.json
```

`config.json` must contain the same structure used by `CausalDataGenerator`.

## Learn more

- [Documentation](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/) — full reference for every config option, mechanism, and noise model.
- [Tutorial](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/tutorial.html) — narrative walkthrough.
- [How-to guides](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/howto/) — task-focused recipes.
- [Explanation](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/explanation/) — model formulations and design rationale.
- [API reference](https://averinpa.github.io/constraint-based-causal-discovery-suite/dagsampler/reference/) — every public function and class.
- [`examples/`](examples/) — runnable notebooks.

## Development

```bash
uv pip install -e ".[dev]"
pytest -q
```
