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 metagenomics$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 (or biomData in case of metagenomics)
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.
Additional arguments in metagenomics$new()
The metagenomics class also offers the loading of a phylogenetic tree as
a phylo class (see as.phylo) that can be supplied to treeData.
When a treeData is supplied than every class field is arranged according to
the tree tip labels.
The biomData argument expects a BIOM v2.1.0. in either
HDF5 or JSON format. The biomData must be supplied via a filepath and required
contents are checked upfront, such as the existence of
"/observation/matrix/data",
"/observation/matrix/indptr",
"/observation/matrix/indices",
"/observation/metadata/taxonomy",
"/observation/ids",
"/sample/ids"
.
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.
Super class
omics -> metagenomics
Active bindings
treeDataA "phylo" class, see as.phylo.
Methods
Inherited methods
metagenomics$new()
Usage
metagenomics$new(
countData = NULL,
metaData = NULL,
featureData = NULL,
treeData = NULL,
biomData = NULL,
feature_names = c("Kingdom", "Phylum", "Class", "Order", "Family", "Genus", "Species")
)Arguments
countDataA path to an existing file, Matrix, data.table or data.frame (default:
NULL).metaDataA path to an existing file, data.table or data.frame (default:
NULL).featureDataA path to an existing file, data.table or data.frame (default:
NULL).treeDataA path to an existing newick file or class "phylo", see read.tree (default:
NULL).biomDataA path to an existing biom file, version 2.1.0 (see h5read) or JSON format (see validate_json_file) (default:
NULL).feature_namesA character vector to name the feature names that fit the supplied
featureData(default:c("Kingdom", "Phylum", "Class", "Order", "Family", "Genus", "Species")).
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")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
tree_file <- system.file("extdata", "tree.newick", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file, # optional
treeData = tree_file # optional
)
## Method 2: Load from a biom file
biom_file <- system.file("extdata", "biomv2.biom", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
biomData = biom_file
)metagenomics$write_biom()
Creates a BIOM file in HDF5 format, which is compatible to the python biom-format v2.1.0.
It only saves the featureData and countData to the biom format, no treeData is supported thus far.
Arguments
filenameA character variable of a non-existing file path (e.g.
"output.biom"or"my/path/output.biom")
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")
tree_file <- system.file("extdata", "tree.newick", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
treeData = tree_file
)
taxa$write_biom(filename = "output.biom")
file.remove("output.biom")Examples
## ------------------------------------------------
## Method `metagenomics$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")
features_file <- system.file("extdata", "features.tsv", package = "OmicFlow")
tree_file <- system.file("extdata", "tree.newick", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file, # optional
treeData = tree_file # optional
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ✔ treeData 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
#> treeData: 242 tips × 241 nodes
## Method 2: Load from a biom file
biom_file <- system.file("extdata", "biomv2.biom", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
biomData = biom_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
## ------------------------------------------------
## Method `metagenomics$write_biom()`
## ------------------------------------------------
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")
tree_file <- system.file("extdata", "tree.newick", package = "OmicFlow")
taxa <- metagenomics$new(
metaData = metadata_file,
countData = counts_file,
featureData = features_file,
treeData = tree_file
)
#> ✔ metaData template passed the JSON validation.
#> ℹ Checking for duplicated identifiers ..
#> ✔ featureData is loaded.
#> ✔ countData is loaded.
#> ✔ treeData 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
#> treeData: 242 tips × 241 nodes
taxa$write_biom(filename = "output.biom")
file.remove("output.biom")
#> [1] TRUE
