SomaDataIO

https://somalogic.github.io/SomaDataIO/
Admin
SomaDataIO is an R package that loads, exports, and manipulates SomaScan proteomic data from ADAT...
Tokens:67,129
Snippets:432
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### List Example Data Files within SomaDataIO

Source: https://somalogic.github.io/SomaDataIO/index.html

List the full paths to the example data files included within the installed SomaDataIO package. This typically includes a light-weight version of example_data.adat.

```r
dir(system.file("extdata", package = "SomaDataIO"), full.names = TRUE)
```

--------------------------------

### Install SomaDataIO from GitHub (Development Version)

Source: https://somalogic.github.io/SomaDataIO/index.html

Install the most current development version of SomaDataIO from its GitHub repository.

```r
remotes::install_github("SomaLogic/SomaDataIO")
```

--------------------------------

### Example: Get and Summarize Analyte Annotation Data

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalyteInfo.html

Demonstrates how to obtain analyte annotation data using getAnalyteInfo and then summarize it by 'Dilution' using dplyr.

```R
# Get Aptamer table
anno_tbl <- getAnalyteInfo(example_data)
anno_tbl
#> # A tibble: 5,284 × 22
#>    AptName      SeqId SeqIdVersion SomaId TargetFullName Target UniProt
#>    <chr>        <chr>        <dbl> <chr>  <chr>          <chr>  <chr>  
#>  1 seq.10000.28 1000…            3 SL019… Beta-crystall… CRBB2  P43320 
#>  2 seq.10001.7  1000…            3 SL002… RAF proto-onc… c-Raf  P04049 
#>  3 seq.10003.15 1000…            3 SL019… Zinc finger p… ZNF41  P51814 
#>  4 seq.10006.25 1000…            3 SL019… ETS domain-co… ELK1   P19419 
#>  5 seq.10008.43 1000…            3 SL019… Guanylyl cycl… GUC1A  P43080 
#>  6 seq.10011.65 1001…            3 SL019… Inositol poly… OCRL   Q01968 
#>  7 seq.10012.5  1001…            3 SL014… SAM pointed d… SPDEF  O95238 
#>  8 seq.10013.34 1001…            3 SL025… Fc_MOUSE       Fc_MO… Q99LC4 
#>  9 seq.10014.31 1001…            3 SL007… Zinc finger p… SLUG   O43623 
#> 10 seq.10015.1… 1001…            3 SL014… Voltage-gated… KCAB2  Q13303 
#> # ℹ 5,274 more rows
#> # ℹ 15 more variables: EntrezGeneID <chr>, EntrezGeneSymbol <chr>,
#> #   Organism <chr>, Units <chr>, Type <chr>, Dilution <chr>,
#> #   PlateScale_Reference <dbl>, CalReference <dbl>,
#> #   Cal_Example_Adat_Set001 <dbl>, ColCheck <chr>,
#> #   CalQcRatio_Example_Adat_Set001_170255 <dbl>,
#> #   QcReference_170255 <dbl>, Cal_Example_Adat_Set002 <dbl>, …

# Use `dplyr::group_by()`
dplyr::tally(dplyr::group_by(anno_tbl, Dilution))  # print summary by dilution
#> # A tibble: 4 × 2
#>   Dilution     n
#>   <chr>    <int>
#> 1 0           12
#> 2 0.005      173
#> 3 0.5        828
#> 4 20        4271
```

--------------------------------

### Install SomaDataIO from GitHub (Latest Release)

Source: https://somalogic.github.io/SomaDataIO/index.html

Install the most recent stable release of SomaDataIO from GitHub.

```r
remotes::install_github("SomaLogic/SomaDataIO@*release")
```

--------------------------------

### List Files in Analysis Directory - R

Source: https://somalogic.github.io/SomaDataIO/articles/cli-merge-tool.html

Lists the files present in the analysis directory after creating the example ADAT and clinical data files. This confirms the setup for the merge operation.

```r
dir(analysis_dir)
#> [1] "clin-data.csv"  "ex-data-9.adat" "merge_clin.R"
```

--------------------------------

### Install SomaDataIO from GitHub (Specific Release)

Source: https://somalogic.github.io/SomaDataIO/index.html

Install a specific tagged release of SomaDataIO from GitHub by providing the version tag.

```r
remotes::install_github("SomaLogic/SomaDataIO@v5.3.0")
```

--------------------------------

### Download Example SomaScan Data

Source: https://somalogic.github.io/SomaDataIO/index.html

Download the original SomaScan ADAT file used in examples directly from GitHub.

```bash
wget https://raw.githubusercontent.com/SomaLogic/SomaLogic-Data/main/example_data.adat
```

