From 5d2eb15ada7f4e6bd74e36fb180e4c50de219f8f Mon Sep 17 00:00:00 2001 From: Giulio Benedetti Date: Thu, 13 Mar 2025 22:11:45 +0200 Subject: [PATCH 1/5] Reorganise utils --- NAMESPACE | 2 ++ R/iSEE-default.R | 35 ++------------------- R/utils.R | 73 ++++++++++++++++++++++++++++++++++++++++++++ man/utils.Rd | 43 ++++++++++++++++++++++++++ pkgdown/_pkgdown.yml | 1 + 5 files changed, 121 insertions(+), 33 deletions(-) create mode 100644 R/utils.R create mode 100644 man/utils.Rd diff --git a/NAMESPACE b/NAMESPACE index f1b0733..e4f6544 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,7 @@ # Generated by roxygen2: do not edit by hand +export(.check_all_panels) +export(.check_panel) export(AbundanceDensityPlot) export(AbundancePlot) export(ColumnGraphPlot) diff --git a/R/iSEE-default.R b/R/iSEE-default.R index a48e8fc..4b85126 100644 --- a/R/iSEE-default.R +++ b/R/iSEE-default.R @@ -51,12 +51,6 @@ setGeneric("iSEE", iSEE::iSEE) #' @export #' @importFrom iSEE createLandingPage ExperimentColorMap ReducedDimensionPlot #' ComplexHeatmapPlot RowDataTable ColumnDataTable -#' @importFrom TreeSummarizedExperiment TreeSummarizedExperiment rowLinks -#' colLinks -#' @importFrom SingleCellExperiment reducedDims -#' @importFrom S4Vectors metadata -#' @importFrom SummarizedExperiment rowData colData -#' @importFrom mia taxonomyRanks setMethod("iSEE", "TreeSummarizedExperiment", function(se, initial = c(RowDataTable(), ColumnDataTable(), RowTreePlot(), AbundancePlot(), AbundanceDensityPlot(), ReducedDimensionPlot(), @@ -64,35 +58,10 @@ setMethod("iSEE", "TreeSummarizedExperiment", landingPage = createLandingPage(), tour = NULL, appTitle = NULL, runLocal = TRUE, voice = FALSE, bugs = FALSE, saveState = NULL, ...) { - initial <- .check_panel(se, initial, "RowDataTable", rowData) - initial <- .check_panel(se, initial, "ColumnDataTable", colData) - initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) - initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) - initial <- .check_panel(se, initial, "AbundancePlot", taxonomyRanks) - initial <- .check_panel(se, initial, "ReducedDimensionPlot", reducedDims) - initial <- .check_panel(se, initial, "LoadingPlot", reducedDims) - initial <- .check_panel(se, initial, "ScreePlot", reducedDims) - initial <- .check_panel(se, initial, "RDAPlot", reducedDims) - initial <- .check_panel(se, initial, "RowGraphPlot", metadata) - initial <- .check_panel(se, initial, "ColumnGraphPlot", metadata) + initial <- .check_all_panels(se, initial) iSEE::iSEE(se, initial = initial, extra = initial, colormap = colormap, landingPage = landingPage, tour = tour, appTitle = appTitle, runLocal = runLocal, voice = voice, bugs = bugs, saveState = saveState, ...) -}) - -#' @importFrom S4Vectors isEmpty -#' @importFrom methods is -.check_panel <- function(se, panel_list, panel_class, panel_fun, wtext) { - - no_keep <- unlist(lapply(panel_list, function(x) is(x, panel_class))) - - if( any(no_keep) && (is.null(panel_fun(se)) || isEmpty(panel_fun(se))) ){ - panel_list <- panel_list[!no_keep] - warning("no valid ", as.character(substitute(panel_fun)), - " fields for ", panel_class, call. = FALSE) - } - - return(panel_list) -} \ No newline at end of file +}) \ No newline at end of file diff --git a/R/utils.R b/R/utils.R new file mode 100644 index 0000000..234c171 --- /dev/null +++ b/R/utils.R @@ -0,0 +1,73 @@ +#' iSEEtree utils +#' +#' Utility functions to check the existence of specific elements in a +#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} +#' that are compulsory when using certain panels. +#' +#' @return +#' \code{.check_panel} returns the input \code{initial} list of panels excluding +#' the checked panel if \code{panel_fun} is \code{NULL} or empty. +#' \code{.check_all_panels} applies \code{.check_panel} to multiple panels and +#' returns the a filtered version of \code{initial}. +#' +#' @examples +#' # Import libraries +#' library(mia) +#' library(TreeSummarizedExperiment) +#' +#' # Import TreeSE +#' data("Tengeler2020", package = "mia") +#' tse <- Tengeler2020 +#' +#' # Create list of panels +#' initial <- c(RowTreePlot(), ColumnTreePlot()) +#' # If RowTreePlot is in initial, check whether rowLinks is defined +#' initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) +#' # If ColumnTreePlot is in initial, check whether colLinks is defined +#' initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) +#' +#' # View filtered list of panels +#' initial +#' +#' @name utils +NULL + +#' @rdname utils +#' @export +#' @importFrom TreeSummarizedExperiment TreeSummarizedExperiment rowLinks +#' colLinks +#' @importFrom SingleCellExperiment reducedDims +#' @importFrom S4Vectors metadata +#' @importFrom SummarizedExperiment rowData colData +#' @importFrom mia taxonomyRanks +.check_all_panels <- function(se, initial){ + initial <- .check_panel(se, initial, "RowDataTable", rowData) + initial <- .check_panel(se, initial, "ColumnDataTable", colData) + initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) + initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) + initial <- .check_panel(se, initial, "AbundancePlot", taxonomyRanks) + initial <- .check_panel(se, initial, "ReducedDimensionPlot", reducedDims) + initial <- .check_panel(se, initial, "LoadingPlot", reducedDims) + initial <- .check_panel(se, initial, "ScreePlot", reducedDims) + initial <- .check_panel(se, initial, "RDAPlot", reducedDims) + initial <- .check_panel(se, initial, "RowGraphPlot", metadata) + initial <- .check_panel(se, initial, "ColumnGraphPlot", metadata) + return(initial) +} + +#' @rdname utils +#' @export +#' @importFrom S4Vectors isEmpty +#' @importFrom methods is +.check_panel <- function(se, panel_list, panel_class, panel_fun, wtext) { + + no_keep <- unlist(lapply(panel_list, function(x) is(x, panel_class))) + + if( any(no_keep) && (is.null(panel_fun(se)) || isEmpty(panel_fun(se))) ){ + panel_list <- panel_list[!no_keep] + warning("no valid ", as.character(substitute(panel_fun)), + " fields for ", panel_class, call. = FALSE) + } + + return(panel_list) +} \ No newline at end of file diff --git a/man/utils.Rd b/man/utils.Rd new file mode 100644 index 0000000..700eb2d --- /dev/null +++ b/man/utils.Rd @@ -0,0 +1,43 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{utils} +\alias{utils} +\alias{.check_all_panels} +\alias{.check_panel} +\title{iSEEtree utils} +\usage{ +.check_all_panels(se, initial) + +.check_panel(se, panel_list, panel_class, panel_fun, wtext) +} +\value{ +\code{.check_panel} returns the input \code{initial} list of panels excluding +the checked panel if \code{panel_fun} is \code{NULL} or empty. +\code{.check_all_panels} applies \code{.check_panel} to multiple panels and +returns the a filtered version of \code{initial}. +} +\description{ +Utility functions to check the existence of specific elements in a +\code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} +that are compulsory when using certain panels. +} +\examples{ +# Import libraries +library(mia) +library(TreeSummarizedExperiment) + +# Import TreeSE +data("Tengeler2020", package = "mia") +tse <- Tengeler2020 + +# Create list of panels +initial <- c(RowTreePlot(), ColumnTreePlot()) +# If RowTreePlot is in initial, check whether rowLinks is defined +initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) +# If ColumnTreePlot is in initial, check whether colLinks is defined +initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) + +# View filtered list of panels +initial + +} diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 2d7f1d8..c8c390a 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -28,6 +28,7 @@ reference: - subtitle: Default layout - contents: - iSEE + - utils - subtitle: Package - contents: - iSEEtree From a195b79c3e8c98cca2e91dde2d7d87e00d1cd8ca Mon Sep 17 00:00:00 2001 From: Giulio Benedetti Date: Mon, 17 Mar 2025 13:27:20 +0200 Subject: [PATCH 2/5] Refine documentation --- inst/REFERENCES.bib | 55 +++++++++++++ vignettes/iSEEtree.Rmd | 176 ++++++++++++++++++++++++----------------- vignettes/panels.Rmd | 59 +++++++++++--- 3 files changed, 208 insertions(+), 82 deletions(-) create mode 100644 inst/REFERENCES.bib diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib new file mode 100644 index 0000000..ae6bb81 --- /dev/null +++ b/inst/REFERENCES.bib @@ -0,0 +1,55 @@ +@Manual{core2024r, + title = {R: A Language and Environment for Statistical Computing}, + author = {{R Core Team}}, + organization = {R Foundation for Statistical Computing}, + address = {Vienna, Austria}, + year = {2024}, + url = {https://www.R-project.org/}, + } + +@misc{benedetti2024iseetree, + title={{iSEEtree: interactive explorer for hierarchical data}}, + author={Giulio Benedetti and Ely Seraidarian and Theotime Pralas and Akewak Jeba and Tuomas Borman and Leo Lahti}, + year={2024}, + eprint={2412.02882}, + archivePrefix={arXiv}, + primaryClass={cs.MS}, + url={https://arxiv.org/abs/2412.02882} +} + +@article{rue2018isee, + title={{iSEE: interactive SummarizedExperiment explorer}}, + author={Rue-Albrecht, Kevin and Marini, Federico and Soneson, Charlotte and Lun, Aaron TL}, + journal={F1000Research}, + volume={7}, + year={2018}, + publisher={Faculty of 1000 Ltd}, + doi={10.12688/f1000research.14966.1} +} + +@Manual{chang2024shiny, + title = {shiny: Web Application Framework for R}, + author = {Winston Chang and Joe Cheng and JJ Allaire and Carson Sievert and Barret Schloerke and Yihui Xie and Jeff Allen and Jonathan McPherson and Alan Dipert and Barbara Borges}, + year = {2024}, + note = {R package version 1.9.1}, + url = {https://CRAN.R-project.org/package=shiny}, + } + +@Manual{borman2024mia, + title = {mia: Microbiome analysis}, + author = {Tuomas Borman and Felix G.M. Ernst and Sudarshan A. Shetty and Leo Lahti}, + year = {2024}, + note = {R package version 1.14.0}, + url = {https://bioconductor.org/packages/mia}, + doi = {10.18129/B9.bioc.mia}, +} + +@article{huang2021treesummarizedexperiment, + title={{TreeSummarizedExperiment: a S4 class for data with hierarchical structure}}, + author={Huang, Ruizhu and Soneson, Charlotte and Ernst, Felix GM and Rue-Albrecht, Kevin C and Yu, Guangchuang and Hicks, Stephanie C and Robinson, Mark D}, + journal={F1000Research}, + volume={9}, + year={2021}, + publisher={Faculty of 1000 Ltd}, + doi={10.12688/f1000research.26669.2} +} \ No newline at end of file diff --git a/vignettes/iSEEtree.Rmd b/vignettes/iSEEtree.Rmd index 5c7cf7d..51a2021 100644 --- a/vignettes/iSEEtree.Rmd +++ b/vignettes/iSEEtree.Rmd @@ -1,5 +1,5 @@ --- -title: "iSEEtree: interactive exploration of microbiome data" +title: "iSEEtree: interactive explorer for hierarchical data" author: - name: Giulio Benedetti affiliation: University of Turku @@ -14,6 +14,7 @@ output: number_sections: true self_contained: true code_folding: show +bibliography: ../inst/REFERENCES.bib date: "`r doc_date()`" package: "`r pkg_ver('iSEEtree')`" vignette: > @@ -29,29 +30,14 @@ knitr::opts_chunk$set( ) ``` -```{r vignetteSetup, echo=FALSE, message=FALSE, warning=FALSE} -## Bib setup -library(RefManageR) - -## Write bibliography information -bib <- c( - R = citation(), - BiocStyle = citation("BiocStyle")[1], - knitr = citation("knitr")[1], - RefManageR = citation("RefManageR")[1], - rmarkdown = citation("rmarkdown")[1], - testthat = citation("testthat")[1] -) -``` - # Introduction ## Motivation iSEEtree is a Bioconductor package for the interactive visualisation of -microbiome 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 +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 @@ -60,45 +46,79 @@ in the [iSEE-verse website](https://isee.github.io/) and the respectively. iSEEtree is meant for new and experienced users alike, who desire to create and -interact with several graphics for microbiome data, without the need for an -in-depth knowledge of the underlying mia functionality. Current microbiome-specific -panels include phylogenetic trees, ordination plots and compositional plots, -which can be further explored below in this article. Other more generic panels -are also reused from the iSEE package and can be experimented in -[this article](https://isee.github.io/iSEE/articles/basic.html). +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 -following panels represent an easy-to-use interactive version of the miaViz -plotting functions: +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). -- [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. Its interpretation is - explained in the OMA chapter on - [Exploration](https://microbiome.github.io/OMA/docs/devel/pages/12_quality_control.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. Its interpretation is explained - in the OMA chapter on - [Community Composition](https://microbiome.github.io/OMA/docs/devel/pages/21_microbiome_community.html). -- [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. -- [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. + 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. Its interpretation is explained in the OMA chapter on - [Community Similarity](https://microbiome.github.io/OMA/docs/devel/pages/20_beta_diversity.html). + 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: @@ -113,9 +133,14 @@ 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 @@ -165,6 +190,33 @@ 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 @@ -175,16 +227,16 @@ information to cite the package and the overall approach. Thank you! citation("iSEEtree") ``` -## Background Knowledge +## Acknowledgements -iSEEtree is based on many other packages and in particular on those that have -implemented the infrastructure needed for dealing with omics data, microbiome -data and interactive visualisation. That is, packages like -[_SummarizedExperiment_](https://bioconductor.org/packages/3.18/bioc/html/SummarizedExperiment.html), -[_TreeSummarizedExperiment_](https://bioconductor.org/packages/3.18/bioc/html/TreeSummarizedExperiment.html), -[_mia_](https://bioconductor.org/packages/3.18/bioc/html/mia.html), -[_iSEE_](https://bioconductor.org/packages/3.18/bioc/html/iSEE.html) and -[_shiny_](https://cran.r-project.org/web/packages/shiny/). +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 @@ -208,18 +260,6 @@ error. # Reproducibility -iSEEtree was made possible thanks to: - -- R `r Citep(bib[["R"]])` -- `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])` -- `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` -- `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])` -- `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` -- `r CRANpkg("testthat")` `r Citep(bib[["testthat"]])` - -This package was developed using -[_usethis_](https://cran.r-project.org/web/packages/usethis/). - R session information: ```{r reproduce, echo=FALSE} @@ -229,11 +269,3 @@ sessionInfo() ``` # References - -This vignette was generated using `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])` -with `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` and `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` running behind the scenes. Citations were generated with `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`. - -```{r vignetteBiblio, results="asis", echo=FALSE, warning=FALSE, message=FALSE} -## Print bibliography -PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html")) -``` diff --git a/vignettes/panels.Rmd b/vignettes/panels.Rmd index da60d94..dbdf381 100644 --- a/vignettes/panels.Rmd +++ b/vignettes/panels.Rmd @@ -52,10 +52,11 @@ the app. This catalogue is divided into four sections: | Panel name | Panel class | Purpose | |------------------------|----------------------|-------------------------------------| -| Abundance plot | AbundancePlot | Feature composition by sample | +| Abundance plot | AbundancePlot | Feature abundance by sample | | Abundance density plot | AbundanceDensityPlot | Feature distribution across samples | | Prevalence plot | PrevalencePlot | Feature prevalence across samples | -| Complex heatmap plot | ComplexHeatmapPlot | Whole assay composition | +| Feature assay plot | FeatureAssayPlot | Feature counts by column variable | +| Complex heatmap plot | ComplexHeatmapPlot | Counts by features and samples | ## Abundance plot @@ -94,8 +95,26 @@ SCREENSHOT("screenshots/AbundanceDensityPlot.png", delay=20) Coming soon! +## Feature assay plot + +The Feature assay plot is inherited from iSEE. It is based on the +scater function plotRowData and can be used to visualise the counts of a +specific feature across samples grouped by a column variable. + +See its image in the iSEE panel catalogue: +[FeatureAssayPlot](https://isee.github.io/panels.html#featureassayplot) + ## Complex heatmap plot +The Reduced dimension plot is inherited from iSEE. It is based on the +ComplexHeatmap function Heatmap, which shows an entire assay as a heatmap where +rows and columns represent features and samples, respectively. Hierarchical +clustering as well as grouping by a variable can be performed across both +dimensions. + +See its image in the iSEE panel catalogue: +[ComplexHeatmapPlot](https://isee.github.io/panels.html#complexheatmapplot) + # Ordination Analysis {#sec-ordination} | Panel name | Panel class | Purpose | @@ -157,10 +176,13 @@ SCREENSHOT("screenshots/LoadingPlot.png", delay=20) ## Reduced dimension plot The Reduced dimension plot is inherited from iSEE. It is based on the -scater function plotReducedDim and and can be used to visualise the results +scater function plotReducedDim and can be used to visualise the results of an ordination analysis with both supervised and unsupervised methods as dot plot with reduced dimensions as coordinate axes. +See its image in the iSEE panel catalogue: +[ReducedDimensionPlot](https://isee.github.io/panels.html#reduceddimensionplot) + # Structural Analysis {#sec-structure} | Panel name | Panel class | Purpose | @@ -209,13 +231,15 @@ SCREENSHOT("screenshots/RowGraphPlot.png", delay=20) # Other panels {#sec-other} -| Panel name | Panel class | Purpose | -|--------------------|----------------|---------------------------------------------| -| Row tile plot | RowTreePlot | Variable distribution across feature groups | -| Column tile plot | ColumnTreePlot | Variable distribution across sample groups | -| Mediation plot | MediationPlot | Results of mediation analysis | -| Row data plot | RowDataPlot | Variables from feature metadata | -| Column data plot | ColumnDataPlot | Variables from sample metadata | +| Panel name | Panel class | Information | +|--------------------|-----------------|---------------------------------------------| +| Row tile plot | RowTilePlot | Variable distribution across feature groups | +| Column tile plot | ColumnTilePlot | Variable distribution across sample groups | +| Mediation plot | MediationPlot | Results of mediation analysis | +| Row data table | RowDataTable | Table of feature metadata | +| Column data table | ColumnDataTable | Table of sample metadata | +| Row data plot | RowDataPlot | Feature variable distribution | +| Column data plot | ColumnDataPlot | Sample variable distribution | ## Row/Column tile plots @@ -225,6 +249,17 @@ Coming soon! Coming soon! +## Row/Column data tables + +The Row and column data tables are inherited from iSEE. They are rendered as +a tidy table of feeature or sample variables, respectively. From those, it is +possible to select a subset of the observations and transmit it to one or many +other panels. + +See their images in the iSEE panel catalogue: +[RowDataPlot](https://isee.github.io/panels.html#rowdataplot) and +[ColumnDataPlot](https://isee.github.io/panels.html#columndataplot) + ## Row/Column data plots The Row and column data plots are inherited from iSEE. They are based on the @@ -232,6 +267,10 @@ scater functions plotRowData and plotColData and can be used to visualise feature or sample metadata as scatter plots when the x variable is continuous or boxplots when the x variable is discrete. +See their images in the iSEE panel catalogue: +[RowDataTable](https://isee.github.io/panels.html#rowdatatable) and +[ColumnDataTable](https://isee.github.io/panels.html#columndatatable) + # Reproducibility R session information: From 2eaa138b628910f71eae2a5db8f7674df59eb010 Mon Sep 17 00:00:00 2001 From: Giulio Benedetti Date: Mon, 17 Mar 2025 13:51:47 +0200 Subject: [PATCH 3/5] Add citation --- R/utils.R | 4 ++-- inst/CITATION | 20 ++++++++++++++++++++ inst/REFERENCES.bib | 10 ---------- man/utils.Rd | 4 ++-- vignettes/iSEEtree.Rmd | 1 - 5 files changed, 24 insertions(+), 15 deletions(-) create mode 100644 inst/CITATION diff --git a/R/utils.R b/R/utils.R index 234c171..60e49ed 100644 --- a/R/utils.R +++ b/R/utils.R @@ -22,9 +22,9 @@ #' # Create list of panels #' initial <- c(RowTreePlot(), ColumnTreePlot()) #' # If RowTreePlot is in initial, check whether rowLinks is defined -#' initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) +#' initial <- .check_panel(tse, initial, "RowTreePlot", rowLinks) #' # If ColumnTreePlot is in initial, check whether colLinks is defined -#' initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) +#' initial <- .check_panel(tse, initial, "ColumnTreePlot", colLinks) #' #' # View filtered list of panels #' initial diff --git a/inst/CITATION b/inst/CITATION new file mode 100644 index 0000000..1ee4e59 --- /dev/null +++ b/inst/CITATION @@ -0,0 +1,20 @@ +citHeader("To cite iSEEtree in publications use:") + +citEntry( + entry = "Article", + title = "iSEEtree: interactive explorer for hierarchical data", + author = personList( + as.person("Giulio Benedetti"), + as.person("Ely Seraidarian"), + as.person("Theotime Pralas"), + as.person("Akewak Jeba"), + as.person("Tuomas Borman"), + as.person("Leo Lahti") + ), + journal = "arXiv", + year = "2024", + url = "https://arxiv.org/abs/2412.02882", + textVersion = paste("Benedetti, G., Seraidarian, E., Pralas, T., Jeba, A.", + "Borman, T., & Lahti, L. (2024). iSEEtree: interactive explorer for", + "hierarchical data. arXiv. doi: https://doi.org/10.48550/arXiv.2412.02882") +) \ No newline at end of file diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib index ae6bb81..6f9488e 100644 --- a/inst/REFERENCES.bib +++ b/inst/REFERENCES.bib @@ -7,16 +7,6 @@ @Manual{core2024r url = {https://www.R-project.org/}, } -@misc{benedetti2024iseetree, - title={{iSEEtree: interactive explorer for hierarchical data}}, - author={Giulio Benedetti and Ely Seraidarian and Theotime Pralas and Akewak Jeba and Tuomas Borman and Leo Lahti}, - year={2024}, - eprint={2412.02882}, - archivePrefix={arXiv}, - primaryClass={cs.MS}, - url={https://arxiv.org/abs/2412.02882} -} - @article{rue2018isee, title={{iSEE: interactive SummarizedExperiment explorer}}, author={Rue-Albrecht, Kevin and Marini, Federico and Soneson, Charlotte and Lun, Aaron TL}, diff --git a/man/utils.Rd b/man/utils.Rd index 700eb2d..4e54340 100644 --- a/man/utils.Rd +++ b/man/utils.Rd @@ -33,9 +33,9 @@ tse <- Tengeler2020 # Create list of panels initial <- c(RowTreePlot(), ColumnTreePlot()) # If RowTreePlot is in initial, check whether rowLinks is defined -initial <- .check_panel(se, initial, "RowTreePlot", rowLinks) +initial <- .check_panel(tse, initial, "RowTreePlot", rowLinks) # If ColumnTreePlot is in initial, check whether colLinks is defined -initial <- .check_panel(se, initial, "ColumnTreePlot", colLinks) +initial <- .check_panel(tse, initial, "ColumnTreePlot", colLinks) # View filtered list of panels initial diff --git a/vignettes/iSEEtree.Rmd b/vignettes/iSEEtree.Rmd index 51a2021..20b91e6 100644 --- a/vignettes/iSEEtree.Rmd +++ b/vignettes/iSEEtree.Rmd @@ -223,7 +223,6 @@ 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 info citation("iSEEtree") ``` From 0ece08d6dd278353b3ff9d5809781df63f013072 Mon Sep 17 00:00:00 2001 From: Giulio Benedetti Date: Mon, 17 Mar 2025 15:14:25 +0200 Subject: [PATCH 4/5] Fix docs --- R/class-AbundanceDensityPlot.R | 3 ++- R/class-AbundancePlot.R | 3 ++- R/class-LoadingPlot.R | 3 ++- R/class-RDAPlot.R | 3 ++- R/class-ScreePlot.R | 4 ++-- R/family-GraphPlot.R | 2 +- R/family-TreePlot.R | 2 +- R/iSEEtree-package.R | 4 ++-- R/utils.R | 1 + man/AbundanceDensityPlot.Rd | 3 ++- man/AbundancePlot.Rd | 3 ++- man/GraphPlot.Rd | 2 +- man/LoadingPlot.Rd | 3 ++- man/RDAPlot.Rd | 3 ++- man/ScreePlot.Rd | 4 ++-- man/TreePlot.Rd | 2 +- man/{iSEEtree.Rd => iSEEtree-package.Rd} | 4 ++-- man/utils.Rd | 1 + pkgdown/_pkgdown.yml | 2 +- 19 files changed, 31 insertions(+), 21 deletions(-) rename man/{iSEEtree.Rd => iSEEtree-package.Rd} (96%) diff --git a/R/class-AbundanceDensityPlot.R b/R/class-AbundanceDensityPlot.R index aaf68bc..3582ba5 100644 --- a/R/class-AbundanceDensityPlot.R +++ b/R/class-AbundanceDensityPlot.R @@ -15,7 +15,8 @@ #' \item \code{order_descending}, a string specifying the descending order. #' } #' -#' In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +#' In addition, this class inherits all slots from its parent class +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @return #' The \code{AbundanceDensityPlot(...)} constructor creates an instance of an diff --git a/R/class-AbundancePlot.R b/R/class-AbundancePlot.R index 428047c..6cec5c6 100644 --- a/R/class-AbundancePlot.R +++ b/R/class-AbundancePlot.R @@ -13,7 +13,8 @@ #' \item \code{add_legend}, a logical indicating if the color legend should appear. #' } #' -#' In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +#' In addition, this class inherits all slots from its parent class +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @return #' The \code{AbundancePlot(...)} constructor creates an instance of an diff --git a/R/class-LoadingPlot.R b/R/class-LoadingPlot.R index ffdae73..c85d470 100644 --- a/R/class-LoadingPlot.R +++ b/R/class-LoadingPlot.R @@ -14,7 +14,8 @@ #' \item \code{add.tree}, a logical indicating whether the tree should be shown. #' } #' -#' In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +#' In addition, this class inherits all slots from its parent class +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @return #' The \code{LoadingPlot(...)} constructor creates an instance of an diff --git a/R/class-RDAPlot.R b/R/class-RDAPlot.R index edf9f28..1853cdf 100644 --- a/R/class-RDAPlot.R +++ b/R/class-RDAPlot.R @@ -30,7 +30,8 @@ #' on the coordinate axes. #' } #' -#' In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +#' In addition, this class inherits all slots from its parent class +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @return #' The \code{RDAPlot(...)} constructor creates an instance of a RDAPlot class, diff --git a/R/class-ScreePlot.R b/R/class-ScreePlot.R index f853b45..b42f89a 100644 --- a/R/class-ScreePlot.R +++ b/R/class-ScreePlot.R @@ -45,8 +45,8 @@ #' (Default: \code{c("eig", "varExplained")}) #' } #' -#' In addition, this class inherits all slots from its parent -#' \linkS4class{Panel} class. +#' In addition, this class inherits all slots from its parent class +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @return #' The \code{ScreePlot(...)} constructor creates an instance of an ScreePlot diff --git a/R/family-GraphPlot.R b/R/family-GraphPlot.R index 274416b..d7888ec 100644 --- a/R/family-GraphPlot.R +++ b/R/family-GraphPlot.R @@ -35,7 +35,7 @@ #' } #' #' In addition, this class inherits all slots from its parent class -#' \linkS4class{Panel}. +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @seealso #' \linkS4class{RowGraphPlot} diff --git a/R/family-TreePlot.R b/R/family-TreePlot.R index 2cd0542..6ec7796 100644 --- a/R/family-TreePlot.R +++ b/R/family-TreePlot.R @@ -41,7 +41,7 @@ #' } #' #' In addition, this class inherits all slots from its parent -#' \linkS4class{Panel} class. +#' \code{\link[iSEE:Panel-class]{Panel}}. #' #' @seealso #' \linkS4class{RowTreePlot} diff --git a/R/iSEEtree-package.R b/R/iSEEtree-package.R index 6912cd2..4f269f6 100644 --- a/R/iSEEtree-package.R +++ b/R/iSEEtree-package.R @@ -1,6 +1,6 @@ #' iSEE extension for the TreeSummarizedExperiment container #' -#' `iSEEtree` is an extension of \pkg{iSEE} that provides panels for the +#' \code{iSEEtree} is an extension of \pkg{iSEE} that provides panels for the #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} #' container, enabling the interactive visualisation of typical microbiome data. #' The panel layout of iSEEtree is described in \code{\link{iSEE}}. @@ -14,6 +14,6 @@ #' #' @docType package #' @keywords internal -#' @name iSEEtree +#' @name iSEEtree-package #' "_PACKAGE" diff --git a/R/utils.R b/R/utils.R index 60e49ed..5d79371 100644 --- a/R/utils.R +++ b/R/utils.R @@ -29,6 +29,7 @@ #' # View filtered list of panels #' initial #' +#' @keywords internal #' @name utils NULL diff --git a/man/AbundanceDensityPlot.Rd b/man/AbundanceDensityPlot.Rd index e1c80ea..a795451 100644 --- a/man/AbundanceDensityPlot.Rd +++ b/man/AbundanceDensityPlot.Rd @@ -27,7 +27,8 @@ The following slots control the thresholds used in the visualisation: \item \code{order_descending}, a string specifying the descending order. } -In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +In addition, this class inherits all slots from its parent class +\code{\link[iSEE:Panel-class]{Panel}}. } \examples{ diff --git a/man/AbundancePlot.Rd b/man/AbundancePlot.Rd index be1fd32..03e039e 100644 --- a/man/AbundancePlot.Rd +++ b/man/AbundancePlot.Rd @@ -25,7 +25,8 @@ The following slots control the thresholds used in the visualization: \item \code{add_legend}, a logical indicating if the color legend should appear. } -In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +In addition, this class inherits all slots from its parent class +\code{\link[iSEE:Panel-class]{Panel}}. } \examples{ diff --git a/man/GraphPlot.Rd b/man/GraphPlot.Rd index 12d856e..b4566ea 100644 --- a/man/GraphPlot.Rd +++ b/man/GraphPlot.Rd @@ -42,7 +42,7 @@ by when \code{shape_parameters = "Node"}. (Default: \code{NULL}) } In addition, this class inherits all slots from its parent class -\linkS4class{Panel}. +\code{\link[iSEE:Panel-class]{Panel}}. } \seealso{ diff --git a/man/LoadingPlot.Rd b/man/LoadingPlot.Rd index dd9110c..7eea387 100644 --- a/man/LoadingPlot.Rd +++ b/man/LoadingPlot.Rd @@ -26,7 +26,8 @@ The following slots control the thresholds used in the visualisation: \item \code{add.tree}, a logical indicating whether the tree should be shown. } -In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +In addition, this class inherits all slots from its parent class +\code{\link[iSEE:Panel-class]{Panel}}. } \examples{ diff --git a/man/RDAPlot.Rd b/man/RDAPlot.Rd index 1a609b8..daf9dbb 100644 --- a/man/RDAPlot.Rd +++ b/man/RDAPlot.Rd @@ -41,7 +41,8 @@ should appear in the labels. on the coordinate axes. } -In addition, this class inherits all slots from its parent \linkS4class{Panel} class. +In addition, this class inherits all slots from its parent class +\code{\link[iSEE:Panel-class]{Panel}}. } \examples{ diff --git a/man/ScreePlot.Rd b/man/ScreePlot.Rd index 6b4bce6..4f32328 100644 --- a/man/ScreePlot.Rd +++ b/man/ScreePlot.Rd @@ -57,8 +57,8 @@ components on the x-axis. If \code{FALSE}, indices are shown instead. (Default: \code{c("eig", "varExplained")}) } -In addition, this class inherits all slots from its parent -\linkS4class{Panel} class. +In addition, this class inherits all slots from its parent class +\code{\link[iSEE:Panel-class]{Panel}}. } \examples{ diff --git a/man/TreePlot.Rd b/man/TreePlot.Rd index f0d25a2..e142709 100644 --- a/man/TreePlot.Rd +++ b/man/TreePlot.Rd @@ -48,7 +48,7 @@ equalised. (Default: \code{FALSE}) } In addition, this class inherits all slots from its parent -\linkS4class{Panel} class. +\code{\link[iSEE:Panel-class]{Panel}}. } \seealso{ diff --git a/man/iSEEtree.Rd b/man/iSEEtree-package.Rd similarity index 96% rename from man/iSEEtree.Rd rename to man/iSEEtree-package.Rd index eae1216..7247ed9 100644 --- a/man/iSEEtree.Rd +++ b/man/iSEEtree-package.Rd @@ -1,9 +1,9 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/iSEEtree-package.R \docType{package} -\name{iSEEtree} -\alias{iSEEtree-package} +\name{iSEEtree-package} \alias{iSEEtree} +\alias{iSEEtree-package} \title{iSEE extension for the TreeSummarizedExperiment container} \description{ \code{iSEEtree} is an extension of \pkg{iSEE} that provides panels for the diff --git a/man/utils.Rd b/man/utils.Rd index 4e54340..a425d03 100644 --- a/man/utils.Rd +++ b/man/utils.Rd @@ -41,3 +41,4 @@ initial <- .check_panel(tse, initial, "ColumnTreePlot", colLinks) initial } +\keyword{internal} diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index c8c390a..b29625b 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -31,4 +31,4 @@ reference: - utils - subtitle: Package - contents: - - iSEEtree + - iSEEtree-package From 25bcbbef233e62622c20a72bd4aaa8b03af3cc6b Mon Sep 17 00:00:00 2001 From: Giulio Benedetti Date: Mon, 17 Mar 2025 15:28:31 +0200 Subject: [PATCH 5/5] Fix utils vignettes --- R/utils.R | 31 +++++++++++++++++++++++-------- man/utils.Rd | 20 ++++++++++++++++++-- 2 files changed, 41 insertions(+), 10 deletions(-) diff --git a/R/utils.R b/R/utils.R index 5d79371..ab400a9 100644 --- a/R/utils.R +++ b/R/utils.R @@ -4,9 +4,24 @@ #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} #' that are compulsory when using certain panels. #' +#' @param se a +#' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} +#' object. +#' +#' @param initial \code{Panel vector}. A list of panel objects to check. +#' +#' @param panel.class \code{Character vector}. A list of panel names +#' corresponding to panel objects in \code{initial}. +#' +#' @param panel.fun \code{Function scalar}. The element of \code{se} whose +#' existance should be checked. +#' +#' @param wtext \code{Character scalar}. Text of the warning message returned +#' if \code{panel.fun} does not exist or is empty. +#' #' @return #' \code{.check_panel} returns the input \code{initial} list of panels excluding -#' the checked panel if \code{panel_fun} is \code{NULL} or empty. +#' the checked panel if \code{panel.fun} is \code{NULL} or empty. #' \code{.check_all_panels} applies \code{.check_panel} to multiple panels and #' returns the a filtered version of \code{initial}. #' @@ -60,15 +75,15 @@ NULL #' @export #' @importFrom S4Vectors isEmpty #' @importFrom methods is -.check_panel <- function(se, panel_list, panel_class, panel_fun, wtext) { +.check_panel <- function(se, initial, panel.class, panel.fun, wtext) { - no_keep <- unlist(lapply(panel_list, function(x) is(x, panel_class))) + no_keep <- unlist(lapply(initial, function(x) is(x, panel.class))) - if( any(no_keep) && (is.null(panel_fun(se)) || isEmpty(panel_fun(se))) ){ - panel_list <- panel_list[!no_keep] - warning("no valid ", as.character(substitute(panel_fun)), - " fields for ", panel_class, call. = FALSE) + if( any(no_keep) && (is.null(panel.fun(se)) || isEmpty(panel.fun(se))) ){ + initial <- initial[!no_keep] + warning("no valid ", as.character(substitute(panel.fun)), + " fields for ", panel.class, call. = FALSE) } - return(panel_list) + return(initial) } \ No newline at end of file diff --git a/man/utils.Rd b/man/utils.Rd index a425d03..ad52f46 100644 --- a/man/utils.Rd +++ b/man/utils.Rd @@ -8,11 +8,27 @@ \usage{ .check_all_panels(se, initial) -.check_panel(se, panel_list, panel_class, panel_fun, wtext) +.check_panel(se, initial, panel.class, panel.fun, wtext) +} +\arguments{ +\item{se}{a +\code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} +object.} + +\item{initial}{\code{Panel vector}. A list of panel objects to check.} + +\item{panel.class}{\code{Character vector}. A list of panel names +corresponding to panel objects in \code{initial}.} + +\item{panel.fun}{\code{Function scalar}. The element of \code{se} whose +existance should be checked.} + +\item{wtext}{\code{Character scalar}. Text of the warning message returned +if \code{panel.fun} does not exist or is empty.} } \value{ \code{.check_panel} returns the input \code{initial} list of panels excluding -the checked panel if \code{panel_fun} is \code{NULL} or empty. +the checked panel if \code{panel.fun} is \code{NULL} or empty. \code{.check_all_panels} applies \code{.check_panel} to multiple panels and returns the a filtered version of \code{initial}. }