---
title: "iSEEtree: interactive explorer for hierarchical data"
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('iSEEtree')`"
vignette: >
    %\VignetteIndexEntry{iSEEtree}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

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

# Introduction

## Motivation

iSEEtree is a Bioconductor package for the interactive visualisation of
hierarchical data stored in a TreeSummarizedExperiment (TreeSE) container. On
the one side, it leverages and extends the graphics of the iSEE package, which
is designed for the generic SummarizedExperiment class. On the other side, it
employs the statistical and visual tools for microbiome data science provided by
the mia family of packages. Thus, iSEE and mia represent the two building blocks
of iSEEtree. Detailed introductory material on these two frameworks is available
in the [iSEE-verse website](https://isee.github.io/) and the
[OMA Bioconductor book](https://microbiome.github.io/OMA/docs/devel/),
respectively.

iSEEtree is meant for new and experienced users alike, who desire to create and
interact with several graphics for hierarchical data, without the need for an
in-depth knowledge of the underlying mia functionality. Current panels include
compositional plots, ordination graphs and structural tree or networks, which
are further discussed in the current article and in the
[online package documentation](https://microbiome.github.io/iSEEtree/).
Other more generic panels are also inherited from the parent package iSEE and
its many extensions.

## Panels

iSEEtree derives its microbiome-related visualisation methods from the
[miaViz](https://microbiome.github.io/miaViz/) package, which is code-based and
requires basic knowledge of R programming and microbiome data structures. The
panels provided represent an easy-to-use interactive version of most miaViz
plotting functions. They allow to visualise several aspects of hierarchical data
by three general approaches: compositional, ordination and structural analysis.

### Compositional Analysis

These panels can be used to explore sample composition and feature prevalence
or abundance across samples. This topic is further discussed in the OMA chapter
on [Community Composition](https://microbiome.github.io/OMA/docs/devel/pages/composition.html).

- [AbundancePlot](https://microbiome.github.io/iSEEtree/reference/AbundancePlot.html):
  a compositional barplot of the samples, where every bar is a sample composed
  by different features in different colours.
- [AbundanceDensityPlot](https://microbiome.github.io/iSEEtree/reference/AbundanceDensityPlot.html):
  a density plot of the top features, where every line is a feature and the x
  axis shows its abundance for different samples.
- PrevalencePlot: coming soon!

### Ordination Analysis

These panels show the results of ordination analyses or dimensionality reduction
methods applied to the assay data, both in terms of reduced components as well
as explained variance and feature importance. This topic is further discussed in
the OMA chapter on
[Community Similarity](https://microbiome.github.io/OMA/docs/devel/pages/20_beta_diversity.html).

- [RDAPlot](https://microbiome.github.io/iSEEtree/reference/RDAPlot.html): an
  supervised ordination plot of the samples, where every dot is a sample on a
  reduced dimensional space and every arrow reflects the contribution of a
  sample variable.
- [LoadingPlot](https://microbiome.github.io/iSEEtree/reference/LoadingPlot.html):
  a heatmap or barplot of the loadings or contributions of each feature to the
  reduced dimensions of PCA, PCoA or another ordination method.
- [ScreePlot](https://microbiome.github.io/iSEEtree/reference/LoadingPlot.html):
  a barplot of the contributions of each reduced dimension component to the
  explained variance.

### Structural Analysis

The structure or organisation of hierarchical data can be explored with the
tree and network visualisations that provide a holistic picture of the
structured relationships across features or samples. This topic is further
discussed in the OMA chapters on
[Exploration](https://microbiome.github.io/OMA/docs/devel/pages/quality_control.html) and
[Networks](https://microbiome.github.io/OMA/docs/devel/pages/network_learning.html).

- [RowTreePlot](https://microbiome.github.io/iSEEtree/reference/RowTreePlot.html):
  a phylogenetic tree of the features, where every tip is a feature and two
  neighbouring tips are more closely related than two far apart from each other.
- [ColumnTreePlot](https://microbiome.github.io/iSEEtree/reference/ColumnTreePlot.html):
  the hierarchical organisation of the samples, where every tip is a sample and
  the closer the more related they are.
- [RowGraphPlot](https://microbiome.github.io/iSEEtree/reference/RowGraphPlot.html):
  the network organisation of the features, where every node is a feature and
  edges reflect the degree of connection between features.
- [ColumnGraphPlot](https://microbiome.github.io/iSEEtree/reference/ColumnGraphPlot.html):
  the network organisation of the samples, where every node is a sample and
  edges reflect the degree of connection between samples.

### Other Panels

By default, the iSEEtree layout also includes the following panels inherited by
iSEE:

- [RowDataTable](https://isee.github.io/iSEE/articles/basic.html#row-data-tables)
- [ColumnDataTable](https://isee.github.io/iSEE/articles/basic.html#column-data-tables)
- [ReducedDimensionPlot](https://isee.github.io/iSEE/articles/basic.html#reduced-dimension-plots)
- [ComplexHeatmapPlot](https://isee.github.io/iSEE/articles/basic.html#heat-maps)

The [ColumnDataPlot](https://isee.github.io/iSEE/articles/basic.html#coldataplot)
could also prove useful for the visualisation of column variables such as
alpha diversity indices. Its interpretation is explained in the OMA chapter on
[Community Diversity](https://microbiome.github.io/OMA/docs/devel/pages/14_alpha_diversity.html).

For more information on the available panels, users are directed to the
[iSEEtree panel catalogue](https://microbiome.github.io/iSEEtree/articles/panels.html)
in the main package documentation.

# Tutorial

## Installation

R is an open-source statistical environment which can be easily modified to
enhance its functionality via packages. iSEEtree is an R package available on
[Bioconductor](https://bioconductor.org/). R can be installed on any operating
system from [CRAN](https://cran.r-project.org/) after which you can install
iSEEtree by using the following commands in your R session:

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

BiocManager::install("iSEEtree")
```

