pilotr (R) pilotr hex logo

CRAN status R-CMD-check Lifecycle: experimental License: MIT DOI 10.32614/CRAN.package.pilotr

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.

Installation

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")

Quick start

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.6668

The 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 script

The 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.

Try it without installing

A serverless build of the no-code app runs in your browser, with no installation required and no data uploaded.

Learn more

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

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.

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.