Metadata-Version: 2.4
Name: pilotr
Version: 0.3.0
Summary: Simulate experimental and behavioural data from a portable design specification (cross-language with the R package of the same name).
Author-email: Pablo Bernabeu <pcbernabeu@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://pablobernabeu.github.io/pilotr/
Project-URL: Repository, https://github.com/pablobernabeu/pilotr
Project-URL: Documentation, https://pablobernabeu.github.io/pilotr/python/
Project-URL: Issues, https://github.com/pablobernabeu/pilotr/issues
Keywords: simulation,power analysis,mixed-effects,experimental design,behavioural science
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: power
Requires-Dist: scipy>=1.7; extra == "power"
Provides-Extra: mixed
Requires-Dist: scipy>=1.7; extra == "mixed"
Requires-Dist: statsmodels>=0.13; extra == "mixed"
Requires-Dist: pandas>=1.3; extra == "mixed"
Provides-Extra: dev
Requires-Dist: scipy>=1.7; extra == "dev"
Requires-Dist: statsmodels>=0.13; extra == "dev"
Requires-Dist: pandas>=1.3; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# pilotr (Python)

<!-- badges: start -->
[![PyPI](https://img.shields.io/pypi/v/pilotr.svg)](https://pypi.org/project/pilotr/)
[![python-tests](https://github.com/pablobernabeu/pilotr/actions/workflows/python-tests.yml/badge.svg)](https://github.com/pablobernabeu/pilotr/actions/workflows/python-tests.yml)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21266313.svg)](https://doi.org/10.5281/zenodo.21266313)
<!-- badges: end -->

Python implementation of pilotr. It simulates experimental and behavioural data from a
portable JSON design specification.

This is the feature-parity twin of [the R package](https://pablobernabeu.github.io/pilotr/r/) of
the same name. The two share the design specification and the random-number generator, so the
same specification and seed produce identical data in either language, bit for bit apart from a
documented tolerance of a few units in the last place where an unrounded response family applies
`exp()` or `log()` to the linear predictor. See the
[project README](https://github.com/pablobernabeu/pilotr) for the full toolkit (the no-code
app, the R package and the specification format).

## Install

```bash
pip install pilotr             # core engine (pure Python, dependency-free)
pip install "pilotr[power]"    # + scipy, for the simulation-based power demo
pip install "pilotr[mixed]"    # + scipy, statsmodels and pandas, for crossed mixed-effects power
```

Requires Python 3.9 or later. The generative core has no dependencies.

For development, install from a checkout of the repository instead. Clone
<https://github.com/pablobernabeu/pilotr> and run `pip install .` (or `pip install ".[dev]"`)
from the `python` directory.

## Quick start

A design specification is an ordinary dictionary, so the shortest example needs nothing beyond
the package itself.

```python
from pilotr import simulate

spec = {
    "name": "two_group", "seed": 2024,
    "units": {"subject": {"n": 64}},
    "factors": [{"name": "group", "levels": ["control", "treatment"],
                 "contrasts": {"effect": [-0.5, 0.5]}, "between": "subject"}],
    "fixed": {"intercept": 100, "coefficients": {"effect": 5}},
    "response": {"family": "gaussian", "name": "score", "sigma": 10},
}

data = simulate(spec)               # 64 rows
```

Given the same specification and seed, this reproduces the data generated by the R package
to full floating-point precision.

## Try it without installing

A serverless build runs entirely in your browser, with no installation required and no data
uploaded. It is available as a [no-code app](https://pablobernabeu.github.io/pilotr/app/).

## Learn more

The [Python documentation site](https://pablobernabeu.github.io/pilotr/python/) walks through the
quick start, the response families, power and design analysis, the specification format and the
API reference. The full repository, including the R package and the no-code app, is at
<https://github.com/pablobernabeu/pilotr>.

## Citation

If pilotr contributes to published work, please cite it.

> Bernabeu, P. (2026). *pilotr: Simulate experimental and behavioural data from a portable
> design specification* (R and Python package version 0.3.0).
> https://doi.org/10.5281/zenodo.21266313

The [About page](https://pablobernabeu.github.io/pilotr/python/about/) carries the same citation
with a BibTeX entry, and a short note on the developer. The repository also ships
[`CITATION.cff`](https://github.com/pablobernabeu/pilotr/blob/main/CITATION.cff), which is what
GitHub's *Cite this repository* button reads.

## Licence

MIT. See [LICENSE](https://github.com/pablobernabeu/pilotr/blob/main/python/LICENSE).

## Contributing

Issues and pull requests are welcome. The
[contributing guide](https://github.com/pablobernabeu/pilotr/blob/main/.github/CONTRIBUTING.md)
describes the development setup and the conventions the package follows, and everyone taking
part is asked to honour the
[Code of Conduct](https://github.com/pablobernabeu/pilotr/blob/main/.github/CODE_OF_CONDUCT.md).
