TITLE: Instructional tutorial for using demuxlet
AUTHORS: Hyun Min Kang, Meena Subramaniam, Sasha Targ, Michelle Nguyen, Lenka Maliskova, Elizabeth McCarthy, Eunice Wan, Simon Wong, Lauren Byrnes, Cristina M Lanata, Rachel E Gate, Sara Mostafavi, Alexander Marson, Noah Zaitlen, Lindsey A Criswell, Chun Jimmie Ye

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block"><span style = "font-weight:bold;">Genetic multiplexing of barcoded single cell RNA-seq</span></div><div class = "text-block"><span style = "font-weight:bold;">Introduction</span></div><div class = "text-block"><span style = "font-weight:bold;font-style:italic;">demuxlet </span><span>is a software tool to deconvolute sample identity and identify multiplets when multiple samples are pooled by barcoded single cell sequencing.</span><span style = "font-weight:bold;font-style:italic;">demuxlet </span><span>takes (1) a SAM/BAM/CRAM file produced by the standard 10x sequencing platform, or any other barcoded single cell RNA-seq (with proper --tag-UMI and --tag-group) options (2) a VCF/BCF file containing the genotype (GT), posterior probability (GP), or genotype likelihood (GL) to assign each barcode to a specific sample (or a pair of samples) in the VCF file.</span></div><div class = "text-block"><span style = "font-weight:bold;">Tutorial for demuxlet</span></div><div class = "text-block"><span>This tutorial provides streamlined instructions for using the tool </span><span style = "font-weight:bold;">demuxlet</span><span>. For a more detailed description of all of the options available to use with </span><span style = "font-weight:bold;">demuxlet</span><span>, please refer to the README (attached in .zip file). </span><span style = "font-weight:bold;">demuxlet </span><span>has several dependencies and this tutorial provides steps to use a docker instance to minimize compatibility issues and an alternative of installing demuxlet from source. </span></div><div class = "text-block"><span style = "font-weight:bold;">demuxlet </span><span>is a software tool to deconvolute sample identity and identify multiplets when multiple samples are pooled by barcoded single cell sequencing. </span><span style = "font-weight:bold;">demuxlet </span><span>requires the following input files:</span></div><div class = "text-block"><ol style = "list-style-type: decimal;"><li style = "counter-reset:ol0;"><span>a SAM/BAM/CRAM file produced by the standard 10x sequencing platform, or any other barcoded single cell RNA-seq (with proper </span><span style = "font-weight:bold;">--tag-UMI </span><span>and </span><span style = "font-weight:bold;">--tag-group</span><span>) options.</span></li><li style = "counter-reset:ol0;">a VCF/BCF file containing the genotype (GT), posterior probability (GP), or genotype likelihood (GL) to assign each barcode to a specific sample (or a pair of samples) in the VCF file.</li></ol></div></div>

