---
title: "miaTime: Microbiome Time Series Analysis"
date: "`r Sys.Date()`"
package: 
    miaTime
output: 
    BiocStyle::html_document:
        fig_height: 7
        fig_width: 10
        toc: yes
        toc_depth: 2
        number_sections: true
vignette: >
    %\VignetteIndexEntry{miaTime}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false

library(knitr)
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    cache = TRUE,
    message = FALSE,
    warning = FALSE,
    echo = TRUE
)
```

## Introduction

`miaTime` is a package in the `r BiocStyle::Biocpkg("mia")` family, providing
tools for time series manipulation using the
`r BiocStyle::Biocpkg("TreeSummarizedExperiment")` data container.

## Installation

`miaTime` is hosted on Bioconductor, and can be installed using via
`BiocManager`.

```{r}
#| label: install
#| eval: false

BiocManager::install("miaTime")
```

## Load the package

Once installed, `miaTime` is made available in the usual way.

```{r}
#| label: load_package

library(miaTime)
```

## Divergence between time points

Divergence refers to the quantification of dissimilarity or difference between 
microbiome samples taken at different time points. This concept is crucial for 
tracking how microbial communities change or evolve over time, either in 
individuals or experimental conditions.

### Types of divergence provided

`miaTime` provides several functions for calculating divergences:

 - Baseline divergence: Measures the dissimilarity between each sample and a 
 reference (typically the first time point) within a group (such as per subject).

 - Stepwise (rolling) divergence: Assesses the change between consecutive (or 
 defined interval) time points by comparing each sample to the previous ith
 sample in the series.
 
The divergence is typically calculated using a beta diversity metric, such as 
Bray-Curtis dissimilarity, which quantifies how different two communities are 
in terms of their composition.

For rolling or stepwise divergences, the calculation measures how much the 
community shifts from one sampling point to the next.

### Purpose

Quantifying divergence allows researchers to:

- Track temporal instability or stability of the microbiome.

- Compare change rates between individuals or treatments.

- Identify significant shifts or stable periods in the microbiome composition.

### Practical application

For example, in a human gut microbiome time series, calculating divergence helps 
determine how resistant the microbial ecosystem is to perturbations (such as 
antibiotics or diet changes) and how long it takes to return (if at all) to 
its original state.

Divergences can be calculated with `*Divergence()` functions. In the example
below, for each subject, we calculate the divergence of their samples by
comparing them to the first time point.

```{r}
#| label: base_divergence

data(hitchip1006)
tse <- hitchip1006

res <- getBaselineDivergence(
    tse, time.col = "time", group = "sample", 
    name = c("baseline", "time_diff", "ref_samples"))
res |> head()
```

A more convenient and preferred approach is to store the values directly in
`colData` using the `add*Divergence()` functions. In the example below, we
calculate stepwise divergences with a lag of 1, meaning that for each sample,
the divergence is calculated by comparing it to the previous time point for
the same subject.

```{r}
#| label: time_divergence

tse <- addStepwiseDivergence(tse, time.col = "time")
colData(tse)
```

## Visualize time series

We can visualize time series data with `r BiocStyle::Biocpkg("miaViz")`. Below,
we visualize 5 most abundant taxa.

```{r}
#| label: plot_series

library(miaViz)

p <- plotSeries(tse, assay.type = "counts", 
    time.col = "time", 
    features = getTop(tse, 5), 
    colour.by = "rownames")
p
```

## Session info

```{r}
#| label: session_info

sessionInfo()
```