### Install curatedMetagenomicData from Bioconductor

Source: https://waldronlab.io/curatedMetagenomicData/index.html

Use BiocManager::install to install the package from Bioconductor. This is the recommended installation method for most users.

```r
BiocManager::install("curatedMetagenomicData")
```

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

### Install curatedMetagenomicData from GitHub

Source: https://waldronlab.io/curatedMetagenomicData/index.html

Install the package directly from GitHub using BiocManager::install. This method allows for installing with dependencies and building vignettes.

```r
BiocManager::install("waldronlab/curatedMetagenomicData", dependencies = TRUE, build_vignettes = TRUE)
```

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

### Download Specific Dataset

Source: https://waldronlab.io/curatedMetagenomicData/reference/curatedMetagenomicData.html

Download a specific dataset by its full name. Set `dryrun = FALSE` to actually download the data. This example retrieves relative abundance data.

```R
curatedMetagenomicData("AsnicarF_2017.relative_abundance", dryrun = FALSE)
#> 
#> $`2021-10-14.AsnicarF_2017.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Carnobacteriaceae|g__Granulicatella|s__Granulicatella_elegans
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> $`2021-10-14.AsnicarF_2017.relative_abundance`
#> class: TreeSummarizedExperiment 
#> dim: 298 24 
#> metadata(0):
#> assays(1): relative_abundance
#> rownames(298):
#>   k__Bacteria|p__Proteobacteria|c__Gammaproteobacteria|o__Enterobacterales|f__Enterobacteriaceae|g__Escherichia|s__Escherichia_coli
#>   k__Bacteria|p__Actinobacteria|c__Actinobacteria|o__Bifidobacteriales|f__Bifidobacteriaceae|g__Bifidobacterium|s__Bifidobacterium_bifidum
#>   ... ...
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Streptococcaceae|g__Streptococcus|s__Streptococcus_gordonii
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Aerococcaceae|g__Abiotrophia|s__Abiotrophia_sp_HMSC24B09
#> rowData names(7): superkingdom phylum ... genus species
#> colnames(24): MV_FEI1_t1Q14 MV_FEI2_t1Q14 ... MV_MIM5_t2M14
#>   MV_MIM5_t3F15
#> colData names(22): study_name subject_id ... pregnant lactating
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: a LinkDataFrame (298 rows)
#> rowTree: 1 phylo tree(s) (10430 leaves)
#> colLinks: NULL
#> colTree: NULL
#> 
```

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

### Merge Relative Abundance Data

Source: https://waldronlab.io/curatedMetagenomicData/reference/mergeData.html

Fetches and merges relative abundance data. This example shows the output structure and potential row dropping messages.

```r
curatedMetagenomicData("LiJ_20.+.relative_abundance", dryrun = FALSE) |>
    mergeData()
#> 
#> $`2021-03-31.LiJ_2014.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Atopobiaceae|g__Olsenella|s__Olsenella_profusa
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Bacillales|f__Bacillales_unclassified|g__Gemella|s__Gemella_bergeri
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Carnobacteriaceae|g__Granulicatella|s__Granulicatella_elegans
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Firmicutes|c__Erysipelotrichia|o__Erysipelotrichales|f__Erysipelotrichaceae|g__Bulleidia|s__Bulleidia_extructa
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> $`2021-10-14.LiJ_2017.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> class: TreeSummarizedExperiment 
#> dim: 691 456 
#> metadata(0):
#> assays(1): relative_abundance
#> rownames(691):
#>   k__Bacteria|p__Bacteroidetes|c__Bacteroidia|o__Bacteroidales|f__Bacteroidaceae|g__Bacteroides|s__Bacteroides_plebeius
#>   k__Bacteria|p__Bacteroidetes|c__Bacteroidia|o__Bacteroidales|f__Bacteroidaceae|g__Bacteroides|s__Bacteroides_caccae
#>   ... 
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Neisseriales|f__Neisseriaceae|g__Neisseria|s__Neisseria_elongata
#>   k__Bacteria|p__Proteobacteria|c__Gammaproteobacteria|o__Enterobacterales|f__Morganellaceae|g__Providencia|s__Providencia_alcalifaciens
#> rowData names(7): superkingdom phylum ... genus species
#> colnames(456): DLF005-IE DLM006-IE ... nHM612836 nHMX11726
#> colData names(28): study_name subject_id ... location smoker
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: a LinkDataFrame (691 rows)
#> rowTree: 1 phylo tree(s) (10430 leaves)
#> colLinks: NULL
#> colTree: NULL
```

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

