Skip to content
Visualize scRNA-seq results.
C++ HTML R Tcl C JavaScript Other
Branch: master
Clone or download
Latest commit d855223 Jun 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Docker Update Dockerfile. May 9, 2019
examples
images Add data format figure. Jun 13, 2019
screenshots Update screenshots and GIF. May 11, 2019
source Update cerebroApp. Apr 29, 2019
.gitignore Rearrange example data set. Apr 29, 2019
LICENSE.md Transition to internally using cerebroApp. Mar 29, 2019
README.md Add data format figure. Jun 13, 2019
notes.md Syntax. Apr 1, 2019

README.md

Cerebro

Screenshot Cerebro: overview panel

This is the standalone version of Cerebro, cell report browser, (currently available for macOS and Windows) which allows users to interactively visualize various parts of single cell transcriptomics data without requiring bioinformatic expertise.

The core is the cerebroApp Shiny application which is bottled into a standalone app using Electron. Therefore, it can also be run on web servers and Linux machines, requiring only R and a set of dependencies.

Input data needs to be prepared using the cerebroPrepare R package which was built specifically for this purpose. It offers functionality to export a Seurat object (both v2 and v3 are supported) to the correct format in a single step. The file should be saved either with the .rds or .crb extension, indicating that internally it is an RDS object. Furthermore, the cerebroPrepare package also provides functions to perform a set of (optional) analyses, e.g. pathway enrichment analysis based on marker gene lists of groups of cells.

The exported .crb file is then loaded into Cerebro and shows all available information.

Key features:

  • Interactive 2D and 3D dimensional reductions.
  • Sample and cluster overview panels.
  • Tables of most expressed genes and marker genes for samples and clusters.
  • Tables of enriched pathways in marker gene lists.
  • Query gene(s) and gene sets from MSigDB and show their expression in dimensional reductions.
  • All plots can be exported to PNG. In addition, 2D dimensional reductions can be exported to PDF.
  • Tables can be downloaded in CSV or Excel format.

Basic examples for Seurat v2 and v3 workflows and subsequent exporting can be found in the examples folder. There you can also find the raw data and the output file that can be loaded into Cerebro.

Further screenshots can be found in the screenshots folder.

Interface panels in details

Load data

Select input file (.rds or .crb). Shows number of cells, samples, clusters, as well as experiment name and organism.

Overview

Shows 2D and 3D dimensional reductions. Cells can be colored by meta data variables, automatically coloring the cells using a categorical or continuous scale. Cells can be randomly down-sampled to improve performance.

Samples

