--- 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