Preset for cell-barcoded PCR TCR amplicons

[racng]

I have a TCR amplicon library made from single cells with primers in V and C regions. Cell-barcodes were inserted after C Region, and another ID sequence inserted before the V region (sequence differs for TRAV and TRAB). R1 starts form the UMI+C region, and R2 starts from the ID+V region.
I considered using the generic-tcr-amplicon-umi preset but I was concerned that it would get confused by TRA and TRB genes sharing a barcode. What preset should I use that would allow for cell-barcode correction without handling UMI?

Also, what preset should I use for alignment? A lot of TCR tutorials in documentation uses -p default_4.0. Should I use that or generic-tcr-amplicon?

I have set floatLeftBound=true for gene regions where primers are used as I saw in the documentation guides.
However, I am curious about why the default values use local alignment for V right bound and J left bound, but global alignment for C Left Bound?

mixcr align \
  --tag-pattern "^(CELL:N{6})(R1:*) \ ^tacaggaagcctcagca(R2:*) | ^caggagggctcggca(R2:*)"
  -OvParameters.geneFeatureToAlign="VTranscriptWithout5UTRWithP" #Not 5'RACE
  -OvParameters.parameters.floatingLeftBound=true #V-primers are used
  -OvParameters.parameters.floatingRightBound=true #default
  -OjParameters.parameters.floatingLeftBound=true #default
  -OjParameters.parameters.floatingRightBound=false #Reverse primers are located in C-gene region
  -OcParameters.parameters.floatingLeftBound=false #default
  -OcParameters.parameters.floatingRightBound=true #Reverse primers are located in C-gene region

After alignment, what settings should I use for refineTagsAndSort to correct the CELL barcodes?

Many thanks! I appreciate all the features, documentation, and examples you provided!

[PoslavskySV]

Hi Rachel,

thanks for reaching us. We'll look into this and provide you a guidelines tomorrow.

BR,
Stan

[racng]

I realized some of the under the hood parameters are not available. I ended up trying this out and it seemed to work:

mixcr align \
	-f \
	-p generic-tcr-amplicon --rna --species hsa \
	--floating-left-alignment-boundary --floating-right-alignment-boundary C\
	--tag-pattern "^(CELL:N{6})(R1:*) \ ^tacaggaagcctcagca(R2:*) | ^caggagggctcggca(R2:*)" \
	--report $OUTDIR/R1R2_D10.report.txt \
	$DATADIR/raw/D10_S46_L001_R1_001.fastq.gz \
	$DATADIR/raw/D10_S46_L001_R2_001.fastq.gz \
	$OUTDIR/R1R2_D10.vdjca

mixcr refineTagsAndSort \
	-f \
	--report $OUTDIR/R1R2_D10.refine.report.txt \
	--set-whitelist CELL=file:barcode_whitelist.txt \
	$OUTDIR/R1R2_D10.vdjca \
	$OUTDIR/R1R2_D10.refined.vdjca

# Assembly with corrected barcodes
mixcr assemble \
	-f \
	-OassemblingFeatures="CDR3" \
	-OseparateByJ=true \
	-OseparateByV=true \
	-OseparateByC=true \
	--report $OUTDIR/R1R2_D10.refined.assemble.report.txt \
	$OUTDIR/R1R2_D10.refined.vdjca \
	$OUTDIR/R1R2_D10.refined.clns 

mixcr exportClones \
	-f \
	--split-by-tags Cell -tags cell -cellGroup \
	-readCount -readFraction \
	-nFeature CDR3 -aaFeature CDR3 -vGene -dGene -jGene -cGene \
	$OUTDIR/R1R2_D10.refined.clns \
	$OUTDIR/R1R2_D10.refined.tsv 

I also tried adding --cell-level when running assemble but it didn't make a difference. Is it aware of cell tags by default?
It is weird that the exported clone table have only null values under "Cell Group".

I would still appreciate whatever advice you have. Thanks!

[Alex-Davydov]

Hi,
In the attachment you can find a preset for your type of single cell vdj protocol. You should put this YAML file in the folder where you run MiXCR (the whitelist file named barcode_whitelist.txt also should be there). Then run mixcr analyze with the following command:
mixcr analyze local:preset-sc-tcr-cdr3 R1.fastq(.gz) R2.fastq(.gz) output/
If you will see false positive clones/cells in the results we can adjust the filters to eliminate them.

I also tried adding --cell-level when running assemble but it didn't make a difference. Is it aware of cell tags by default?
It is weird that the exported clone table have only null values under "Cell Group".

By default no, we have various presets for assemble step for different types of data (eg tagged or not tagged). The generic-tcr-amplicon preset uses base assembler (assembler with default parameters optimised for usual rep-seq data), but for single cell data we need the one that can deal with cell barcodes.

I am looking forward to your feedback,
Best
Alex

preset-sc-tcr-cdr3.yaml.zip

