index.qmd

---
pagetitle: "DeclareDesign"
toc: false
page-layout: full
section-divs: false
anchor-sections: false
css: index.css
execute:
  message: false
  error: false
  warning: false
  cache: true
  code-overflow: wrap
---

::: {.grid .align-items-center}

::: {.g-col-12 .g-col-md-6}  

<p class="hdr1">Declare and diagnose your research design</p>

<p class="hdr2">DeclareDesign is a set of software tools to plan, implement, analyze, and communicate about empirical research</p>

<br>

::: {.grid}

::: {.g-col-12 .g-col-lg-4 .text-center}

[Get Started](getting-started/){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

::: {.g-col-12 .g-col-lg-4 .text-center}

[Software](/r/declaredesign/){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

::: {.g-col-12 .g-col-lg-4 .text-center}

[Read Book](https://book.declaredesign.org){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

:::

:::

  
::: {.g-col-12 .g-col-md-6}  
[![](https://book.declaredesign.org/figures/cover.jpg){width=80% fig-id="img-border"}](https://book.declaredesign.org)
:::

:::

<!-- Figure 5.1 / MIDA -->

## MIDA framework for describing research designs

::: {.grid .align-items-center}

::: {.g-col-12 .g-col-md-8}  
![](static/mida.svg){width=80% fig-id="img-border"}
:::

::: {.g-col-12 .g-col-md-4}  

The MIDA framework describes the four elements of any empirical research design:

- **Model:** the worlds you consider
- **Inquiry:** the question you ask
- **Data strategy:** sampling, treatment assignment, and measurement procedures
- **Answer strategy:** estimation, testing, interpretation, and visualization procedures

Read [Chapter 5](https://book.declaredesign.org/declaration-diagnosis-redesign/declaring-designs.html) of *Research Design in the Social Sciences* to learn how these four research design elements connect to reality and simulations that can be used to plan and improve research designs.


:::

:::

<!-- tabset -->

## Declare-Diagnose-Redesign algorithm for designing research

* **Declare** designs in code following the MIDA framework.
* **Diagnose** declared designs through Monte Carlo simulation to learn their properties, such as bias and power.
* **Redesign** data and answer strategy features to optimize designs under logistical, financial, and ethical constraints.

Here is an illustration of using DeclareDesign for a two-arm randomized trial:

::: {.panel-tabset}

## 1. Declare

::: {.grid}
::: {.g-col-12 .g-col-md-6}
```{r, echo = FALSE, message = FALSE}
library(tidyverse)
library(knitr)
```
```{r}
library(DeclareDesign)

sample_size <- 100

# Declare a two-arm trial in code
two_arm_trial <-
  declare_model(N = sample_size,
                U = rnorm(N),
                potential_outcomes(Y ~ 0.2 * Z + U)) +
  declare_inquiry(ATE = mean(Y_Z_1 - Y_Z_0)) +
  declare_assignment(Z = complete_ra(N, prob = 0.5)) +
  declare_measurement(Y = reveal_outcomes(Y ~ Z)) +
  declare_estimator(Y ~ Z, inquiry = "ATE")
```
:::

::: {.g-col-12 .g-col-md-6}
```{r, eval = FALSE}
# Draw a simulated dataset 
draw_data(two_arm_trial)
```
```{r, echo = FALSE}
draw_data(two_arm_trial) |> 
  head(3) |> 
  kable(digits = 2)
```

```{r, eval = FALSE}
# Obtain a simulated estimate and estimand
run_design(two_arm_trial)
```
```{r, echo = FALSE}
run_design(two_arm_trial) |> 
  select(estimate, std.error, p.value, inquiry, estimand) |> 
  kable(digits = 2)
```
:::

:::


## 2. Diagnose

::: {.grid}

::: {.g-col-12 .g-col-md-6}

```{r, eval = FALSE}
# Simulate the research design 500 times and 
#   summarize the simulations
diagnosis <- diagnose_design(two_arm_trial, sims = 500)
tidy(diagnosis)
```
```{r, echo = FALSE}
diagnosis <- diagnose_design(two_arm_trial)
tidy(diagnosis) |> 
  select(diagnosand, estimate, std.error) |> 
  kable(digits = 3, row.names = FALSE)
```

:::

::: {.g-col-12 .g-col-md-6}

```{r, eval = FALSE}
library(ggplot2)

# Visualize simulated sampling distribution
ggplot(data = get_simulations(diagnosis), 
       aes(x = estimate)) +
  geom_histogram() 
```
```{r dev.args = list(bg = 'transparent')}
#| fig.width: 4
#| fig.height: 3
#| echo: false
sims <- diagnosis |> get_simulations() 
diagnosands <- diagnosis |> get_diagnosands()

ggplot(sims, aes(estimate)) +
  geom_histogram(color = NA, fill = "#72B4F3", bins = 30) +
  geom_vline(
    data = diagnosands,
    aes(xintercept = mean_estimate),
    color = gray(0.1),
    lty = "dashed"
  ) +
  geom_vline(
    data = diagnosands,
    aes(xintercept = mean_estimand),
    color = "#C6227F",
    lwd = 1.25
  ) +
  annotate(
    "text",
    x = diagnosands$mean_estimand + 0.025,
    y = 50,
    hjust = 0,
    label = "Estimand",
    color = "#C6227F"
  ) +
  annotate(
    "text",
    x = diagnosands$mean_estimate - 0.025,
    y = 50,
    hjust = 1,
    label = "Average estimate",
    color = gray(0.1)
  ) +
  labs(x = "Simulation sampling distribution of estimator", y = "Density") +
  theme_minimal()
```
:::

:::


## 3. Redesign

::: {.grid}

::: {.g-col-12 .g-col-md-6}

```{r, eval = FALSE}
# Redesign over sample size and calculate power
diagnosis <-
  two_arm_trial |>
  redesign(sample_size = c(250, 500, 750, 1000, 1250)) |>
  diagnose_designs() |>
  tidy() |>
  filter(diagnosand == "power")

# Visualize power curve over sample sizes
ggplot(diagnosis, aes(sample_size, estimate)) + 
  geom_point() +
  geom_line()
```

:::

::: {.g-col-12 .g-col-md-6}

```{r dev.args = list(bg = 'transparent')}
#| fig.width: 6
#| fig.height: 3
#| echo: false
#| code-overflow: wrap
designs_ss <- 
  two_arm_trial |> 
  redesign(sample_size = c(250, 500, 750, 1000, 1250))

diagnosis_ss <- 
  diagnose_design(designs_ss, 
                  sims = 500)

diagnosands <- 
  diagnosis_ss |> 
  tidy() |> 
  filter(diagnosand == "power")

ggplot(diagnosands, aes(sample_size, estimate)) + 
  geom_ribbon(aes(ymin = conf.low, ymax = conf.high), fill = "#72B4F3", color = NA) + 
  geom_point() +
  geom_line() +
  geom_hline(yintercept = 0.8, color = "#C6227F", linewidth = 1, lty = "dashed") + 
  annotate("text", x = 800, y = 0.75, label = "80% power target", hjust = 0) + 
  labs(x = "Sample size", y = "Statistical power") + 
  theme_minimal()
```

:::

:::


:::



<!-- grid of content -->

## Library of common research designs 

The MIDA framework can accomodate observational and experimental, descriptive and causal, qualitative and quantitative research designs. Part III of *Research Design in the Social Sciences* illustrates the framework for these common designs.

::: {.grid}

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}

### Observational designs for descriptive inference

[Simple random sampling](https://book.declaredesign.org/library/observational-descriptive.html#simple-random-sampling)<br />
[Cluster random sampling](https://book.declaredesign.org/library/observational-descriptive.html#sec-ch15s2)<br />
[Multi-level regression and poststratification](https://book.declaredesign.org/library/observational-descriptive.html#sec-ch15s3)<br />
[Index creation](https://book.declaredesign.org/library/observational-descriptive.html#index-creation)

:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}

### Observational designs for causal inference

[Process tracing](https://book.declaredesign.org/library/observational-causal.html#sec-ch16s1)<br />
[Selection-on-observables](https://book.declaredesign.org/library/observational-causal.html#sec-ch16s2)<br />
[Difference-in-differences](https://book.declaredesign.org/library/observational-causal.html#sec-ch16s3)<br />
[Instrumental variables](https://book.declaredesign.org/library/observational-causal.html#sec-ch16s4)<br />
[Regression discontinuity designs](https://book.declaredesign.org/library/observational-causal.html#sec-ch16s5)

:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}

### Experimental designs for descriptive inference

[Audit experiments](https://book.declaredesign.org/library/experimental-descriptive.html#audit-experiments)<br />
[List experiments](https://book.declaredesign.org/library/experimental-descriptive.html#list-experiments)<br />
[Conjoint experiments](https://book.declaredesign.org/library/experimental-descriptive.html#sec-ch17s3)<br />
[Behavioral games](https://book.declaredesign.org/library/experimental-descriptive.html#behavioral-games)

:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}

### Experimental designs for causal inference

[Two-arm randomized experiments](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s1)<br />
[Block-randomized experiments](https://book.declaredesign.org/library/experimental-causal.html#block-randomized-experiments)<br />
[Cluster-randomized experiments](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s3)<br />
[Subgroup designs](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s4)<br />
[Factorial experiments](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s5)<br />
[Encouragement designs](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s6)<br />
[Placebo-controlled experiments](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s7)<br />
[Stepped-wedge experiments](https://book.declaredesign.org/library/experimental-causal.html#stepped-wedge-experiments)<br />
[Randomized saturation experiments](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s9)<br />
[Experiments over networks](https://book.declaredesign.org/library/experimental-causal.html#sec-ch18s10)

:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}

### Complex designs

[Discovery using causal forests](https://book.declaredesign.org/library/complex.html#discovery-using-causal-forests)<br />
[Structural estimation](https://book.declaredesign.org/library/complex.html#sec-ch19s2)<br />
[Meta-analysis](https://book.declaredesign.org/library/complex.html#sec-ch19s3)<br />
[Multi-site studies](https://book.declaredesign.org/library/complex.html#multi-site-studies)

:::

:::

<!-- take action -->

<br/><br/>

::: {.grid .align-items-center}

::: {.g-col-12 .g-col-lg-2 .g-col-md-4 .g-start-lg-2 .text-center}

[Get Started](/getting-started/){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

::: {.g-col-12 .g-col-lg-2 .g-col-md-4 .text-center}

[Software](/r/declaredesign/){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

::: {.g-col-12 .g-col-lg-2 .g-col-md-4 .text-center}

[Read Book](https://book.declaredesign.org){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"} 

:::

::: {.g-col-12 .g-col-lg-2 .g-start-md-3 .g-col-md-4 .text-center}

[Read Blog](/blog){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"}

:::

::: {.g-col-12 .g-col-lg-2 .g-col-md-4 .text-center}

[About](/about){.btn-action-primary .btn-action .btn .btn-success .btn-lg role="button"}

:::

:::