Add sample annotation merging guidance (#145)

* Add sample annotation merging guidance

- added `ex_clin_data` object with
  additional sample annotation fields
  `smoking_status` and `alcohol_use` to
  demonstrate merging to a `soma_adat`
  object
- updated README and loading and wrangling
  vignette article with section including
  code to join this object to the
  example_data adat

Author: scheidec

R/data.R

@@ -7,7 +7,7 @@
 #' group for studies or provide any metrics for SomaScan data in general.
 #'
 #' @name SomaScanObjects
-#' @aliases example_data ex_analytes ex_anno_tbl ex_target_names
+#' @aliases example_data ex_analytes ex_anno_tbl ex_target_names ex_clin_data
 #' @docType data
 #'
 #' @section Data Description:
@@ -64,6 +64,11 @@
 #'     target names contained in `example_data`. This object (or one like it) is
 #'     convenient at the console via auto-complete for labeling and/or creating
 #'     plot titles on the fly.}
+#'
+#'   \item{ex_clin_data}{A table containing `SampleId`, `smoking_status`, and
+#'     `alcohol_use` fields for each clinical sample in `example_data` used to
+#'     demonstrate how to merge sample annotation information to an existing
+#'     `soma_adat` object.}
 #' }
 #'
 #' @source \url{https://github.com/SomaLogic/SomaLogic-Data}

README.Rmd

@@ -157,7 +157,7 @@ library(help = SomaDataIO)
 
 ## Objects and Data
 
-The `SomaDataIO` package comes with four (4) objects available
+The `SomaDataIO` package comes with five (5) objects available
 to users to run canned examples (or analyses). They can be accessed once
 `SomaDataIO` has been attached via `library()`. They are:
 
@@ -175,6 +175,9 @@ to users to run canned examples (or analyses). They can be accessed once
 * `ex_analytes`: the analyte (feature) variables in `example_data`
 * `ex_anno_tbl`: the annotations table associated with `example_data`
 * `ex_target_names`: a mapping object for analyte -> target
+* `ex_clin_data`: a table containing variables `SampleId`, `smoking_status` and
+  `alcohol_use` to demonstrate merging clinical sample annotation information
+  to a `soma_adat` object
 * See also `?SomaScanObjects`
 
 
@@ -212,7 +215,7 @@ adat_path
 
 # `adat_path` should be the elaborated path and file name of the *.adat file to
 # be loaded into the R workspace from your local file system
-# (e.g. file_path = "PATH_TO_ADAT/my_adat.adat")
+# (e.g. adat_path = "PATH_TO_ADAT/my_adat.adat")
 my_adat <- read_adat(file = adat_path)
 
 # test object class
@@ -238,6 +241,31 @@ S3 methods to the most popular
 methods(class = "soma_adat")
 ```
 
+#### Merging Sample Annotation Data
+
+The `example_data` object includes some sample annotation data built-in, with
+the variables `Age` and `Sex` included for clinical samples, but in practice 
+ADAT files generally do not have any clinical or sample annotation data fields
+included.
+
+To merge sample annotation data into an existing `soma_adat` class object,
+use the `left_join()` method.  Here, joining the `ex_clin_data` object adds in
+two additional clinical variables, `smoking_status` and `alcohol_use`:
+
+```{r merge-annotations}
+# `clin_path` should be the elaborated path and file name of the *.csv or
+# similar file to be loaded into the R workspace from your local file system
+# (e.g. clin_path = "PATH_TO_CLIN/clin_data.csv")
+# clin_data <- readr::read_csv(clin_path)
+
+merged_adat <- my_adat |> 
+  dplyr::left_join(ex_clin_data, by = "SampleId") 
+
+merged_adat |> 
+  dplyr::select(SampleId, Age, Sex, smoking_status, alcohol_use) |> 
+  head(n = 3)
+```
+
 Please see the article [Loading and Wrangling SomaScan](https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html)
 for more details about available `soma_adat` methods.
 

README.md

@@ -6,7 +6,7 @@
 <!-- badges: start -->
 
 ![GitHub
-version](https://img.shields.io/badge/Version-6.1.0.9000-success.svg?style=flat&logo=github)
+version](https://img.shields.io/badge/Version-6.2.0.9000-success.svg?style=flat&logo=github)
 [![CRAN
 status](http://www.r-pkg.org/badges/version/SomaDataIO)](https://cran.r-project.org/package=SomaDataIO)
 [![Downloads](https://cranlogs.r-pkg.org/badges/SomaDataIO)](https://cran.r-project.org/package=SomaDataIO)
@@ -132,7 +132,7 @@ library(help = SomaDataIO)
 
 ## Objects and Data
 
-The `SomaDataIO` package comes with four (4) objects available to users
+The `SomaDataIO` package comes with five (5) objects available to users
 to run canned examples (or analyses). They can be accessed once
 `SomaDataIO` has been attached via `library()`. They are:
 
@@ -157,6 +157,10 @@ to run canned examples (or analyses). They can be accessed once
 
 - `ex_target_names`: a mapping object for analyte -\> target
 
+- `ex_clin_data`: a table containing variables `SampleId`,
+  `smoking_status` and `alcohol_use` to demonstrate merging clinical
+  sample annotation information to a `soma_adat` object
+
 - See also `?SomaScanObjects`
 
 ------------------------------------------------------------------------
@@ -192,7 +196,7 @@ adat_path
 
 # `adat_path` should be the elaborated path and file name of the *.adat file to
 # be loaded into the R workspace from your local file system
-# (e.g. file_path = "PATH_TO_ADAT/my_adat.adat")
+# (e.g. adat_path = "PATH_TO_ADAT/my_adat.adat")
 my_adat <- read_adat(file = adat_path)
 
 # test object class
@@ -260,6 +264,54 @@ methods(class = "soma_adat")
 #> see '?methods' for accessing help and source code
 ```
 
+#### Merging Sample Annotation Data
+
+The `example_data` object includes some sample annotation data built-in,
+with the variables `Age` and `Sex` included for clinical samples, but in
+practice ADAT files generally do not have any clinical or sample
+annotation data fields included.
+
+To merge sample annotation data into an existing `soma_adat` class
+object, use the `left_join()` method. Here, joining the `ex_clin_data`
+object adds in two additional clinical variables, `smoking_status` and
+`alcohol_use`:
+
+``` r
+# `clin_path` should be the elaborated path and file name of the *.csv or
+# similar file to be loaded into the R workspace from your local file system
+# (e.g. clin_path = "PATH_TO_CLIN/clin_data.csv")
+# clin_data <- readr::read_csv(clin_path)
+
+merged_adat <- my_adat |> 
+  dplyr::left_join(ex_clin_data, by = "SampleId") 
+
+merged_adat |> 
+  dplyr::select(SampleId, Age, Sex, smoking_status, alcohol_use) |> 
+  head(n = 3)
+#> ══ SomaScan Data ═══════════════════════════════════════════════════════════════
+#>      SomaScan version     V4 (5k)
+#>      Signal Space         5k
+#>      Attributes intact    ✓
+#>      Rows                 3
+#>      Columns              5
+#>      Clinical Data        5
+#>      Features             0
+#> ── Column Meta ─────────────────────────────────────────────────────────────────
+#> ℹ SeqId, SeqIdVersion, SomaId, TargetFullName, Target, UniProt, EntrezGeneID,
+#> ℹ EntrezGeneSymbol, Organism, Units, Type, Dilution, PlateScale_Reference,
+#> ℹ CalReference, Cal_Example_Adat_Set001, ColCheck,
+#> ℹ CalQcRatio_Example_Adat_Set001_170255, QcReference_170255,
+#> ℹ Cal_Example_Adat_Set002, CalQcRatio_Example_Adat_Set002_170255, Dilution2
+#> ── Tibble ──────────────────────────────────────────────────────────────────────
+#> # A tibble: 3 × 6
+#>   row_names      SampleId   Age Sex   smoking_status alcohol_use
+#>   <chr>          <chr>    <int> <chr> <chr>          <chr>      
+#> 1 258495800012_3 1           76 F     Never          Yes        
+#> 2 258495800004_7 2           55 F     Never          Yes        
+#> 3 258495800010_8 3           47 M     Never          No         
+#> ════════════════════════════════════════════════════════════════════════════════
+```
+
 Please see the article [Loading and Wrangling
 SomaScan](https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html)
 for more details about available `soma_adat` methods.

data-raw/SomaScanObjects.R

@@ -5,13 +5,28 @@ data <- example_data
 x <- ex_analytes
 y <- ex_anno_tbl
 z <- ex_target_names
+zz <- ex_clin_data
 
 # 'new'
 example_data <- read_adat("example_data.adat")  # download via wget
 ex_analytes  <- getAnalytes(example_data)
 ex_anno_tbl  <- getAnalyteInfo(example_data)
 ex_target_names <- getTargetNames(ex_anno_tbl)
 
+withr::with_seed(123, {
+  ex_clin_data <- example_data |>
+    dplyr::filter(SampleType == "Sample") |>
+    dplyr::mutate(
+      smoking_status = sample(c("Current", "Past", "Never"),
+                              size = 170, replace = TRUE),
+      alcohol_use    = sample(c("Yes", "No"),
+                              size = 170, replace = TRUE)
+    ) |>
+    select(SampleId, smoking_status, alcohol_use) |>
+    as_tibble()
+})
+
+
 # 'save only if necessary'
 if ( !isTRUE(all.equal(data, example_data)) ) {
   save(example_data, file = "data/example_data.rda", compress = "xz")
@@ -20,6 +35,7 @@ if ( !isTRUE(all.equal(data, example_data)) ) {
 # 'save only if necessary'
 if ( !all(isTRUE(all.equal(x, ex_analytes)),
           isTRUE(all.equal(y, ex_anno_tbl)),
-          isTRUE(all.equal(z, ex_target_names))) ) {
-  save(ex_analytes, ex_anno_tbl, ex_target_names, file = "data/data_objects.rda", compress = "xz")
+          isTRUE(all.equal(z, ex_target_names)),
+          isTRUE(all.equal(zz, ex_clin_data))) ) {
+  save(ex_analytes, ex_anno_tbl, ex_target_names, ex_clin_data, file = "data/data_objects.rda", compress = "xz")
 }

data/data_objects.rda

@@ -180,6 +180,32 @@ males |>
 ```
 
 
+#### Merging Sample Annotation Data
+
+The `example_data` object includes some sample annotation data built-in, with
+the variables `Age` and `Sex` included for clinical samples, but in practice 
+ADAT files generally do not have any clinical or sample annotation data fields
+included.
+
+To merge sample annotation data into an existing `soma_adat` class object,
+use the `left_join()` method.  Here, joining the `ex_clin_data` `tibble` object
+adds in two additional clinical variables, `smoking_status` and `alcohol_use`:
+
+```{r merge-annotations}
+# `clin_path` should be the elaborated path and file name of the *.csv or
+# similar file to be loaded into the R workspace from your local file system
+# (e.g. clin_path = "PATH_TO_CLIN/clin_data.csv")
+# clin_data <- readr::read_csv(clin_path)
+
+merged_adat <- my_adat |> 
+  dplyr::left_join(ex_clin_data, by = "SampleId") 
+
+merged_adat |> 
+  dplyr::select(SampleId, Age, Sex, smoking_status, alcohol_use) |> 
+  head(n = 3)
+```
+
+
 ### Available S3 Methods `soma_adat`
 
 ```{r methods}