Skip to content

pilotr (Python)

pilotr simulates experimental and behavioural data from a portable JSON design specification. The same specification drives the R package, a no-code web app and this Python package. Given the same spec and seed, all three produce bit-identical data.

Install

pip install pilotr             # core engine (pure Python, dependency-free)
pip install "pilotr[power]"    # + scipy, for the simulation-based power demo

Requires Python 3.9 or later; the generative core has no dependencies. scipy (for power) and statsmodels with pandas (for power_mixed) are optional extras. For development, install from a checkout of the repository instead:

git clone https://github.com/pablobernabeu/pilotr.git
pip install ./pilotr/python

Quick start

A design is a plain dictionary, or a JSON file, describing the units, factors, fixed effects, optional random effects and a response family. Simulate from it with simulate:

These examples run live

The code blocks on this page (and throughout these docs) are executed when the site is built, so the tables and plots are real pilotr output. table(...) and show(...) are small helpers that render a result as a Markdown table or an inline figure.

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
print(table(data.head(5)))          # the first rows, as a table
subject group score
1 control 95.7
2 control 90.1
3 control 119
4 control 86.4
5 control 103

len(data) is the number of observations, data.head(n) returns the first rows as a list of dicts, and data.to_csv("data.csv") writes the table to disk.

To run a spec authored elsewhere (for example, one downloaded from the no-code app), load it with load_spec and simulate. Here we load one of the worked examples that ship with pilotr, using pilotr_example to find it inside the installed package:

from pilotr import load_spec, pilotr_example, simulate

data = simulate(load_spec(pilotr_example("poisson_counts_between")))
print(table(data.head(5)))
subject group count
1 control 3
2 control 5
3 control 3
4 control 9
5 control 6

Where to go next

Archived on Zenodo: DOI