--------------------------------

### Example Data Objects

Source: https://somalogic.github.io/SomaDataIO/reference/SomaScanObjects.html

Overview of the example data objects available in SomaDataIO.

```APIDOC
## Example Data and Objects

Source: `R/data.R`
`SomaScanObjects.Rd`

The `example_data` object is intended to provide existing and prospective SomaLogic customers with example data to enable analysis preparation prior to receipt of SomaScan data, and also for those generally curious about the SomaScan data deliverable. It is **not** intended to be used as a control group for studies or provide any metrics for SomaScan data in general.

### `example_data`

a `soma_adat` parsed via `read_adat()` containing 192 samples (see below for breakdown of sample type). There are 5318 columns containing 5284 analyte features and 34 clinical meta data fields. These data have been pre-processed via the following steps:
  * hybridization normalized (all samples)
  * calibrators and buffers median normalized
  * plate scaled
  * calibrated
  * Adaptive Normalization by Maximum Likelihood (ANML) of QC and clinical samples

**Note1:** The `Age` and `Sex` (`M`/`F`) fields contain simulated values designed to contain biological signal.
**Note2:** The `SampleType` column contains sample source/type information and usually the `SampleType == Sample` represents the "client" samples.
**Note3:** The original source file can be found at
\url{https://github.com/SomaLogic/SomaLogic-Data}.

### `ex_analytes`

character string of the analyte features contained in the `soma_adat` object, derived from a call to `getAnalytes()`.

### `ex_anno_tbl`

a lookup table corresponding to a transposed data frame of the "Col.Meta" attribute of an ADAT, with an index key field `AptName` included in column 1, derived from a call to `getAnalyteInfo()`.

### `ex_target_names`

A lookup table mapping `SeqId` feature names -> 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.

### `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
https://github.com/SomaLogic/SomaLogic-Data
SomaLogic Operating Co., Inc.

## Data Description
The `example_data` object contains a SomaScan V4 study from healthy normal individuals. The RFU measurements themselves and other identifiers have been altered to protect personally identifiable information (PII), but also retain underlying biological signal as much as possible. There are 192 total EDTA-plasma samples across two 96-well plate runs which are broken down by the following types:
  * 170 clinical samples (client study samples)
  * 10 calibrators (replicate controls for combining data across runs)
  * 6 QC samples (replicate controls used to assess run quality)
  * 6 Buffer samples (no protein controls)

## Data Processing
The standard V4 data normalization procedure for EDTA-plasma samples was applied to this dataset. For more details on the data standardization process see the Data Standardization and File Specification Technical Note. General details are outlined above.

## Examples
```
```

--------------------------------

### Install Biobase Package

Source: https://somalogic.github.io/SomaDataIO/reference/adat2eSet.html

Installs the Biobase package from Bioconductor. Ensure BiocManager is installed first.

```r
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("Biobase", version = remotes::bioc_version())
```

--------------------------------

### Example Usage of calcOutlierMap

Source: https://somalogic.github.io/SomaDataIO/reference/calcOutlierMap.html

Demonstrates how to use the `calcOutlierMap` function with example data. It shows filtering data, calculating the outlier map, and checking the class of the returned object.

```R
dat <- example_data |> dplyr::filter(SampleType == "Sample")
om <- calcOutlierMap(dat)
class(om)
#> [1] "outlier_map" "Map"         "list"       
```

--------------------------------

### Install SomaDataIO from CRAN

Source: https://somalogic.github.io/SomaDataIO/index.html

Use this command to install the SomaDataIO package directly from CRAN.

```r
install.packages("SomaDataIO")
```

--------------------------------

### Create Example ADAT Data - R

Source: https://somalogic.github.io/SomaDataIO/articles/cli-merge-tool.html

Generates a subset of example SomaScan data and writes it to an ADAT file within the specified analysis directory. This serves as the base data for the merge operation.

```r
feats <- withr::with_seed(3, sample(getAnalytes(example_data), 5L))
sub_adat <- dplyr::select(example_data, PlateId, SlideId, Subarray,
                          SampleId, Age, all_of(feats)) |> head(9L)
withr::with_dir(analysis_dir,
  write_adat(sub_adat, file = "ex-data-9.adat")
)
#> ✔ ADAT passed all checks and traps.
#> ✔ ADAT written to: "ex-data-9.adat"
```

--------------------------------

### Examples of is_seqFormat

Source: https://somalogic.github.io/SomaDataIO/reference/is_seqFormat.html

Demonstrates testing character vectors and soma_adat objects for the required sequence format.

