Metadata-Version: 2.5
Name: tabdgp
Version: 0.2.0
Summary: A data-generating process for grouped and flat tables, to be matched to a registry of real tables
Project-URL: Repository, https://github.com/adkipnis/tabdgp
Project-URL: Issues, https://github.com/adkipnis/tabdgp/issues
Author-email: Alex Kipnis <adkipnis@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: numpy<3,>=2.3
Requires-Dist: pydantic<3,>=2.12
Description-Content-Type: text/markdown

[![CI](https://github.com/adkipnis/tabdgp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/adkipnis/tabdgp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/tabdgp)](https://pypi.org/project/tabdgp/)
[![Python](https://img.shields.io/pypi/pyversions/tabdgp)](https://github.com/adkipnis/tabdgp/blob/main/pyproject.toml)
[![Licence](https://img.shields.io/badge/licence-MIT-blue)](https://github.com/adkipnis/tabdgp/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23322845.svg)](https://doi.org/10.5281/zenodo.23322845)

# TabDGP

A data-generating process (DGP) for grouped and flat tables.

TabDGP simulates tabular datasets from a random structural causal model (SCM) and aims to
reproduce the quirks of real data. Each table comes with the graph and the settings that
generated it.

> **Alpha.** Release 0.2 draws grouped and flat tables from defaults that are round guesses;
> the rest is planned below. Before 1.0, a release may change the dataset a key draws.

## Highlights

- **Grouped or flat.** One to three grouping factors by default, nested or crossed, with 2 to
  400 groups each. A covariate varies by row or is constant within the groups of one factor.
  `Hyperprior.flat()` draws none.
- **White-box.** Each dataset carries its graph, latent nodes, column metadata and hyperparameters.
- **Reproducible.** A dataset is a pure function of its key (a seed and an index) and the
  hyperprior, whatever batch or worker draws it.
- **Overridable.** Replace any default distribution by a point value or another distribution.

## Install

```
pip install tabdgp
```

## Quickstart

```python
from tabdgp import Hyperprior, draw

hyperprior = Hyperprior.grouped(rows=100, design_columns=5)  # two overrides on the grouped preset
dataset = draw(seed=0, index=0, hyperprior=hyperprior)  # the key: a seed and an index
unit = dict(zip(dataset.graph.names, dataset.graph.unit))  # per row, or per group of a factor
for name, column in dataset.metadata.items():
    print(name, column.type, unit[name], dataset.columns[name][:3].round(2))
print(len(dataset.latent), 'latent nodes,', dataset.graph.parents.sum(), 'edges')
```

```text
g0 categorical g0 [4 5 2]
g1 categorical g1 [ 6 22 29]
g2 categorical g2 [7 7 5]
x0 binary g0 [1 1 1]
x1 binary row [1 1 1]
x2 continuous row [0.36 0.69 0.15]
x3 binary row [0 0 0]
x4 binary row [0 1 0]
7 latent nodes, 16 edges
```

## Planned

- **Quirk axes:** group confounding, rare levels, ties, bounds, near dependence and more.
- **Matched defaults**, fitted to and checked against
  [mixedbench](https://github.com/adkipnis/mixedbench)'s real grouped tables, then widened.
- **An outcome node**, optional, for white-box misspecified datasets, with within-group time and
  a binary treatment.

## Learn more

[`CONTEXT.md`](https://github.com/adkipnis/tabdgp/blob/main/CONTEXT.md) defines the vocabulary.

## Contributing

Issues and pull requests are welcome; see
[`CONTRIBUTING.md`](https://github.com/adkipnis/tabdgp/blob/main/CONTRIBUTING.md).

## Citing

Please cite the release you used, from
[`CITATION.cff`](https://github.com/adkipnis/tabdgp/blob/main/CITATION.cff) or GitHub's "Cite
this repository".

## Licence

[MIT](https://github.com/adkipnis/tabdgp/blob/main/LICENSE).
