README.Rmd

---
output: github_document
---


<!-- README.md is generated from README.Rmd. Please edit that file -->


```{r setup, include = FALSE}
#Sys.setlocale("LC_COLLATE", "C")
Sys.setlocale("LC_COLLATE", "en_US.UTF-8") # ensure common sorting envir
library(SomaDataIO)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
dcf <- read.dcf(file = file.path(".", "DESCRIPTION"))
if ( nrow(dcf) < 1L)
  stop("DESCRIPTION file of package is corrupt.", call. = FALSE)
desc <- as.list(dcf[1L, ])
ver <- paste0("https://img.shields.io/badge/Version-", desc$Version,
              "-success.svg?style=flat&logo=github")
```


# SomaDataIO <a href="https://somalogic.github.io/SomaDataIO/"><img src="man/figures/logo.png" align="right" height="138" alt="SomaDataIO website" /></a>


<!-- badges: start -->
![GitHub version](`r ver`)
[![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)
[![R-CMD-check](https://github.com/SomaLogic/SomaDataIO/workflows/R-CMD-check/badge.svg)](https://github.com/SomaLogic/SomaDataIO/actions)
[![Codecov test coverage](https://codecov.io/gh/SomaLogic/SomaDataIO/branch/main/graph/badge.svg)](https://app.codecov.io/gh/SomaLogic/SomaDataIO?branch=main)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
<!-- badges: end -->


The `SomaDataIO` R package loads and exports 'SomaScan' data via the
SomaLogic Operating Co., Inc. structured text file called an ADAT (`*.adat`).
The package also exports auxiliary functions for manipulating, wrangling,
and extracting relevant information from an ADAT object once in memory.
Basic familiarity with the R environment is assumed, as is the ability to install
contributed packages from the Comprehensive R Archive Network (CRAN).

If you run into any issues/problems with `SomaDataIO` full documentation
of the most recent
[release](https://github.com/SomaLogic/SomaDataIO/releases)
can be found at our
[website of articles and workflows](https://somalogic.github.io/SomaDataIO/).
If the issue persists we encourage you to consult the
[issues](https://github.com/SomaLogic/SomaDataIO/issues/)
page and, if appropriate, submit an issue and/or feature request.


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


## Usage

The `SomaDataIO` package is licensed under the
[MIT](https://github.com/SomaLogic/SomaDataIO/blob/main/LICENSE.md)
license and is intended solely for research use only (“RUO”) purposes.
The code contained herein may _not_ be used for diagnostic, clinical,
therapeutic, or other commercial purposes.


## Installation

The easiest way to install `SomaDataIO` is to install directly from CRAN:

```{r install-cran, eval = FALSE}
install.packages("SomaDataIO")
```

Alternatively from GitHub:

```{r install-gh, eval = FALSE}
remotes::install_github("SomaLogic/SomaDataIO")
```

which installs the most current "development" version from the repository
`HEAD`. To install the _most recent_ release, use:

```{r install-release, eval = FALSE}
remotes::install_github("SomaLogic/SomaDataIO@*release")
```

To install a *specific* tagged release, use:

```{r install-version, eval = FALSE}
remotes::install_github("SomaLogic/SomaDataIO@v5.3.0")
```


#### Package Dependencies

The `SomaDataIO` package was intentionally developed to contain a
limited number of dependencies from CRAN. This makes
the package more stable to external software design changes but
also limits its contained feature set. With this in mind, `SomaDataIO`
aims to strike a balance providing long(er)-term stability and a
limited set of features.
Below are the package dependencies
(see also the [DESCRIPTION](https://github.com/SomaLogic/SomaDataIO/blob/main/DESCRIPTION)
file):

* [R (>= 4.1.0)](https://cran.r-project.org/)
* [cli](https://cran.r-project.org/package=cli)
* [dplyr](https://cran.r-project.org/package=dplyr)
* [lifecycle](https://cran.r-project.org/package=lifecycle)
* [magrittr](https://cran.r-project.org/package=magrittr)
* [readxl](https://cran.r-project.org/package=readxl)
* [tibble](https://cran.r-project.org/package=tibble)
* [tidyr](https://cran.r-project.org/package=tidyr)


#### Biobase

The `Biobase` package is _suggested_, being required by only
two functions, `pivotExpressionSet()` and `adat2eSet()`.
[Biobase](https://www.bioconductor.org/packages/release/bioc/html/Biobase.html)
must be installed separately from
[Bioconductor](https://www.bioconductor.org)
by entering the following from the `R` Console:

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

Information about Bioconductor can be found here:
[https://bioconductor.org/install/](https://bioconductor.org/install/)


#### Loading

Upon _successful_ installation, load `SomaDataIO` as normal:

```{r load-somadataio, eval = FALSE}
library(SomaDataIO)
```

For an index of available commands:
```{r help, eval = FALSE}
library(help = SomaDataIO)
```


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


## Objects and Data

The `SomaDataIO` package comes with four (4) objects available
to users to run canned examples (or analyses). They can be accessed once
`SomaDataIO` has been attached via `library()`. They are:

* `example_data`: the original 'SomaScan' file (`example_data.adat`) can
  be found [here](https://github.com/SomaLogic/SomaLogic-Data) or downloaded
  directly via:
  ```bash
  wget https://raw.githubusercontent.com/SomaLogic/SomaLogic-Data/main/example_data.adat
  ```
  - within `SomaDataIO` it has been replaced by an abbreviated,
    light-weight version containing only the first 10 samples:
    ```r
    dir(system.file("extdata", package = "SomaDataIO"), full.names = TRUE)
    ```
* `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
* See also `?SomaScanObjects`


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


## Main (I/O) Features 

* Loading data (Import)
    + parse and import a `*.adat` text file into an `R` session
      as a `soma_adat` object.

* Wrangling data (manipulation)
    + subset, reorder, and list various fields of a `soma_adat` object.
    + `?SeqId` analyte (feature) matching.
    + [dplyr](https://dplyr.tidyverse.org) and [tidyr](https://tidyr.tidyverse.org) verb
      S3 methods for the `soma_adat` class.
    + `?rownames` helpers that do not break `soma_adat` attributes.
    + please see the article [Loading and Wrangling 'SomaScan'](https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html)

* Exporting data (Output)
    + write out a `soma_adat` object as a `*.adat` text file.


## Loading an ADAT

Loading an ADAT text file is simple using `read_adat()`:

```{r read-adat}
# Sample file name
f <- system.file("extdata", "example_data10.adat",
                 package = "SomaDataIO", mustWork = TRUE)
my_adat <- read_adat(f)

# test object class
is.soma_adat(my_adat)

# S3 print method (forwards -> tibble)
my_adat
```

Please see the article [Loading and Wrangling SomaScan](https://somalogic.github.io/SomaDataIO/articles/tips-loading-and-wrangling.html)
for more details and options.


## Wrangling

The `soma_adat` class comes with numerous class-specific
S3 methods to the most popular
[dplyr](https://dplyr.tidyverse.org) and
[tidyr](https://tidyr.tidyverse.org) generics.

```{r methods}
# see full complement of `soma_adat` methods
methods(class = "soma_adat")
```

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.


## ADAT structure

The `soma_adat` object also contains specific structure that are useful
to users. Please also see `?colmeta` or `?annotations` for further
details about these fields.


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


## Typical 'SomaScan' Analysis

This section now lives in individual package articles.
For further detail please see:

- Two-group comparison (e.g. differential expression) via *t*-test
  + see `stats::t.test()`
  + see workflow: [Two-Group Comparison](https://somalogic.github.io/SomaDataIO/articles/stat-two-group-comparison.html)

- Multi-group comparison (e.g. differential expression) via ANOVA
  + see `stats::aov()`
  + see workflow: [ANOVA Three-Group Analysis](https://somalogic.github.io/SomaDataIO/articles/stat-three-group-analysis-anova.html)

- Binary classification
  + see `stats::glm()`
  + see workflow: [Binary Classification](https://somalogic.github.io/SomaDataIO/articles/stat-binary-classification.html)

- Linear regression
  + see `stats::lm()`
  + see workflow: [Linear Regression](https://somalogic.github.io/SomaDataIO/articles/stat-linear-regression.html)

Note that, in an effort to reduce package size and dependencies, these articles
and workflows are only accessible via the `SomaDataIO` `pkgdown` website, and
are not included with the installed package.

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


## MIT LICENSE

* See:
  - [LICENSE](https://github.com/SomaLogic/SomaDataIO/blob/main/LICENSE.md)
* The MIT license:
  - [https://choosealicense.com/licenses/mit/](https://choosealicense.com/licenses/mit/)
  - [https://www.tldrlegal.com/license/mit-license/](https://www.tldrlegal.com/license/mit-license)
* Further:
  - "SomaDataIO" and "SomaLogic" are trademarks owned by
    SomaLogic Operating Co., Inc. No license is hereby granted to
    these trademarks other than for purposes of identifying the origin or
    source of this Software.