```R
# character S3 method
is_seqFormat(names(example_data))   # no; meta data not ^seq.
#> [1] FALSE
is_seqFormat(tail(names(example_data), -20L))   # yes
#> [1] FALSE

# soma_adat S3 method
is_seqFormat(example_data)
#> [1] TRUE
```

--------------------------------

### Load SomaDataIO Package

Source: https://somalogic.github.io/SomaDataIO/index.html

Load the SomaDataIO package into your R session after successful installation.

```r
library(SomaDataIO)
```

--------------------------------

### Perform linear transformations on matrices and soma_adat objects

Source: https://somalogic.github.io/SomaDataIO/reference/transform.html

Examples demonstrating matrix multiplication for scaling and the application of the transform method to a soma_adat object.

```R
# simplified example of underlying operations
M <- matrix(1:12, ncol = 4)
M
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    4    7   10
#> [2,]    2    5    8   11
#> [3,]    3    6    9   12

v <- 1:4
M %*% diag(v)    # transform columns
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    8   21   40
#> [2,]    2   10   24   44
#> [3,]    3   12   27   48

v <- 1:3
diag(v) %*% M    # transform rows
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    4    7   10
#> [2,]    4   10   16   22
#> [3,]    9   18   27   36

# dummy ADAT example:
v    <- c(2, 0.5)     # double seq1; half seq2
adat <- data.frame(sample      = paste0("sample_", 1:3),
                   seq.1234.56 = c(1, 2, 3),
                   seq.9999.88 = c(4, 5, 6) * 10)
adat
#>     sample seq.1234.56 seq.9999.88
#> 1 sample_1           1          40
#> 2 sample_2           2          50
#> 3 sample_3           3          60

# `soma_adat` to invoke S3 method dispatch
class(adat) <- c("soma_adat", "data.frame")
trans <- transform(adat, v)
data.frame(trans)
#>     sample seq.1234.56 seq.9999.88
#> 1 sample_1           2          20
#> 2 sample_2           4          25
#> 3 sample_3           6          30
```

--------------------------------

### Examples of addClass

Source: https://somalogic.github.io/SomaDataIO/reference/addClass.html

Demonstrates adding single or multiple classes to an object, including handling of duplicates and re-ordering.

```R
class(iris)
#> [1] "data.frame"

addClass(iris, "new") |> class()
#> [1] "new"        "data.frame"

addClass(iris, c("A", "B")) |> class()    # 2 classes
#> [1] "A"          "B"          "data.frame"

addClass(iris, c("A", "data.frame")) |> class()    # no duplicates
#> [1] "A"          "data.frame"

addClass(iris, c("data.frame", "A")) |> class()    # re-orders if exists
#> [1] "data.frame" "A"
```

--------------------------------

### Example Usage of getAnalytes and getMeta

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalytes.html

Demonstrates extracting analyte lists, counting features, filtering controls, and retrieving clinical metadata.

```R
# RFU feature variables
apts <- getAnalytes(example_data)
head(apts)
#> [1] "seq.10000.28" "seq.10001.7"  "seq.10003.15" "seq.10006.25"
#> [5] "seq.10008.43" "seq.10011.65"
getAnalytes(example_data, n = TRUE)
#> [1] 5284

# vector string
bb <- getAnalytes(names(example_data))
all.equal(apts, bb)
#> [1] TRUE

# create some control sequences
# ~~~~~~~~~ Spuriomer ~~~ HybControl ~~~
apts2 <- c("seq.2053.2", "seq.2171.12", head(apts))
apts2
#> [1] "seq.2053.2"   "seq.2171.12"  "seq.10000.28" "seq.10001.7" 
#> [5] "seq.10003.15" "seq.10006.25" "seq.10008.43" "seq.10011.65"
no_crtl <- getAnalytes(apts2, rm.controls = TRUE)
no_crtl
#> [1] "seq.10000.28" "seq.10001.7"  "seq.10003.15" "seq.10006.25"
#> [5] "seq.10008.43" "seq.10011.65"
setdiff(apts2, no_crtl)
#> [1] "seq.2053.2"  "seq.2171.12"

# clinical variables
mvec <- getMeta(example_data)
head(mvec, 10)
#>  [1] "PlateId"         "PlateRunDate"    "ScannerID"      
#>  [4] "PlatePosition"   "SlideId"         "Subarray"       
#>  [7] "SampleId"        "SampleType"      "PercentDilution"
#> [10] "SampleMatrix"   
getMeta(example_data, n = TRUE)
#> [1] 34

# test 'data.frame' and 'character' S3 methods are identical
identical(getMeta(example_data), getMeta(names(example_data))) # TRUE
#> [1] TRUE
```

--------------------------------