### Merge Marker Abundance Data

Source: https://waldronlab.io/curatedMetagenomicData/reference/mergeData.html

Fetches and merges marker abundance data for a specified dataset. Ensure the curatedMetagenomicData package is installed and loaded.

```r
curatedMetagenomicData("LiJ_20.+.marker_abundance", dryrun = FALSE) |>
    mergeData()
#> class: SummarizedExperiment 
#> dim: 77729 456 
#> metadata(0):
#> assays(1): marker_abundance
#> rownames(77729): 39491__A0A395UVM9__DXB76_04540
#>   39491__A0A395UZL1__DXB76_05950 ... 1262937__R7LHU6__BN805_01557
#>   712117__F3PBR4__HMPREF9056_02502
#> rowData names(0):
#> colnames(456): DLF005-IE DLM006-IE ... nHM612836 nHMX11726
#> colData names(28): study_name subject_id ... location smoker
```

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

### Load Required R Packages

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Load the dplyr and DT packages for demonstrating curatedMetagenomicData functionality.

```R
library(dplyr)
library(DT)
```

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

### List Datasets with Pattern Matching

Source: https://waldronlab.io/curatedMetagenomicData/reference/curatedMetagenomicData.html

Use pattern matching to list available datasets. This is useful for exploring datasets related to a specific study or sample type.

```R
curatedMetagenomicData("AsnicarF_20.+")
#> 2021-03-31.AsnicarF_2017.gene_families
#> 2021-03-31.AsnicarF_2017.marker_abundance
#> 2021-03-31.AsnicarF_2017.marker_presence
#> 2021-03-31.AsnicarF_2017.pathway_abundance
#> 2021-03-31.AsnicarF_2017.pathway_coverage
#> 2021-03-31.AsnicarF_2017.relative_abundance
#> 2021-10-14.AsnicarF_2017.gene_families
#> 2021-10-14.AsnicarF_2017.marker_abundance
#> 2021-10-14.AsnicarF_2017.marker_presence
#> 2021-10-14.AsnicarF_2017.pathway_abundance
#> 2021-10-14.AsnicarF_2017.pathway_coverage
#> 2021-10-14.AsnicarF_2017.relative_abundance
#> 2021-03-31.AsnicarF_2021.gene_families
#> 2021-03-31.AsnicarF_2021.marker_abundance
#> 2021-03-31.AsnicarF_2021.marker_presence
#> 2021-03-31.AsnicarF_2021.pathway_abundance
#> 2021-03-31.AsnicarF_2021.pathway_coverage
#> 2021-03-31.AsnicarF_2021.relative_abundance
```

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

### Download Raw Counts with Pattern Matching

Source: https://waldronlab.io/curatedMetagenomicData/reference/curatedMetagenomicData.html

Retrieve raw counts for datasets matching a pattern. This is useful when you need the original count data for downstream analysis. Note that `dryrun = FALSE` is required for actual download.

```R
curatedMetagenomicData("AsnicarF_20.+.relative_abundance", dryrun = FALSE, counts = TRUE)
#> 
#> $`2021-10-14.AsnicarF_2017.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> $`2021-03-31.AsnicarF_2021.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#>   k__Eukaryota|p__Eukaryota_unclassified|c__Eukaryota_unclassified|o__Eukaryota_unclassified|f__Hexamitidae|g__Giardia|s__Giardia_intestinalis
#> $`2021-10-14.AsnicarF_2017.relative_abundance`
#> class: TreeSummarizedExperiment 
#> dim: 298 24 
#> metadata(0):
#> assays(1): relative_abundance
#> rownames(298):

```

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

### Query Available Resources by Pattern

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Searches for and returns the titles of available data resources in the curatedMetagenomicData package that match a given regular expression pattern. By default, it only returns titles.

```r
curatedMetagenomicData("AsnicarF_20.+")
## 2021-03-31.AsnicarF_2017.gene_families
## 2021-03-31.AsnicarF_2017.marker_abundance
## 2021-03-31.AsnicarF_2017.marker_presence
## 2021-03-31.AsnicarF_2017.pathway_abundance
## 2021-03-31.AsnicarF_2017.pathway_coverage
## 2021-03-31.AsnicarF_2017.relative_abundance
## 2021-10-14.AsnicarF_2017.gene_families
## 2021-10-14.AsnicarF_2017.marker_abundance
## 2021-10-14.AsnicarF_2017.marker_presence
## 2021-10-14.AsnicarF_2017.pathway_abundance
## 2021-10-14.AsnicarF_2017.pathway_coverage
## 2021-10-14.AsnicarF_2017.relative_abundance
## 2021-03-31.AsnicarF_2021.gene_families
## 2021-03-31.AsnicarF_2021.marker_abundance
## 2021-03-31.AsnicarF_2021.marker_presence
## 2021-03-31.AsnicarF_2021.pathway_abundance
## 2021-03-31.AsnicarF_2021.pathway_coverage
## 2021-03-31.AsnicarF_2021.relative_abundance
```

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