Shows sample-centric perspective of data.

  • Composition of samples by cluster as table and plot.
  • Distribution of number of transcripts and expressed genes by sample.
  • Distribution of mitochondrial and ribosomal gene expression by sample (if it was computed with cerebroPrepare.
  • Cell cycle by sample, either determined by the Seurat function or using Cyclone (if it was computed and assigned during exporting).

Clusters

Shows cluster-centric perspective of data. See info about Samples panel above for more details.

Most expressed genes

If computed in cerebroPrepare, provides tables of most expressed genes by sample and cluster.

Marker genes

If computed in cerebroPrepare, provides tables of marker genes by sample and cluster.

Enriched pathways

If computed in cerebroPrepare, provides tables of enriched pathways in marker gene lists of samples and clusters.

Gene expression

Allows to show the expression of specified genes (showing the average per cell if multiple genes) in the data set. Calculation is triggered after pressing SPACE or ENTER. Multiple genes must be submitted in separate lines or separated by either space, comma, semicolon. Shows which genes are available or missing (or misspelled) in data set. Expression levels are shown in dimensional reductions and as violin plots for every sample and cluster. Average expression across all cells of the 50 most expressed genes (of the ones specified by the user) are shown as well to quickly spot which genes drive the color scale.

Gene set expression

Basically the same as the gene expression panel except that it allows to select gene sets from MSigDB (requires internet connection). Only available for human and mouse data.

Gene ID conversion

Provides table that allows to convert gene IDs and names. Includes GENCODE identifier, ENSEMBL identifier, HAVANA identifier, gene symbol and gene type. Only available for mouse and human. Based on GENCODE annotation version M16 (mouse) and version 27 (human).

Analysis info

Overview of parameters that were used during the analysis, as long as they were provided. Also shows list of mitochondrial and ribosomal genes present in the data set if computed with cerebroPrepare.

Motivation

Single cell RNA-sequencing data is rich and complex. Allowing experimental biologists to explore the results is beneficial for the iterative scientific process of performing analysis and deriving conclusions. Cerebro provides an easy way to access the data without any bioinformatic expertise.

Installation

Download Cerebro for your OS from here, unpack and launch. Currently, Cerebro is available only for macOS and Windows.

Users of all platforms can alternatively launch the app through the dedicated cerebroApp R package or romanhaa/cerebro Docker container.

Alternative 1: cerebroApp R package

Requirements: R (version 3.5.1 or higher)

A convenient IDE would be RStudio. Make sure to install cerebroApp using BiocManager::install() to get the most recent version of dependencies on Bioconductor.

BiocManager::install("romanhaa/cerebroApp")
cerebroApp::launchApp()

Alternative 2: romanhaa/cerebro Docker container

Requirements: Docker

docker pull romanhaa/cerebro:latest
docker run -p 8080:8080 -v <export_folder>:/plots romanhaa/cerebro
# for example
docker run -p 8080:8080 -v ~/Desktop:/plots romanhaa/cerebro

Then, in your browser you navigate to the address printed in the terminal, e.g. 127.0.0.1:8080.

Note 1: Binding a local directory with -v <export_folder>:/plots is only necessary if you want to export dimensional reductions from Cerebro.

Note 2: If you need to change the port, you can do that like this:

docker run -p <port_of_choice>:8080 -v <export_folder>:/plots romanhaa/cerebro
# OR
docker run -p <port_of_choice>:<port_of_choice> -v <export_folder>:/plots romanhaa/cerebro Rscript -e 'shiny::runApp(cerebroApp::launchApp(), port=<port_of_choice>, host="0.0.0.0", launch.browser=FALSE)'

pbmc_10k_v3 example data set

Find documentation and commands for the pbmc_10k_v3 example data set here.

Conversion of other single cell data formats

Currently, the cerebroPrepare R package only provides a functions to export a Seurat (v2 or v3) object to the Cerebro input file. However, there are a few other important single cell data storage formats, e.g. AnnData (used by scanpy, SingleCellExperiment (used by scran and scater, and CellDataSet (used by Monocle). Ideally, we would like to provide export functions for all of those formats. However, the reality is, especially considering that these formats can change with updates of the respective packages, this would correspond to an enormous maintance effort. For the moment, we can take advantage of the conversion and export functions that some of those packages mentioned before already provide.

In the figure below, we highlight how you can generate the Cerebro input file from any of the four major formats.

Single cell data formats

Technical notes

Building from source

On macOS

To package Cerebro you need Git and Node.js (which comes with npm) installed on your computer. Then, from the command line, run:

# clone this repository
git clone https://gitlab.com/romanhaa/Cerebro.git
# install Electron packager
npm install electron-packager --global
# go into the repository
cd Cerebro
# install dependencies
npm install
# run the app
npm start
# build the app
npm run package-mac

To build the Windows version under macOS it is necessary to install Wine. I experienced problems with missing libraries of the stable version (4.0) so I recommend to use the developers version (4.4) using Homebrew:

brew tap caskroom/versions
brew update
brew install caskroom/versions/wine-devel
npm run package-win

On Windows

If you're using Linux Bash for Windows, see this guide or use node from the command prompt.

Troubleshooting

  • If the app shows a blank/white window, press CMR+R (macOS) or CTRL+R (Windows) to refresh the page. Especially on slower machines it can happen that the interface loads before the Shiny application is launched.

Credits

Contribute

To report any bugs, submit patches, or request new features, please log an issue through the issue tracker. For direct inquiries, please send an email to roman.hillje@ieo.it.

License

Copyright (c) 2019 Roman Hillje

The MIT License (MIT)

You can’t perform that action at this time.