### Get Index of Available Commands

Source: https://somalogic.github.io/SomaDataIO/index.html

View an index of all available commands within the loaded SomaDataIO package.

```r
library(help = SomaDataIO)
```

--------------------------------

### Clean Names Examples

Source: https://somalogic.github.io/SomaDataIO/reference/cleanNames.html

Demonstrates the cleaning of strings containing whitespace, special characters, and specific normalization patterns.

```R
cleanNames("    sdkfj...sdlkfj.sdfii4994### ")
#> [1] "sdkfj.sdlkfj.sdfii4994"

cleanNames("Hyb..Scale")
#> [1] "HybControlNormScale"
```

--------------------------------

### Plotting Outlier Map Example

Source: https://somalogic.github.io/SomaDataIO/reference/plot.Map.html

Demonstrates the pipeline from filtering data to calculating and plotting an outlier map.

```R
example_data |>
  dplyr::filter(SampleType == "Sample") |>
  head(10) |>
  calcOutlierMap() |>
  plot(flags = 0.05)
```

--------------------------------

### Create Example Clinical Data - R

Source: https://somalogic.github.io/SomaDataIO/articles/cli-merge-tool.html

Generates dummy clinical data with a common key ('SampleId') and new variables, then saves it as a CSV file. This data will be merged with the ADAT file.

```r
df <- data.frame(SampleId = as.character(seq(1, 9, by = 2)),  # common key
                 group    = c("a", "b", "a", "b", "a"),
                 newvar   = withr::with_seed(1, rnorm(5)))
df
#>   SampleId group     newvar
#> 1        1     a -0.6264538
#> 2        3     b  0.1836433
#> 3        5     a -0.8356286
#> 4        7     b  1.5952808
#> 5        9     a  0.3295078

# write clinical data to file
withr::with_dir(analysis_dir,
  write.csv(df, file = "clin-data.csv", row.names = FALSE)
)
```

--------------------------------

### Examples of diffAdats

Source: https://somalogic.github.io/SomaDataIO/reference/diffAdats.html

Demonstrates comparing identical objects, objects with missing columns, shuffled metadata, and modified RFU values.

```R
# subset `example_data` for speed
# all SeqIds from 2000 -> 2999
seqs <- grep("^seq\\.2[0-9]{3}", names(example_data), value = TRUE)
ex_data_small <- head(example_data[, c(getMeta(example_data), seqs)], 10L)
dim(ex_data_small)
#> [1]  10 264

# no diff to itself
diffAdats(ex_data_small, ex_data_small)
#> ══ Checking ADAT attributes & characteristics ═════════════════════════
#> → Attribute names are identical       ✓
#> → Attributes are identical            ✓
#> → ADAT dimensions are identical       ✓
#> → ADAT row names are identical        ✓
#> → ADATs contain identical Features    ✓
#> → ADATs contain same Meta Fields      ✓
#> ── Checking the data matrix ───────────────────────────────────────────
#> → All Clinical data is identical      ✓
#> → All Feature data is identical       ✓
#> ═══════════════════════════════════════════════════════════════════════

# remove random column
rm <- withr::with_seed(123, sample(1:ncol(ex_data_small), 1))
diffAdats(ex_data_small, ex_data_small[, -rm])
#> ══ Checking ADAT attributes & characteristics ═════════════════════════
#> → Attribute names are identical       ✓
#> → Attributes are identical            ✖
#> → ADAT dimensions are identical       ✖
#> →   ADATs have same # of rows         ✓
#> →   ADATs have same # of columns      ✖
#> →   ADATs have same # of features     ✖
#> →   ADATs have same # of meta data    ✓
#> → ADAT row names are identical        ✓
#> → ADATs contain identical Features    ✖
#> → ADATs contain same Meta Fields      ✓
#> "ex_data_small"
#> "ex_data_small[, -rm]"
#>          seq.2790.54
#> 
#> ✔ Continuing on the "*INTERSECT*" of ADAT columns
#> ── Checking the data matrix ───────────────────────────────────────────
#> → All Clinical data is identical      ✓
#> → All Feature data is identical       ✓
#> ═══════════════════════════════════════════════════════════════════════

# randomly shuffle Subarray
diffAdats(ex_data_small, dplyr::mutate(ex_data_small, Subarray = sample(Subarray)))
#> ══ Checking ADAT attributes & characteristics ═════════════════════════
#> → Attribute names are identical       ✓
#> → Attributes are identical            ✓
#> → ADAT dimensions are identical       ✓
#> → ADAT row names are identical        ✓
#> → ADATs contain identical Features    ✓
#> → ADATs contain same Meta Fields      ✓
#> ── Checking the data matrix ───────────────────────────────────────────
#> → All Clinical data is identical      ✖
#>     No. fields that differ            1
#> ── Clinical data diffs ────────────────────────────────────────────────
#> "Subarray"
#> NULL
#> → All Feature data is identical       ✓
#> ═══════════════════════════════════════════════════════════════════════

# modify 2 RFUs randomly
new <- ex_data_small
new[5L, c(rm, rm + 1L)] <- 999
diffAdats(ex_data_small, new)
#> ══ Checking ADAT attributes & characteristics ═════════════════════════
#> → Attribute names are identical       ✓
#> → Attributes are identical            ✓
#> → ADAT dimensions are identical       ✓
#> → ADAT row names are identical        ✓
#> → ADATs contain identical Features    ✓
#> → ADATs contain same Meta Fields      ✓
#> ── Checking the data matrix ───────────────────────────────────────────
#> → All Clinical data is identical      ✓
#> → All Feature data is identical       ✖
#>     No. fields that differ            2
#> ── Feature data diffs ─────────────────────────────────────────────────
#> "seq.2790.54" and "seq.2794.60"
#> NULL
#> ═══════════════════════════════════════════════════════════════════════
```

