Merge pull request #354 from USEPA/352-update-vignette-for-loec-changes

352 updates to vignette for loec changes

Author: cthunes

Diff for: vignettes/Introduction_Appendices.Rmd

@@ -1172,7 +1172,7 @@ corrected data",
 the \'mc3_aeid\' table to the corrected data to define response",
 "Fit: Model the concentration-response data utilizing ten
 objective curve-fitting functions from tcplfit2: (1) constant, (2) hill, (3) gain-loss, (4) polynomial-linear, (5) polynomial-quadratic, (6) power, (7) exponential-2, (8) exponential-3, (9) exponential-4, (10) exponential-5",
-"Model Selection/Acitivty Call: Select the winning model, define
+"Model Selection/Activity Call: Select the winning model, define
 the response cutoff based on methods in the \'mc5_aeid\' table, and
 determine activity",
 "Flag: Flag potential false positive and false negative fits", 
@@ -1861,6 +1861,29 @@ htmlTable(output,
           )
 ```
 
+In addition, there may be situations where traditional modeling under <font face="CMTT10">tcplFit2</font> is not totally appropriate. For example, data which have limited efficacy, do not have continuous response values, or have a limited number of experimental concentrations tested may be candidates for "loec", or the lowest observed effective concentration, potency and hitcalling determinations. A "loec" in <font face="CMTT10">tcpl</font> is defined as the lowest experimental dose where all responses surpass the cutoff.
+
+There are two methods for including a "loec" within the output of level 5 processing and stored within the `mc5_param` table. The "include" method stores the "loec" alongside regular <font face="CMTT10">tcplFit2</font> winning model fitting, whereas the "ow" (overwrite) method does the same while also overwriting key values, i.e. $model\_type$, $fitc$ (fit category), $modl$ (winning model), and $hitc$ (1 or 0 based on whether a "loec" occurs). See [Plotting](#additional-examples) for how "loec"-fit data are plot.
+
+```{r warning = FALSE, echo = FALSE}
+Method <- c(15,34)
+Method_Name <- c("ow_loec.coff", "include_loec.coff")
+Description <- c(
+  "Identify the lowest observed effective concentration (loec) where the values of all responses are outside the cutoff band (i.e. abs(resp) > cutoff). loec is stored alongside winning model and potency estimates. Assume <br/>- modl = 'loec'<br/>- fitc = 100<br/>- model_type = 1<br/>- hit call = 1 if loec exists, 0 if not.",
+  "Identify the lowest observed effective concentration (loec) where the values of all responses are outside the cutoff band (i.e. abs(resp) > cutoff). loec is stored alongside winning model and potency estimates."
+)
+# Compile all of the information for the table.
+output <- data.frame(Method,Method_Name,Description)
+# Export/print the table to an html rendered table.
+htmlTable(output,
+          align = 'l',
+          align.header = 'l',
+          rnames = FALSE  ,
+          css.cell =  ' padding-bottom: 5px;  vertical-align:top; padding-right: 10px;min-width: 5em ',
+          caption="Table 12: Level 5 methods for including loec values and overwriting others."
+          )
+```
+
 The example we include in this vignette for demonstrating the assignment of level 5 methods specifies three different efficacy cutoff estimates for consideration.  These efficacy cutoff estimates include $3*\mathit{bmad}$, $log_2(1.2)$, and $5*\mathit{bmad}$, which correspond to $\mathit{mthd\_id}$ assignments 1, 3, and 5 respectively, and the largest of these three values will be selected as the cutoff for the endpoint. With the methods assigned, the data are ready for MC5 processing.
 
 ```{r eval=FALSE}
@@ -3254,7 +3277,9 @@ tcplPlot(dat = plot_data, by = "aeid", multi = TRUE, output = "pdf", fileprefix
 
 ### - Plot LOEC (Lowest Observed Effective Concentration)
 
-<font face="CMTT10">tcplPlot</font> now supports the plotting of vertical "LOEC" lines, automatically detecting when multi-concentration data is hit-called using the new level 5 processing method "loec.coff". Comparison LOEC plotting with other LOEC samples or crossed with traditional hit-called data with winning models is also supported.
+<font face="CMTT10">tcplPlot</font> now supports automatically adding the "loec" to the plot, i.e., a vertical line, when detecting multi-concentration data with hit-calling using the new level 5 processing method "ow_loec.coff". Comparison plotting with "loec" across samples or with traditional hit-calling results using the winning models is also supported.
+
+Note - for data processed with the level 5 method "include_loec.coff", <font face="CMTT10">tcplPlot</font> will not automatically generate this kind of plot. A current workaround is to pre-load the plotting data using `tcplPlotLoadData` and update the $\mathit{model\_type}$ column to `1` for any or all sample(s). Future <font face="CMTT10">tcpl</font> versions may include additive "loec" lines as an option.
 
 ```{r plot_loec, eval = FALSE}
 # default parameters used here: type = "mc"