Metadata-Version: 2.4
Name: superstats
Version: 0.0.1
Summary: Estimating time-varying parameters with deep learning
Author: Lukas Schumacher and Stefan Radev
License: MIT License
        
        Copyright (c) 2026 Lukas Schumacher
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax>=0.11.0
Requires-Dist: bayesflow>=2.0.12
Requires-Dist: numba>=0.63.1
Requires-Dist: ipywidgets>=8.1.8
Provides-Extra: all
Requires-Dist: ipython; extra == "all"
Requires-Dist: ipykernel; extra == "all"
Requires-Dist: jupyter; extra == "all"
Requires-Dist: jupyterlab; extra == "all"
Requires-Dist: line-profiler; extra == "all"
Requires-Dist: nbconvert; extra == "all"
Requires-Dist: pre-commit; extra == "all"
Requires-Dist: ruff; extra == "all"
Requires-Dist: myst-nb~=1.2; extra == "all"
Requires-Dist: numpydoc~=1.8; extra == "all"
Requires-Dist: pydata-sphinx-theme~=0.16; extra == "all"
Requires-Dist: sphinx~=8.1.3; extra == "all"
Requires-Dist: sphinx-polyversion==1.1; extra == "all"
Requires-Dist: sphinx_design~=0.6; extra == "all"
Requires-Dist: sphinxcontrib-bibtex~=2.6; extra == "all"
Requires-Dist: snowballstemmer~=2.2.0; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: pytest-rerunfailures; extra == "all"
Requires-Dist: pytest-xdist; extra == "all"
Provides-Extra: dev
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: line-profiler; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: cuda
Requires-Dist: jax[cuda13]>=0.11.0; extra == "cuda"
Provides-Extra: docs
Requires-Dist: myst-nb~=1.2; extra == "docs"
Requires-Dist: numpydoc~=1.8; extra == "docs"
Requires-Dist: pydata-sphinx-theme~=0.16; extra == "docs"
Requires-Dist: sphinx~=8.1.3; extra == "docs"
Requires-Dist: sphinx-polyversion==1.1; extra == "docs"
Requires-Dist: sphinx_design~=0.6; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex~=2.6; extra == "docs"
Requires-Dist: snowballstemmer~=2.2.0; extra == "docs"
Provides-Extra: test
Requires-Dist: nbconvert; extra == "test"
Requires-Dist: ipython; extra == "test"
Requires-Dist: ipykernel; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-rerunfailures; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Dynamic: license-file

<div align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="img/superstats-long-light.svg">
  <source media="(prefers-color-scheme: light)" srcset="img/superstats-long-dark.svg">
  <img alt="Overview graphic  of superstats" src="./img/superstats-long-light.svg">
</picture>
</div>
<br>

[![Tests](https://img.shields.io/github/actions/workflow/status/LuSchumacher/superstats/tests.yml?branch=main&style=for-the-badge&label=Tests)](https://github.com/LuSchumacher/superstats/actions/workflows/tests.yml)
[![Coverage](https://img.shields.io/codecov/c/github/LuSchumacher/superstats/main?style=for-the-badge&label=Coverage)](https://app.codecov.io/gh/LuSchumacher/superstats/tree/main)
[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen?style=for-the-badge)](https://github.com/LuSchumacher/superstats/issues)

## What is Superstats?

Superstats is a Python library for simulation and Bayesian estimation of dynamic models with time-varying parameters.

The library aims to be domain-agnostic, but for now focuses on cognitive modeling. It provides users with:

- A lean API for non-stationary models: specify which parameters change across time, and how.
- A library of transition models: random walks, ARs, jump processes, mixtures, and Gaussian processes.
- Built-in cognitive models, plus a plug-in interface for any simulator of your own.
- Amortized Bayesian inference built on top of [BayesFlow](https://github.com/bayesflow-org/bayesflow): train once, then quickly fit every data set.
- Diagnostics and visualization tools for every critical step in a principled Bayesian workflow.

## Conceptual overview

<div align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="img/superstats-arch-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="img/superstats-arch-light.svg">
  <img alt="Overview graphic  of superstats" src="./img/superstats-arch-light.svg">
</picture>
</div>
<br>

A superstatistical model has two levels. A **low-level observation model** $\mathcal{G}$ generates the data at each time step.
A **high-level transition model** $\mathcal{T}$ describes how the parameters of that model evolve:

$$\theta_t = \mathcal{T}(\theta_{0:t-1}; \eta) \qquad x_t = \mathcal{G}(x_{1:t-1}; \theta_t, \lambda)$$

`superstats` trains a neural estimator on simulations from any generative model of this form and returns the joint posterior $p(\theta_{1:T}, \eta, \lambda \mid x_{1:T})$ over all time-varying parameters $\theta_{1:T}$ and time-invariant parameters $(\eta, \lambda)$.


## Install

We support Python 3.12 to 3.14. Install the latest version from source:

```bash
pip install superstats
```

If you want the latest features, you can install from source:

```bash
pip install git+https://github.com/LuSchumacher/superstats.git@dev"
```

## Getting started

A complete workflow using a diffusion decision model whose drift rate and thresold are free to vary across time:

```python
import superstats as sup

# 1. Assume which parameters move, and how
joint_prior = sup.JointPrior(
    v=sup.transition.RandomWalk(),
    a=sup.transition.RandomWalk(),
    tau=sup.Prior(dist="halfnormal", scale=0.15),
    bias=0.5
)

# 2. Plug in an observation model (any simulator will do)
generative_model = sup.GenerativeModel(
    prior=joint_prior,
    model=sup.simulation.sample_ddm,
    missing="random",
    contamination="random_choice"
)

# 3. Train a neural approximator
workflow = sup.Workflow(simulator=generative_model)
history = workflow.fit_online(num_steps=100, epochs=20, batch_size=16)

# 4. Fit any number of data sets, instantly
samples = workflow.sample(data=rt_data, num_samples=250)
```

It is highly recommended to use a GPU for fast training and inference. For an in-depth exposition, check out the examples below.

## Examples

| Notebook | What it covers |
|---|---|
| [Minimal workflow demo](examples/minimal_workflow_demo.ipynb) | Short path from prior to posterior |
| Extensive workflow demo | Coming soon |

More examples are always welcome. If you have an application, please consider opening a pull request.


## Contributing

Contributions are welcome. Install from source and see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Reporting issues

Please open an issue on [GitHub](https://github.com/LuSchumacher/superstats/issues) for bug reports and
feature requests. For questions about the underlying inference machinery, the
[BayesFlow Forums](https://discuss.bayesflow.org/) are a good place to ask.

## Citation

If you use `superstats` in your research, please cite:

```bibtex
@article{schumacher2023neural,
  title   = {Neural superstatistics for {B}ayesian estimation of dynamic cognitive models},
  author  = {Schumacher, Lukas and B{\"u}rkner, Paul-Christian and Voss, Andreas and K{\"o}the, Ullrich and Radev, Stefan T.},
  journal = {Scientific Reports},
  volume  = {13},
  number  = {1},
  pages   = {13778},
  year    = {2023},
  doi     = {10.1038/s41598-023-40278-3}
}

@article{schumacher2025validation,
  title   = {Validation and comparison of non-stationary cognitive models: A diffusion model application},
  author  = {Schumacher, Lukas and Schnuerch, Martin and Voss, Andreas and Radev, Stefan T.},
  journal = {Computational Brain \& Behavior},
  volume  = {8},
  number  = {2},
  pages   = {191--210},
  year    = {2025},
  doi     = {10.1007/s42113-024-00218-4}
}
```

## License

MIT