--------------------------------

### Manipulating Row Names and Columns

Source: https://somalogic.github.io/SomaDataIO/reference/rownames.html

Examples demonstrating how to move row names to columns, convert columns to row names, and verify the reversibility of these operations.

```R
df <- data.frame(a = 1:5, b = rnorm(5), row.names = LETTERS[1:5])
df
#>   a           b
#> A 1  0.07003485
#> B 2 -0.63912332
#> C 3 -0.04996490
#> D 4 -0.25148344
#> E 5  0.44479712
rn2col(df)              # default name is `.rn`
#>   .rn a           b
#> 1   A 1  0.07003485
#> 2   B 2 -0.63912332
#> 3   C 3 -0.04996490
#> 4   D 4 -0.25148344
#> 5   E 5  0.44479712
rn2col(df, "AptName")   # pass `name =`
#>   AptName a           b
#> 1       A 1  0.07003485
#> 2       B 2 -0.63912332
#> 3       C 3 -0.04996490
#> 4       D 4 -0.25148344
#> 5       E 5  0.44479712

# moving columns
df$mtcars <- sample(names(mtcars), 5)
col2rn(df, "mtcars")   # with a warning
#> Warning: `df` already has row names. They will be over-written.
#>      a           b
#> vs   1  0.07003485
#> mpg  2 -0.63912332
#> gear 3 -0.04996490
#> qsec 4 -0.25148344
#> hp   5  0.44479712

# Move back and forth easily
# Leaves original object un-modified
identical(df, col2rn(rn2col(df)))
#> [1] TRUE
```

--------------------------------

### Merge Clinical Data Examples

Source: https://somalogic.github.io/SomaDataIO/reference/merge_clin.html

Demonstrates retrieving clinical data, reading it into a data frame, and preparing a subset of an ADAT object for merging.

```R
# retrieve clinical data
clin_file <- system.file("cli/merge", "meta.csv",
                         package = "SomaDataIO",
                         mustWork = TRUE)
clin_file
#> [1] "/Users/runner/work/_temp/Library/SomaDataIO/cli/merge/meta.csv"

# view clinical data to be merged:
# 1) `group`
# 2) `newvar`
clin_df <- read.csv(clin_file, colClasses = c(SampleId = "character"))
clin_df
#>   SampleId group    newvar
#> 1        1     a -0.757960
#> 2        3     b -0.363479
#> 3        5     a  1.010235
#> 4        7     b  1.342776
#> 5        9     a -3.010827

# create mini-adat
apts <- withr::with_seed(123, sample(getAnalytes(example_data), 2L))
adat <- head(example_data, 9L) |>   # 9 x 2
  dplyr::select(SampleId, all_of(apts))
```

--------------------------------

### Load Required Libraries for SomaDataIO

Source: https://somalogic.github.io/SomaDataIO/articles/pre-processing.html

Load the necessary R libraries for data manipulation and analysis with SomaDataIO. Ensure ggplot2, dplyr, and purrr are installed.

```R
library(SomaDataIO)
library(ggplot2)
library(dplyr)
library(purrr)
```

--------------------------------

### Math Generics for soma_adat

Source: https://somalogic.github.io/SomaDataIO/reference/groupGenerics.html

Applies mathematical transformations to the RFU data of soma_adat objects. Requires the object to be a soma_adat class. Example includes log, log10, floor, sqrt, round, and antilog transformations.

