Release candidate 6.3.0 (SomaLogic#147)

- simplified examples of calcOutlierMap() and
  s3 methods to reduce execution times
- fixed spelling errors and updated WORDLIST
- updated NEWS.md and cran-comments.md
- addresses items in SomaLogic#146

Author: scheidec

NEWS.md

@@ -1,5 +1,61 @@
 # SomaDataIO (development version)
 
+### New Functions
+
+* Added `preProcessAdat()` function
+  - added new function `preProcessAdat()` to filter features,
+    filter samples, generate data QC plots of normalization
+    scale factors by covariates, and perform standard analyte
+    RFU transformations including log10, centering, and scaling
+
+* Added `calcOutlierMap()` function
+  - added `calcOutlierMap()` and its print and plot
+    S3 methods, along with `getOutlierIds()` for
+    identifying sample level outliers from outlier map object
+  - added `ggplot2` as a package dependency
+
+### Function and Object Improvements
+
+* Added `ex_clin_data` object
+  - a `tibble` object with additional sample annotation fields
+    `smoking_status` and `alcohol_use` to demonstrate merging to a
+    `soma_adat` object
+
+### Documentation Updates
+
+* Added pre-processing vignette article
+  - includes guidance on pre-processing SomaScan data for
+    a typical analysis
+  - provides an example of recommended workflow of 
+    filtering features, filtering samples, performing data
+    QC checks, and transformations of RFU features
+  - introduces usage of the `preProcessAdat()` function
+
+* Improved adat ingest documentation in `README`
+  - added comments to clarify file path input to `read_adat()`
+    example in `README`
+    
+* Updated stat workflow articles to begin with reading in adat
+  - updated data preparation chunks with comments about
+    how to download and read in the the `example_data.adat` object
+  - data preparation chunks now use the `preProcessAdat()`
+    function for pre-processing
+
+* Added sample annotation merging guidance
+  - updated `README` and loading and wrangling vignette
+    article with section including code to join the 
+    `ex_clin_data` object to the `example_data` adat
+
+### Internal :construction:
+
+* Added helper utility functions for snapshot plot unit tests
+  - added helper utility functions `figure()`, `close_figure()`,
+    `save_png()`, and `expect_snapshot_plot()` for saving plot
+    snapshot output to `testthat/helper.R`
+  - added snapshot unit tests for `preProcessAdat()`
+    messaging, print and QC plot output
+
+
 # SomaDataIO 6.2.0
 
 ### New Functions

R/calcOutlierMap.R

@@ -36,26 +36,22 @@
 #'   \item{legend.sub}{A character string containing the plot legend subtitle.}
 #' @author Stu Field
 #' @examples
-#' om <- calcOutlierMap(example_data)
+#' dat <- example_data |> dplyr::filter(SampleType == "Sample")
+#' om <- calcOutlierMap(dat)
 #' class(om)
 #'
 #' # S3 print method
 #' om
 #'
 #' # `sample.order = "frequency"` orders samples by outlier frequency
-#' om <- calcOutlierMap(example_data, sample.order = "frequency")
+#' om <- calcOutlierMap(dat, sample.order = "frequency")
 #' om$rows.by.freq
 #' om$sample.order
 #'
-#' # order samples by user specified indices
-#' om <- calcOutlierMap(example_data, sample.order = 192:1)
-#' om$sample.order
-#'
 #' # order samples field in Adat
-#' om <- calcOutlierMap(example_data, sample.order = "Sex")
+#' om <- calcOutlierMap(dat, sample.order = "Sex")
 #' om$sample.order
 #' @importFrom stats median
-
 #' @export
 calcOutlierMap <- function(data, anno_tbl = NULL,
                            apt.order = c(NA, "dilution", "signal"),

R/plotMap.R

@@ -26,7 +26,7 @@
 #' @param gridlinelwd Width of the gridlines.
 #' @param gridlinelty Line type of the gridlines.
 #' @param main Character. Main title for the plot.
-#'   See [ggtitle()] for `ggplot2` style graphics.
+#'   See [ggplot2::ggtitle()] for `ggplot2` style graphics.
 #' @param x.lab Character. Optional string for the x-axis. Otherwise
 #'   one is automatically generated (default).
 #' @param y.lab Character. Optional string for the y-axis. Otherwise
@@ -42,17 +42,20 @@
 #'   The file name must also include the desired file type extension;
 #'   this will be used to determine the file type,
 #'   e.g. a file named `foo.png` will be saved as a `PNG`.
-#'   See [ggsave()] for a full list of file type (device) options.
+#'   See [ggplot2::ggsave()] for a full list of file type (device) options.
 #' @param plot.width If `"filename != NULL"`, the width of the plot image file.
 #' @param plot.height If `"filename != NULL"`, the height of the plot image file.
 #' @param plot.scale If `"filename != NULL"`, the scale of the plot image file.
 #' @param ... Arguments required by the `plot()` generic. Currently unused.
 #' @return Plot an image of the passed matrix.
 #' @author Stu Field, Amanda Hiser
-#' @seealso [ggplot()], [geom_raster()]
+#' @seealso [ggplot2::ggplot()], [ggplot2::geom_raster()]
 #' @examples
-#' om <- calcOutlierMap(example_data)
-#' plot(om, flags = 0.05)
+#' example_data |>
+#'   dplyr::filter(SampleType == "Sample") |>
+#'   head(10) |>
+#'   calcOutlierMap() |>
+#'   plot(flags = 0.05)
 #' @importFrom dplyr mutate group_by row_number ungroup
 #' @importFrom ggplot2 element_text element_blank element_rect unit
 #' @importFrom ggplot2 labs scale_x_discrete scale_x_continuous theme

R/preProcessAdat.R

@@ -2,7 +2,7 @@
 #'
 #' Pre-process an ADAT file containing raw analyte RFU values in preparation
 #' for analysis. For more details please refer to the [pre-processing how-to
-#' article](https://somalogic.github.io/SomaDataIO/articles/pre-processing.html)
+#' article](https://somalogic.github.io/SomaDataIO/dev/articles/pre-processing.html)
 #'
 #' The `soma_adat` object is pre-processed with the following steps:
 #'

cran-comments.md

@@ -1,10 +1,10 @@
 
-# Submission 6.2.0
+# Submission 6.3.0
 
 - This is a submission to an existing CRAN package.
 
-- It contains feature upgrades, minor internal bug-fixes,
-  and improved documentation.
+- It contains new functionality, a new vignette article and
+  improved documentation.
 
 
 ## Reverse Dependencies
@@ -27,13 +27,8 @@ The following `notes` were displayed during
 `devtools::check(remote = TRUE, manual = TRUE)`:
 
 ```
-❯ checking CRAN incoming feasibility ... [7s/72s] NOTE
+❯ checking CRAN incoming feasibility ... [7s/28s] NOTE
   Maintainer: ‘Caleb Scheidel <[email protected]>’
-  
-  New maintainer:
-    Caleb Scheidel <[email protected]>
-  Old maintainer(s):
-    Stu Field <[email protected]>
 
 ❯ checking installed package size ... NOTE
     installed size is  6.0Mb
@@ -42,7 +37,6 @@ The following `notes` were displayed during
       extdata   1.1Mb
 ```
 
-
 ## Package Size
 
 - Package tarball from `R CMD build` is 4.2Mb
@@ -52,31 +46,35 @@ The following `notes` were displayed during
 
 ```
 name	              user	system	elapsed
-Col.Meta	          0.23	0.01	0.25	
-SeqId	              0.03	0.02	0.05	
-SomaDataIO-package	  0.08	0.02	0.10	
-SomaScanObjects	      0.25	0.00	0.25	
-adat-helpers	      0.05	0.00	0.04	
-adat2eSet	          0.31	0.04	0.36	
-addClass	          0	    0	    0 	
-calc_eLOD	          0.01	0.00	0.01	
-cleanNames	          0	    0	    0	
-diffAdats	          0.33	0.00	0.33	
-getAnalyteInfo	      0.11	0.00	0.11	
-getAnalytes	          0.02	0.00	0.01	
-groupGenerics	      0.28	0.00	0.28	
-is_intact_attr	      0	    0 	    0	
-is_seqFormat	      0	    0	    0	
-lift_adat	          0.25	0.02	0.26	
-loadAdatsAsList	      1.36	0.00	1.36	
-merge_clin	          0.08	0.00	0.08	
-parseHeader	          0.08	0.01	0.09	
-pivotExpressionSet	  0.07	0.00	0.06	
-read_adat	          1.22	0.00	1.22	
-read_annotations	  0	    0	    0	
-rownames	          0	    0	    0	
-soma_adat	          0.2 	0.0 	0.2	
-transform	          0	    0	    0	
-write_adat	          0.24	0.01	0.25
+Col.Meta	          0.34	0.00	  0.34	
+SeqId	              0.03	0.02	  0.05	
+SomaDataIO-package	0.12	0.00	  0.12	
+SomaScanObjects	    0.36	0.00	  0.36	
+adat-helpers	      0.06	0.00	  0.08	
+adat2eSet	          0.58	0.06	  0.64	
+addClass	          0   	0   	  0	
+calcOutlierMap	    4.49	0.29	  4.78	
+calc_eLOD	          0.03	0.00	  0.03	
+cleanNames	        0	    0	      0	
+diffAdats	          0.47	0.05	  0.51	
+getAnalyteInfo	    0.17	0.00	  0.17	
+getAnalytes	        0.01	0.00	  0.01	
+getOutlierIds	      2.03	0.09	  2.14	
+groupGenerics	      0.49	0.00	  0.49	
+is_intact_attr	    0.01	0.00	  0.02	
+is_seqFormat	      0.02	0.00	  0.02	
+lift_adat	          0.44	0.00	  0.44	
+loadAdatsAsList	    1.67	0.02	  1.69	
+merge_clin	        0.12	0.01	  0.14	
+parseHeader	        0.14	0.02	  0.15	
+pivotExpressionSet	0.11	0.00	  0.11	
+plot.Map	          1.78	0.06	  1.84	
+preProcessAdat	    1.88	0.03	  1.91	
+read_adat	          1.44	0.03	  1.47	
+read_annotations	  0 	  0   	  0	
+rownames	          0.01	0.00	  0.01	
+soma_adat	          0.29	0.00	  0.29	
+transform	          0	    0	      0	
+write_adat	        0.40	0.01	  0.42
 ```
 

inst/WORDLIST

@@ -38,6 +38,8 @@ LF
 Lifecycle
 MERCHANTABILITY
 MacOS
+MADs
+NHS
 NormScale
 ORCID
 PII
@@ -125,4 +127,5 @@ tada
 th
 tibble
 tidyr
+untransformed
 vectorized

man/calcOutlierMap.Rd

@@ -302,7 +302,7 @@ and removed.
 ### Sample Level Outliers by RFU
 
 It is also important to evaluate if there are any sample-level outliers
-by RFU measurements. For standard plasma and serum studies Standard Biotools'
+by RFU measurements. For standard plasma and serum studies Standard BioTools'
 recommended outlier definition is any sample where `>= 5%` of RFU measurements
 exceed 6 median absolute deviations (MADs) and 5x fold-change from median
 signal.
@@ -539,7 +539,7 @@ SeqId B in the original sample prep. All comparisons should be made between
 sample groups *within* a given SeqId. The RFU value, as well as log10 RFU and
 z-score, is dependent on variety of analyte-specific factors such as the
 SOMAmer Reagent-target protein binding kinetics, the dilution bin of the
-SOMAmer reagant, NHS-biotin conjagation efficiency of the SOMAmer, and other
+SOMAmer reagent, NHS-biotin conjugation efficiency of the SOMAmer, and other
 factors intrinsic to the SOMAmer Reagent within the SomaScan assay.