pilotr
Simulate Experimental and Behavioural Data from a Portable Design Specification
Generative simulation of experimental and behavioural data sets from a
portable JavaScript Object Notation (JSON) design specification shared with the
'Python' package of the same name.
Supports user-specified fixed effect sizes, crossed by-subject and by-item random
intercepts and slopes, predictors measured with error, realistic response families
(Gaussian, lognormal, shifted lognormal, ex-Gaussian, Bernoulli, Poisson, ordinal and
Beta), and simulation-based power and precision-based design analysis, including the
Type S and Type M errors of Gelman and Carlin (2014)
pilotr (R) 
Simulate experimental and behavioural data from a portable design specification, with integrated simulation-based power and design analysis (the Type S and Type M errors, and precision against a region of practical equivalence).
pilotr lets you pilot a study before you run it. Describe the design you plan to collect, with its groups, conditions, sample sizes, effect sizes and outcome family, and pilotr generates the data that design would produce. You can then check the study’s power and design analysis before gathering anything. A single specification drives three interchangeable interfaces, namely a no-code web app, this R package and the Python package.
This is the twin of the Python
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. The Python package carries
the generative core. The R package additionally offers precision/ROPE
design analysis, the lme4 reference backend for mixed-effects power,
the brms bridge, the analysis-script emitters, the helpers that derive
the analysis model and build specifications, and the app launcher.
Installation
# install.packages("remotes")
remotes::install_github("pablobernabeu/pilotr", subdir = "r/pilotr")
Quick start
The package ships a specification per design family, so the example
below runs as it stands. pilotr_example() returns the path to one of
them, here a crossed by-subject and by-item reaction-time design.
library(pilotr)
spec <- load_spec(pilotr_example("crossed_mixed_rt"))
data <- simulate_design(spec)
head(data)
#> subject item condition RT
#> 1 1 1 related 668.6564
#> 2 1 1 unrelated 727.3870
#> 3 1 2 related 699.1907
#> 4 1 2 unrelated 502.9760
#> 5 1 3 related 661.0859
#> 6 1 3 unrelated 516.6668
The specification carries a seed, so those rows are the same on every
machine and in the Python twin. Point load_spec() at your own
design.json to simulate a design of your own.
Power and design analysis run from the same object. The call below is
not evaluated here because it needs a few hundred model fits and lme4,
which the package suggests without requiring.
power_mixed(spec, n_sims = 200) # crossed-LMM power + Type S/M (lme4)
cat(generate_r_script(spec)) # a self-contained, reproducible script
The power
article
shows its output, alongside a power curve over sample size and
target_n(), which solves that curve for the sample size a target power
needs and reports an interval on it.
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 Get started article walks through the core loop of describe, simulate, inspect and export, and the other articles each go deeper into one part of the workflow. The full repository, including the specification format and the no-code app, is at https://github.com/pablobernabeu/pilotr.
Citation
citation("pilotr")
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. The full text is in the repository’s LICENSE file.
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.