---
title: "miaDash"
author: 
  - name: Giulio Benedetti
    affiliation: University of Turku
    email: giulio.benedetti@utu.fi
output:
    BiocStyle::html_document:
        fig_height: 7
        fig_width: 10
        toc: true
        toc_float: true
        toc_depth: 2
        number_sections: true
        self_contained: true
        code_folding: show
bibliography: ../inst/REFERENCES.bib
date: "`r doc_date()`"
package: "`r pkg_ver('miaDash')`"
vignette: >
  %\VignetteIndexEntry{miaDash}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

This notebook provides a practical introduction to the Microbiome Analysis
Dashboard (miaDash), an interactive app to analyse and explore microbiome data.
Feel free to try it online at
[this address](miadash-microbiome.2.rahtiapp.fi/) with your data or one of
the ready-to-use example datasets. Here, its usage and functionality are
described in more detail.

## Motivation

Most of the tools available for microbiome data analysis require some knowledge
of programming. This represents a burden for practitioners more interested
in getting results than learning how to program. To this end, miaDash aims to
make microbiome analysis accessible to anyone who needs it, with or without any
computational skills.

As a word of caution, while the app removes the burden of programming, it is
still critical to understand the nature of microbiome data and how it can be
analysed. Such knowledge can be acquired from the online book [Orchestrating
Microbiome Analysis](https://microbiome.github.io/OMA/) (OMA) and several other
independent resources. The following section presents what is currently possible
in the app.

## Interface

The interface is divided into five tabs that reflect the steps of a typical
microbiome analysis pipeline. First, the dataset of interest can be uploaded
through the Import tab, where several data types and file formats are supported.
Alternatively, one of the available example datasets can be used for practice.
Second, a set of operations can be applied to the dataset through the
Manipulate tab, which include methods for subsetting features by prevalence,
agglomerating by taxonomic level and transforming assays. Third, the dataset
can be analysed through the Estimate tab, which provide common techniques to
quantify alpha and beta diversity. Finally, results can be explored through the
Visualise tab, where an interactive explorer can be launched with a customisable
set of panels that illustrate different aspects of the data. The full catalogue
of available panels can be found
[here](https://microbiome.github.io/iSEEtree/articles/panels.html).

# Tutorial

The app can be used online or locally, depending on resource availability and
size of the dataset to analyse. In general, the online version is freely
available, so that data of any type can be tested there. However, running the
app locally might be a better option for larger datasets (> 1000 features). In
this case, you may also consider subsetting and/or agglomerating the data.

## Installation

If you decided to run the app locally, make sure to have R installed in your
machine and execute the following command:

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

BiocManager::install("miaDash")
```

Once the package is successfully installed, you should have access to the
development version of miaDash.

## Example

This section shows how to get started with miaDash. If you are using it locally,
run the next code chunk to launch the app. Otherwise, you can skip it.

```{r start, message=FALSE, warning=FALSE}
# Import miaDash
library(miaDash)

# Launch miaDash
if (interactive()) {
  miaDash()
}
```

```{r screenfun, eval=!exists("SCREENSHOT"), include=FALSE}
SCREENSHOT <- function(x, ...) knitr::include_graphics(x)
```

As described in Section [1.2](#interface), The dashboard consists of five
different windows with tools to import, manipulate, analyse and visualise
the dataset of choice. After launching the app, it appears as follows:

```{r screenplot1, echo=FALSE, out.width="100%"}
SCREENSHOT("screenshots/dashboard.png", delay = 20)
```

At first, the variety of options might feel intimidating, so you can click on
the question mark on the top right to receive a short tour of the windows
available in the app.

Once the dataset was imported and analysed according to your objective, you can
choose which visualisations to use from the Visualise window and press the
button "Launch iSEEtree" to create and customise the plots. After adjusting the
parameters of the different panels, the app might look something like this:

```{r screenplot2, echo=FALSE, out.width="100%"}
SCREENSHOT("screenshots/iSEEtree.png", delay = 20)
```

As before, you can click on the question mark on the top right to receive a tour
of the panels and their parameters. The best way to get familiar with the
interface is to experiment with the parameters below each panel.

# Resources

## Citation

We hope that miaDash will be useful for your research. Please use the following
information to cite the package and the overall approach. Thank you!

```{r citation}
## Citation info
citation("miaDash")
```

## Background Knowledge

miaDash originates from the joint effort of the R/Bioconductor community. It is
mainly based on the following software:

- [R](https://www.r-project.org/), statistical programming language [@core2024r]
- [mia](https://bioconductor.org/packages/release/bioc/html/mia.html), framework for microbiome data analysis [@borman2024mia]
- [iSEEtree](https://bioconductor.org/packages/release/bioc/html/iSEEtree.html), TreeSummarizedExperiment interactive explorer [@benedetti2024iseetree]
- [iSEE](https://bioconductor.org/packages/release/bioc/html/iSEE.html), SummarizedExperiment interactive explorer [@rue2018isee]
- [TreeSummarizedExperiment](https://bioconductor.org/packages/release/bioc/html/TreeSummarizedExperiment.htmlm), S4 container for hierarchical data [@huang2020treesummarizedexperiment]
- [shiny](https://cran.r-project.org/web/packages/shiny/index.html), web app development in R [@chang2024shiny]

## Help

You can reach us by one of the communication channels listed
[here](https://microbiome.github.io/OMA/docs/devel/pages/support.html). We are
happy to receive questions, suggestions as well as contributions. For the last
point, check the
[contributor guidelines](https://microbiome.github.io/mia/CONTRIBUTING.html).

# Reproducibility

R session information:

```{r reproduce, echo=FALSE}
# Session info
options(width = 120)
sessionInfo()
```

# References