Package 'curatedMetagenomicData'

Access Curated Metagenomic Data

Description

To access curated metagenomic data users will use curatedMetagenomicData() after "shopping" the sampleMetadata data.frame for resources they are interested in. The dryrun argument allows users to perfect a query prior to returning resources. When dryrun = TRUE, matched resources will be printed before they are returned invisibly as a character vector. When dryrun = FALSE, a list of resources containing SummarizedExperiment and/or TreeSummarizedExperiment objects, each with corresponding sample metadata, is returned. Multiple resources can be returned simultaneously and if there is more than one date corresponding to a resource, the most recent one is selected automatically. Finally, if a relative_abundance resource is requested and counts = TRUE, relative abundance proportions will be multiplied by read depth and rounded to the nearest integer.

Usage

curatedMetagenomicData(
  pattern,
  dryrun = TRUE,
  counts = FALSE,
  rownames = "long"
)

Arguments

pattern	regular expression pattern to look for in the titles of resources available in curatedMetagenomicData; "" will return all resources
dryrun	if TRUE (the default), a character vector of resource names is returned invisibly; if FALSE, a list of resources is returned
counts	if FALSE (the default), relative abundance proportions are returned; if TRUE, relative abundance proportions are multiplied by read depth and rounded to the nearest integer prior to being returned
rownames	the type of rownames to use for relative_abundance resources, one of: "long" (the default, the full MetaPhlAn clade string), "short" (species name), or "NCBI" (NCBI Taxonomy ID). These are different vocabularies; see the Taxonomic names section below before merging with profiles generated elsewhere.

Details

Above "resources" refers to resources that exists in Bioconductor's ExperimentHub service. In the context of curatedMetagenomicData, these are study-level (sparse) matrix objects used to create SummarizedExperiment and/or TreeSummarizedExperiment objects that are ultimately returned as the list of resources. Only the gene_families dataType (see returnSamples) is stored as a sparse matrix in ExperimentHub – this has no practical consequences for users and is done to optimize storage. When searching for "resources", users will use the study_name value from the sampleMetadata data.frame.

Value

if dryrun = TRUE, a character vector of resource names is returned invisibly; if dryrun = FALSE, a list of resources is returned

Taxonomic names

The three rownames options do not use the same vocabulary, which matters when merging curatedMetagenomicData with profiles generated elsewhere.

"long" is the unmodified MetaPhlAn clade string, exactly as it appears in the MetaPhlAn database used to generate the data (mpa_v30_CHOCOPhlAn_201901 for the MetaPhlAn3 resources here). It matches an external profile exactly when that profile was generated from the same database, so it is the option to use when joining against a merged_abundance_table.

"short" and "NCBI" are derived by resolving each clade's NCBI Taxonomy ID against NCBI when the package data are built, so they reflect NCBI taxonomy as of that point rather than the taxonomy frozen in the MetaPhlAn database. Neither is looked up at retrieval time: both are snapshots, refreshed only when the packaged taxonomy is regenerated. Where a taxon was reclassified between the two, the "short" name differs from the MetaPhlAn clade name, and such taxa fail to match on a merge by name with no error raised. MetaPhlAn3 reports Bacteroides_dorei while "short" gives Phocaeicola_dorei. This affects about 7% of returned rows, including the 2020 split of Lactobacillus across several new genera. Roughly half of the affected rows are phages, which MetaPhlAn names after the host rather than by NCBI's virus genus.

"short" and "NCBI" also return slightly fewer rows than "long". A handful of MetaPhlAn clades are species groups and complexes that NCBI resolves no further than genus, so they have no species-level name or identifier to label them with and are dropped, with a warning naming them. "NCBI" drops a few more: NCBI has merged species that MetaPhlAn still reports separately, so two or three clades can share one identifier, and those rows are summed into one with a message listing what was merged. Use "long" to keep every row.

To join on NCBI Taxonomy ID, use the integer rowData() column for the species rank rather than the row names. That column holds identifiers only when the resource was requested with rownames = "NCBI"; with "long" or "short" the same column holds character names. Species identifiers are stable across genus reclassification, but genus identifiers are not: Bacteroides is 816 and Phocaeicola is 909656, so a genus-level identifier join fails in exactly the way a name join does. The "NCBI" row names carry the same species identifiers, so either works as a key.

