Question about custom preset (Seq-Well)

[iommuno]

Dear developers,

I have a question about custom presets. I have scTCR-seq Seq-Well data, which has the following format:

Read 1 uses custom sequencing primers that lie right at the outer edge of the constant region genes.

I tried mixcr with this command:
mixcr analyze generic-tcr-amplicon-umi -f --species mmu --dna --floating-left-alignment-boundary --rigid-right-alignment-boundary C --tag-pattern "^(R1:*)\^(CELL:N{12})(UMI:N{8})" /path/to/TCR_R1.fastq.gz /path/to/TCR_I1.fastq.gz /path/to/outdir/

Mixcr align runs through, but mixcr refineTagsAndSort stops with this error:
4.2.0; built=Thu Jan 26 20:40:26 CET 2023; rev=b0f194e0c6; lib=repseqio.v2.1 picocli.CommandLine$ExecutionException: Error while running command refineTagsAndSort java.lang.IllegalArgumentException: Unexpected filter tag request. Requested UMI but next level is CELL. at com.milaboratory.mixcr.cli.Main.registerExceptionHandlers$lambda-11(Main.kt:301) at picocli.CommandLine.execute(CommandLine.java:2088) at com.milaboratory.mixcr.cli.CommandAnalyze$Cmd.run0(CommandAnalyze.kt:310) at com.milaboratory.mixcr.cli.MiXCRCommand.run(MiXCRCommand.kt:36) at picocli.CommandLine.executeUserObject(CommandLine.java:1939) at picocli.CommandLine.access$1300(CommandLine.java:145) at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2358) at picocli.CommandLine$RunLast.handle(CommandLine.java:2352) at picocli.CommandLine$RunLast.handle(CommandLine.java:2314) at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2179) at picocli.CommandLine$RunLast.execute(CommandLine.java:2316) at com.milaboratory.mixcr.cli.Main.registerLogger$lambda-25(Main.kt:387) at picocli.CommandLine.execute(CommandLine.java:2078) at com.milaboratory.mixcr.cli.Main.main(Main.kt:87) Caused by: java.lang.IllegalArgumentException: Unexpected filter tag request. Requested UMI but next level is CELL. at com.milaboratory.mitool.refinement.TagCorrector$FilterGrouping.getKeyExtractor(TagCorrector.kt:950) at com.milaboratory.mitool.refinement.gfilter.KeyedFilterContext.getKeyExtractor(Filter.kt:96) at com.milaboratory.mitool.refinement.gfilter.GroupFilter.filter(GroupFilter.kt:277) at com.milaboratory.mitool.refinement.TagCorrector.calculate(TagCorrector.kt:656) at com.milaboratory.mixcr.cli.CommandRefineTagsAndSort$Cmd.run1(CommandRefineTagsAndSort.kt:360) at com.milaboratory.mixcr.cli.MiXCRCommandWithOutputs.run0(MiXCRCommandWithOutputs.kt:69) at com.milaboratory.mixcr.cli.MiXCRCommand.run(MiXCRCommand.kt:36) at picocli.CommandLine.executeUserObject(CommandLine.java:1939) at picocli.CommandLine.access$1300(CommandLine.java:145) at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2358) at picocli.CommandLine$RunLast.handle(CommandLine.java:2352) at picocli.CommandLine$RunLast.handle(CommandLine.java:2314) at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2179) at picocli.CommandLine$RunLast.execute(CommandLine.java:2316) at com.milaboratory.mixcr.cli.Main.registerLogger$lambda-25(Main.kt:387) at picocli.CommandLine.execute(CommandLine.java:2078) ... 12 more

I am not sure if generic-tcr-amplicon-umi is meant to be run with both cell barcode and UMI. Can you help me figure out the correct preset for this type of data?

[PoslavskySV]

Hi Ioanna,

generic-tcr-amplicon-umi is not suited for single cell analysis. We'll take a look and provide you a correct command to use (or a preset) shortly.

BR,
Stan

[iommuno]

Hi Stan,

Thank you very much! Really appreciate you always giving such quick user feedback.

Best,
Ioanna

[iommuno]

Also, sorry for putting this in 'Issues'. If I had noticed the 'Discussions' tab earlier, I would have posted the question here.

[Alex-Davydov]

Hi Ioanna,
In the attachment you can find a preset for SeqWell vdj data. You should put this YAML file in the folder where you run MiXCR and run mixcr analyze using the following command:
mixcr analyze local:seqwell_v1 --species <species> R1.fastq(.gz) I1.fastq(.gz) output/

If you have a cell barcodes whitelist we can add it to the preset. If you will realise that you have false positive clones/cells in the results we can adjust the filters to eliminate the artificial clones/cells.
I am looking forward to your feedback,
Best
Alex

seqwell_v1.yaml.zip

[PoslavskySV]

@iommuno Did you have a chance to test this preset?

[iommuno]

Hi Alex, hi Stan,

No, I'm really sorry I haven't had the chance to test it yet. It is on my to do list for this week though. I will let you know how it went by early next week. Would that be ok?

Best,
Ioanna

[PoslavskySV]

Of course - thank you!

[iommuno]

Hi Alex, hi Stan,

Thanks for providing me with a Seq-Well preset. I just ran it and it went through without any problems! The output also looks reasonable, as far as I can tell.

@Alex-Davydov : Just for my understanding, how would you define and identify false positive clones/cells? Are you looking at this in a whitelist context - so a cell/clone is false positive because it's cell barcode is not within a range of possible options?
Or is there a different way to assess this? I don't think there is a barcode whitelist for this type of data (split-and-pool randomly generated 12bp barcodes), so I'm not sure how to evaluate this. Let me know how you would approach it.

Again, thanks for helping me out with this! I really appreciate your help.

Best,
Ioanna

[Alex-Davydov]

Hi Ioanna,
Each cell can have maximum 2 TRB and 2 TRA chains (or 2 IGH - 2IGK/IGL), but often there are more and we need to filter out these erroneous clones. Two filters are already in your preset: filtering UMI and cells by reads count and UMI count respectively (automatic thresholding). In refineTagsAndSort report in section "Final report" you can find the actual values of these thresholds (Nested filter 0 corresponds to reads per UMI, nested filter 1 - UMIs per cell). Check the number of reads that were accepted after reads per UMI filter: value from the line "Records weight accepted" should be more then 90%, if less it means that the library has not enough sequencing depth. In this case it is better to turn of these filters (in the attachment you can find the preset without filters).
Additionally we can filter erroneous clones/cells using different strategies:

• using cumulative top of number of reads/UMIs per cell (or even per cell and immunological chain) to filter out clones which are made up of less then 5% (for example) of total reads/UMIs in cell.
• using the coverage of VDJRegion to filter out UMIs that cover only some parts of vdj (more likely it is a some sort of contamination)
  These are the most efficient filters for single cell vdj protocols.
  Hope this helps,
  Alex

seqwell_v2.yaml.zip

[iommuno]

Hi Alex,

Thank you for explaining, that makes sense. I attach all reports of the v1 preset run with filters and the v2 preset without. For the v1 run, the ‘Records weight accepted‘ for the #0 nested filter (reads/UMI) was >97 %, so I guess the data has sufficient sequencing depth and we can keep the filters turned on. Thanks for the support!

Best,
Ioanna

v1_SW_git.align.report.txt
v1_SW_git.refine.report.txt
v1_SW_git.assemble.report.txt
v2_SW_git.align.report.txt
v2_SW_git.refine.report.txt
v2_SW_git.assemble.report.txt