```R
# subset `example_data` for speed
# all SeqIds from 2000 -> 2999
seqs <- grep("^seq\.2[0-9]{3}", names(example_data), value = TRUE)
ex_data_small <- head(example_data[, c(getMeta(example_data), seqs)], 10L)
dim(ex_data_small)
#>  [1]  10 264

ex_data_small$seq.2991.9
#>  [1] 4921.8 4392.2 4791.5 6017.2 5711.3 5092.4 4417.9 5394.3 6111.4
#> [10] 6045.2

# Math Generics:
# -------------
# log-transformation
a <- log(ex_data_small)
a$seq.2991.9
#>  [1] 8.501430 8.387586 8.474599 8.702377 8.650202 8.535505 8.393420
#>  [8] 8.593098 8.717911 8.707020

b <- log10(ex_data_small)
b$seq.2991.9
#>  [1] 3.692124 3.642682 3.680471 3.779394 3.756735 3.706923 3.645216
#>  [8] 3.731935 3.786141 3.781411
isTRUE(all.equal(b, log(ex_data_small, base = 10)))
#> [1] TRUE

# floor
c <- floor(ex_data_small)
c$seq.2991.9
#>  [1] 4921 4392 4791 6017 5711 5092 4417 5394 6111 6045

# square-root
d <- sqrt(ex_data_small)
d$seq.2991.9
#>  [1] 70.15554 66.27368 69.22066 77.57061 75.57314 71.36105 66.46729
#>  [8] 73.44590 78.17544 77.75088

# rounding
e <- round(ex_data_small)
e$seq.2991.9
#>  [1] 4922 4392 4792 6017 5711 5092 4418 5394 6111 6045

# inverse log
antilog(1:4)
#> [1]    10   100  1000 10000

alog <- antilog(b)
all.equal(ex_data_small, alog)    # return `b` -> linear space
#> [1] TRUE
```

--------------------------------

### Filter Rows Based on 'Target' Pattern

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalyteInfo.html

Use `dplyr::filter()` with `grepl()` to select rows where the 'Target' column matches a regular expression pattern. This example filters for targets starting with 'MMP'.

```R
anno_tbl %>%
  dplyr::filter(grepl("^MMP", Target))
```

--------------------------------

### ADAT Loading and Collapsing Workflow

Source: https://somalogic.github.io/SomaDataIO/reference/loadAdatsAsList.html

Demonstrates locating ADAT files, loading them into a list, and collapsing them into a single soma_adat object.

```R
# only 1 file in directory
dir(system.file("extdata", package = "SomaDataIO"))
#> [1] "example_data10.adat"

files <- system.file("extdata", package = "SomaDataIO") |>
  dir(pattern = "[.]adat$", full.names = TRUE) |> rev()

adats <- loadAdatsAsList(files)
class(adats)
#> [1] "list"

# collapse into 1 ADAT
collapsed <- collapseAdats(adats)
class(collapsed)
#> [1] "soma_adat"  "data.frame"
```

--------------------------------

### Set up Train/Test Data Split

Source: https://somalogic.github.io/SomaDataIO/articles/stat-linear-regression.html

Creates training and testing datasets by randomly sampling from the cleaned data. Ensures no overlap between the two sets using `withr::with_seed` for reproducibility.

```r
# idx = hold-out 
idx   <- withr::with_seed(3, sample(1:nrow(cleanData), size = nrow(cleanData) - 50))
train <- cleanData[idx, ]
test  <- cleanData[-idx, ]

# assert no overlap
isTRUE(
  all.equal(intersect(rownames(train), rownames(test)), character(0))
)
#> [1] TRUE

```

--------------------------------

### Basic Data Inspection and Transformations with soma_adat

Source: https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html

Demonstrates how to inspect the head of a soma_adat column and apply common mathematical transformations such as log10, square root, and rounding. Also shows how to check for low signaling values and verify data integrity using all.equal.

```R
head(my_adat$seq.2429.27)
#> [1]  8642.3 12472.1 14627.7 13579.8  8938.8  6738.8
```

```R
logData <- log10(my_adat)    # a typical log10() transform
head(logData$seq.2429.27)
#> [1] 3.936629 4.095940 4.165176 4.132893 3.951279 3.828583
```

```R
roundData <- round(my_adat)
head(roundData$seq.2429.27)
#> [1]  8642 12472 14628 13580  8939  6739
```

```R
sqData <- sqrt(my_adat)
head(sqData$seq.2429.27)
#> [1]  92.96397 111.67856 120.94503 116.53240  94.54523  82.09019
```

```R
antilog(1:4)
#> [1]    10   100  1000 10000
```

