From c2c5f88f389eca5a0af9782ddcf9966b13915ebb Mon Sep 17 00:00:00 2001 From: Roman Hillje Date: Thu, 24 Sep 2020 17:08:21 +0200 Subject: [PATCH] Update vignettes and other documents. --- man/Cerebro_v1.3.Rd | 76 ++++++++++++- .../prepare_Cerebro_files_for_edge_cases.Rmd | 48 +++++++-- other_documents/testing_prodecure_v1.3.Rmd | 3 +- pkgdown/_pkgdown.yml | 4 +- ...and_visualize_custom_tables_and_plots.Rmd} | 101 +++++++++++++++--- vignettes/overview_of_cerebro_v1.3_class.Rmd | 8 +- vignettes/release_notes_v1.3.Rmd | 18 ++-- 7 files changed, 222 insertions(+), 36 deletions(-) rename vignettes/{export_and_visualize_custom_tables.Rmd => export_and_visualize_custom_tables_and_plots.Rmd} (62%) diff --git a/man/Cerebro_v1.3.Rd b/man/Cerebro_v1.3.Rd index 5b9f808..94dc631 100644 --- a/man/Cerebro_v1.3.Rd +++ b/man/Cerebro_v1.3.Rd @@ -122,10 +122,14 @@ format in a named \code{list} called `tables`} \item \href{#method-getTrajectory}{\code{Cerebro_v1.3$getTrajectory()}} \item \href{#method-addExtraMaterial}{\code{Cerebro_v1.3$addExtraMaterial()}} \item \href{#method-addExtraTable}{\code{Cerebro_v1.3$addExtraTable()}} +\item \href{#method-addExtraPlot}{\code{Cerebro_v1.3$addExtraPlot()}} \item \href{#method-getExtraMaterialCategories}{\code{Cerebro_v1.3$getExtraMaterialCategories()}} \item \href{#method-checkForExtraTables}{\code{Cerebro_v1.3$checkForExtraTables()}} \item \href{#method-getNamesOfExtraTables}{\code{Cerebro_v1.3$getNamesOfExtraTables()}} \item \href{#method-getExtraTable}{\code{Cerebro_v1.3$getExtraTable()}} +\item \href{#method-checkForExtraPlots}{\code{Cerebro_v1.3$checkForExtraPlots()}} +\item \href{#method-getNamesOfExtraPlots}{\code{Cerebro_v1.3$getNamesOfExtraPlots()}} +\item \href{#method-getExtraPlot}{\code{Cerebro_v1.3$getExtraPlot()}} \item \href{#method-print}{\code{Cerebro_v1.3$print()}} \item \href{#method-clone}{\code{Cerebro_v1.3$clone()}} } @@ -980,8 +984,9 @@ Add content to extra material field. \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{category}}{Name of category. At the moment, only \code{tables} is a -valid category.} +\item{\code{category}}{Name of category. At the moment, only \code{tables} and +\code{plots} are valid categories. Tables must be in \code{data.frame} +format and plots must be created with \code{ggplot2}.} \item{\code{name}}{Name of material, will be used to select it in Cerebro.} @@ -1010,6 +1015,26 @@ Add table to `extra_material` slot. } } \if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-addExtraPlot}{}}} +\subsection{Method \code{addExtraPlot()}}{ +Add plot to `extra_material` slot. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Cerebro_v1.3$addExtraPlot(name, plot)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{name}}{Name of material, will be used to select it in Cerebro.} + +\item{\code{plot}}{Plot that should be added, must be created with +\code{ggplot2} (class: \code{ggplot}).} +} +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-getExtraMaterialCategories}{}}} \subsection{Method \code{getExtraMaterialCategories()}}{ @@ -1070,6 +1095,53 @@ Requested table in \code{data.frame} format. } } \if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-checkForExtraPlots}{}}} +\subsection{Method \code{checkForExtraPlots()}}{ +Check whether there are plots in the extra materials. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Cerebro_v1.3$checkForExtraPlots()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +\code{logical} indicating whether there are plots in the extra +materials. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-getNamesOfExtraPlots}{}}} +\subsection{Method \code{getNamesOfExtraPlots()}}{ +Get names of plots in extra materials. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Cerebro_v1.3$getNamesOfExtraPlots()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +\code{vector} containing names of plots in extra materials. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-getExtraPlot}{}}} +\subsection{Method \code{getExtraPlot()}}{ +Get plot from extra materials. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Cerebro_v1.3$getExtraPlot(name)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{name}}{Name of plot.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +Requested plot made with \code{ggplot2}. +} +} +\if{html}{\out{
}} \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-print}{}}} \subsection{Method \code{print()}}{ diff --git a/other_documents/prepare_Cerebro_files_for_edge_cases.Rmd b/other_documents/prepare_Cerebro_files_for_edge_cases.Rmd index ffb4485..6e304ba 100644 --- a/other_documents/prepare_Cerebro_files_for_edge_cases.Rmd +++ b/other_documents/prepare_Cerebro_files_for_edge_cases.Rmd @@ -362,18 +362,22 @@ exportFromSeurat( ) ``` -## Export custom table in extra material +## Extra material + +### Table ```{r eval=FALSE} pbmc_Seurat_copy <- pbmc_Seurat +custom_table <- tibble( + a = "this", + b = "is", + c = "a", + d = "test" +) + pbmc_Seurat_copy@misc$extra_material$tables <- list( - "test" = tibble( - a = "this", - b = "is", - c = "a", - d = "test" - ) + "test" = custom_table ) exportFromSeurat( @@ -392,6 +396,36 @@ exportFromSeurat( ) ``` +### Plot + +```{r eval=FALSE} +library(ggplot2) + +pbmc_Seurat_copy <- pbmc_Seurat + +custom_plot <- ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) + + geom_point() + +pbmc_Seurat_copy@misc$extra_material$plots <- list( + "iris" = custom_plot +) + +exportFromSeurat( + pbmc_Seurat_copy, + assay = 'SCT', + slot = 'data', + file = '~/Dropbox/Cerebro_development/pbmc_Seurat_dgCMatrix.crb', + experiment_name = 'pbmc_Seurat', + organism = 'hg', + columns_groups = c('sample','seurat_clusters','cell_type_singler_blueprintencode_main'), + columns_cell_cycle = c('cell_cycle_seurat'), + column_nUMI = 'nCount_RNA', + column_nGene = 'nFeature_RNA', + add_all_meta_data = TRUE, + verbose = FALSE +) +``` + ## Format of expression data ### `dgCMatrix` diff --git a/other_documents/testing_prodecure_v1.3.Rmd b/other_documents/testing_prodecure_v1.3.Rmd index 43ed818..26d5c2c 100644 --- a/other_documents/testing_prodecure_v1.3.Rmd +++ b/other_documents/testing_prodecure_v1.3.Rmd @@ -210,7 +210,6 @@ source('~/Research/GitHub/cerebroApp_v1.3/R/getMostExpressedGenes.R') ``` ```{r eval=FALSE} -# names(pbmc_Seurat@misc$most_expressed_genes) <- c('sample','seurat_clusters') pbmc_Seurat@misc$most_expressed_genes$by_sample <- NULL pbmc_Seurat@misc$most_expressed_genes$by_cluster <- NULL @@ -306,7 +305,7 @@ pbmc_Seurat <- extractMonocleTrajectory(monocle, pbmc_Seurat, 'highly_variable_g # Export data ```{r eval=FALSE} -source('~/Research/GitHub/cerebroApp_v1.3/R/Cerebro_v1.3-class.R') +source('~/Research/GitHub/cerebroApp_v1.3/R/class-Cerebro_v1.3.R') source('~/Research/GitHub/cerebroApp_v1.3/R/exportFromSeurat.R') source('~/Research/GitHub/cerebroApp_v1.3/R/exportFromSCE.R') diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 69d0616..7f5a40d 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -14,8 +14,8 @@ navbar: href: articles/Cerebro_interface_v1.2.html - text: "Export an SCE/SingleCellExperiment object" href: articles/export_a_data_set_in_SCE_format.html - - text: "Export and visualize custom tables" - href: articles/export_and_visualize_custom_tables.html + - text: "Export and visualize custom tables and plots" + href: articles/export_and_visualize_custom_tables_and_plots.html - text: "Launch Cerebro with pre-loaded data set" href: articles/launch_cerebro_with_pre-loaded_data_set.html - text: "Host Cerebro on shinyapps.io" diff --git a/vignettes/export_and_visualize_custom_tables.Rmd b/vignettes/export_and_visualize_custom_tables_and_plots.Rmd similarity index 62% rename from vignettes/export_and_visualize_custom_tables.Rmd rename to vignettes/export_and_visualize_custom_tables_and_plots.Rmd index 630b1a0..f6b33c9 100644 --- a/vignettes/export_and_visualize_custom_tables.Rmd +++ b/vignettes/export_and_visualize_custom_tables_and_plots.Rmd @@ -1,5 +1,5 @@ --- -title: "Export and visualize custom table" +title: "Export and visualize custom tables and plots" author: "Roman Hillje" date: "`r format(Sys.time(), '%d %B, %Y')`" output: @@ -9,7 +9,7 @@ output: self_contained: yes mode: selfcontained vignette: > - %\VignetteIndexEntry{Export and visualize custom table} + %\VignetteIndexEntry{Export and visualize custom tables and plots} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -23,11 +23,13 @@ knitr::opts_chunk$set( # Overview -In previous cerebroApp versions, a very specific format for tables containing marker genes and enriched pathways was expected, resulting in a severe limitation of which methods you can use to generate the results, or alternatively requiring manual modification of the table to fit the format. Since cerebroApp v1.3, it is possible to export and visualize tables of any format in Cerebro, as long as they are a `data.frame`. Due to dynamic column formatting and color highlighting, the table content can be visually enhanced anyway. +cerebroApp v1.3 provides new possibilities to export and visualize custom data that you would like to share alongside with your scRNA-seq data. At the time of writing, you can attach tables and plots (made with ggplot2) to your data set. In this article, I will show you to do it. + +# Tables -Here, I will give you an example how you can export tables that were not produced by cerebroApp and visualize them in Cerebro anyway. +In previous cerebroApp versions, a very specific format for tables containing marker genes and enriched pathways was expected, resulting in a severe limitation of which methods you can use to generate the results, or alternatively requiring manual modification of the table to fit the format. Since cerebroApp v1.3, it is possible to export and visualize tables of any format in Cerebro, as long as they are a `data.frame`. Due to dynamic column formatting and color highlighting, the table content can be visually enhanced anyway. -# Marker genes and enriched pathways +## Marker genes and enriched pathways Let's assume you have a `Seurat` object but generated tables of differentially expressed genes and enriched pathways using other tools/methods than those built into cerebroApp. To export those tables, you just need to put it in the right place, following a "method" and "name" scheme. In this example, we assume you have a table of marker genes called `custom_table` that looks like this: @@ -101,22 +103,24 @@ You can see that among the marker gene results is the `custom_method` and `custo Then, after loading the data into Cerebro, we will see this: -Custom marker gene table in Cerebro +Custom marker gene table in Cerebro Granted, this isn't a very pretty table, but you get the idea. -# Extra material +## Extra material When you have tables that might be useful to interpret the data set but don't contain marker genes, differentially expressed genes, or enriched pathways, then you can add them as extra material. Again, just make sure you follow the general structure. In the case of a `Seurat` object, store the tables with an interpretable name in a list at `@misc$extra_material$tables`. You can see an example below, where we store the same example table as before: ```{r eval=FALSE} +custom_table <- tibble( + a = "this", + b = "is", + c = "a", + d = "test" +) + pbmc_Seurat@misc$extra_material$tables <- list( - "test" = tibble( - a = "this", - b = "is", - c = "a", - d = "test" - ) + "test" = custom_table ) exportFromSeurat( @@ -169,6 +173,75 @@ extra material: This time, you see that our table with the name "test" was exported as part of the extra material. In Cerebro, when a data set contains extra material, a tab will appear in the side bar which will give you access to the table, as shown in the screenshot: -Custom table as extra material in Cerebro +Custom table as extra material in Cerebro Again, this table isn't particularly informative, but hopefully you got an idea of the procedure. + +# Plots + +Custom plots can be exported and visualized in the "Extra material" tab as well. The only requirement is that they were produced with ggplot2. + +Let's look at an example in which we create a simple plot with ggplot2, call it `iris`, and add it to the Seurat object: + +```{r eval=FALSE} +library(ggplot2) + +custom_plot <- ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) + + geom_point() + +pbmc_Seurat@misc$extra_material$plots <- list( + "iris" = custom_plot +) + +exportFromSeurat( + pbmc_Seurat, + assay = 'SCT', + slot = 'data', + file = '~/Dropbox/Cerebro_development/pbmc_Seurat.crb', + experiment_name = 'pbmc_Seurat', + organism = 'hg', + columns_groups = c('sample','seurat_clusters','cell_type_singler_blueprintencode_main'), + columns_cell_cycle = c('cell_cycle_seurat'), + column_nUMI = 'nCount_RNA', + column_nGene = 'nFeature_RNA', + add_all_meta_data = TRUE, + verbose = FALSE +) +``` + +``` +[11:54:33] Start collecting data... +[11:54:33] Overview of Cerebro object: + +class: Cerebro_v1.3 +cerebroApp version: 1.3.0 +experiment name: pbmc_Seurat +organism: hg +date of analysis: 2020-02-19 +date of export: 2020-09-24 +number of cells: 5,697 +number of genes: 15,907 +grouping variables (3): sample, seurat_clusters, cell_type_singler_blueprintencode_main +cell cycle variables (1): cell_cycle_seurat +projections (2): UMAP, UMAP_3D +trees (3): sample, seurat_clusters, cell_type_singler_blueprintencode_main +most expressed genes: sample, seurat_clusters, cell_type_singler_blueprintencode_main +marker genes: + - cerebro_seurat (3): sample, seurat_clusters, cell_type_singler_blueprintencode_main +enriched pathways: + - cerebro_seurat_enrichr (3): sample, seurat_clusters, cell_type_singler_blueprintencode_main, + - cerebro_GSVA (3): sample, seurat_clusters, cell_type_singler_blueprintencode_main +trajectories: + - monocle2 (1): highly_variable_genes +extra material: + - plots (1): iris + +[11:54:33] Saving Cerebro object to: ~/Dropbox/Cerebro_development/pbmc_Seurat_dgCMatrix.crb +[11:54:37] Done! +``` + +In the log messages of the export process, we see that the plot was correctly extracted and is listed in the "extra material". + +In Cerebro, we can now access this table in the "Extra material" tab through the "plots" category. + +Custom plot as extra material in Cerebro diff --git a/vignettes/overview_of_cerebro_v1.3_class.Rmd b/vignettes/overview_of_cerebro_v1.3_class.Rmd index ded4d4b..5450498 100644 --- a/vignettes/overview_of_cerebro_v1.3_class.Rmd +++ b/vignettes/overview_of_cerebro_v1.3_class.Rmd @@ -53,13 +53,15 @@ Let's look at some details. Overall, the object is organized as such: │ └── (named list) │ └── (depends on method, most likely a list or data frame) └── extra_material (named list) - └── tables (named list) - └── (data.frame) + ├── tables (named list) + │ └── (data.frame) + └── plots (named list) + └── (ggplot-object) ``` Interaction with the Cerebro object will be done through internal methods, providing additional control for the correct format of the object. -As long as you follow the described scheme, you can export and visualize any data frame that is stored in the `marker_genes` or `enriched_pathways` slots. I have prepared a vignette with some more details that you can find [here](export_and_visualize_custom_tables.html). +As long as you follow the described scheme, you can export and visualize any data frame that is stored in the `marker_genes` or `enriched_pathways` slots. I have prepared a vignette with some more details that you can find [here](export_and_visualize_custom_tables_and_plots.html). Please make sure to use names for items in lists, otherwise it will likely result in an error. diff --git a/vignettes/release_notes_v1.3.Rmd b/vignettes/release_notes_v1.3.Rmd index 25bf7ec..9120d8d 100644 --- a/vignettes/release_notes_v1.3.Rmd +++ b/vignettes/release_notes_v1.3.Rmd @@ -19,7 +19,7 @@ vignette: > This release of Cerebro/cerebroApp comes with some major changes, enough to justify a dedicated article. Here, I will go over the changes and motivations. -TL;DR: Maybe the best thing to happen in 2020! +TL;DR: Possibly the best thing to happen in 2020! # Flexible grouping variables @@ -143,7 +143,7 @@ In the "Marker genes" and "Enriched pathways" tabs, in addition to the group lev Marker genes -Moreover, it is now possible to export results for marker genes / differentially expressed genes and enriched pathways generated other tools. You can find an example on how to do that in this vignette: [Export and visualize custom tables](export_and_visualize_custom_tables.html). +Moreover, it is now possible to export results for marker genes / differentially expressed genes and enriched pathways generated other tools. You can find an example on how to do that in this vignette: [Export and visualize custom tables and plots](export_and_visualize_custom_tables_and_plots.html). As in previous versions of Cerebro, you can export the tables in CSV or Excel format and hide columns using the "Column visibility" button. @@ -173,13 +173,19 @@ The "States by group" panel works similar to the "Composition by other group" in In the "Expression metrics" panel you can visualize the number of transcripts, number of expressed genes, and the percentage of mitochondrial and ribosomal transcripts for each state. +__Note:__ This tab is only visible if any trajectory is present in the currently loaded data set. + ## Extra material -In some cases, it is useful to share material with Cerebro users that doesn't fit into any of the existing categories. For those cases, a new tab called "Extra material" has been created. It will only appear if extra material is present in the data set. At the moment, only tables (data frames) can be exported as extra material, but support for other types of content can be added in the future upon user request. You can see an example below: +In some cases, it is useful to share material with Cerebro users that doesn't fit into any of the existing categories. For those cases, a new tab called "Extra material" has been created. It will only appear if extra material is present in the data set. At the moment, only tables (data frames) and plots (made with ggplot2) can be exported as extra material, but support for other types of content can be added in the future upon user request. You can see two examples below: + +Extra material + +Extra material -Extra material +Have a look at this vignette if you would like to know how you can export your tables as additional material: [Export and visualize custom tables and plots](export_and_visualize_custom_tables_and_plots.html). -Have a look at this vignette if you would like to know how you can export your tables as additional material: [Export and visualize custom tables](export_and_visualize_custom_tables.html). +__Note:__ This tab is only visible if any extra material is present in the currently loaded data set. ## Miscellaneous @@ -208,7 +214,7 @@ I prepared a couple of vignettes to highlight some of the new features and optio * [The cerebroApp workflow (Seurat)](cerebroApp_workflow_Seurat.html) * [Export an SCE/SingleCellExperiment object](export_a_data_set_in_SCE_format.html) -* [Export and visualize custom tables](export_and_visualize_custom_tables.html) +* [Export and visualize custom tables and plots](export_and_visualize_custom_tables_and_plots.html) * [Launch Cerebro with pre-loaded data set](launch_cerebro_with_pre-loaded_data_set.html) * [Host Cerebro on shinyapps.io](host_cerebro_on_shinyapps.html) * [Control access to Cerebro with a login page](control_access_to_cerebro_with_a_login_page.html)