rowData() holds one vocabulary at a time, determined by rownames: character names for "long" and "short", integer NCBI Taxonomy IDs for "NCBI". A "long" object therefore gives a clade-string to NCBI-name mapping on its own, because its row names and its rowData() names are different vocabularies. Getting the integer identifiers alongside the names takes a second call.

See Also

mergeData, returnSamples, sampleMetadata

Examples

curatedMetagenomicData("AsnicarF_20.+")

curatedMetagenomicData("AsnicarF_2017.relative_abundance", dryrun = FALSE)

curatedMetagenomicData("AsnicarF_20.+.relative_abundance", dryrun = FALSE, counts = TRUE)

---

Merge curatedMetagenomicData List

Description

To merge the list elements returned from curatedMetagenomicData into a single SummarizedExperiment or TreeSummarizedExperiment object, users will use mergeData() provided elements are the same dataType (see returnSamples). This is useful for analysis across entire studies (e.g. meta-analysis); however, when doing analysis across individual samples (e.g. mega-analysis) returnSamples is preferable.

Usage

mergeData(mergeList)

Arguments

mergeList

a list returned from curatedMetagenomicData where all of the elements are of the same dataType (see returnSamples)

Details

Internally, mergeData() must full join assays and rowData slots of each SummarizedExperiment or TreeSummarizedExperiment object (colData is merged slightly more efficiently by row binding). While dplyr methods are used for maximum efficiency, users should be aware that memory requirements can be large when merging many list elements.

Value

when mergeList elements are of dataType (see returnSamples) relative_abundance, a TreeSummarizedExperiment object is returned; otherwise, a SummarizedExperiment object is returned

See Also

curatedMetagenomicData, returnSamples

Examples

curatedMetagenomicData("LiJ_20.+.marker_abundance", dryrun = FALSE) |>
    mergeData()

curatedMetagenomicData("LiJ_20.+.pathway_abundance", dryrun = FALSE) |>
    mergeData()

curatedMetagenomicData("LiJ_20.+.relative_abundance", dryrun = FALSE) |>
    mergeData()

---

Return Samples Across Studies

Description

To return samples across studies, users will use returnSamples() along with the sampleMetadata data.frame subset to include only desired samples and metadata. The subset sampleMetadata data.frame will be used to get the desired resources, mergeData will be used to merge them, and the subset sampleMetadata data.frame will be used again to subset the SummarizedExperiment or TreeSummarizedExperiment object to include only desired samples and metadata.

Usage

returnSamples(sampleMetadata, dataType, counts = FALSE, rownames = "long")

Arguments

sampleMetadata	the sampleMetadata data.frame subset to include only desired samples and metadata
dataType	the data type to be returned; one of the following: "gene_families" "marker_abundance" "marker_presence" "pathway_abundance" "pathway_coverage" "relative_abundance"
counts	if FALSE (the default), relative abundance proportions are returned; if TRUE, relative abundance proportions are multiplied by read depth and rounded to the nearest integer prior to being returned
rownames	the type of rownames to use for relative_abundance resources, one of: "long" (the default, the full MetaPhlAn clade string), "short" (species name), or "NCBI" (NCBI Taxonomy ID). These are different vocabularies; see the Taxonomic names section of curatedMetagenomicData before merging with profiles generated elsewhere.

Details

At present, curatedMetagenomicData resources exists only as entire studies which requires potentially getting many resources for a limited number of samples. Furthermore, because it is necessary to use mergeData internally, the same caveats detailed under Details in mergeData apply here.

Value

when dataType = "relative_abundance", a TreeSummarizedExperiment object is returned; otherwise, a SummarizedExperiment object is returned

Examples

sampleMetadata |>
    dplyr::filter(age >= 18) |>
    dplyr::filter(!base::is.na(alcohol)) |>
    dplyr::filter(body_site == "stool") |>
    dplyr::select(where(~ !base::all(base::is.na(.x)))) |>
    returnSamples("relative_abundance")

---

Manually Curated Sample Metadata

Description

Manually curated sample metadata for all samples in curatedMetagenomicData.

Usage

sampleMetadata

Format

An object of class data.frame with 22588 rows and 141 columns.

---