README.Rmd

---
output: github_document
---


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


```{r setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  fig.align = "left"
)
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")
```

```{r load-pkgs, echo = FALSE, message = FALSE}
library(SomaPlotr)
library(ggplot2)
library(patchwork)
library(scales)

# Simulate numeric vectors
withr::with_seed(123, {
   x <- rnorm(200, mean = 3)
   y <- x + rnorm(length(x), sd = 0.2)  # Add random Gaussian noise, centered at zero
})

# Simulate fold change & p-value dataset
withr::with_seed(101, {
  fc1 <- sort(runif(500, -2.5, 0))   # Z-scores as fold changes
  fc2 <- sort(runif(500, 0, 2.5))    # Z-scores as fold changes
  p1  <- pnorm(fc1)
  p2  <- pnorm(fc2, lower.tail = FALSE)
  p   <- jitter(c(p1, p2), amount = 0.1)
  p[p < 0] <- runif(sum(p < 0), 1e-05, 1e-02)   # Use floor p < 0 after jittering
  fc_df <- data.frame(fc = c(fc1, fc2), p = p)
})

# Simulate a clinical data frame
timepoint <- c("Treatment", "Relapse", "Remission")
withr::with_seed(101, {
  clin_df <- data.frame(
    TimePoint   = sample(timepoint, 80, replace = TRUE),
    seq.1234.56 = stats::rnorm(80, mean = 12, sd = 5)
  )
})

# Use example datasets above to create plots
cdf <- plotCDF(x)
ccc <- plotConcord(x = x, y = y, main = "Concordance of 2 Continuous Variables")
volc <- plotVolcano(fc_df, FC = fc, p.value = p, cutoff = 0.1)
bx   <- boxplotGrouped(clin_df, y = "seq.1234.56", group.var = "TimePoint", 
                       beeswarm = TRUE, main = "Box Plot of Sample Timepoint")
```

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


