---
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()
```

