--- title: "Contributing a design" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Contributing a design} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE ) ``` # The short version 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: 1. **Fork** the repository and clone your fork. 2. **Add your file** in `inst/designs/`. 3. **Refresh** so library artifacts are built for the new design. 4. **Check** with `audit_designs()` and `designs_shiny_app()` to see it all working. 5. Open a **pull request**. In more detail: # 1. Fork Fork [DesignLibrary](https://github.com/DeclareDesign/DesignLibrary) on GitHub and clone your fork. Work from the package source tree (or set `options(DesignLibrary.root = "...")` so helpers find `inst/designs/`). # 2. Add your file 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: ```r 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. # 3. Refresh After adding or editing a design, rebuild the index, run the audit, and bake diagnosis previews: ```r options(DesignLibrary.root = "/path/to/your/DesignLibrary") refresh_library() ``` That step creates the artifacts the library and Shiny browser expect for your design. # 4. Check At minimum: ```r list_designs() make_design("my_design") audit_designs() designs_shiny_app() ``` 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. # 5. Pull request 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. # YAML fields 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: ```yaml --- 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 --- ``` # Checklist ```{r checklist, eval = TRUE} library(DesignLibrary) contributor_checklist() ```