<!-- badges: start -->
![GitHub version](`r ver`)
[![CRAN status](http://www.r-pkg.org/badges/version/SomaPlotr)](https://cran.r-project.org/package=SomaPlotr)
[![](https://cranlogs.r-pkg.org/badges/grand-total/SomaPlotr)](https://cran.r-project.org/package=SomaPlotr)
[![R-CMD-check](https://github.com/SomaLogic/SomaPlotr/workflows/R-CMD-check/badge.svg)](https://github.com/SomaLogic/SomaPlotr/actions)
[![Codecov test coverage](https://codecov.io/gh/SomaLogic/SomaPlotr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/SomaLogic/SomaPlotr?branch=main)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
<!-- badges: end -->






## Overview

The `SomaPlotr` R package contains various standardized plotting 
functions designed to visualize SomaScan data in the R statistical environment.
`SomaPlotr` is based on the "Grammar of Graphics"
([Wilkinson, 2005](https://link.springer.com/book/10.1007/0-387-28695-0)), the 
same layered framework of mapping variables to aesthetics that provides a 
structure for [ggplot2](https://cran.r-project.org/package=ggplot2). 
As such, `SomaPlotr` largely utilizes ggplot-style syntax, and can easily and 
quickly create fully labeled, colored figures of SomaScan data.

`SomaPlotr` is designed to generate figures that are well-suited for the 
exploration and visualization of SomaScan data. `SomaPlotr` is therefore
biased towards cumulative distribution function (CDF) plots, probability 
density function (PDF) plots, volcano and concordance plots, grouped boxplots, 
and more.

```{r plot-grid, echo = FALSE, fig.width = 13, fig.height = 11}
# Display plots in a grid w/ patchwork
(cdf + ccc) / (volc + bx )
```

Keep reading (in the [Examples](#examples) section below) to see how these graphics can 
be generated using functions in `SomaPlotr`. 

For a full table of the visualizations that can be created with 
`SomaPlotr`, see the [Usage](#usage) section below. For additional examples and 
details, see the package vignette (`vignette("SomaPlotr")`).


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


## Installation

`SomaPlotr` can be installed from [GitHub](https://github.com/SomaLogic/SomaPlotr)
using the [remotes](https://CRAN.R-project.org/package=remotes) package as 
follows:

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


## <a id="usage"></a>Usage

To load `SomaPlotr`, simply make a call to `library()`:

```{r library, eval = FALSE}
library(SomaPlotr)
```

`SomaPlotr` provides tools to create figures commonly used for the visualization 
of SomaScan data. While the package does not include a comprehensive list of all
possible graphics, those that it _does_ contain are popular for exploring and 
analyzing patterns in SomaScan.


## Primary Functionality

The table below provides a high-level summary of the graphics that can be 
created with `SomaPlotr`:

| Plot type     | Description | Function(s)           |
| :------------ | :-------- | :-------------------- |
| CDF           | Empirical cumulative distribution function | `plotCDF()`, `plotCDFlist()`, `plotCDFbyGroup()` |
| PDF           | Probability density function | `plotPDF()`, `plotPDFlist()`, `plotCDFbyGroup()` |
| Volcano       | Statistical significance vs. magnitude of fold change | `plotVolcano()`, `plotVolcanoHTML()` |
| Concordance   | Correlation coefficients of values in numeric vectors `x` and `y` | `plotConcord()`       |
| Histogram     | Frequency distribution of numeric data | `plotDoubleHist()`    |
| Boxplot       | Locality, spread and skewness of numeric data via quartiles | `boxplotBeeswarm()`, `boxplotGrouped()`, `boxplotSubarray()` |
| Longitudinal  | Graphical representation of numeric data over time, by subject (also called a "trace plot") |`plotLongitudinal()`  |



## <a id="examples"></a>Examples

The plotting functions in `SomaPlotr` require a SomaScan dataset as input, 
and generate a complete, labeled figure that can be further customized and 
modified, if desired.

Using `SomaPlotr`, the previously shown boxplot comparing RFU values across
groups can be generated via `boxplotGrouped()`:

```{r boxplot-grouped}
# Simulate an example dataset
timepoint <- c("Treatment", "Relapse", "Remission")
withr::with_seed(101, {
  clin_df <- data.frame(
    TimePoint   = sample(timepoint, 80, replace = TRUE),
    seq.1234.56 = stats::rnorm(80, mean = 12, sd = 5)
  )
})

# Create grouped boxplot w/ customized title
boxplotGrouped(
  clin_df,
  y = "seq.1234.56", 
  group.var = "TimePoint", 
  beeswarm = TRUE, 
  main = "Box Plot of Sample Timepoint"
)
```

Similarly, we can replicate the CDF plot in the introductory figure above
via `plotCDF()`:

```{r cdf, out.width = "60%"}
x <- withr::with_seed(101, rnorm(100, mean = 4))
cdf <- plotCDF(x)
cdf
```

A quantile/percentile line
(the <span style="color:red">red line</span> in the figure below)
can be added to an existing CDF plot via `addCDFquantiles()`: 

```{r cdf-quantiles, out.width = "60%"}
cdf + addCDFquantiles(x, col = "red")
```

For a more in-depth overview of the package and a full list of example plots, 
please see the package vignette: 
`vignette("SomaPlotr")`.


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


## Color Palettes

`SomaPlotr` provides color palettes that correspond to SomaLogic Operating 
Co., Inc. company color schemes:

```{r palette-soma, out.width = "60%", fig.height = 4}
scales::show_col(palette_soma(n = 8))
```

These palettes can be incorporated into figures in a variety of ways. The 
`soma_colors` and `soma_colors2` objects provide individual 
hex colors for the SomaLogic color scheme. These objects can be used
to transform the [ggplot2](https://ggplot2.tidyverse.org/) default 
color palette.

```{r soma-colors2, out.width = "60%"}
data.frame(x = seq_along(soma_colors2), y = seq_along(soma_colors2)) |> 
  ggplot(aes(x = x, y = y)) +
  geom_bar(stat = "identity", fill = soma_colors2) +
  scale_x_discrete(labels = names(soma_colors2)) +
  theme(axis.title.y = element_blank(),
        axis.text.y = element_blank(),
        axis.ticks.y = element_blank())
```


## Themes

The `theme_soma()` theme and `scale_color_soma()` functions provide a uniform 
plotting and color scheme. By using the `theme_soma()` theme, polished,
publication ready figures can be generated with consistent font sizes,
backgrounds, legend positions, and more.

Below, the left plot (`p1`) was created with the `mtcars` data set, using all 
`ggplot2` defaults. The right plot (`p2`) uses the same data set, but with the 
`theme_soma()` theme and `scale_color_soma()` color scale applied.

```{r theme-soma}
p1 <- ggplot(mtcars, aes(x = hp, y = mpg, color = factor(cyl))) +
  geom_point(alpha = 0.5, size = 4)

p2 <- p1 + 
  theme_soma() + 
  scale_color_soma()
```

```{r theme-comparison, echo=FALSE, fig.width=11, fig.height=5}
p1 + p2
```

More detailed examples illustrating how to apply these themes can be found in 
`vignette("themes-and-palettes")`. 
For a full list of available color scales and themes, see 
`?SomaPlotr::theme_soma`.


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


## MIT LICENSE

* See:
  - [LICENSE](https://github.com/SomaLogic/SomaPlotr/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:
  - "SomaPlotr" 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.