[STEPS]
?. [Getting Started]
Please select between the two following options: 1. Installating from Docker2. Installing from source
?. [Getting Started]
Running demuxlet from dockerWe have created a docker container at yimmieg/demuxlet to run demuxlet through docker.You can run it with$ docker run -v path/to/tutorial:/data yimmieg/demuxlet --sam /data/$bam --vcf /data/$vcf --field $(GT or GP or PL) --out /data/$filename
Add bam file name for $bam and vcf file name for $vcf. Use  or  if vcf file is compressed.The options for --field are individual genotypes (GT), posterior probability (GP), or genotype likelihood (PL). If using GT  --field option for, you must include --geno-error, which is the genotype error rate.
?. [Getting Started]
demuxlet outputThe demuxlet software produces three output files.[prefix].best The .best file contains the assignments of the best sample identity (singlet: SNG-; doublet: DBL-; ambiguous: AMB-) in the BEST column for each cell barcode identified in the BARCODE column along with details of the statistics used to determine the best identity.The [prefix].single file contains the statistics for matching each cell with each possible sampleFor complete descriptions of the columns in each output file, please see the demuxlet README.
?. [Analyzing the sample dataset]
Create directory and download datasetsNow, let's first download the data we need. We are now providing a one-stop-shop to download all of the data you need for the tutorial:https://ucsf.box.com/s/vg1bycvsjgyg63gkqsputprq5rxzjl6k. After downloading and unzipping (it's BIG), you should have a directory called demuxlet.tutorial.
?. [Analyzing the sample dataset]
Run demuxlet$ cd demuxlet.tutorial $ docker run -v ./:/data yimmieg/demuxlet --sam /data/jurkat_293t_downsampled_n500_full_bam.bam --vcf /data/jurkat_293t_exons_only.vcf --field GT --out data/jurkat_293t_demuxlet
?. [Analyzing the sample dataset]
Compare the called genotypes vs transcriptome dataIn this analysis, we will use R to produce a t-SNE (t-Distributed Stochastic Neighbor Embedding) plot of the cells from the 293T:Jurkat 10x experiment with the cells colored by the assignments from the demuxlet pipeline.library(ggplot2); library(data.table);  ## let's read in the barcodes tsne demuxlet ## let's filter for the barcodes that we sampled  df ggplot(aes(tsne1,tsne2,color=cell.type),data=df)+geom_point()
After this, you should get the following image:
?. [Analyzing the sample dataset]
Let's also take a look at the doublets.ggplot(aes(tsne1,tsne2,color=doublet),data=df)+geom_point()
After that, you should get the following image:
?. [Getting Started]
Installing dockerFirst, get docker for whatever platform you feel comfortable with: https://www.docker.com/get-started
?. [Getting Started]
Before installing demuxlet, you need to install htslib in the same directory you want to install demuxlet (i.e. demuxlet and htslib should be siblings).After installing htslib, you can clone the current snapshot of this repository to install as well$ git clone https://github.com/statgen/demuxlet.git $ cd demuxlet $ autoreconf -vfi $ ./configure  (with additional options such as --prefix) $ make $ make install (may require root privilege)
Remember to add demuxlet to $PATH
?. [Analyzing the sample dataset]
Create directory and download datasetsNow, let's first download the data we need. We are now providing a one-stop-shop to download all of the data you need for the tutorial: https://ucsf.box.com/s/vg1bycvsjgyg63gkqsputprq5rxzjl6k. After downloading and unzipping (it's BIG), you should have a directory called demuxlet.tutorial.
?. [Analyzing the sample dataset]
Run demuxlet$ cd demuxlet.tutorial $ demuxlet --sam /data/jurkat_293t_downsampled_n500_full_bam.bam --vcf /data/jurkat_293t_exons_only.vcf --field GT --out data/jurkat_293t_demuxlet
?. [Analyzing the sample dataset]
Compare the called genotypes vs transcriptome dataIn this analysis, we will use R to produce a t-SNE (t-Distributed Stochastic Neighbor Embedding) plot of the cells from the 293T:Jurkat 10x experiment with the cells colored by the assignments from the demuxlet pipeline.library(ggplot2); library(data.table);  ## let's read in the barcodes tsne demuxlet ## let's filter for the barcodes that we sampled  df ggplot(aes(tsne1,tsne2,color=cell.type),data=df)+geom_point()
After this, you should get the following image:
?. [Analyzing the sample dataset]
Let's also take a look at the doublets.ggplot(aes(tsne1,tsne2,color=doublet),data=df)+geom_point()
After that, you should get the following image:
?. [Analyzing the sample dataset]
Create directory and download datasetsNow, let's first download the data we need. We are now providing a one-stop-shop to download all of the data you need for the tutorial: https://ucsf.box.com/s/vg1bycvsjgyg63gkqsputprq5rxzjl6k. After downloading and unzipping (it's BIG), you should have a directory called demuxlet.tutorial.
?. [Analyzing the sample dataset]
Run demuxlet$ cd demuxlet.tutorial $ docker run -v ./:/data yimmieg/demuxlet --sam /data/jurkat_293t_downsampled_n500_full_bam.bam --vcf /data/jurkat_293t_exons_only.vcf --field GT --out data/jurkat_293t_demuxlet
?. [Analyzing the sample dataset]
Compare the called genotypes vs transcriptome dataIn this analysis, we will use R to produce a t-SNE (t-Distributed Stochastic Neighbor Embedding) plot of the cells from the 293T:Jurkat 10x experiment with the cells colored by the assignments from the demuxlet pipeline.library(ggplot2); library(data.table);  ## let's read in the barcodes tsne demuxlet ## let's filter for the barcodes that we sampled  df ggplot(aes(tsne1,tsne2,color=cell.type),data=df)+geom_point()
After this, you should get the following image:
?. [Analyzing the sample dataset]
Let's also take a look at the doublets.ggplot(aes(tsne1,tsne2,color=doublet),data=df)+geom_point()
After that, you should get the following image:
?. [Getting Started]
Running demuxlet from dockerWe have created a docker container at yimmieg/demuxlet to run demuxlet through docker.You can run it with$ docker run -v path/to/tutorial:/data yimmieg/demuxlet --sam /data/$bam --vcf /data/$vcf --field $(GT or GP or PL) --out /data/$filename