### Return Specific Data Resource with Short Row Names

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Retrieves a specific data resource ('AsnicarF_2017.relative_abundance') and returns it as a list of SummarizedExperiment objects. Sets the row names to use species names ('short') instead of the default long format.

```r
curatedMetagenomicData("AsnicarF_2017.relative_abundance", dryrun = FALSE, rownames = "short")
## $`2021-10-14.AsnicarF_2017.relative_abundance`
## class: TreeSummarizedExperiment 
## dim: 298 24 
## metadata(0): 
## assays(1): relative_abundance
## rownames(298): species:Escherichia coli species:Bifidobacterium bifidum
##   ... species:Streptococcus gordonii species:Abiotrophia sp. HMSC24B09
## rowData names(7): superkingdom phylum ... genus species
## colnames(24): MV_FEI1_t1Q14 MV_FEI2_t1Q14 ... MV_MIM5_t2M14
##   MV_MIM5_t3F15
## 
```

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

### Filter and Return Samples with Metadata

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Filters sample metadata based on age, alcohol consumption, and body site, then returns a SummarizedExperiment object with relative abundance data. Ensures only non-NA metadata columns are kept.

```R
sampleMetadata |>
    filter(age >= 18) |>
    filter(!is.na(alcohol)) |
    filter(body_site == "stool") |
    select(where(~ !all(is.na(.x)))) |
    returnSamples("relative_abundance", rownames = "short")
## class: TreeSummarizedExperiment 
## dim: 832 702 
## metadata(0): 
## assays(1): relative_abundance
## rownames(832): species:Prevotella copri species:Prevotella sp. CAG:520
##   ... species:Corynebacterium aurimucosum species:Corynebacterium
##   coyleae
## rowData names(7): superkingdom phylum ... genus species
## colnames(702): JAS_1 JAS_10 ... YSZC12003_37879 YSZC12003_37880
## colData names(48): study_name subject_id ...
##   age_twins_started_to_live_apart zigosity
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):
## rowLinks: a LinkDataFrame (832 rows)
## rowTree: 1 phylo tree(s) (10430 leaves)
## colLinks: NULL
## colTree: NULL
```

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

### Load Required R Packages

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Loads necessary R packages for data manipulation and analysis, including stringr, mia, scater, and vegan.

```R
library(stringr)
library(mia)
library(scater)
library(vegan)
```

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

### Return Samples Function Signature

Source: https://waldronlab.io/curatedMetagenomicData/reference/returnSamples.html

This is the basic usage signature for the returnSamples function. It outlines the required and optional arguments for retrieving data.

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

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

### Access Sample Metadata

Source: https://waldronlab.io/curatedMetagenomicData/reference/sampleMetadata.html

Access the manually curated sample metadata object. This object is a data.frame containing 22588 rows and 141 columns.

```r
sampleMetadata
```

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

### Create Alternative Experiments for Taxonomic Ranks

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Uses the splitByRanks function to create alternative experiments for each taxonomic rank (e.g., Genus) within the alcoholStudy object, preparing data for diversity analysis.

```R
altExps(alcoholStudy) <-
    splitByRanks(alcoholStudy)
```

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

### Convert Data to Phyloseq Object

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Converts a SummarizedExperiment object to a phyloseq object for downstream analysis. Use this when you need to leverage phyloseq functionalities.

```r
convertToPhyloseq(alcoholStudy, assay.type = "relative_abundance")
```

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

### Prepare Sample Data for Alcohol Study Analysis

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Filters sampleMetadata to include adults (age >= 18) with known alcohol consumption status from stool samples, removing NA metadata columns, and retrieving relative abundance data.

```R
alcoholStudy <-
    filter(sampleMetadata, age >= 18) |>
    filter(!is.na(alcohol)) |>
    filter(body_site == "stool") |>
    select(where(~ !all(is.na(.x)))) |>
    returnSamples("relative_abundance", rownames = "short")
```

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

