Repo for the FastCAR (Fast Correction of Ambient RNA) R package
Go to file
MarijnBerg 42b2d340c5 Added changes to readme 2021-11-01 16:41:25 +01:00
Images Added changes to readme 2021-11-01 16:41:25 +01:00
R Swapped base R plots for ggplot 2021-11-01 14:42:49 +01:00
man Commiting just the actual package code 2020-03-25 15:18:06 +01:00
.Rbuildignore Added changes to readme 2021-11-01 16:41:25 +01:00
.gitignore Added changes to readme 2021-11-01 16:41:25 +01:00
DESCRIPTION Changed the DESCRIPTION to include dependencies 2020-03-26 10:49:56 +01:00
FastCAR.Rproj Improved Readme 2020-03-26 11:51:08 +01:00
NAMESPACE Improved Readme 2020-03-26 11:51:08 +01:00
README.md Added changes to readme 2021-11-01 16:41:25 +01:00

README.md

FastCAR

FastCAR is an R package to remove ambient RNA from cells in droplet based single cell RNA sequencing data.

Installation

FastCAR can be installed from git with the following command.

devtools::install_git("https://git.web.rug.nl/P278949/FastCAR")

Running FastCAR is quite simple. First load the library and dependencies.

library(Matrix)
library(Seurat)
library(qlcMatrix)
library(pheatmap)
library(ggplot2)
library(gridExtra)

Specify the locations of the expression matrices

cellExpressionFolder  = c("Cellranger_output/sample1/filtered_feature_bc_matrix/")
fullMatrixFolder      = c("Cellranger_output/sample1/raw_feature_bc_matrix/")

Load both the cell matrix and the full matrix

cellMatrix     = read.cell.matrix(cellExpressionFolder)
fullMatrix     = read.full.matrix(fullMatrixFolder)

The following functions give an idea of the effect that different settings have on the ambient RNA profile. These are optional as they do take a few minutes and the default settings work fine Plotting the number of empty droplets, the number of genes identified in the ambient RNA, and the number of genes that will be corrected for at different UMI cutoffs,

ambProfile = describe.ambient.RNA.sequence(fullCellMatrix = fullMatrix, 
                                           start = 10, 
                                           stop = 500, 
                                           by = 10, 
                                           contaminationChanceCutoff = 0.05)
                                           
plot.ambient.profile(ambProfile)

picture

The actual effect on the chances of genes affecting your DE analyses can be determined and visualized with the following function

  
  correctionEffectProfile = describe.correction.effect(allExpression, cellExpression, 50, 500, 10, 0.05)
  
  plot.correction.effect.chance(correctionEffectProfile)
  

picture

How many reads will be removed of these genes can be visualized from the same profile


  plot.correction.effect.removal(correctionEffectProfile)

picture

Set the empty droplet cutoff and the contamination chance cutoff

The empty droplet cutoff is the number of UMIs a droplet can contain at the most to be considered empty. 100 works fine but we tested this method in only one tissue. For other tissues these settings may need to be changed. Increasing this number also increases the highest possible value of expression of a given gene. As the correction will remove this value from every cell it is adviced not to set this too high and thereby overcorrect the expression in lowly expressing cells.

The contamination chance cutoff is the allowed probability of a gene contaminating a cell. As we developed FastCAR specifically for differential expression analyses between groups we suggest setting this such that not enough cells could be contaminated to affect this. In a cluster of a thousand cells divided into two groups there would be 2-3 cells per group with ambient RNA contamination of any given gene. Such low cell numbers are disregarded for differential expression analyses.

There is an experimental function that gives a recommendation based on the ambient profiling results. This selects the first instance of the maximum number of genes being corrected for. I have no idea yet if this is actually a good idea.

emptyDropletCutoff = recommend.empty.cutoff(ambProfile)
emptyDropletCutoff        = 150 
contaminationChanceCutoff = 0.005

Determine the ambient RNA profile and remove the ambient RNA from each cell

ambientProfile = determine.background.to.remove(fullMatrix, cellMatrix, emptyDropletCutoff, contaminationChanceCutoff)
cellMatrix     = remove.background(cellMatrix, ambientProfile)

This corrected matrix can be used to to make a Seurat object

seuratObject = CreateSeuratObject(cellMatrix) 

Authors

License

This project is licensed under the GPL-3 License - see the LICENSE.md file for details

Changelog

v0.1

First fully working version of the R package

v0.2

Fixed function to write the corrected matrix to file. Added readout of which genes will be corrected for and how many reads will be removed per cell Added some input checks to functions

v0.2

Fixed a bug that caused FastCAR to be incompatible with biobase libraries Added better profiling to determine the effect of different settings on the corrections Swapped base R plots for ggplot2 plots