Date: 2026-04-28

# miaTime: Microbiome Time Series Analysis

#### 2026-04-28

#### Package

miaTime

# Contents

## 1 Introduction

`miaTime` is a package in the mia family, providing tools for time series manipulation using the TreeSummarizedExperiment data container.

## 2 Installation

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

    BiocManager::install("miaTime")

## 3 Load the package

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

    library(miaTime)

## 4 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.

### 4.1 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.

### 4.2 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.

### 4.3 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.

    data(hitchip1006)
    tse <- hitchip1006

    res <- getBaselineDivergence(
        tse, time.col = "time", group = "sample",
        name = c("baseline", "time_diff", "ref_samples"))
    res |> head()
    #> DataFrame with 6 rows and 3 columns
    #>           baseline time_diff ref_samples
    #>          <numeric> <numeric> <character>
    #> Sample-1         0         0    Sample-1
    #> Sample-2         0         0    Sample-2
    #> Sample-3         0         0    Sample-3
    #> Sample-4         0         0    Sample-4
    #> Sample-5         0         0    Sample-5
    #> Sample-6         0         0    Sample-6

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.

    tse <- addStepwiseDivergence(tse, time.col = "time")
    colData(tse)
    #> DataFrame with 1151 rows and 13 columns
    #>                   age      sex nationality DNA_extraction_method  project
    #>             <integer> <factor>    <factor>              <factor> <factor>
    #> Sample-1           28   male            US                    NA        1
    #> Sample-2           24   female          US                    NA        1
    #> Sample-3           52   male            US                    NA        1
    #> Sample-4           22   female          US                    NA        1
    #> Sample-5           25   female          US                    NA        1
    #> ...               ...      ...         ...                   ...      ...
    #> Sample-1168        50   female Scandinavia                     r       40
    #> Sample-1169        31   female Scandinavia                     r       40
    #> Sample-1170        31   female Scandinavia                     r       40
    #> Sample-1171        52   male   Scandinavia                     r       40
    #> Sample-1172        52   male   Scandinavia                     r       40
    #>             diversity   bmi_group  subject      time      sample divergence
    #>             <numeric>    <factor> <factor> <numeric> <character>  <numeric>
    #> Sample-1         5.76 severeobese        1         0    Sample-1         NA
    #> Sample-2         6.06 obese              2         0    Sample-2         NA
    #> Sample-3         5.50 lean               3         0    Sample-3         NA
    #> Sample-4         5.87 underweight        4         0    Sample-4         NA
    #> Sample-5         5.89 lean               5         0    Sample-5         NA
    #> ...               ...         ...      ...       ...         ...        ...
    #> Sample-1168      5.87 severeobese      244       8.1 Sample-1168   0.479394
    #> Sample-1169      5.87 overweight       245       2.3 Sample-1169   0.356508
    #> Sample-1170      5.92 overweight       245       8.2 Sample-1170   0.434298
    #> Sample-1171      6.04 overweight       246       2.1 Sample-1171   0.403581
    #> Sample-1172      5.74 overweight       246       7.9 Sample-1172   0.485427
    #>             time_diff                             ref_samples
    #>             <numeric>                                  <list>
    #> Sample-1           NA                                      NA
    #> Sample-2           NA                                      NA
    #> Sample-3           NA                                      NA
    #> Sample-4           NA                                      NA
    #> Sample-5           NA                                      NA
    #> ...               ...                                     ...
    #> Sample-1168       0.2                             Sample-1172
    #> Sample-1169       0.2                             Sample-1171
    #> Sample-1170       0.1                 Sample-1127,Sample-1168
    #> Sample-1171       0.7 Sample-1016,Sample-1022,Sample-1027,...
    #> Sample-1172       0.1                             Sample-1162

## 5 Visualize time series

We can visualize time series data with miaViz. Below, we visualize 5 most abundant taxa.

    library(miaViz)

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