[racng]

Thank you for providing the custom preset file! I have tried it on my data and it works. It looks like this new preset reduces the number of noisy clone and results in more reads for the dominant clones, which is great! I was wondering if this is a result of different filtering or correction settings in the refineTagsAndSort or assemble steps? Or is it a result of turning on cellLevel during assemble step?

[racng]

I have also sequenced this type of library using Nanopore sequencing and I want to do the same cell-level assembly. I see that there are some specific settings for aligning and assembling Nanopore reads. link. I know how to remove the R2 tag patters.

What fields should I include to optimize mixcr for nanopore? I think for the chemistry version we are using, the error rate is about 1%.

The extra configs for align in preset align-kaligner2-long-read looks very complicated and I am not sure what to incorporate.

Do I add these overides for assemble? specificMutationProbability: 0.01 makes sense

  assemble:
    inheritFrom: assemble-base
    overrides:
      clnaOutput: true
      cloneAssemblerParameters:
        badQualityThreshold: 0
        minimalQuality: 15
        cloneClusteringParameters:
          clusteringFilter:
            type: relativeConcentration
            specificMutationProbability: 0.01

[Alex-Davydov]

Hi,
In a couple of days, I will prepare the new preset for nanopore data with tags (cell barcode, umi etc), and you will be able to use it. It will be pretty much the same as what you used for Illumina data but with different aligner parameters and weakened quality filters in assemble step as you mentioned. We need to add some updates to MiXCR that are necessary for single-read data like yours.
Am I right that the nanopore read contains a cell barcode at the beginning and reverse complement of tacaggaagcctcagca and caggagggctcggca at the end?

[racng]

Thank you so much!
This is the current working tag pattern which seemed to work (without adjusting other settings yet in the yaml):

tagPattern: |
      ^N{:29}(CELLI5:N{8})tcgtcggcagcgtcagatgtgtataagagacag(CELLUMI:N{6})(R1:*)(MIUP3:tgctgaggcttcctgta)ctgtctcttatacacatctccgagcccacgagac(CELLI7:N{8})N{:24} | 
      ^N{:29}(CELLI5:N{8})tcgtcggcagcgtcagatgtgtataagagacag(CELLUMI:N{6})(R1:*)(MIUP3:tgccgagccctcctg)ctgtctcttatacacatctccgagcccacgagac(CELLI7:N{8})N{:24}

and corresponding whitelist config:

whitelists:
    CELLI5: file:i5_whitelist.txt
    CELLI7: file:i7_whitelist.txt
    CELLUMI: file:barcode_whitelist.txt

I had demultiplexed my samples based on i5/i7 index already with cutadapt, but I kept the adapters in the read for troubleshooting. So I am designating the i5/i7 index as cell barcodes instead of sample barcodes.
The 5' end adapter = i5 handle + i5 index + R1 adapter
The 3' end adapter = reverse complement of i7 handle + i7 index + R2 adapter (already transformed in the tag pattern here)
This is of course non-optimal to use illumina sample indexing for nanopore sequencing, but the library was originally prepared for Miseq. In the future we will use other sample barcodes so it will not be as complicated and I could adjust it appropriately.
The flanking N{:d} allows for partial matching of i5/i7 handles.
I don't need MIUP3 for my analysis, but I made it a group to visually separate it from the R2 adapter region.

I noticed that the bestHit for V/J gene do not have allele information.
Can I add findAlleles under pipeline:?

If I want to change the path of CELLUMI whitelist depending on the run, can I override the default parameter from the command line?

[Alex-Davydov]

Hi,
In the attachment you can find a new preset for ONT data. You can provide to MiXCR raw fast file and all steps including demultiplexing by i5 and i7 Illumina indexes will be done by analyze command. The only thing you need to do is to create sample table with sample names and corresponding i5 and i7 indexes (see example below).

Sample	TagPattern	SMPLI5	SMPLI7
Sample1		ATGCGTAT	CTGAGTTG
Sample2		CTGTGGCA	CCATTTGA

And run analysis with the following command:
mixcr analyze local:preset-ont-v1 --sample-table your_sample_table.tsv R1.fastq(.gz) result/

Can I add findAlleles under pipeline:?

No, you cannot include findAlleles in pipeline.

Hope this helps,
Alex
preset-ont-v1.yaml.zip

[racng]

Thank you for providing this preset file! One issue I encountered is that using assembleContigs changed the output when I use exportClones with -nFeatureImputed VDJTranscriptWithout5UTR. With assembleContigs included, I end up with a VDJ transcript with a lot of stop codons for the alpha chain (due to 3 extra bases), and region_not_covered for the beta chain. The imputed nucleotide feature with assembleContigs ON has a perfect match with the imputed feature with assembleContigs OFF for the last 400 bases. Is there a way to adjust the parameters for assembleContigs to ignore bad bases, and impute the rest with the reference.