(lineplot) Second pass over reference values vignette.

vignettes/lineplot_reference_values.Rmd

@@ -14,14 +14,14 @@ knitr::opts_chunk$set(
 )
 ```
 
-This article describes how to display reference values in `mod_lineplot` charts and discusses the not-so-intuitive
+This article describes how to display reference values in `mod_lineplot` charts and discusses the
 behavior of reference lines in the presence of grouped data.
 
 # A basic plot
 
-As a starting point, let's imagine we want to inspect the following tiny subject-level (`sl`) and laboratory values (`lb`) datasets (*click to expand*):
+As a starting point, let's imagine we want to inspect the following toy subject-level (`sl`) and laboratory values (`lb`) datasets:
 
-<details><summary>Subject-level dataset</summary>
+<details><summary>Subject-level dataset <i><small>[expand/collapse]</small></i></summary>
 ```{r, echo = FALSE}
 # Inspired in safetyData:adam_adsl
 sl <- data.frame(
@@ -34,7 +34,7 @@ knitr::kable(sl, format = "markdown")
 ```
 </details>
 
-<details><summary>Laboratory values dataset</summary>
+<details><summary>Laboratory values dataset <i><small>[expand/collapse]</small></i></summary>
 ```{r, echo = FALSE}
 # Inspired in safetyData:adam_lbc
 lb <- data.frame(
@@ -57,8 +57,8 @@ module_list <- list(
     module_id = "lineplot", bm_dataset_name = "lb", group_dataset_name = "sl",
     subjid_var = "SUBJID", cat_var = "PARCAT1", par_var = "PARAM", value_vars = "AVAL",
     visit_vars = "AVISITN", default_cat = "CHEM", default_par = "Imaginariol (mmol/L)",
-    #default_main_group = "COUNTRY" # nolint
-    , ref_line_vars = c("A1LO", "A1HI")
+    #default_main_group = "SEX", # nolint
+    ref_line_vars = c("A1LO", "A1HI")
   )
 )
 
@@ -77,7 +77,7 @@ dv.explorer.parameter::mod_lineplot(
   module_id = "lineplot", bm_dataset_name = "lb", group_dataset_name = "sl",
   subjid_var = "SUBJID", cat_var = "PARCAT1", par_var = "PARAM", 
   value_vars = "AVAL", visit_vars = "AVISITN", default_cat = "CHEM", 
-  default_par = "Cholesterol (mmol/L)", default_main_group = "SEX"
+  default_par = "Imaginariol (mmol/L)", default_main_group = "SEX"
 )
 ```
 
@@ -86,7 +86,7 @@ Which generates the following plot:
 
 # Grouped and ungrouped reference values
 
-We can provide a value for the `ref_line_vars` parameter so that in points to one or more `lb` numerical columns holding reference values:
+We can modify that call to `mod_lineplot` by providing a value for the `ref_line_vars` parameter so that in points to one or more `lb` numerical columns holding reference values:
 ```{r, eval=FALSE}
 dv.explorer.parameter::mod_lineplot(
   ..., default_main_group = "SEX", ref_line_vars = c("A1LO", "A1HI")
@@ -95,13 +95,13 @@ dv.explorer.parameter::mod_lineplot(
 
 Which produces:
 ![](images/lineplot_ref_line_01.png)
-Examining this plot we can see the three distinct reference values available in the original `bm` dataset. There is a `A1HI` value 
-common to all of our (two) subjects. It's indicated with a continuous black line. There are also two `A1LO` values that coincide with
-our selected grouping. Since the plot already provides colors for those groups, `mod_lineplot` to also plot those lines in matching colors.
+Examining this plot, we can see the three distinct reference values available in the original `bm` dataset. There is one `A1HI` value 
+common to our two subjects. It's indicated with a continuous black line. There are also two `A1LO` values that coincide with
+our selected grouping. Since the plot already provides colors for the "female" and "male" categories, `mod_lineplot` paints those lines in matching colors.
 
-# Which demographic value dictates distinct reference values?
+# Which demographic variable dictates distinct reference values?
 
-The original `bm` dataset does not tell us anything about origin of the different values of the `A1LO` reference values. It may very well be the case that `SEX` is indeed the variable that dictates which reference value to use but, in the absence of more information, `COUNTRY` would work equally well.
+The original `bm` dataset does not explain which variable leads to subjects having different `A1LO` reference values. One of the two subjects as a `A1LO` of 3.85 and the other one of 4.03. It's likely that `SEX` is the variable that justifies the difference. However, given the totality of the data, `COUNTRY` would work just as well. If we change the main grouping to `COUNTRY`, the plot remains the same except for the grouping legend:
 
 ```{r, eval=FALSE}
 dv.explorer.parameter::mod_lineplot(
@@ -110,42 +110,41 @@ dv.explorer.parameter::mod_lineplot(
 ```
 ![](images/lineplot_ref_line_02.png)
 
-This plot is still factually correct in the sense that the color of each `AVAL` line is color-matched with the `A1LO` value that accompanies it in the `lb` dataset.
+This plot is still factually correct in the sense that the color of each `AVAL` line is color-matched with the `A1LO` value that 
+shares the same row in the `lb` dataset.
 
 # Disappearing reference lines
 
-What happens then if we don't provide a grouping variable?
+What happens if we don't provide a main grouping variable?
 
 ```{r, eval=FALSE}
 dv.explorer.parameter::mod_lineplot(
   ..., ref_line_vars = c("A1LO", "A1HI")
 )
 ```
-In this case, `mod_lineplot` can't plot the `A1LO` reference values in a way that ties them to each of the two `AVAL` lines, so they are simply dropped:
+In this case, `mod_lineplot` can't plot the `A1LO` reference lines in a way that ties them to each of the two `AVAL` lines, so they are dropped:
 
 ![](images/lineplot_ref_line_03.png)
 
-Notice however, that the `A1HI` value keeps applying to all `AVAL` lines, so it is kept.
+Notice, however, that the `A1HI` value still applies to both black `AVAL` lines, so it is kept.
 
-# Inspecting all reference values
+# Displaying all reference values
 
-Sometimes it's useful to be able to see *all* reference values regardless of whether they can be represented truthfully given some 
-particular data grouping. In this case, users can override the built-in reference line filter by checking the "Show all reference values"
-option under the "Settings" drop-down menu.
+Sometimes it's useful to see *all* reference values regardless of whether they can be represented truthfully under some particular data grouping. To do that, users can override the built-in reference line filter by checking the "Show all reference values" option under the "Settings" drop-down menu.
 
 ![](images/lineplot_ref_line_04.png)
 
-After doing that, all unique reference values are shown in black. The legend is also modified to point out the non-standard nature of the plot.
+If we do that, all unique reference values are shown. The legend entries are also modified to point out the non-standard nature of the plot.
 
 ![](images/lineplot_ref_line_05.png)
 
 # Requirements for reference values
 
-Reference value dataset variables should:
+All reference value variables assigned to `ref_line_vars` should:
 
 - be numerical
 - remain constant across every combination of subject and parameter of the dataset
 
-If one of these conditions is not met during module start-up, `mod_lineplot` produces a suitable message, such as:
+If one of these conditions is not met during module start-up, `mod_lineplot` will produce a suitable error message, such as:
 
 ![](images/lineplot_ref_line_06.png)