## Example

The panels described above can be generated for a model TreeSE object in the
following example:

```{r start, message=FALSE, warning=FALSE}
library(iSEEtree)
library(mia)
library(scater)

# Import TreeSE
data("Tengeler2020", package = "mia")
tse <- Tengeler2020

# Add relabundance assay
tse <- transformAssay(tse, method = "relabundance")

# Add reduced dimensions
tse <- runMDS(tse, assay.type = "relabundance")

# Launch iSEE
if (interactive()) {
  iSEE(tse)
}
```

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

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

# Resources

## Open datasets

TreeSE objects can be constructed from raw data and standardised file formats.
However, several packages provide access to demonstration datasets used to
familiarise with the use of TreeSE objects. A complete list of resources is
available in the OMA chapter on
[Data Import](https://microbiome.github.io/OMA/docs/devel/pages/import.html#sec-example-data).

In addition, we provide the Microbiome Analysis Dashboard (miaDash), a web app
based on iSEEtree that offers a complete interface to import, analyse and
visualise microbiome data, or to easily access mia datasets for experimentation
purposes. The app is hosted online at
[this address](https://miadash-microbiome.2.rahtiapp.fi/) by the Finnish IT
Center for Science (CSC).

## Other tutorials

Users interested in general topics about the iSEE interface are redirected to
the [documentation](https://isee.github.io/iSEE) of the iSEE parent package,
which provides ideas and solutions on how to:

- use iSEE with big data
- configure iSEE apps
- deploy custom panels
- share information across panels
- control the interface with speech

## Citation

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

```{r citation}
citation("iSEEtree")
```

## Acknowledgements

iSEEtree 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]
- [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 [@huang2021treesummarizedexperiment]
- [shiny](https://cran.r-project.org/web/packages/shiny/index.html), web app development in R [@chang2024shiny]

If you are asking yourself the question “Where do I start using Bioconductor?”
you might be interested in
[this blog post](https://lcolladotor.github.io/2014/10/16/startbioc/#.VkOKbq6rRuU).

## Help

As package developers, we try to explain clearly how to use our packages and in
which order to use the functions. But R and Bioconductor have a steep learning
curve so it is critical to learn where to ask for help. The blog post quoted
above mentions some but we would like to highlight the
[Bioconductor support site](https://support.bioconductor.org/) as the main
resource for getting help: remember to use the iSEEtree tag and check the
[older posts](https://support.bioconductor.org/t/iSEEtree/). Other alternatives
are available such as creating GitHub issues and tweeting. However, please note
that if you want to receive help you should adhere to the
[posting guidelines](https://www.bioconductor.org/help/support/posting-guide/).
It is particularly critical that you provide a small reproducible example and
your session information so package developers can track down the source of the
error.

# Reproducibility

R session information:

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

# References