## 6 Session info

    sessionInfo()
    #> R version 4.6.0 Patched (2026-04-24 r89963)
    #> Platform: aarch64-apple-darwin23
    #> Running under: macOS Tahoe 26.3.1
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> time zone: America/New_York
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats4    stats     graphics  grDevices utils     datasets  methods
    #> [8] base
    #>
    #> other attached packages:
    #>  [1] miaViz_1.20.0                   ggraph_2.2.2
    #>  [3] ggplot2_4.0.3                   miaTime_1.2.0
    #>  [5] mia_1.20.0                      TreeSummarizedExperiment_2.20.0
    #>  [7] Biostrings_2.80.0               XVector_0.52.0
    #>  [9] SingleCellExperiment_1.34.0     MultiAssayExperiment_1.38.0
    #> [11] SummarizedExperiment_1.42.0     Biobase_2.72.0
    #> [13] GenomicRanges_1.64.0            Seqinfo_1.2.0
    #> [15] IRanges_2.46.0                  S4Vectors_0.50.0
    #> [17] BiocGenerics_0.58.0             generics_0.1.4
    #> [19] MatrixGenerics_1.24.0           matrixStats_1.5.0
    #> [21] knitr_1.51                      BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>   [1] RColorBrewer_1.1-3          jsonlite_2.0.0
    #>   [3] magrittr_2.0.5              magick_2.9.1
    #>   [5] ggbeeswarm_0.7.3            farver_2.1.2
    #>   [7] rmarkdown_2.31              fs_2.1.0
    #>   [9] vctrs_0.7.3                 memoise_2.0.1
    #>  [11] DelayedMatrixStats_1.34.0   ggtree_4.2.0
    #>  [13] tinytex_0.59                htmltools_0.5.9
    #>  [15] S4Arrays_1.12.0             BiocNeighbors_2.6.0
    #>  [17] janeaustenr_1.0.0           SparseArray_1.12.0
    #>  [19] gridGraphics_0.5-1          sass_0.4.10
    #>  [21] bslib_0.10.0                tokenizers_0.3.0
    #>  [23] htmlwidgets_1.6.4           plyr_1.8.9
    #>  [25] DECIPHER_3.8.0              cachem_1.1.0
    #>  [27] igraph_2.3.0                lifecycle_1.0.5
    #>  [29] pkgconfig_2.0.3             rsvd_1.0.5
    #>  [31] Matrix_1.7-5                R6_2.6.1
    #>  [33] fastmap_1.2.0               tidytext_0.4.3
    #>  [35] digest_0.6.39               aplot_0.2.9
    #>  [37] ggnewscale_0.5.2            patchwork_1.3.2
    #>  [39] scater_1.40.0               irlba_2.3.7
    #>  [41] SnowballC_0.7.1             vegan_2.7-3
    #>  [43] beachmat_2.28.0             labeling_0.4.3
    #>  [45] polyclip_1.10-7             abind_1.4-8
    #>  [47] mgcv_1.9-4                  compiler_4.6.0
    #>  [49] fontquiver_0.2.1            withr_3.0.2
    #>  [51] S7_0.2.2                    BiocParallel_1.46.0
    #>  [53] viridis_0.6.5               DBI_1.3.0
    #>  [55] ggforce_0.5.0               MASS_7.3-65
    #>  [57] rappdirs_0.3.4              DelayedArray_0.38.0
    #>  [59] bluster_1.22.0              permute_0.9-10
    #>  [61] tools_4.6.0                 vipor_0.4.7
    #>  [63] otel_0.2.0                  beeswarm_0.4.0
    #>  [65] ape_5.8-1                   glue_1.8.1
    #>  [67] nlme_3.1-169                grid_4.6.0
    #>  [69] cluster_2.1.8.2             reshape2_1.4.5
    #>  [71] gtable_0.3.6                tidyr_1.3.2
    #>  [73] BiocSingular_1.28.0         tidygraph_1.3.1
    #>  [75] ScaledMatrix_1.20.0         ggrepel_0.9.8
    #>  [77] pillar_1.11.1               stringr_1.6.0
    #>  [79] yulab.utils_0.2.4           splines_4.6.0
    #>  [81] dplyr_1.2.1                 tweenr_2.0.3
    #>  [83] treeio_1.36.0               lattice_0.22-9
    #>  [85] tidyselect_1.2.1            DirichletMultinomial_1.54.0
    #>  [87] fontLiberation_0.1.0        scuttle_1.22.0
    #>  [89] fontBitstreamVera_0.1.1     gridExtra_2.3
    #>  [91] bookdown_0.46               xfun_0.57
    #>  [93] graphlayouts_1.2.3          stringi_1.8.7
    #>  [95] lazyeval_0.2.3              ggfun_0.2.0
    #>  [97] yaml_2.3.12                 evaluate_1.0.5
    #>  [99] codetools_0.2-20            gdtools_0.5.0
    #> [101] tibble_3.3.1                BiocManager_1.30.27
    #> [103] ggplotify_0.1.3             cli_3.6.6
    #> [105] systemfonts_1.3.2           jquerylib_0.1.4
    #> [107] dichromat_2.0-0.1           Rcpp_1.1.1-1.1
    #> [109] parallel_4.6.0              ecodive_2.2.6
    #> [111] sparseMatrixStats_1.24.0    decontam_1.32.0
    #> [113] viridisLite_0.4.3           tidytree_0.4.7
    #> [115] ggiraph_0.9.6               scales_1.4.0
    #> [117] purrr_1.2.2                 crayon_1.5.3
    #> [119] rlang_1.2.0