```R
sum(my_adat < 100)  # low signalling values
#> [1] 693
```

```R
all.equal(my_adat, sqrt(my_adat^2))
#> [1] TRUE
```

```R
all.equal(my_adat, antilog(log10(my_adat)))
#> [1] TRUE
```

--------------------------------

### Get Flagged Sample IDs from Outlier Map

Source: https://somalogic.github.io/SomaDataIO/reference/getOutlierIds.html

Use this function to get the indices of samples flagged as outliers. Specify the `flags` threshold and optionally include additional variables from the original data.

```R
getOutlierIds(x, flags = 0.05, data = NULL, include = NULL)
```

```R
# flagged outliers
# create a single sample outlier (12)
out_adat <- example_data
apts     <- getAnalytes(out_adat)
out_adat[12, apts] <- out_adat[12, apts] * 10

om <- calcOutlierMap(out_adat)
getOutlierIds(om, out_adat, flags = 0.05, include = c("Sex", "Subarray"))
#>   idx  Sex Subarray
#> 1  12    M        5
#> 2  13 <NA>        4
#> 3  43 <NA>        8
#> 4  87 <NA>        6
#> 5 143 <NA>        4
#> 6 151 <NA>        4
#> 7 173 <NA>        4
```

--------------------------------

### Find overlapping sequence IDs

Source: https://somalogic.github.io/SomaDataIO/reference/SeqId.html

Identifies overlapping sequence IDs between two subsets of features extracted from example data.

```R
feats <- getAnalytes(example_data)

match_df <- getSeqIdMatches(feats[1:100], feats[90:500])  # 11 overlapping
match_df
```

--------------------------------

### Bind ADATs via Union

Source: https://somalogic.github.io/SomaDataIO/reference/loadAdatsAsList.html

Example of using dplyr::bind_rows to perform a union-based vertical bind on a list of ADAT objects.

```R
adats <- loadAdatsAsList(files)
union_adat <- dplyr::bind_rows(adats, .id = "SourceFile")
```

--------------------------------

### Split Data Using Base R sample() and Indexing

Source: https://somalogic.github.io/SomaDataIO/articles/tips-train-test-setup.html

This method uses base R's `sample()` function to generate random indices for splitting the data into training and testing sets. Ensure reproducibility by setting a seed.

```R
n     <- nrow(raw)
idx   <- withr::with_seed(1, sample(1:n, floor(n / 2))) # sample random 50% (n = 5) 
train <- raw[idx, ]
test  <- raw[-idx, ]
train
```

```R
test
```

--------------------------------

### Create Temporary Analysis Directory - R

Source: https://somalogic.github.io/SomaDataIO/articles/cli-merge-tool.html

Creates a temporary directory for analysis files. This is a preparatory step before copying the merge script and creating data files.

```r
analysis_dir <- tempfile(pattern = "somascan-")
# create directory
dir.create(analysis_dir)

# sanity check
dir.exists(analysis_dir)
#> [1] TRUE

# copy merge tool into analysis directory
file.copy(merge_script, to = analysis_dir)
#> [1] TRUE
```

--------------------------------

### Get SeqId from string

Source: https://somalogic.github.io/SomaDataIO/reference/SeqId.html

Extracts SeqIds from a character vector. Use `trim.version = TRUE` to remove the version number for legacy data.

```r
getSeqId(x, trim.version = FALSE)
```

--------------------------------

### Listing Available Group Generics for Math, Comparison, Arithmetic, and Summary Operations

Source: https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html

Shows how to retrieve lists of available group generics for different mathematical and logical operations supported by the soma_adat object. This is useful for understanding the range of transformations and comparisons that can be applied.

```R
getGroupMembers("Math")
#>  [1] "abs"      "sign"     "sqrt"     "ceiling"  "floor"    "trunc"   
#>  [7] "cummax"   "cummin"   "cumprod"  "cumsum"   "exp"      "expm1"   
#> [13] "log"      "log10"    "log2"     "log1p"    "cos"      "cosh"    
#> [19] "sin"      "sinh"     "tan"      "tanh"     "acos"     "acosh"   
#> [25] "asin"     "asinh"    "atan"     "atanh"    "cospi"    "sinpi"   
#> [31] "tanpi"    "gamma"    "lgamma"   "digamma"  "trigamma"
```

```R
getGroupMembers("Compare")
#> [1] "==" ">"  "<"  "!=" "<=" ">="
```

```R
getGroupMembers("Arith")
#> [1] "+"   "-"   "*"   "^"   "%%"  "%/%") "/"
```

```R
getGroupMembers("Summary")
#> [1] "max"   "min"   "range" "prod"  "sum"   "any"   "all"
```