### Retrieve a Single SummarizedExperiment

Source: https://waldronlab.io/curatedMetagenomicData/index.html

Fetch a specific resource, such as relative abundance data, as a TreeSummarizedExperiment object. Set dryrun = FALSE to retrieve the data. The rownames argument controls the type of row names used.

```r
curatedMetagenomicData("AsnicarF_2017.relative_abundance", dryrun = FALSE, rownames = "short")
```

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

### Display Sample Metadata Table

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Filters and displays the first 10 rows and 10 columns of sample metadata for a specific study, excluding any rows with NA values. Uses the datatable function for interactive display.

```r
sampleMetadata |
    filter(study_name == "AsnicarF_2017") |
    select(where(~ !any(is.na(.x)))) |
    slice(1:10) |
    select(1:10) |
    datatable(options = list(dom = "t"), extensions = "Responsive")
```

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

### Package Citation

Source: https://waldronlab.io/curatedMetagenomicData/authors.html

This is the BibTeX entry for citing the curatedMetagenomicData package and its associated publication. It includes details such as title, authors, journal, volume, pages, and DOI.

```bibtex
@Article{
  title = {Accessible, curated metagenomic data through {ExperimentHub}},
  author = {Edoardo Pasolli and Lucas Schiffer and Paolo Manghi and Audrey Renson and Valerie Obenchain and Duy Tin Truong and Francesco Beghini and Faizan Malik and Marcel Ramos and Jennifer B Dowd and Curtis Huttenhower and Martin Morgan and Nicola Segata and Levi Waldron},
  journal = {Nat. Methods},
  volume = {14},
  number = {11},
  pages = {1023--1024},
  month = {oct},
  year = {2017},
  language = {en},
  issn = {1548-7091, 1548-7105},
  pmid = {29088129},
  doi = {10.1038/nmeth.4468},
  pmc = {PMC5862039},
}
```

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

### Merge Pathway Abundance Data

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Downloads pathway abundance data and merges the resulting list elements into a single SummarizedExperiment object. This function works for every dataType and returns the appropriate data structure.

```r
curatedMetagenomicData("AsnicarF_20.+.pathway_abundance", dryrun = FALSE) |>
    mergeData()
```

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

### Retrieve Relative Abundance Counts

Source: https://waldronlab.io/curatedMetagenomicData/index.html

Fetch relative abundance data as counts by setting counts = TRUE. This multiplies proportions by read depth and rounds to the nearest integer. Multiple resources can be retrieved in a named list.

```r
curatedMetagenomicData("AsnicarF_20.+.relative_abundance", dryrun = FALSE, counts = TRUE, rownames = "short")
```

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

### Calculate and Plot Beta Diversity (UMAP)

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Calculates Uniform Manifold Approximation and Projection (UMAP) coordinates to visualize between-sample diversity. Plots are colored and shaped by alcohol consumption.

```r
alcoholStudy |>
    runUMAP(exprs_values = "relative_abundance", altexp = "genus", name = "UMAP") |>
    plotReducedDim("UMAP", colour_by = "alcohol", shape_by = "alcohol") +
    labs(x = "UMAP 1", y = "UMAP 2") +
    guides(colour = guide_legend(title = "Alcohol"), shape = guide_legend(title = "Alcohol")) +
    theme(legend.position = c(0.90, 0.85))
```

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

### Estimate and Plot Alpha Diversity (Shannon Index)

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Estimates the Shannon diversity index and plots the results, colored and shaped by alcohol consumption. Use this to visualize within-sample diversity differences.

```r
alcoholStudy |>
    estimateDiversity(assay.type = "relative_abundance", index = "shannon") |>
    plotColData(x = "alcohol", y = "shannon", colour_by = "alcohol", shape_by = "alcohol") +
    labs(x = "Alcohol", y = "Alpha Diversity (H')") +
    guides(colour = guide_legend(title = "Alcohol"), shape = guide_legend(title = "Alcohol")) +
    theme(legend.position = "none")
```

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

### Query Available Studies

Source: https://waldronlab.io/curatedMetagenomicData/index.html

Use the curatedMetagenomicData() method to query for available studies. By default, it returns only the titles of matching resources. A regular expression can be used to filter results.

```r
curatedMetagenomicData("AsnicarF_20.+")
```

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

### Merge Marker Abundance Data

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Downloads marker abundance data and merges the resulting list elements into a single SummarizedExperiment object. Use when elements are of the same dataType.

```r
curatedMetagenomicData("AsnicarF_20.+.marker_abundance", dryrun = FALSE) |>
    mergeData()
```

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

