
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. Both packages use the same design
specification and random-number generator, so the same specification and
seed produce identical data in either language wherever the two share a
maths library, as on Linux, except in a rare Beta case under R 4.6.0 or
later that the cross-language
article describes. Elsewhere, a value that passes through
exp(), log() or pow() can differ
in its last bits, as the same article sets out.
The Python package includes the generative core, simulation-based
power, the helpers that derive the analysis model,
power_report() and the curve solvers
solve_curve() and target_n(). The R package
additionally offers precision/ROPE design analysis, power curves for
mixed-effects designs, the lme4 reference backend for
mixed-effects power, the brms bridge, the analysis-script
emitters, the helpers that build, calibrate and sweep specifications,
and the app launcher.
pilotr is on CRAN:
install.packages("pilotr")The development version installs from the r/pilotr
subdirectory of the GitHub
repository:
# install.packages("remotes")
remotes::install_github("pablobernabeu/pilotr", subdir = "r/pilotr")The package includes eight example specifications, 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.6668The specification includes a seed, so those rows are the same on
every machine and in the Python twin, to the last bit wherever the maths
library is the same. 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 the
lme4 and lmerTest packages, which pilotr
suggests without requiring.
power_mixed(spec, n_sims = 200) # crossed-LMM power + Type S/M (lme4, lmerTest)
cat(generate_r_script(spec)) # a self-contained, reproducible scriptThe power
article shows the output of power_mixed(), 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.
A serverless build of the no-code app runs in your browser, with no installation required and no data uploaded.
The Get started article walks through the core workflow of describing, simulating, inspecting and exporting a design, and each of the other articles covers one part of the workflow in more detail. The repository, including the specification format and the no-code app, is at https://github.com/pablobernabeu/pilotr.
citation("pilotr")The DOI that CRAN assigned to the package is https://doi.org/10.32614/CRAN.package.pilotr, and it covers every version.
The About
page gives the same citation, with a BibTeX entry, and a short note
on the developer. The repository also includes
CITATION.cff, which GitHub’s ‘Cite this repository’ button
reads.
MIT. The full text is in the repository’s LICENSE file.
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.