---
title: "HuMMANet"
author: "Nalin Arora, Shivangi Verma"
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
vignette: >
  %\VignetteIndexEntry{HuMMANet}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

if (!requireNamespace("HuMMANet", quietly = TRUE)) {
  stop("Package 'HuMMANet' must be installed to render this vignette.")
}
```

## Introduction

`HuMMANet` is a Bioconductor experiment data package for paired human
microbiome-metabolome studies. It provides a unified interface to curated
study-level species profiles, original and harmonized metabolite profiles,
matched sample metadata, and study-specific annotation resources, with study
data distributed through `ExperimentHub`.

The central motivation for the package is to provide a reusable resource for
paired study species and metabolite data together with supporting annotations,
so that users can work with these studies in a consistent and reproducible way.
Rather than manually assembling heterogeneous files from individual studies,
users can access matched tables and annotation resources through a common API in
the Bioconductor ecosystem.

Typical use cases for `HuMMANet` include:

- loading matched microbiome and metabolome data for a single study without
  manually reconciling sample identifiers
- comparing harmonized metabolite profiles across multiple studies
- linking quantitative metabolite features to identifier mappings, pathway
  annotations, disease associations, microbial producer annotations, and drug
  similarity resources
- extracting assay matrices and sample metadata for downstream statistical or
  machine learning workflows

Each study bundle can include the following modalities:

- `MetadataProfile`: sample-level study metadata, including sample identifiers,
  subject or participant annotations, clinical covariates, longitudinal labels,
  body site information, and other variables needed to interpret the study.
- `taxaAbundanceProfile`: the curated microbial abundance table for a study,
  aligned to the study samples and representing taxa or related microbial
  features.
- `OriginalMetaboliteProfile`: the curated metabolomics matrix prior to
  HuMMANet harmonization, preserving the original study-specific metabolite
  feature space.
- `harmonizedMetaboliteProfile`: the HuMMANet-processed metabolomics matrix
  after harmonization, designed to support more consistent comparisons across
  studies.
- `metaboliteIdentifierMapping`: metabolite identifier mapping tables that link
  HuMMANet identifiers to external resources such as HMDB, PubChem, KEGG,
  ChEBI, structural descriptors, and standardized metabolite names.
- `microbialProducerAnnotations`: curated annotations linking metabolites to
  potential microbial producers or species-level producer evidence.
- `metaboliteDiseaseAssociations`: curated disease associations for metabolites
  represented in a study.
- `metabolitePathwayAnnotations`: curated pathway annotations for study
  metabolites.
- `drugBankSimilarityMatches`: DrugBank similarity matches for study
  metabolites.
- `drugCentralSimilarityMatches`: DrugCentral similarity matches for study
  metabolites.

Each study is represented as a `MultiAssayExperiment` object:

- `colData()` stores the `MetadataProfile`
- `experiments()` stores assay-level containers for
  `taxaAbundanceProfile`, `OriginalMetaboliteProfile`, and
  `harmonizedMetaboliteProfile`
- long-form annotation tables are attached in `metadata()`

This representation is useful because it keeps the paired modalities for a
study synchronized through a shared sample-level metadata table while still
allowing each assay to preserve its own feature space and feature annotations.
For example, microbial taxa and metabolites do not share the same rows, but
they do share the same study samples. `MultiAssayExperiment` is designed
exactly for this setting.

Within each study object:

- `taxaAbundanceProfile` is stored as a `SummarizedExperiment` containing a
  taxa-by-sample abundance matrix.
- `OriginalMetaboliteProfile` is stored as a `SummarizedExperiment` containing
  the original curated metabolite feature table for the study.
- `harmonizedMetaboliteProfile` is stored as a `SummarizedExperiment`
  containing the harmonized metabolite table together with feature-level
  identifier annotations in `rowData()`.
- long-form annotation resources such as pathway, disease, microbial producer,
  and drug similarity tables are attached in `metadata()` because they are
  annotation tables rather than sample-by-feature assay matrices.

The package is structured as a lightweight `ExperimentHub` interface package.
Large study bundles live outside the source tarball, while the package ships
the accessor functions, metadata, and documentation needed to discover and load
those resources reproducibly.

## Installation

Install from Bioconductor:

```{r install-bioc, eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("HuMMANet")
```

Install the development version from GitHub:

```{r install-github, eval = FALSE}
if (!requireNamespace("remotes", quietly = TRUE)) {
    install.packages("remotes")
}
remotes::install_github("ShivangiV-IIITD/HuMMANet")
```

## Load the package

```{r load-packages}
library(HuMMANet)
library(MultiAssayExperiment)
library(SummarizedExperiment)
```


## Discover available studies

```{r list-studies}
studies <- HuMMANet_studies()
length(studies)
head(studies)
```

The study identifiers returned by `HuMMANet_studies()` are the main entry points
for downstream loading. These identifiers are also present in the study index,
which can be used to inspect available modalities before loading a full study
object.

## Inspect the study index

```{r study-index}
idx <- HuMMANet_study_index()
head(
  idx[, c(
    "study",
    "has_MetadataProfile",
    "has_taxaAbundanceProfile",
    "has_OriginalMetaboliteProfile",
    "has_harmonizedMetaboliteProfile"
  )]
)
```

The study index provides one row per study. In addition to the study identifier,
it records availability flags and file-level information for the metadata,
species, original metabolite, harmonized metabolite, and annotation resources.
This is useful when deciding which studies and which data layers to retrieve
for a particular analysis.

The study-loading examples below illustrate the intended user workflow through
the package accessors.

## Load one study

```{r load-study}
study_id <- idx$study[[1]]
available <- HuMMANet_available_modalities(
  study_id
)
available

one_study <- HuMMANet_load_study(
  study_id
)
class(one_study)
names(experiments(one_study))
colData(one_study)[1:3, 1:6]
```

At this point `one_study` is a `MultiAssayExperiment`. The assay names returned
by `experiments(one_study)` correspond to the core quantitative data layers,
while `colData(one_study)` contains the matched sample metadata shared across
those assays.

## Inspect the study structure

```{r inspect-structure}
experiments(one_study)
sampleMap(one_study)
```

`experiments(one_study)` lists the assay-level objects stored in the study.
Each of these is a `SummarizedExperiment`, so standard Bioconductor accessors
such as `assay()`, `rowData()`, and `colData()` can be used on the individual
assays. `sampleMap(one_study)` records how assay-level columns map back to the
shared study-level sample metadata.

## Load the study metadata

```{r load-metadata}
metadata_profile <- HuMMANet_load_modality(
  study_id,
  "MetadataProfile"
)
dim(metadata_profile)
head(metadata_profile[, seq_len(min(6, ncol(metadata_profile)))])
```

This is equivalent to inspecting `as.data.frame(colData(one_study))`, but the
modality accessor is convenient when you want the metadata table directly for
custom joins or downstream analysis.

## Inspect the original metabolite profile

```{r original-profile}
original_profile <- HuMMANet_load_modality(
  study_id,
  "OriginalMetaboliteProfile"
)
class(original_profile)
dim(assay(original_profile))
head(rownames(original_profile))
head(colnames(original_profile))
```

The quantitative assay matrix is accessed with `assay(original_profile)`. As in
all `SummarizedExperiment` objects, rows correspond to features and columns
correspond to samples. This makes it straightforward to extract the original
study-specific metabolite matrix while preserving its feature identities.

## Load the harmonized metabolite profile

```{r harmonized-profile}
harmonized_profile <- HuMMANet_load_modality(
  study_id,
  "harmonizedMetaboliteProfile"
)
class(harmonized_profile)
dim(assay(harmonized_profile))
head(
  rowData(harmonized_profile)[, seq_len(min(6, ncol(rowData(harmonized_profile))))]
)
```

The harmonized metabolite profile is especially useful for cross-study
comparison because the feature layer is paired with identifier-level annotation
in `rowData(harmonized_profile)`. This allows users to inspect harmonized
metabolite identifiers, names, and external database mappings alongside the
quantitative matrix.

## Inspect the taxa abundance profile

```{r taxa-profile}
taxa_profile <- HuMMANet_load_modality(
  study_id,
  "taxaAbundanceProfile"
)
class(taxa_profile)
dim(assay(taxa_profile))
head(rownames(taxa_profile))
head(colnames(taxa_profile))
```

This assay stores the microbial feature abundance matrix for the study. Because
it is also represented as a `SummarizedExperiment`, it can be handled with the
same accessors as the metabolite assays, which keeps the study workflow
consistent across modalities.

## Load an annotation table

```{r pathway-annotations}
pathway_annotations <- HuMMANet_load_modality(
  study_id,
  "metabolitePathwayAnnotations"
)
dim(pathway_annotations)
head(pathway_annotations[, seq_len(min(6, ncol(pathway_annotations)))])
```

Unlike the assay modalities, annotation resources such as pathways, diseases,
microbial producer annotations, and drug similarity matches are long-form
tables. They are returned as `data.frame` objects because they are naturally
represented as annotations rather than sample-by-feature matrices.

## Inspect study-level annotation metadata

```{r study-metadata-slot}
names(metadata(one_study))
```

The `metadata()` slot of the study object stores the annotation resources that
were requested during loading. This is helpful when you want to keep the study
object intact and access all associated annotation layers from a single
container instead of managing separate tables manually.

## Extract assay matrices for downstream analysis

```{r assay-matrices}
harm_mat <- assay(harmonized_profile)
taxa_mat <- assay(taxa_profile)

dim(harm_mat)
dim(taxa_mat)
```

These extracted matrices can be used directly in downstream workflows for
ordination, association testing, machine learning, or other custom analyses.
The companion `rowData()` and `colData()` accessors preserve the feature-level
and sample-level context required for reproducible analysis.

## Subset a study object

```{r subset-study}
sample_keep <- rownames(colData(one_study))[seq_len(min(5, nrow(colData(one_study))))]
study_subset <- one_study[, sample_keep]

study_subset
```

Subsetting a `MultiAssayExperiment` by columns subsets the shared sample space
and keeps the assay-level containers synchronized. This is one of the main
advantages of using standard Bioconductor containers for paired multi-omics
data, because users do not need to manually subset each assay and metadata
table separately.

## Load multiple studies and modalities

```{r multiple-studies}
selected_studies <- studies[seq_len(min(2, length(studies)))]
multi <- HuMMANet(
    studies = selected_studies,
    modalities = c("MetadataProfile", "OriginalMetaboliteProfile")
)

names(multi)
class(multi[[1]])
names(experiments(multi[[1]]))
```

The top-level `HuMMANet()` convenience function returns a named list of
study-level `MultiAssayExperiment` objects. This is useful when iterating across
multiple studies while preserving the same container structure for each one.

## Session information

```{r session-info}
sessionInfo()
```