### Filter Sample Metadata and Return Relative Abundance in R

Source: https://waldronlab.io/curatedMetagenomicData/reference/returnSamples.html

This snippet filters `sampleMetadata` to include individuals aged 18+, with non-NA alcohol data, and stool body site. It then selects columns without all NA values and retrieves relative abundance data for the filtered samples.

```R
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")
#> 
#> $`2021-10-14.KaurK_2020.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Atopobiaceae|g__Olsenella|s__Olsenella_profusa
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#> $`2021-03-31.KeohaneDM_2020.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#> $`2021-03-31.QinN_2014.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Atopobiaceae|g__Olsenella|s__Olsenella_profusa
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Bacillales|f__Bacillales_unclassified|g__Gemella|s__Gemella_bergeri
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Carnobacteriaceae|g__Granulicatella|s__Granulicatella_elegans
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Firmicutes|c__Erysipelotrichia|o__Erysipelotrichales|f__Erysipelotrichaceae|g__Bulleidia|s__Bulleidia_extructa
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> $`2021-03-31.ThomasAM_2018a.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Atopobiaceae|g__Olsenella|s__Olsenella_profusa
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Bacillales|f__Bacillales_unclassified|g__Gemella|s__Gemella_bergeri
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Carnobacteriaceae|g__Granulicatella|s__Granulicatella_elegans
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Firmicutes|c__Erysipelotrichia|o__Erysipelotrichales|f__Erysipelotrichaceae|g__Bulleidia|s__Bulleidia_extructa
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
#>   k__Bacteria|p__Synergistetes|c__Synergistia|o__Synergistales|f__Synergistaceae|g__Cloacibacillus|s__Cloacibacillus_evryensis
#> $`2021-03-31.XieH_2016.relative_abundance`
#> dropping rows without rowTree matches:
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Atopobiaceae|g__Olsenella|s__Olsenella_profusa
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Collinsella|s__Collinsella_stercoris
#>   k__Bacteria|p__Actinobacteria|c__Coriobacteriia|o__Coriobacteriales|f__Coriobacteriaceae|g__Enorma|s__[Collinsella]_massiliensis
#>   k__Bacteria|p__Firmicutes|c__Bacilli|o__Lactobacillales|f__Carnobacteriaceae|g__Granulicatella|s__Granulicatella_elegans
#>   k__Bacteria|p__Firmicutes|c__Clostridia|o__Clostridiales|f__Ruminococcaceae|g__Ruminococcus|s__Ruminococcus_champanellensis
#>   k__Bacteria|p__Firmicutes|c__Erysipelotrichia|o__Erysipelotrichales|f__Erysipelotrichaceae|g__Bulleidia|s__Bulleidia_extructa
#>   k__Bacteria|p__Proteobacteria|c__Betaproteobacteria|o__Burkholderiales|f__Sutterellaceae|g__Sutterella|s__Sutterella_parvirubra
```

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

### Merge Pathway Abundance Data

Source: https://waldronlab.io/curatedMetagenomicData/reference/mergeData.html

Fetches and merges pathway abundance data for a specified dataset. This operation requires the curatedMetagenomicData package.

```r
curatedMetagenomicData("LiJ_20.+.pathway_abundance", dryrun = FALSE) |>
    mergeData()
#> class: SummarizedExperiment 
#> dim: 27110 456 
#> metadata(0):
#> assays(1): pathway_abundance
#> rownames(27110): UNMAPPED UNINTEGRATED ... PWY-7539:
#>   6-hydroxymethyl-dihydropterin diphosphate biosynthesis III
#>   (Chlamydia)|g__Prevotella.s__Prevotella_buccae LACTOSECAT-PWY:
#>   lactose and galactose degradation
#>   I|g__Escherichia.s__Escherichia_coli
#> rowData names(0):
#> colnames(456): DLF005-IE DLM006-IE ... nHM612836 nHMX11726
#> colData names(28): study_name subject_id ... location smoker
```

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

### Merge Relative Abundance Data with Short Rownames

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Downloads relative abundance data with short row names and merges the resulting list elements into a single TreeSummarizedExperiment object. This is useful for analysis across entire studies.

```r
curatedMetagenomicData("AsnicarF_20.+.relative_abundance", dryrun = FALSE, rownames = "short") |>
    mergeData()
```

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

### returnSamples Function

Source: https://waldronlab.io/curatedMetagenomicData/reference/returnSamples.html

