Update vignette to include info about new unidentified feature retent…

…ion option

vignettes/LOBSTAHS.Rmd

@@ -395,41 +395,48 @@ Once we've created our database (or we've decided to use the appropriate onboard
 
     If the user wishes to use the retention time restriction feature with his/her own retention time data (highly recommended) a .csv table can be created from an Excel template available in the same subdirectory (/LOBSTAHS/doc/) of the R library path where the database generation templates reside. The template can be downloaded as [LOBSTAHS_rt.windows.xlsx](https://github.com/vanmooylipidomics/LOBSTAHS/blob/master/inst/doc/xlsx/LOBSTAHS_rt.windows.xlsx) from the LOBSTAHS GitHub repository.
 
-     **Important note:** To account for shifts in retention time that occur during chromatographic alignment in xcms, LOBSTAHS automatically expands the retention time ranges given in the `rt.windows` table by 10% at each extreme. If xcms retention time correction results in large differences between raw and corrected retention times, the user should elect **not** to apply retention time restriction in LOBSTAHS (i.e., set `rt.restrict = FALSE`) since valid feartures could be lost. The extent of deviation between raw and corrected retention times can be diagnosed using the retention time correction profile plot, obtained with `plottype = "mdevden"` when calling `retcor` in xcms. A future version of LOBSTAHS will allow the user to the set the factor by which the lipid class retention time windows should be expanded.
+     **Important note:** To account for shifts in retention time that occur during chromatographic alignment in xcms, LOBSTAHS automatically expands the retention time ranges given in the `rt.windows` table by 10% at each extreme. If xcms retention time correction results in large differences between raw and corrected retention times, the user should elect **not** to apply retention time restriction in LOBSTAHS (i.e., set `rt.restrict = FALSE`) since valid features could be lost. The extent of deviation between raw and corrected retention times can be diagnosed using the retention time correction profile plot, obtained with `plottype = "mdevden"` when calling `retcor` in xcms. A future version of LOBSTAHS will allow the user to the set the factor by which the lipid class retention time windows should be expanded.
 
 1. Next, assignments with an odd total number of acyl carbon atoms can be eliminated (achieved by setting `exclude.oddFA = TRUE`). Applies only to acyl lipids (i.e., IP-DAG, TAG, PUA, or free fatty acids). Useful if data are (or are believed to be) of exclusively eukaryotic origin, since synthesis of fatty acids with odd numbers of carbon atoms is not known in eukaryotes.<sup>[9](#note9)</sup>
 
 1. A series of adduct ion hierarchy rules are then applied to the remaining assignments. The theory and development of these rules is described in Collins et al 2016.<sup>[1](#note1)</sup> and summarized in the [schematic above](#schematic). During the adduct ion screening process, a [series of codes](#schematic) are applied to each assignment to indicate the degree to which it satisfied the hierarchy rules Unlike the other screening features, application of the adduct ion hierarchy rules is not optional.
 
 1. Once the list of compound assignments has been screened by pseudospectrum according to the user's specifications, the assignments are then evaluated as a single group to identify possible isomers and isobars (compounds having distinct but very similar *m/z*). These isomers and isobars are annotated with [additional codes](#schematic) so the user can examine them in subsequent analysis.
 
-Once done, `doLOBscreen` returns a `LOBSet` object containing the fully screened dataset. To screen the PtH2O2lipids `xsAnnotate` object using the same settings that produced the results in Collins et al. 2016<sup>[1](#note1)</sup>, we would run:
+Once done, `doLOBscreen` returns a `LOBSet` object containing the fully screened dataset. LOBSTAHS v1.3.3 and newer allows the user to retain data for all features in the original `xsAnnotate` object &mdash; those that were not identified or were discarded during the screening process, in addition to data for those features to which a compound assignment was applied from the database. This is useful when untargeted follow-on data analysis is anticipated, or the user simply wants to export data for all features present in the original dataset, not just those for which a LOBSTAHS identity was found.
+
+To screen the PtH2O2lipids `xsAnnotate` object using the same settings that produced the results in Collins et al. 2016<sup>[1](#note1)</sup>, we would run:
 
 ```{r, eval = FALSE}
 myPtH2O2LOBSet = doLOBscreen(ptH2O2lipids$xsAnnotate, polarity = "positive",
                              database = NULL, remove.iso = TRUE,
                              rt.restrict =  TRUE, rt.windows = NULL,
-                             exclude.oddFA = TRUE, match.ppm = 2.5)
+                             exclude.oddFA = TRUE, match.ppm = 2.5
+                             retain.unidentified = FALSE)
 ```
 
-In this example, the object "myPtH2O2LOBSet" would be identical to the screened `LOBSet` in the PtH2O2lipids package (`ptH2O2lipids$LOBSet`). Information about a `LOBSet` can be viewed by calling the object at the R prompt. For example:
+In this example, the object "myPtH2O2LOBSet" is not identical to the screened `LOBSet` in the PtH2O2lipids package (`ptH2O2lipids$LOBSet`) because the default database now includes many more comopounds than it did when the package was first released in 2015. Information about a `LOBSet` can be viewed by calling the object at the R prompt. For example:
 
 ```{r, warning = FALSE, message = FALSE, eval = FALSE}
 ptH2O2lipids$LOBSet
-#> A positive polarity "LOBSet" containing LC-MS peak data. Compound assignments and adduct ion hierarchy screening annotations applied to 16 samples using the "LOBSTAHS" package.
+#> A positive polarity "LOBSet" containing LC-MS peak data. Compound assignments
+#> and adduct ion hierarchy screening annotations applied to 16 samples using the
+#> "LOBSTAHS" package.
 #> 
-#> Individual peaks: 21869 
-#> Peak groups: 1595 
-#> Compound assignments: 1969 
-#> m/z range: 551.425088845409-1269.09515435315 
+#> No. individual peaks with LOBSTAHS compound assignments: 21869 
+#> No. peak groups with LOBSTAHS compound assignments: 1595 
+#> No. LOBSTAHS compound assignments: 1969 
+#> m/z range of features identified using LOBSTAHS: 551.425088845409-1269.09515435315 
 #> 
-#> Peak groups having possible regisomers: 556 
-#> Peak groups having possible structural functional isomers: 375 
-#> Peak groups having isobars indistinguishable within ppm matching tolerance: 84 
+#> Identified peak groups having possible regisomers: 556 
+#> Identified peak groups having possible structural functional isomers: 375 
+#> Identified peak groups having isobars indistinguishable within ppm matching
+#>  tolerance: 84 
 #> 
-#> Restrictions applied prior to conducting adduct ion hierarchy screening: remove.iso, rt.restrict, exclude.oddFA 
+#> Restrictions applied prior to conducting adduct ion hierarchy screening:
+#>  remove.iso, rt.restrict, exclude.oddFA 
 #> 
-#> Match tolerance used for database assignments: 2.5 ppm
+#> Match tolerance used for LOBSTAHS database assignments: 2.5 ppm
 #> 
 #> Memory usage: 1.26 MB
 ```
@@ -459,7 +466,7 @@ LOBisoID_diagnostics(ptH2O2lipids$LOBSet)
 
 ### Follow-on analysis of screened data
 
-With the set of screened compound assignments in hand, we now have several options. Users familiar with R can extract data for further analysis or screening directly from the `LOBSet` object. Alternatively, the function `getLOBpeaklist` can be used to extract a table of results from the `LOBSet`. Options in `getLOBpeaklist` allow the user to (1) include isomer and isobar cross-references (the default; recommended) and (2) simultaneously generate a .csv file with the results. The .csv file is exported with a unique timestamp to the R working directory.
+With the set of screened compound assignments in hand, we now have several options. Users familiar with R can extract data for further analysis or screening directly from the `LOBSet` object. Alternatively, the function `getLOBpeaklist` can be used to extract a table of results from the `LOBSet`. Options in `getLOBpeaklist` allow the user to (1) include isomer and isobar cross-references (the default; recommended), (2) include data for features in the original `xsAnnotate` object that were not identified or were discarded during the screening process, and (3) simultaneously generate a .csv file with the results. The .csv file is exported with a unique timestamp to the R working directory.
 
 ### Package updates and improvements