DesignLibrary

A library of declared research designs for DeclareDesign.

Version 2.0.0 supersedes DesignLibrary 0.1.10 on CRAN; see Upgrading from 0.1.

install.packages("DesignLibrary")

Idea

Tiny API

list_designs()
make_design("two_arm_simple")
make_design("two_arm_simple", b = 0.5)
two_arm_designer(N = 40, ate = 0.2)  # DesignLibrary 0.1 name
make_design("2.1", b = 0.5)          # book alias
get_args("two_arm_simple")
get_code("two_arm_simple")             # simple make_design() + full source
designs_shiny_app()
install_library_dependencies()        # Imports + Shiny Suggests + YAML packages
copy_library_shiny("path/to/app")     # standalone Shiny folder for the server

Maintainer one-stop:

refresh_library()   # index + audit + bake previews (sims = 100)
build_docs()        # pkgdown site -> docs/ (safe on Dropbox / Windows)

If pkgdown::build_site() fails with write_html / “Error closing file”, use build_docs() instead: it builds in a local temp folder, then copies into docs/.

Upgrading from 0.1

The fifteen 0.1 designers (two_arm_designer(), block_cluster_two_arm_designer(), and so on) keep their names and, with the exceptions below, their arguments. Each now builds a library design, so two_arm_designer(N = 40) and make_design("two_arm_flexible", N = 40) return the same design.

The vignette Upgrading from DesignLibrary 0.1 (vignette("upgrading")) works through every break with code, and the full list is in NEWS.md under “Breaking changes relative to 0.1.10”.

Server deploy

A set of functions help you if you want to deploy the shiny to a server:

install.packages("DesignLibrary")
DesignLibrary::install_library_dependencies()
DesignLibrary::copy_library_shiny("/srv/shiny-server/designlibrary")

Minimal design file

A design can be declared very concisely:

b <- 0
design <-
  declare_model(N = 100, U = rnorm(N), Y_Z_0 = U, Y_Z_1 = U + b) +
  declare_inquiry(ATE = mean(Y_Z_1 - Y_Z_0)) +
  declare_assignment(Z = complete_ra(N)) +
  declare_measurement(Y = Y_Z_1 * Z + Y_Z_0 * (1 - Z)) +
  declare_estimator(Y ~ Z, inquiry = "ATE")

Save as inst/designs/my_design.R. Parameters are discovered from the design; redesign() / make_design() use those names.

However, if you want the design to sing in your shiny, add a YAML. YAML can provide descriptions and definitions and can be used to set preferred diagnosands for the Shiny Diagnosis and Redesign tabs:

id: two_arm_simple
label: Simple two-arm trial
category: template
keywords: [experiment, two-arm]
description: >
  Simple two-arm trial with complete random assignment and a population average treatment effect.
params:
  "N": "Number of units (sample or population size)"
  "b": "Treatment effect (outcome scale)"
diagnosands: [bias, power]
include_in_shiny: true

DeclareDesign 1.x vs 2.0

DesignLibrary 2.0 supersedes DesignLibrary 0.1. Designs are now self-contained declaration files read through make_design(), list_designs(), and get_args(), and parameters are read from the design itself rather than from a designer function’s formals.

DeclareDesign 1.x (and DesignLibrary 0.1) often paired a designer function with a design: parameters lived on the designer, and tools like expand_design(two_arm_designer, N = c(50, 100)) swept that function. Reproducible code was glued on with special extraction ({{{ }}}).

DeclareDesign 2.0 keeps the same declaration verbs (declare_model, +, diagnose_design, …) but treats the declared design itself as redesignable. Free symbols in the design (e.g. b, tau) are found on the object, so:

designs <- redesign(design, tau = c(0.1, 0.3, 0.5))
diagnose_design(designs, sims = 100)

AI use in package development

The design declarations that sit in inst/designs/ are the substantive core of the package and are vouched for by the package authors. However, the DesignLibrary 2.0 library machinery (for calling, listing, and displaying designs, including the Shiny app) was written with and largely by AI coding models, Claude and models used through Cursor among them.

Contributor checklist

See contributor_checklist() or run audit_designs() / refresh_library().