--------------------------------

### Get ADAT Version

Source: https://somalogic.github.io/SomaDataIO/reference/adat-helpers.html

Retrieves the ADAT version number from a parsed ADAT header. The version can be updated by modifying the Header.Meta attribute.

```R
getAdatVersion(example_data)
#> [1] "1.2"

attr(example_data, "Header.Meta")$HEADER$Version <- "99.9"
getAdatVersion(example_data)
#> [1] "99.9"
```

--------------------------------

### Check if AptName format

Source: https://somalogic.github.io/SomaDataIO/reference/SeqId.html

Tests if a character vector matches the AptName format (e.g., 'seq.XXXX').

```r
is.AptName(x)
```

--------------------------------

### Load an ADAT file into R

Source: https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html

Use read_adat to import an ADAT file and is.soma_adat to verify the object class.

```R
# path to *.adat file
# replace with your file path
adat_path <- system.file("extdata", "example_data10.adat",
                         package = "SomaDataIO", mustWork = TRUE)
adat_path
#> [1] "/Users/runner/work/_temp/Library/SomaDataIO/extdata/example_data10.adat"

my_adat <- read_adat(adat_path)

# class test
is.soma_adat(my_adat)
#> [1] TRUE
```

--------------------------------

### Get Target Names

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalyteInfo.html

Retrieves target names from an annotation table. This function is used to map internal identifiers to human-readable target names.

```R
tg <- getTargetNames(anno_tbl)
```

--------------------------------

### Get Analyte Annotation Information

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalyteInfo.html

Retrieves analyte annotation data from a soma_adat object. The 'AptName' column serves as the key index for this data.

```R
getAnalyteInfo(adat)
```

```R
getTargetNames(tbl)
```

```R
getFeatureData(adat)
```

--------------------------------

### getTargetNames

Source: https://somalogic.github.io/SomaDataIO/reference/getAnalyteInfo.html

Creates a lookup table as a named list mapping AptNames to Target names.

```APIDOC
## getTargetNames

### Description
Creates a dictionary of key-value pairs mapping AptNames (e.g., seq.XXXX.XX) to their corresponding TargetNames.

### Parameters
#### Request Body
- **tbl** (tibble) - Required - A tibble object containing analyte target annotation information, typically from getAnalyteInfo().

### Response
#### Success Response (200)
- **list** (object) - A named list object of AptNames and Target names.
```

--------------------------------

### Locate Merge Script - R

Source: https://somalogic.github.io/SomaDataIO/articles/cli-merge-tool.html

Finds the path to the merge_clin.R script within the installed SomaDataIO package. This is the first step to using the CLI tool.

```r
dir(system.file("cli", "merge", package = "SomaDataIO", mustWork = TRUE))
#> [1] "merge_clin.R"     "meta.csv"         "meta2.csv"

merge_script <- system.file("cli/merge", "merge_clin.R", package = "SomaDataIO")
merge_script
#> [1] "/Users/runner/work/_temp/Library/SomaDataIO/cli/merge/merge_clin.R"
```

--------------------------------

### Get Clinical Metadata

Source: https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html

Retrieve the clinical metadata associated with each sample in the SomaDataIO object. The `n = TRUE` argument can be used to count the number of metadata fields.

```R
getMeta(my_adat)             # clinical meta data for each sample
```

```R
getMeta(my_adat, n = TRUE)   # also an `n` argument
```

--------------------------------

### Get matching SeqIds data frame

Source: https://somalogic.github.io/SomaDataIO/reference/SeqId.html

Returns a data frame of matching SeqIds between two vectors. Use `show = TRUE` to display the data frame.

```r
getSeqIdMatches(x, y, show = FALSE)
```

--------------------------------

### Extract and Convert SeqIds

Source: https://somalogic.github.io/SomaDataIO/reference/SeqId.html

Demonstrates extracting SeqIds from strings and converting them to AptName format using a tibble.

```R
x <- c("ABDC.3948.48.2", "3948.88",
       "3948.48.2", "3948-48_2", "3948.48.2",
       "3948-48_2", "3948-88",
       "My.Favorite.Apt.3948.88.9")

tibble::tibble(orig       = x,
               SeqId      = getSeqId(x),
               SeqId_trim = getSeqId(x, TRUE),
               AptName    = seqid2apt(SeqId))
```

--------------------------------

### Load Required Libraries

Source: https://somalogic.github.io/SomaDataIO/articles/stat-binary-classification.html

Load the necessary packages for data manipulation and SomaScan data handling.

```R
library(SomaDataIO)
library(dplyr)
library(tidyr)
library(purrr)
```
Tokens:
Raw