To add a design you only have to contribute a single
self-contained R file under inst/designs/. That
file declares a design and, preferably, a short YAML header. Once it is
there, make_design(), the maintainer audits, and
designs_shiny_app() can all use it.
The contribution workflow is:
inst/designs/.audit_designs() and
designs_shiny_app() to see it all working.In more detail:
Fork DesignLibrary
on GitHub and clone your fork. Work from the package source tree (or set
options(DesignLibrary.root = "...") so helpers find
inst/designs/).
Save a single .R file in inst/designs/.
Name it after the design id (for example my_design.R). Keep
it self-contained: no source() of other designs.
Declare an object named design (or set
object: in YAML to the object name you use).
For example:
b <- 0.2
design <-
declare_model(N = 100, U = rnorm(N), potential_outcomes(Y ~ b * Z + U)) +
declare_inquiry(ATE = mean(Y_Z_1 - Y_Z_0)) +
declare_assignment(Z = complete_ra(N)) +
declare_measurement(Y = reveal_outcomes(Y ~ Z)) +
declare_estimator(Y ~ Z, inquiry = "ATE")Editable parameters are discovered from the design object. Tip strings and library metadata live in optional YAML.
After adding or editing a design, rebuild the index, run the audit, and bake diagnosis previews:
That step creates the artifacts the library and Shiny browser expect for your design.
At minimum:
Confirm the design appears in the Library, opens cleanly, and
diagnosis / redesign behave as you expect. Use
design_info("my_design") and
get_args("my_design") for a quick profile.
Open a pull request from your fork to
DeclareDesign/DesignLibrary. Keep the PR focused on the new
or updated design file and any packages it needs. Mention extra
dependencies in YAML packages: and in the PR description
when relevant.
Optional frontmatter sits between --- lines at the top
of the file.
| Field | Tip |
|---|---|
id |
Substantive snake_case name (e.g. two_arm_simple).
Defaults to the filename stem; a few book designs use a different
id. |
alias |
Optional book reference string (e.g. "2.1"). Quote it
if it looks numeric. |
label |
Short human-readable title shown in the library. |
description |
One or two sentences on what the design does. Use YAML
> for a folded block. |
category |
Grouping label. Use rdss for book designs;
template for teaching starters; otherwise a short group
name. |
keywords |
List of search terms, e.g. [experiment, blocking]. |
packages |
Extra R packages beyond DeclareDesign,
e.g. [margins, broom]. |
diagnosands |
Preferred display diagnosands, e.g. [rmse, bias].
Prefix with - to hide one
(rmse, -bias, power). |
params |
Map parameter names to tip strings. Always quote keys:
"N": "Sample size". Names must match redesignable
parameters. Data frames and matrices are R-only
(make_design(..., dataset = ...)), not Shiny controls. |
coupled |
Optional map from a driver to dependents that must match its length,
e.g. m_arms: [outcome_means, outcome_sds, conditions].
make_design() message()s and the Shiny
redesign help box always show the note. |
book_link |
URL to a book section or external docs. |
include_in_shiny |
true (default) or false. Set
false for incomplete or heavy designs. |
functional |
true (default) or false. Set
false to park a design whose dependencies are unavailable;
it is skipped by the audit, the smoke tests, and dependency
installation, and is never shown in Shiny. |
object |
Name of the design object in the file. Omit if the object is named
design. |
Example header:
library(DesignLibrary)
contributor_checklist()
#> [1] "File lives in inst/designs/ and is self-contained (no source() of other designs)."
#> [2] "Filename matches the substantive id (e.g. two_arm_simple.R)."
#> [3] "YAML frontmatter is optional. If present, may set id, alias (book ref), label, category, keywords, packages, diagnosands, include_in_shiny, functional, book_link, params; object: only if the design is not named `design`."
#> [4] "No YAML is fine: id = filename stem, label = humanized id, category = Other, object = design, include_in_shiny = TRUE, functional = TRUE."
#> [5] "Set functional: false to park a design (e.g. unavailable dependencies). Skipped by audit, smoke tests, and dependency install; forces include_in_shiny: false."
#> [6] "The design object is the source of truth for editable parameters: only names assigned before `design <-` (e.g. N <- 1000; declare_model(N = N, ...)) count. Literals inside declare_* (e.g. declare_model(N = 1000)) are not parameters."
#> [7] "Scalar parameters (N <- 100) can be swept with redesign(N = c(50, 100)). Vector parameters (probs <- c(.1, .2, .3)) are replaced as a whole; the browser edits them as a comma-separated list. Data frames and matrices are package parameters (make_design(..., dataset = ...)), not Shiny controls; name the knob `dataset` (`dataset <- example_pop`), not `data` or the example's own name."
#> [8] "YAML params map names to tip strings; always quote keys (e.g. \"N\": \"Sample size\", \"b\": \"Effect size\"); names must match those redesignable parameters (no extras). Design steps (model_*, inquiry_*, etc.) are not params."
#> [9] "Optional diagnosands: preferred display diagnosands (e.g. diagnosands: rmse, bias or [rmse, bias]); prefix with - to exclude (rmse, -bias, power). Shiny Diagnosis and Redesign use these defaults."
#> [10] "Extra packages listed under packages: and available to install."
#> [11] "Design evaluates under DeclareDesign; redesign() works for documented parameters. A design that loads but does not run fails the audit."
#> [12] "Run refresh_library() from the package source tree after adding or editing designs (or set options(DesignLibrary.root = \"...\"))."