Build Status

conos

Conos: Clustering On Network Of Samples

Basics of using conos

Given a list of individual processed samples (pl), conos processing can be as simple as this:

# Construct Conos object, where pl is a list of pagoda2 objects 
con <- Conos$new(pl)

# Build joint graph
con$buildGraph()

# Find communities
con$findCommunities()

# Generate embedding
con$embedGraph()

# Plot joint graph
con$plotGraph()

# Plot panel with joint clustering results
con$plotPanel()

To see more documentation on the class Conos, run ?Conos.

Tutorials

Please see the following tutorials for detailed examples of how to use conos:

Conos walkthrough:

Adjustment of alignment strength with conos:

Integration with Scanpy:

Note that for integration with Scanpy, users need to save conos files to disk from an R session, and then load these files into Python.

Save conos for Scanpy: * HTML version * Markdown version

Load conos files into Scanpy: * Jupyter Notebook

Integrating RNA-seq and ATAC-seq with conos:

Running RNA velocity on a Conos object

First of all, in order to obtain an RNA velocity plot from a Conos object you have to use the dropEst pipeline to align and annotate your single-cell RNA-seq measurements. You can see this tutorial and this shell script to see how it can be done. In this example we specifically assume that when running dropEst you have used the -V option to get estimates of unspliced/spliced counts from the dropEst directly. Secondly, you need the velocyto.R package for the actual velocity estimation and visualisation.

After running dropEst you should have 2 files for each of the samples: - sample.rds (matrix of counts) - sample.matrices.rds (3 matrices of exons, introns and spanning reads)

The .matrices.rds files are the velocity files. Load them into R in a list (same order as you give to conos). Load, preprocess and integrate with conos the count matrices (.rds) as you normally would. Before running the velocity, you must at least create an embedding and run the leiden clustering. Finally, you can estimate the velocity as follows:

### Assuming con is your Conos object and cms.list is the list of your velocity files ###

library(velocyto.R)

# Preprocess the velocity files to match the Conos object
vi <- velocityInfoConos(cms.list = cms.list, con = con, 
                        n.odgenes = 2e3, verbose = TRUE)

# Estimate RNA velocity
vel.info <- vi %$%
  gene.relative.velocity.estimates(emat, nmat, cell.dist = cell.dist, 
                                   deltaT = 1, kCells = 25, fit.quantile = 0.05, n.cores = 4)

# Visualise the velocity on your Conos embedding 
# Takes a very long time! 
# Assign to a variable to speed up subsequent recalculations
cc.velo <- show.velocity.on.embedding.cor(vi$emb, vel.info, n = 200, scale = 'sqrt', 
                                          cell.colors = ac(vi$cell.colors, alpha = 0.5), 
                                          cex = 0.8, grid.n = 50, cell.border.alpha = 0,
                                          arrow.scale = 3, arrow.lwd = 0.6, n.cores = 4, 
                                          xlab = "UMAP1", ylab = "UMAP2")

# Use cc=cc.velo$cc when running again (skips the most time consuming delta projections step)
show.velocity.on.embedding.cor(vi$emb, vel.info, cc = cc.velo$cc, n = 200, scale = 'sqrt', 
                               cell.colors = ac(vi$cell.colors, alpha = 0.5), 
                               cex = 0.8, arrow.scale = 15, show.grid.flow = TRUE, 
                               min.grid.cell.mass = 0.5, grid.n = 40, arrow.lwd = 2,
                               do.par = F, cell.border.alpha = 0.1, n.cores = 4,
                               xlab = "UMAP1", ylab = "UMAP2")

Installation

To install the latest version of conos, use:

install.packages('devtools')
devtools::install_github('kharchenkolab/conos', build_vignettes = TRUE)

Please note that the package conos depends on data in a data package (conosPanel) that is available through a drat repository on GitHub. To use the conos package, you will need to install conosPanel. There are two equally valid options to install this package:

  1. Users could install conosPanel by adding the drat archive to the list of repositories your system will query when adding and updating R packages. Once you do this, you can install conosPanel with install.packages(), using the command:
library(drat)
addRepo("kharchenkolab")
install.packages("conosPanel")

The following command is also a valid approach:

install.packages('conosPanel', repos='https://kharchenkolab.github.io/drat/', type='source')

Please see the drat documentation for more comprehensive explanations and vignettes.

  1. Another way to install the package conosPanel is to use devtools::install_github():
library(devtools)
install_github("kharchenkolab/conosPanel")

Note: If you are using pagoda2, you should also install the auxiliary package p2data:

install.packages('p2data', repos='https://kharchenkolab.github.io/drat/', type='source')

System dependencies

The dependencies are inherited from pagoda2:

Ubuntu dependencies

To install system dependencies using apt-get, use the following:

sudo apt-get update
sudo apt-get -y install libcurl4-openssl-dev libssl-dev
Red Hat-based distributions dependencies

For Red Hat distributions using yum, use the following command:

yum install openssl-devel libcurl-devel
Mac OS

Using the Mac OS package manager Homebrew, try the following command:

brew install openssl curl-openssl

(You may need to run brew uninstall curl in order for brew install curl-openssl to be successful.)

As of version 1.3.1, conos should successfully install on Mac OS. However, if there are issues, please refer to the following wiki page for further instructions on installing conos with Mac OS: Installing conos for Mac OS

Running conos via Docker

If your system configuration is making it difficult to install conos natively, an alternative way to get conos running is through a docker container.

Note: On Mac OS X, Docker Machine has Memory and CPU limits. To control it, please check instructions either for CLI or for Docker Desktop.

Ready-to-run Docker image

The docker distribution has the latest version and also includes the pagoda2 package. To start a docker container, first install docker on your platform and then start the pagoda2 container with the following command in the shell:

docker run -p 8787:8787 -e PASSWORD=pass pkharchenkolab/conos:latest

The first time you run this command, it will download several large images so make sure that you have fast internet access setup. You can then point your browser to http://localhost:8787/ to get an Rstudio environment with pagoda2 and conos installed (please log in using credentials username=rstudio, password=pass). Explore the docker –mount option to allow access of the docker image to your local files.

Note: If you already downloaded the docker image and want to update it, please pull the latest image with:

docker pull pkharchenkolab/conos:latest

Building Docker image from the Dockerfile

If you want to build image by your own, download the Dockerfile (available in this repo under /dockers) and run to following command to build it:

docker build -t conos .

This will create a “conos” docker image on your system (please be patient, as the build could take approximately 30-50 minutes to finish). You can then run it using the following command:

docker run -d -p 8787:8787 -e PASSWORD=pass --name conos -it conos

References

If you find this software useful for your research, please cite the corresponding paper:

Barkas N., Petukhov V., Nikolaeva D., Lozinsky Y., Demharter S., Khodosevich K., & Kharchenko P.V. 
Joint analysis of heterogeneous single-cell RNA-seq dataset collections. 
Nature Methods, (2019). doi:10.1038/s41592-019-0466-z

The R package can be cited as:

Viktor Petukhov, Nikolas Barkas, Peter Kharchenko, and Evan
Biederstedt (2021). conos: Clustering on Network of Samples. R
package version 1.4.0.