The returnSamples function allows users to retrieve specific data types (e.g., gene families, relative abundance) across studies. It takes a subsetted sampleMetadata data frame and a dataType argument to specify the desired data. Options are available to return raw counts instead of proportions and to customize row names.

```APIDOC
## Function: returnSamples

### Description
Returns samples across studies by utilizing a subsetted sampleMetadata data frame and a specified dataType. It can return either relative abundance proportions or raw counts, and allows customization of row names for relative abundance data.

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

### Arguments

*   **sampleMetadata** (data.frame) - Required. The sampleMetadata data frame subsetted to include only desired samples and metadata.
*   **dataType** (string) - Required. The data type to be returned. Must be one of: "gene_families", "marker_abundance", "marker_presence", "pathway_abundance", "pathway_coverage", "relative_abundance".
*   **counts** (boolean) - Optional. If FALSE (default), relative abundance proportions are returned. If TRUE, relative abundance proportions are multiplied by read depth and rounded to the nearest integer.
*   **rownames** (string) - Optional. The type of rownames to use for "relative_abundance" resources. One of: "long" (default), "short" (species name), or "NCBI" (NCBI Taxonomy ID).

### Value
*   A TreeSummarizedExperiment object is returned when `dataType = "relative_abundance"`.
*   A SummarizedExperiment object is returned for all other `dataType` values.

### Details
This function is designed to retrieve specific data resources across studies. It internally uses `mergeData` and applies its caveats. It is useful for obtaining data for a limited number of samples from potentially large studies.
```

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

### Calculate and Plot Beta Diversity (Bray-Curtis PCoA)

Source: https://waldronlab.io/curatedMetagenomicData/articles/curatedMetagenomicData.html

Calculates Bray-Curtis distances and performs Principal Coordinates Analysis (PCoA) to visualize between-sample diversity. Plots are colored and shaped by alcohol consumption.

```r
alcoholStudy |>
    runMDS(FUN = vegdist, method = "bray", exprs_values = "relative_abundance", altexp = "genus", name = "BrayCurtis") |>
    plotReducedDim("BrayCurtis", colour_by = "alcohol", shape_by = "alcohol") +
    labs(x = "PCo 1", y = "PCo 2") +
    guides(colour = guide_legend(title = "Alcohol"), shape = guide_legend(title = "Alcohol")) +
    theme(legend.position = c(0.90, 0.85))
```

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

### curatedMetagenomicData Function

Source: https://waldronlab.io/curatedMetagenomicData/reference/curatedMetagenomicData.html

The curatedMetagenomicData function allows users to search for and retrieve curated metagenomic data resources. It supports a dry run mode to preview results before fetching the actual data, and options to control the format of returned abundance data.

```APIDOC
## Function: curatedMetagenomicData

### Description
Accesses curated metagenomic data by querying sample metadata. Users can specify a pattern to find resources, control whether to perform a dry run to preview results, and choose how abundance data is returned.

### Usage
```R
curatedMetagenomicData(
  pattern,
  dryrun = TRUE,
  counts = FALSE,
  rownames = "long"
)
```

### Arguments 

*   **pattern** (character) - Regular expression pattern to search for in the titles of available resources. An empty string `""` will return all resources.
*   **dryrun** (logical) - If `TRUE` (default), returns an invisible character vector of resource names. If `FALSE`, returns a `list` of resources.
*   **counts** (logical) - If `FALSE` (default), returns relative abundance proportions. If `TRUE`, relative abundance proportions are multiplied by read depth and rounded to the nearest integer.
*   **rownames** (character) - Specifies the type of `rownames` for `relative_abundance` resources. Options are: `"long"` (default), `"short"` (species name), or `"NCBI"` (NCBI Taxonomy ID).

### Value
*   If `dryrun = TRUE`, an invisible character vector of resource names.
*   If `dryrun = FALSE`, a `list` of resources (SummarizedExperiment and/or TreeSummarizedExperiment objects with corresponding sample metadata).

### Details
Resources are sourced from Bioconductor's ExperimentHub. The function selects the most recent date for a resource if multiple dates are available. For `gene_families` `dataType`, data is stored as a sparse matrix in ExperimentHub, which is optimized for storage and has no practical impact on users.

### See also
`mergeData`, `returnSamples`, `sampleMetadata`
```

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

### Curated Metagenomic Data Function Signature

Source: https://waldronlab.io/curatedMetagenomicData/reference/curatedMetagenomicData.html

The signature for the curatedMetagenomicData function, showing its arguments and default values.

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