chapter on placebo groups

_freeze/notebook/extras/placebo_handling/execute-results/html.json

@@ -0,0 +1,17 @@
+{
+  "hash": "e8827d1a6df9704fb9c729f9728b44df",
+  "result": {
+    "engine": "knitr",
+    "markdown": "# Placebo handling\n\nThis page focuses on E-R data sets that include a placebo group, and how they can be analyzed using the BayesERtools package. \n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(tidyverse)\nlibrary(BayesERtools)\nlibrary(here)\n\ntheme_set(theme_bw(base_size = 12))\n```\n:::\n\n\n\n\n\n\n\n## Simulated data\n\nFor the purposes of this chapter, the `d_sim_placebo` data set from BayesERtools is used. It is similar to the `d_sim_emax` data set used in the Emax chapters, but includes data from a placebo group. The exposure-response relationships in this data set are well-captured by a hyperbolic Emax model:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nd_sim_placebo\n```\n\n<pre class=\"r-output\"><code><span style='color: #555555;'># A tibble: 400 × 11</span>\n      id  dose exp_1 exp_2 rsp_1 rsp_2 cnt_a cnt_b cnt_c bin_d bin_e\n   <span style='color: #555555; font-style: italic;'><int></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span> <span style='color: #555555; font-style: italic;'><dbl></span>\n<span style='color: #555555;'> 1</span>     1     0     0     0  6.49     0  3.06  6.50 5.93      0     1\n<span style='color: #555555;'> 2</span>     2     0     0     0  7.81     0  5.72  3.84 5.60      0     1\n<span style='color: #555555;'> 3</span>     3     0     0     0  7.26     0  4.31  3.68 8.16      0     0\n<span style='color: #555555;'> 4</span>     4     0     0     0  7.45     0  4.03  2.86 9.38      1     1\n<span style='color: #555555;'> 5</span>     5     0     0     0  6.33     0  2.46  3.36 8.29      0     1\n<span style='color: #555555;'> 6</span>     6     0     0     0  7.13     0  4.87  8.90 7.06      0     0\n<span style='color: #555555;'> 7</span>     7     0     0     0  6.07     0  2.87  4.85 0.989     0     1\n<span style='color: #555555;'> 8</span>     8     0     0     0  5.47     1  1.07  5.34 3.34      1     1\n<span style='color: #555555;'> 9</span>     9     0     0     0  7.12     0  3.94  5.68 4.01      1     1\n<span style='color: #555555;'>10</span>    10     0     0     0  8.21     1  7.46  8.16 6.92      1     1\n<span style='color: #555555;'># ℹ 390 more rows</span>\n</code></pre>\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\nd_sim_placebo |> \n  pivot_longer(\n    cols = c(exp_1, cnt_a, cnt_b, cnt_c), \n    names_to = \"variable\",\n    values_to = \"value\"\n  ) |> \n  ggplot(aes(value, rsp_1)) + \n  geom_point(aes(color = factor(dose))) + \n  geom_smooth(formula = y ~ x, method = \"loess\") + \n  facet_wrap(~ variable, scales = \"free_x\")\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/plot-continuous-data-1.png){width=672}\n:::\n:::\n\n\n\n\n\n## Models with placebo data\n\nThere are several ways the analyst might wish to analyse and visualize E-R data that include a placebo group. This section considers the case in which:\n\n- The placebo data are included when estimating model parameters\n- The placebo data are included in the data visualization\n\n### Continuous response\n\nIn the simplest case, a linear E-R model is estimated for continuous response data. The workflow is no different to the usual case when no placebo data is present:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nset.seed(1234)\nermod_lin <- dev_ermod_lin(\n  data = d_sim_placebo,\n  var_resp = \"rsp_1\",\n  var_exposure = \"exp_1\"\n)\n\nplot_er(\n  ermod_lin, \n  show_orig_data = TRUE,\n  options_orig_data = list(var_group = \"dose\")\n)\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/linear-er-placebo-included-1.png){width=672}\n:::\n:::\n\n\n\n\n\nIn the example above, the model does not account for the data very well. An Emax model provides a better description of the exposure-response relationship:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nset.seed(1234)\nermod_emax <- dev_ermod_emax(\n  data = d_sim_placebo,\n  var_resp = \"rsp_1\",\n  var_exposure = \"exp_1\"\n)\n\nplot_er(\n  ermod_emax, \n  show_orig_data = TRUE,\n  options_orig_data = list(var_group = \"dose\")\n)\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/emax-er-placebo-included-1.png){width=672}\n:::\n:::\n\n\n\n\n\n### Binary response\n\nFor binary response data that include a placebo group, plotting is slightly more complicated because it is typical to plot binned data and confidence intervals by exposure quantile. When placebo data is present, it is necessary to set the bin breaks so that the placebo data fall in a distinct bin. This is supported using the `bin_breaks` option to manually specify the bin edges, as shown for a logistic regression model below:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nset.seed(1234)\nermod_bin <- dev_ermod_bin(\n  data = d_sim_placebo,\n  var_resp = \"rsp_2\",\n  var_exposure = \"exp_1\"\n)\n\nplot_er(\n  ermod_bin, \n  show_orig_data = TRUE,\n  options_orig_data = list(\n    var_group = \"dose\",\n    bin_breaks = c(0, 0.001, 6018, 10265, 16964, 44568) \n  )\n)\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/binary-er-placebo-included-1.png){width=672}\n:::\n:::\n\n\n\n\n\nFor a binary Emax regression model, the code is very similar: \n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nset.seed(1234)\nermod_bin_emax <- dev_ermod_bin_emax(\n  data = d_sim_placebo,\n  var_resp = \"rsp_2\",\n  var_exposure = \"exp_1\"\n)\n\nplot_er(\n  ermod_bin_emax, \n  show_orig_data = TRUE,\n  options_orig_data = list(\n    var_group = \"dose\",\n    bin_breaks = c(0, 0.001, 6018, 10265, 16964, 44568) \n  )\n)\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/binary-emax-er-placebo-included-1.png){width=672}\n:::\n:::\n\n\n\n\n\n## Alternative scenarios\n\nIn some cases it is more useful to exclude the placebo group from the model fitting. An example would be when estimating a linear model to determine if the E-R relationship is flat over the dosed range. In this scenario, the workflow is to filter the data prior to estimating the model, and then fit and plot the data as normal:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nset.seed(1234)\n\nermod_lin_noplacebo <- d_sim_placebo |> \n  filter(dose != 0) |> \n  dev_ermod_lin(\n    var_resp = \"rsp_1\",\n    var_exposure = \"exp_1\"\n  )\n\nplot_er(\n  ermod_lin_noplacebo, \n  show_orig_data = TRUE,\n  options_orig_data = list(var_group = \"dose\")\n)\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/linear-er-placebo-excluded-1.png){width=672}\n:::\n:::\n\n\n\n\n\nSometimes it is useful to include the placebo data in the plot even though it did not contribute to the modeling. In this situation, a two-step approach is required to construct the plot: a base plot is constructed by plotting the E-R model without showing the original data, and then overlaying the data manually by adding geoms to the plot:\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nplot_er(\n  ermod_lin_noplacebo, \n  show_orig_data = FALSE,\n) + \n  geom_point(\n    mapping = aes(exp_1, rsp_1, color = factor(dose)),\n    data = d_sim_placebo\n  )\n```\n\n::: {.cell-output-display}\n![](placebo_handling_files/figure-html/linear-er-placebo-in-plot-1.png){width=672}\n:::\n:::\n",
+    "supporting": [
+      "placebo_handling_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}

_quarto.yml

@@ -29,6 +29,9 @@ book:
         - notebook/emax/simulation.qmd
         - notebook/emax/basic_workflow_brms.qmd
         - notebook/emax/covariate_modeling.qmd
+    - part: "Additional topics"
+      chapters:
+        - notebook/extras/placebo_handling.qmd
 
 format:
   html:

notebook/extras/placebo_handling.qmd

@@ -0,0 +1,168 @@
+# Placebo handling
+
+This page focuses on E-R data sets that include a placebo group, and how they can be analyzed using the BayesERtools package. 
+
+```{r}
+#| output: FALSE
+#| message: FALSE
+
+library(tidyverse)
+library(BayesERtools)
+library(here)
+
+theme_set(theme_bw(base_size = 12))
+```
+
+```{r}
+#| include: FALSE
+# Enable colored outputs
+source(here("R", "cli_color_text.R"))
+```
+
+## Simulated data
+
+For the purposes of this chapter, the `d_sim_placebo` data set from BayesERtools is used. It is similar to the `d_sim_emax` data set used in the Emax chapters, but includes data from a placebo group. The exposure-response relationships in this data set are well-captured by a hyperbolic Emax model:
+
+```{r}
+d_sim_placebo
+```
+
+```{r}
+#| label: plot-continuous-data
+d_sim_placebo |> 
+  pivot_longer(
+    cols = c(exp_1, cnt_a, cnt_b, cnt_c), 
+    names_to = "variable",
+    values_to = "value"
+  ) |> 
+  ggplot(aes(value, rsp_1)) + 
+  geom_point(aes(color = factor(dose))) + 
+  geom_smooth(formula = y ~ x, method = "loess") + 
+  facet_wrap(~ variable, scales = "free_x")
+```
+
+## Models with placebo data
+
+There are several ways the analyst might wish to analyse and visualize E-R data that include a placebo group. This section considers the case in which:
+
+- The placebo data are included when estimating model parameters
+- The placebo data are included in the data visualization
+
+### Continuous response
+
+In the simplest case, a linear E-R model is estimated for continuous response data. The workflow is no different to the usual case when no placebo data is present:
+
+```{r}
+#| label: linear-er-placebo-included
+set.seed(1234)
+ermod_lin <- dev_ermod_lin(
+  data = d_sim_placebo,
+  var_resp = "rsp_1",
+  var_exposure = "exp_1"
+)
+
+plot_er(
+  ermod_lin, 
+  show_orig_data = TRUE,
+  options_orig_data = list(var_group = "dose")
+)
+```
+
+In the example above, the model does not account for the data very well. An Emax model provides a better description of the exposure-response relationship:
+
+```{r}
+#| label: emax-er-placebo-included
+set.seed(1234)
+ermod_emax <- dev_ermod_emax(
+  data = d_sim_placebo,
+  var_resp = "rsp_1",
+  var_exposure = "exp_1"
+)
+
+plot_er(
+  ermod_emax, 
+  show_orig_data = TRUE,
+  options_orig_data = list(var_group = "dose")
+)
+```
+
+### Binary response
+
+For binary response data that include a placebo group, plotting is slightly more complicated because it is typical to plot binned data and confidence intervals by exposure quantile. When placebo data is present, it is necessary to set the bin breaks so that the placebo data fall in a distinct bin. This is supported using the `bin_breaks` option to manually specify the bin edges, as shown for a logistic regression model below:
+
+```{r}
+#| label: binary-er-placebo-included
+set.seed(1234)
+ermod_bin <- dev_ermod_bin(
+  data = d_sim_placebo,
+  var_resp = "rsp_2",
+  var_exposure = "exp_1"
+)
+
+plot_er(
+  ermod_bin, 
+  show_orig_data = TRUE,
+  options_orig_data = list(
+    var_group = "dose",
+    bin_breaks = c(0, 0.001, 6018, 10265, 16964, 44568) 
+  )
+)
+```
+
+For a binary Emax regression model, the code is very similar: 
+
+```{r}
+#| label: binary-emax-er-placebo-included
+set.seed(1234)
+ermod_bin_emax <- dev_ermod_bin_emax(
+  data = d_sim_placebo,
+  var_resp = "rsp_2",
+  var_exposure = "exp_1"
+)
+
+plot_er(
+  ermod_bin_emax, 
+  show_orig_data = TRUE,
+  options_orig_data = list(
+    var_group = "dose",
+    bin_breaks = c(0, 0.001, 6018, 10265, 16964, 44568) 
+  )
+)
+```
+
+## Alternative scenarios
+
+In some cases it is more useful to exclude the placebo group from the model fitting. An example would be when estimating a linear model to determine if the E-R relationship is flat over the dosed range. In this scenario, the workflow is to filter the data prior to estimating the model, and then fit and plot the data as normal:
+
+```{r}
+#| label: linear-er-placebo-excluded
+set.seed(1234)
+
+ermod_lin_noplacebo <- d_sim_placebo |> 
+  filter(dose != 0) |> 
+  dev_ermod_lin(
+    var_resp = "rsp_1",
+    var_exposure = "exp_1"
+  )
+
+plot_er(
+  ermod_lin_noplacebo, 
+  show_orig_data = TRUE,
+  options_orig_data = list(var_group = "dose")
+)
+```
+
+Sometimes it is useful to include the placebo data in the plot even though it did not contribute to the modeling. In this situation, a two-step approach is required to construct the plot: a base plot is constructed by plotting the E-R model without showing the original data, and then overlaying the data manually by adding geoms to the plot:
+
+```{r}
+#| label: linear-er-placebo-in-plot
+plot_er(
+  ermod_lin_noplacebo, 
+  show_orig_data = FALSE,
+) + 
+  geom_point(
+    mapping = aes(exp_1, rsp_1, color = factor(dose)),
+    data = d_sim_placebo
+  )
+```
+