pilotr (Python)

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 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 for the full toolkit (the no-code app, the R package and the specification format).

Install

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.

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.

Learn more

The Python documentation site 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 carries the same citation with a BibTeX entry, and a short note on the developer. The repository also ships CITATION.cff, which is what GitHub's Cite this repository button reads.

Licence

MIT. See LICENSE.

Contributing

Issues and pull requests are welcome. The contributing guide describes the development setup and the conventions the package follows, and everyone taking part is asked to honour the Code of Conduct.