OmicFlow is constructed around the main superclass omics that in turn is
inherited by metagenomics and proteomics, that offer additional
fields or methods. The superclass omics contains both public and private
methods, only the public componenents are documented, whereas the private
methods can be accessed via omics$private_methods, which is not supported.
The omics class components use Matrix and data.table in the
background for fast loading and data wrangling, these data structures return
the data by reference, so does the R6 class, therefore classes in OmicFlow do
not create copies of the object unless called via $copy().
All classes needs to be first initialised via the $new() method and
require the metaData and countData field components. Alternatively, you
can also initialise with only the metaData and later add the other fields
via the active binding, but this will not create a back-up and is not advised!
For more hands-on examples see Getting Started with OmicFlow.
Input requirements
Every class in OmicFlow requires at least a metaData and countData field to
be specified. The metaData must contain a SAMPLE_ID and optionally a SAMPLEPAIR_ID,
see section "Metadata validation" below.
The countData can be both a matrix or data frame. If the original contains
rownames, then these will become the FEATURE_ID in featureData (automatically created),
otherwise a random feature identifier is assigned. If the countData is a filetype
or a data frame with both matching sample identifiers in SAMPLE_ID and other
additional columns, then these will be automatically split, columns matching the
SAMPLE_ID will be placed in the countData, any other columns will be placed
in front of the FEATURE_ID column in featureData.
Metadata validation
Every class in OmicFlow begins by validating the sample metadata. This validation checks that sample identifiers match the sample IDs present in the abundance tables.
The validation rules are defined in JSON format in the omics class. Metadata can be supplied as either:
A CSV or TSV file.
A
data.table.
In both cases, metadata must include a header row and follow a one-row-per-sample structure. For file inputs, the header must be on the first line. Columns not described below are permitted and are ignored during metadata validation.
Minimum requirement
The metadata must contain a SAMPLE_ID column.
Each row must have a unique, non-empty sample identifier.
Sample identifiers cannot contain spaces; use underscores (
_) or dashes (-) instead.
Example metadata:
SAMPLE_ID SAMPLEPAIR_ID CONTRAST_Treatment VARIABLE_Age
S1 P1 Drug 42
S2 P1 Placebo 36
S3 P2 Drug 51
Column types and naming rules
Required column
| Column | Type | Rules |
SAMPLE_ID | string | Unique, non-empty, no spaces; one identifier per sample row |
Optional standard columns
| Column | Type | Rules |
SAMPLEPAIR_ID | string | Optional; no spaces. Used for samples that are paired or originate from the same individual or subject. |
Some functions require a SAMEPLEPAIR_ID in the metaData when paired = TRUE is used.
The user can add or remove the SAMPLEPAIR_ID at anytime to the metaData via active binding.
Pattern-based columns
Additional variables can be defined with special column-name prefixes:
CONTRAST_...: Grouping or category labels for differential comparisons. For example,CONTRAST_Treatmentmay containDrugandPlacebo.VARIABLE_...: Numeric or string variables for statistical analysis. For example,VARIABLE_Agemay contain values such as42and51.
Pattern-based columns are only used in $autoFlow(). Currently, only columns
with the CONTRAST_ prefix are supported.
Active bindings
metaDataA data.table with
SAMPLE_IDcolumn.featureDataA data.table with
FEATURE_IDcolumn.countDataA sparseMatrix with rownames matching
FEATURE_IDoffeatureDataand colnames matchingSAMPLE_IDofcountData.
Methods
omics$new()
Usage
omics$new(metaData = NULL, countData = NULL, featureData = NULL)Arguments
metaDataA path to an existing file, data.table or data.frame (default:
NULL).countDataA path to an existing file, Matrix, data.table or data.frame (default:
NULL).featureDataA path to an existing file, data.table or data.frame (default:
NULL).
Examples
library("OmicFlow")
## Method 1: load from filepath
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
## Method 2: Load from data.frame or matrix
n_cols <- 5
n_rows <- 100
n_vals <- n_cols * n_rows
metadata <- data.frame("SAMPLE_ID" = paste0("Sample_", 1:n_cols))
features <- data.frame("FEATURE_ID" = paste0("protein_", 1:n_rows))
counts <- Matrix::Matrix(
1:n_vals, nrow = n_rows, ncol = n_cols,
dimnames = list(features$FEATURE_ID, metadata$SAMPLE_ID)
)
obj <- omics$new(
metaData = metadata,
featureData = features, # optional
countData = counts
)
## Method 3: you have features and counts in a single data.frame
metadata <- data.frame(SAMPLE_ID = c("S1", "S2", "S3"))
counts <- data.frame(
S1 = c(2,3,0),
S2 = c(2,"",1),
S3 = c(2,1,NA),
proteins = c("ZEB1", "ZEB2", "MAPK")
)
obj <- omics$new(
metaData = metadata,
countData = counts
)omics$copy()
This method is very similar to the existing $clone() function,
except it also creates a new save of the back-up of each class that is created when
$new() is called and can be reverted to via $reset()
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
# Perform a modification and copy
obj$scale()
cloned <- obj$copy(deep=TRUE)
cloned$scale(method = "clr")
cloned$reset() # resets to data after clone creation.omics$print()
Displays field parameters of the class via stdout.
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
# method 1 to call print function
obj
# method 2 to call print function
obj$print()omics$reset()
Upon creation of a new class object (i.e. omics, metagenomics or proteomics) a backup of the original data is created.
Since modification of the object is done by reference and duplicates are not made, it is possible to revert back to the unmodified data via $reset().
The methods from the super class omics also contains a private method to prevent any changes to the original object when using methods,
such as ordination, alpha_diversity or foldchange.
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library(ggplot2)
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
taxa <- omics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
# Performs modifications
taxa$scale(transform = log2)
# resets
taxa$reset()
# An inbuilt reset function prevents unwanted modification to the taxa object.
taxa$rankstat(feature_ranks = c("Kingdom", "Phylum", "Family", "Genus", "Species"))omics$removeNAs()
Subset metaData via the complete.cases given a single or vector of column names, then synchronize the object.
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
obj$removeNAs(column = "treatment")omics$feature_subset()
Subset features using a logical expression evaluated in featureData, then synchronize the object.
Arguments
exprA logical expression evaluated in the context of
featureData. Rows for which the expression evaluates toTRUEare retained.
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
obj$feature_subset(Genus == "Pseudomonas")omics$sample_subset()
Subset samples using a logical expression evaluated in metaData, then synchronize the object.
Arguments
exprA logical expression evaluated in the context of
metaData. Rows for which the expression evaluates toTRUEare retained.
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
obj$sample_subset(treatment == "tumor")omics$samplepair_subset()
Subset samplepairs by choosing the number of unique pairs in metaData, then synchronize the object.
Arguments
num_unique_pairsAn integer value to define the number of pairs to subset. The default is NULL, meaning the maximum number of unique pairs will be used to subset the data. Let's say you have three samples for each pair, then the
num_unique_pairswill be set to 3.
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
omics$feature_merge()
Agglomerates features by column, then synchronize the object.
Arguments
feature_rankA character (vector) of columns to aggregate from the
featureData.feature_filterA character (vector) of characters to remove features via regex substring pattern matching (default:
NULL).
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
obj$feature_merge(feature_rank = c("Kingdom", "Phylum"))
obj$feature_merge(feature_rank = "Genus", feature_filter = c("uncultured", "metagenome"))omics$scale()
Feature scaling on the countData. The $scale function is able to apply transformations element-wise on the positive values, (optional: add pseudocounts) and perform normalisation or standardisation methods.
Usage
omics$scale(
method = "tss",
transform = NULL,
base = exp(1),
pseudocount = NULL
)Arguments
methodA character to choose a standardisation/normalisation method, options:
"tss","clr","binary","hellinger","none"(default:"tss")."tss"Total-sum scaling. Each column is divided by their column sum, converting absolute abundance to relative abundances in range from 0 to 1.
"clr"Centered log-ratio-like transformation. Non-zero entries are log-transformed using
logandbase, then each feature row is centered by subtracting by their respective geometric mean. Input counts must be strictly positive for his transformation. Ifpseudocountis used, then output is equal tovegan::decostand(method = "clr"), otherwise the current"clr"approximates thevegan::decostand(method = "rclr"), the main difference is that vegan replaces all zero's by NAs and then excludes them when the arithmetic mean is taken, whereas zero's in"clr"are only not used for log-transformation but preserved when taking the arithmetic mean of each feature row."binary"Presence-absence transformation. Every stored non-zero count is replaced by one, while implicit zeros in the sparse matrix remain zero.
"hellinger"Hellinger transformation. Counts are first total-sum scaled with
"tss"to relative abundances, after which the square root of each non-zero value is taken."none"No transformation. Typically applied when
transformis used.
transformA function to apply on the positive values of
countData, skip standardisation/normalisation withmethod = "none"(default:NULL).baseInput for log to use natural logarithmic scale, log2, log10 or other (default:
exp(1)) in CLR.pseudocountA numeric value to replace zero's (default:
NULL).
Returns
The object is modified in place and returned (invisibly). If a copy is required, please use $copy() beforehand with obj2 <- obj$copy().
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
# standard relative abundance computation
obj$scale()
# CLR
obj$reset()
obj$scale(method = "clr")
# transform
obj$reset()
obj$scale(method = "none", transform = log2)omics$rankstat()
Rank statistics based on featureData.
Counts the number of (unique) features identified for each column of interest from the featureData (excluding the FEATURE_ID).
Arguments
feature_ranksA vector of characters that match the
featureData.uniqueA boolean value to display only unique entries in
feature_ranks(default:FALSE).
Returns
A ggplot object.
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
plt <- obj$rankstat(feature_ranks = c("Kingdom", "Phylum", "Family", "Genus", "Species"))
pltomics$alpha_diversity()
Alpha diversity computation, statistical testing and visualisation.
It computes the alpha diversity via diversity, performs a pairwise wilcoxon statistical test given
groups via the boxjitter_test.
Usage
omics$alpha_diversity(
col_name = lifecycle::deprecated(),
groups,
metric = "shannon",
Brewer.palID = "Set2",
group_by = lifecycle::deprecated(),
split_by = NULL,
evenness = FALSE,
paired = FALSE,
p.adjust.method = "fdr"
)Arguments
col_namegroupsA column name in
metaDatato define the contrast of interest for statistical testing and visualisation.metricAn alpha diversity metric as input to diversity, options:
"shannon","simpson","invsimpson"(default:"shannon").Brewer.palIDA character name for the palette set to be applied, see brewer.pal or colormap (default:
"Set2").group_bysplit_byA column name to split the groups into chunks for grouped statistical test in boxjitter_test (default:
NULL).evennessA boolean wether to divide diversity by number of species, see specnumber (default:
FALSE).pairedA boolean value to perform paired analysis in wilcox.test and samplepair subsetting via
$samplepair_subset()p.adjust.methodA character variable to specify the p.adjust.method to be used (default:
"fdr").
Returns
A list of components:
- data
A data.frame from diversity.
- stats
A pairwise statistics from pairwise_wilcox_test.
- plot
A ggplot object.
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
plt <- obj$alpha_diversity(groups = "treatment",
metric = "shannon")omics$composition()
Creates a long data.table of SAMPLE_IDs, the top 10-15 most abundant bacteria based on the feature_rank with
any additional columns specified via add_cols. The $composition() method works with aggregated
values by running first $feature_merge(), then sorting for the most abundant bacteria based on
the row sums. The output of $composition() can be used as input to composition_plot.
Usage
omics$composition(
feature_rank,
feature_filter = NULL,
col_name = lifecycle::deprecated(),
add_cols = NULL,
feature_top = 10,
Brewer.palID = "RdYlBu"
)Arguments
feature_rankA column name in
featureDatato aggregate via$feature_merge().feature_filterA character or vector of characters to removes features by regex substring pattern matching via
$feature_merge()(default:NULL).col_nameThis argument has been renamed to
add_colsfor more clarity.add_colsOptional, a column name or vector of multiple column names from
metaDatato add to thedatalist name (default":NULL).feature_topA wholenumber of the top features to visualize, the max is 15, due to a limit of palettes (default:
10).Brewer.palIDA character name for the palette set to be applied, see brewer.pal or colormap (default:
"RdYlBu").
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
result <- obj$composition(feature_rank = "Genus",
feature_filter = c("uncultured"),
feature_top = 10)
plt <- composition_plot(data = result$data,
palette = result$palette,
feature_rank = "Genus")omics$distance()
Compute a distance metric from countData
Usage
omics$distance(
metric,
weighted = TRUE,
threads = 1,
normalize = TRUE,
base = exp(1)
)Arguments
metricA dissimilarity metric to be applied on the
countData, options:"bray""jaccard""cosine""manhattan""euclidean""jsd""canberra""unifrac""aitchison"The
"aitchison"metric uses the$scale(method = "clr")without any pseudocounts, see$scale(), followed by euclidean dissimilarity computation.Ref: Aitchison, J. (1986) The Statistical Analysis of Compositional Data. Chapman and Hall, London, 416 p.
weightedA boolean value, to use abundances (
weighted = TRUE) or absence/presence (weighted=FALSE) (default:TRUE).threadsA wholenumber, indicating the number of threads to use (default:
1).normalizeA boolean value, whether to normalize weighted UniFrac distances to be between 0 and 1. Unweighted UniFrac is always normalized (default:
TRUE).baseInput for log to use natural logarithmic scale, log2, log10 or other (default:
exp(1)).
Returns
A column x column dist object.
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
obj$feature_subset(Kingdom == "Bacteria")
dist <- obj$distance(metric = "bray")omics$ordination()
The $ordination() method either computes a distance matrix by specification of the metric or
takes a custom distance matrix via distmat. It then computes either the pairwise PERMANOVA test on
the defined contrast via group_by via pairwise_adonis or the pairwise ANOSIM test via pairwise_anosim.
Which pairwise test to compute is decided via the method argument, where "pcoa" results in
the pairwise_adonis and "nmds" to pairwise_anosim.
It also visualises these results as a scree-plot (only when "pcoa" is used), scores-plot (see ordination_plot)
and an anova-plot (see plot_pairwise_stats). These plots, alongisde the distance matrix, principal components
are returned as a list.
Usage
omics$ordination(
metric = "bray",
method = "pcoa",
group_by,
distmat = NULL,
weighted = TRUE,
normalize = TRUE,
threads = 1,
perm_design = NULL,
perm = 999
)Arguments
metricA dissimilarity or similarity metric to be applied on the
countData, see$distance()(default:"bray").methodOrdination method, options:
"pcoa"or"nmds", see wcmdscale (default:"pcoa")."pcoa"When
"pcoa"(Principal Coordinate Analysis) is chosen, a pairwise PERMANOVA test via pairwise_adonis is conducted on the contrast specified bygroup_bywith n number of permutations,perm."nmds"When
"nmds"(Non-Metric Multidimensional Scaling) is chosen, a pairwise ANOSIM test via pairwise_anosim is conducted on the contrast specified bygroup_bywith n number of permutations,perm. This method returns 2 dimensions by default, and a stress score in thepcslist name, that acts as the confidence, see metaMDS. Since only two dimensions are returned, there is noscree_plotoutput.
group_byA character variable in
metaDatato be used for the pairwise_adonis or pairwise_anosim statistical test.distmatA custom distance matrix as either dist or Matrix (default:
NULL).weightedA boolean value, whether to compute weighted or unweighted dissimilarities, see
$distance()(default:TRUE).normalizeA boolean value, wether to normalize weighted UniFrac distances to be between 0 and 1, see unifrac (default:
TRUE).threadsA wholenumber, indicating the number of threads to use (default:
1).perm_designA function that takes
metaDataand constructs a permutation design with how, see example (default:NULL).permA whole number to define the number of permutations in adonis2 and anosim (default:
999).
Returns
A list of components:
- distmat
A distance dissimilarity in matrix format.
- stats
A statistical test as a data.frame.
- pcs
principal components as a data.frame.
- scree_plot
A ggplot object.
- anova_plot
A ggplot object.
- scores_plot
A ggplot object.
Examples
library("ggplot2")
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
pcoa_plots <- obj$ordination(metric = "bray",
method = "pcoa",
group_by = "treatment",
weighted = TRUE)
pcoa_plotsomics$foldchange()
Differential feature expression for both paired and non-paired data.
The function performs feature agglomeration via $feature_merge() (which can be disabled via feature_merge=FALSE),
subsetting to remove NAs in condition.group via $removeNAs() and finding samplepairs when paired = TRUE is supplied
via $subset_samplepairs().
The fold-changes can be computed differently based on the method and aggregate_method options.
Transformations of the data should be done beforehand via $scale().
Finally, homogeneity of variance is computed based on the selected aggregate_method option. If aggregate_method = "mean" then the row_levene is applied,
and if aggregate_method = "median" is used then the row_brownforsythe is applied. Any filtering of the results is left to the end-user,
volcano plots are automatically added to the list name volcano_plot via volcano_plot.
Usage
omics$foldchange(
condition.group,
condition_A,
condition_B,
method = "identity",
aggregate_method = "median",
group_by = lifecycle::deprecated(),
split_by = NULL,
feature_merge = FALSE,
feature_rank = "FEATURE_ID",
feature_filter = NULL,
paired = FALSE,
pvalue.threshold = 0.05,
logfold.threshold = 0.06,
abundance.threshold = 0
)Arguments
condition.groupA character of an existing column name in
metaData, wherein the conditions A and B are located.condition_AA character (vector) in
condition.group.condition_BA character (vector) in
condition.group.methodA character to choose the method of fold-change computation (default:
"identity")."identity"Computes fold-change via
log2(condition_A) - log2(condition_B), and will handle zero's to preventInfvalues. Proportional data is also supported and will be automatically detected."log"Computes fold-change via
condition_A - condition_B.
How to aggregate the fold-change values for
condition_Aandcondition_Bcan be controlled with theaggregate_methodargument.aggregate_methodA function to aggregate the fold-change values from multiple samples (default:
"median"). options:"mean"It takes the arithmetic mean for each feature, separately for
condition_Aandcondition_B."median"It takes the median for each feature, separately for
condition_Aandcondition_B."geomean"It computes the geometric mean of the positive counts, similar to the estimateSizeFactors, when
type = "poscount". The only difference, is that the code is adapted to handle a sparseMatrix."none"No aggreation is applied, the whole matrix is used as it is.
group_byThis argument has been renamed to
split_byfor more clarity.split_byA character variable of an existing column in
metaDatato split the table in chunks prior to fold-change computation (default:NULL). When disabled then column names will end with_in_all.feature_mergeA boolean value wether to call
$feature_merge()(default:FALSE).feature_rankA column in the
featureDatato use as the feature scope (default:"FEATURE_ID").feature_filterA character or vector of characters to remove features via regex substring pattern matching via
$feature_merge()(default:NULL).pairedA boolean value, the paired is only applicable when a
SAMPLEPAIR_IDcolumn exists within themetaData(default:FALSE), see$samplepair_subset().pvalue.thresholdA numeric value used as a p-value threshold to label and color significant features (default:
0.05), see volcano_plot.logfold.thresholdA numeric value used as a fold-change threshold to label and color significantly expressed features (default:
0.06), see volcano_plot.abundance.thresholdA numeric value used as an abundance threshold to size the scatter dots based on their mean abundance (default:
0), see volcano_plot.
Returns
A list of components:
split_bysubsetsA matrix subset from each
split_byseparated bycondition_Aandcondition_B.- data
A data.table main output of fold-changes between conditions, contains abundance, fold-change, and homogeneity tests.
- volcano_plot
A list of ggplot plots for each contrast of
A vs B, number of plots depend onsplit_byandcondition_Ainput.
Examples
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
## Method 1: using non-log transformation
obj$scale(method = "tss")
dfe <- obj$foldchange(
feature_rank = "Genus",
feature_merge = TRUE,
method = "identity",
aggregate_method = "median",
condition.group = "treatment",
condition_A = "tumor",
condition_B = "healthy"
)
## Method 2: using log transformation
obj$reset()
obj$scale(method = "clr")
dfe <- obj$foldchange(
feature_rank = "Genus",
feature_merge = TRUE,
method = "log",
aggregate_method = "mean",
condition.group = "treatment",
condition_A = "tumor",
condition_B = "healthy"
)omics$autoFlow()
Automated Omics Analysis only works if there are column names in the metaData with the prefix "CONTRAST_",
which is detected via sub-string pattern matching. The transformation of the data is left to the user via the
$scale() method. The $autoFlow() incorporates the following functions:
$rankstat()This function is only applied when
feature_ranksis specified, useful in metagenomics, see$rankstat()for more information.$alpha_diversity()This function only works with the
metagenomicsclass, uses"shannon"metric, and works for both paired and non-paired data, applied on each"CONTRAST_"column, see$alpha_diversity()for more information.$ordination()This function is applied on all classes, multiple
distance_metricscan be supplied, and only the Principal Component method ($ordination(method = "pcoa")) is used. Additional arguments can be controlled withdistance_metrics,distmat,weighted,perm,threads, see$ordination()for more information. NOTE:perm_designis not supported in$autoFlow().$composition()This function is applied on the significant contrasts that are obtained from either
$alpha_diversity()or$ordination(). Multiplefeature_contrastscan be supplied, by default it only uses thefeature_contrasts = "FEATURE_ID". The composition plots are created by default via thecomposition_plot(group_by)withfeature_top = 15. Additional arguments can be controlled withfeature_filter, see$composition()for more information.$foldchange()This function is applied on the significant contrasts that are obtained from either
$alpha_diversity()or$ordination(). Multiplefeature_contrastscan be supplied, by default it only uses thefeature_contrasts = "FEATURE_ID". Additional arguments can be controlled withfc_method,aggregate_method,pvalue.threshold,logfold.threshold,abundance.threshold, see$foldchange()for more information.
The above functions are called in order, only significant contrasts are further used to create
composition and volcano plots. The autoFlow is intended as a first screening of certain
contrasts and extra analysis, such as the use of a permutation design are not supported and should
be applied by the user.
The report argument controls if an rmarkdown document is created, and with filename
the output filename can be specified.
Usage
omics$autoFlow(
feature_contrast = "FEATURE_ID",
feature_filter = NULL,
feature_ranks = NULL,
distance_metrics = c("bray"),
distmat = NULL,
weighted = TRUE,
fc_method = "log",
aggregate_method = "median",
pvalue.threshold = 0.05,
logfold.threshold = 0.06,
abundance.threshold = 0,
perm = 999,
threads = 1,
report = TRUE,
filename = paste0(getwd(), "/report.html")
)Arguments
feature_contrastA character vector of feature columns in the
featureDatato aggregate via$feature_merge()(default:"FEATURE_ID").feature_filterA character vector to filter unwanted features, see
$feature_merge()(default:NULL).feature_ranksA character vector as input to
$rankstat()(default:NULL).distance_metricsA character vector specifying what (dis)similarity metrics to use in
ordination()(default:c("bray")). When you are working with log-transformed data it is advised to use the"euclidean".distmatA path to an existing file or a dense/sparse Matrix format to be used in
$ordination()(default:NULL).weightedA boolean value, whether to compute weighted or unweighted dissimilarities in
$ordination()(default:TRUE).fc_methodA character to choose the method in
$foldchange()(default:"identity")."identity"Computes fold-change via
log2(condition_A) - log2(condition_B), and will handle zero's to preventInfvalues. Proportional data is also supported and will be automatically detected."log"Computes fold-change via
condition_A - condition_B.
aggregate_methodA function to aggregate the matrix values in
$foldchange()by taking e.g. themedianofcondition_Aandcondition_Bprior to substraction, or in the case ofmethod = "identity"to take the median of the fold-changelog2(median(A)) - log2(median(B))(default:median).pvalue.thresholdA numeric value used as a p-value threshold to label and color significant features in
$foldchange()(default:0.05).logfold.thresholdA numeric value used as a fold-change threshold to label and color significantly expressed features in
$foldchange()(default:0.06).abundance.thresholdA numeric value used as an abundance threshold to size the scatter dots based on their mean abundance in
$foldchange()(default:0).permA wholenumber, number of permutations to compare against the null hypothesis of adonis2 or anosim in
$ordination()(default:999).threadsNumber of threads to use, only used in
$distance()when distmat is not supplied (default:1).reportA boolean value to create a HTML markdown report (default:
FALSE). IfFALSEa nested list of the plots and data is returned.filenameA character to name the HTML report to be saved in the current working directory (default:
paste0(getwd(), "/report.html")). Thegetwd()is required for rmarkdown to save it in the right path.
Returns
if report = TRUE a HTML report is generated, otherwise a list containing:
- plots
-
rankstat_plotas a ggplot.alpha_div_plotsas a list of ggplot.pcoa_plotsas a nested matrix of lists with ggplot (contrastsxdistance_metrics).composition_plotsas a nested matrix of lists with ggplot (contrastsxfeature_contrasts).Log2FC_plotsas a nested matrix of lists with ggplot (contrastsxfeature_contrasts).
- data
-
alpha_div_dataas a list of lists ofdataandstats.pcoa_dataas a nested matrix of lists ofstats,dist_matandpcs(contrastsxdistance_metrics).composition_dataas a nested matrix of lists ofdata(contrastsxfeature_contrasts).Log2FC_dataas a nested matrix of lists ofdata(contrastsxfeature_contrasts).
Examples
## ------------------------------------------------
## Method `omics$new()`
## ------------------------------------------------
library("OmicFlow")
## Method 1: load from filepath
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ countData is loaded.
#> ℹ Created placeholder featureData.
## Method 2: Load from data.frame or matrix
n_cols <- 5
n_rows <- 100
n_vals <- n_cols * n_rows
metadata <- data.frame("SAMPLE_ID" = paste0("Sample_", 1:n_cols))
features <- data.frame("FEATURE_ID" = paste0("protein_", 1:n_rows))
counts <- Matrix::Matrix(
1:n_vals, nrow = n_rows, ncol = n_cols,
dimnames = list(features$FEATURE_ID, metadata$SAMPLE_ID)
)
obj <- omics$new(
metaData = metadata,
featureData = features, # optional
countData = counts
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
## Method 3: you have features and counts in a single data.frame
metadata <- data.frame(SAMPLE_ID = c("S1", "S2", "S3"))
counts <- data.frame(
S1 = c(2,3,0),
S2 = c(2,"",1),
S3 = c(2,1,NA),
proteins = c("ZEB1", "ZEB2", "MAPK")
)
obj <- omics$new(
metaData = metadata,
countData = counts
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ℹ Placeholder featureData extracted from countData.
#> ✔ countData is loaded.
## ------------------------------------------------
## Method `omics$copy()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ countData is loaded.
#> ℹ Created placeholder featureData.
# Perform a modification and copy
obj$scale()
cloned <- obj$copy(deep=TRUE)
cloned$scale(method = "clr")
cloned$reset() # resets to data after clone creation.
## ------------------------------------------------
## Method `omics$print()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ countData is loaded.
#> ℹ Created placeholder featureData.
# method 1 to call print function
obj
#>
#> ── <omics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 0 attributes × 242 features
# method 2 to call print function
obj$print()
#>
#> ── <omics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 0 attributes × 242 features
## ------------------------------------------------
## Method `omics$reset()`
## ------------------------------------------------
library(ggplot2)
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
taxa <- omics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
# Performs modifications
taxa$scale(transform = log2)
# resets
taxa$reset()
# An inbuilt reset function prevents unwanted modification to the taxa object.
taxa$rankstat(feature_ranks = c("Kingdom", "Phylum", "Family", "Genus", "Species"))
## ------------------------------------------------
## Method `omics$removeNAs()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
obj$removeNAs(column = "treatment")
## ------------------------------------------------
## Method `omics$feature_subset()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
obj$feature_subset(Genus == "Pseudomonas")
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 3 samples
#> countData: 3 samples × 4 features
#> featureData: 7 attributes × 4 features
## ------------------------------------------------
## Method `omics$sample_subset()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
obj$sample_subset(treatment == "tumor")
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 2 samples
#> countData: 2 samples × 115 features
#> featureData: 7 attributes × 115 features
## ------------------------------------------------
## Method `omics$feature_merge()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
obj$feature_merge(feature_rank = c("Kingdom", "Phylum"))
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 28 features
#> featureData: 7 attributes × 28 features
obj$feature_merge(feature_rank = "Genus", feature_filter = c("uncultured", "metagenome"))
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 20 features
#> featureData: 7 attributes × 20 features
## ------------------------------------------------
## Method `omics$scale()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
# standard relative abundance computation
obj$scale()
# CLR
obj$reset()
obj$scale(method = "clr")
# transform
obj$reset()
obj$scale(method = "none", transform = log2)
## ------------------------------------------------
## Method `omics$rankstat()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
plt <- obj$rankstat(feature_ranks = c("Kingdom", "Phylum", "Family", "Genus", "Species"))
plt
## ------------------------------------------------
## Method `omics$alpha_diversity()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
plt <- obj$alpha_diversity(groups = "treatment",
metric = "shannon")
## ------------------------------------------------
## Method `omics$composition()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
result <- obj$composition(feature_rank = "Genus",
feature_filter = c("uncultured"),
feature_top = 10)
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 63 features
#> featureData: 7 attributes × 63 features
plt <- composition_plot(data = result$data,
palette = result$palette,
feature_rank = "Genus")
## ------------------------------------------------
## Method `omics$distance()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
obj$feature_subset(Kingdom == "Bacteria")
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 185 features
#> featureData: 7 attributes × 185 features
dist <- obj$distance(metric = "bray")
## ------------------------------------------------
## Method `omics$ordination()`
## ------------------------------------------------
library("ggplot2")
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ℹ Final steps .. cleaning & creating back-up
#>
#> ── <metagenomics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 242 features
#> featureData: 7 attributes × 242 features
pcoa_plots <- obj$ordination(metric = "bray",
method = "pcoa",
group_by = "treatment",
weighted = TRUE)
#> 'nperm' >= set of all permutations: complete enumeration.
#> Set of permutations < 'minperm'. Generating entire set.
pcoa_plots
#> $dist
#> S100 S103 S115 S120
#> S100 0.0000000 1.0000000 0.8845188 1.0000000
#> S103 1.0000000 0.0000000 1.0000000 0.9470058
#> S115 0.8845188 1.0000000 0.0000000 1.0000000
#> S120 1.0000000 0.9470058 1.0000000 0.0000000
#>
#> $anova_data
#> pairs Df SumsOfSqs F.Model R2 p.value p.adj
#> 1 tumor vs healthy 1 0.4197984 0.8395968 0.2956747 1 1
#>
#> $pcs
#> PC1 PC2 PC3 treatment samples
#> <num> <num> <num> <char> <char>
#> 1: 0.3808548 0.000000e+00 4.422594e-01 tumor 1
#> 2: -0.3808548 -4.735029e-01 -2.256762e-16 tumor 2
#> 3: 0.3808548 -2.787913e-17 -4.422594e-01 healthy 3
#> 4: -0.3808548 4.735029e-01 -2.603956e-16 healthy 4
#>
#> $scree_plot
#>
#> $anova_plot
#>
#> $scores_plot
#> Too few points to calculate an ellipse
#> Too few points to calculate an ellipse
#> Warning: Removed 2 rows containing missing values or values outside the scale range
#> (`geom_path()`).
#>
## ------------------------------------------------
## Method `omics$foldchange()`
## ------------------------------------------------
library("OmicFlow")
metadata_file <- system.file("extdata", "metadata.tsv", package = "OmicFlow")
counts_file <- system.file("extdata", "counts.tsv", package = "OmicFlow")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
obj <- omics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
## Method 1: using non-log transformation
obj$scale(method = "tss")
dfe <- obj$foldchange(
feature_rank = "Genus",
feature_merge = TRUE,
method = "identity",
aggregate_method = "median",
condition.group = "treatment",
condition_A = "tumor",
condition_B = "healthy"
)
#>
#> ── <omics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 65 features
#> featureData: 7 attributes × 65 features
#> Warning: row_wilcoxon_twosample: 54 of the rows had ties: cannot compute exact p-values with ties.
#> First occurrence at row 3
#> Warning: row_brownforsythe: 65 of the rows had no groups with at least 3 observations.
#> First occurrence at row 1
## Method 2: using log transformation
obj$reset()
obj$scale(method = "clr")
dfe <- obj$foldchange(
feature_rank = "Genus",
feature_merge = TRUE,
method = "log",
aggregate_method = "mean",
condition.group = "treatment",
condition_A = "tumor",
condition_B = "healthy"
)
#>
#> ── <omics> object
#> metaData: 9 variables × 4 samples
#> countData: 4 samples × 65 features
#> featureData: 7 attributes × 65 features
#> Warning: row_wilcoxon_twosample: 54 of the rows had ties: cannot compute exact p-values with ties.
#> First occurrence at row 3
#> Warning: row_levene: 65 of the rows had no groups with at least 3 observations.
#> First occurrence at row 1
