Metadata-Version: 2.4
Name: pilotr
Version: 0.2.1
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/py/
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: 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)

Python implementation of pilotr. It simulates experimental and behavioural data from a
portable JSON design specification, producing output that is bit-identical to the
[R package of the same name](https://pablobernabeu.github.io/pilotr/). 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
```

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

```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/py/) 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>.
