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.