Design profile

              

One-line

Full declaration

Editable parameters



            

Baked preview from the package when available; otherwise run a live diagnosis.



Diagnosands

Diagnosand table

Contribute a design

You contribute one self-contained R file in inst/designs/ . That file holds the declared design and an optional YAML header. Nothing else is required for the library, API, or this browser to pick it up.

Full write-up: Contributing a design (vignette) .

Workflow

  1. Fork the repository on GitHub and clone your fork locally.
  2. Add your file under inst/designs/ . Name it after the design id (e.g. my_design.R ). Declare an object named design (or set object: in YAML). Keep the file self-contained: no source() of other designs.
  3. Refresh so index, audit, and preview artifacts are built for your design:
    options(DesignLibrary.root = "/path/to/your/DesignLibrary")
    refresh_library()
  4. Check locally. At minimum:
    list_designs()
    make_design("my_design")
    audit_designs()
    designs_shiny_app()
    Confirm your design appears in the Library, opens cleanly, and diagnosis/redesign behave as you expect.
  5. Pull request from your fork to DeclareDesign/DesignLibrary . Keep the PR focused on the new (or updated) design file and any packages it needs.

Minimal file

YAML is optional. This is enough:

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

Parameters are discovered from the design object. Tip strings and library metadata live in optional YAML.

YAML fields

Optional frontmatter 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.
alias Optional book reference string (e.g. "2.1"). Quoted 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 the design needs 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". Only top-level assignments before design <- count (N <- 1000), not literals inside declare_*(N = 1000). No design-step names.
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 (e.g. unavailable packages); skips audit/smoke/install and forces include_in_shiny false.
object Name of the design object in the file. Omit if the object is named design.
Example YAML header
---
id: two_arm_simple
label: Simple two-arm trial
category: template
keywords: [experiment, two-arm]
description: >
  Simple two-arm trial with complete random assignment.
params:
  "N": "Sample size"
  "b": "Treatment effect"
diagnosands: [bias, power]
include_in_shiny: true
functional: true
---

Checklist

  • File lives in inst/designs/ and is self-contained (no source() of other designs).
  • Filename matches the substantive id (e.g. two_arm_simple.R).
  • 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`.
  • No YAML is fine: id = filename stem, label = humanized id, category = Other, object = design, include_in_shiny = TRUE, functional = TRUE.
  • Set functional: false to park a design (e.g. unavailable dependencies). Skipped by audit, smoke tests, and dependency install; forces include_in_shiny: false.
  • 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.
  • 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.
  • 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.
  • 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.
  • Extra packages listed under packages: and available to install.
  • Design evaluates under DeclareDesign; redesign() works for documented parameters. A design that loads but does not run fails the audit.
  • Run refresh_library() from the package source tree after adding or editing designs (or set options(DesignLibrary.root = "...")).

In R: contributor_checklist() , audit_designs() , refresh_library() .

Research Design in the Social Sciences

About DesignLibrary

DeclareDesign A library of declared designs in the DeclareDesign ecosystem. Designs are self-contained R files; editable parameters come from the design object.

Built around declaration, diagnosis, and redesign; see Research Design in the Social Sciences .

Package version 2.0.0.