How can I retrieve tags from fastq header?

[Nakyung210]

Checklist before submitting the issue:

• The issue is strongly related to the MiXCR software
• The issue can be reproduced with the most recent version of MiXCR
• There is no answer to the question in the official documentation and there is no duplicate issue in the bug tracker
• Inspection of raw alignments with exportAlignmentsPretty shows that data has the expected architecture, and sample preparation artefacts are not the reason of the problem (if this is the matter of the issue)

Expected Result

Hi,
I want to retrieve UMI and cell barcode which are located in fastq file header while running mixcr align. I've seen in the document that you can extract tag directly from the sequencing read headers using regex (red line in the image below)

\

But when I actually try to do, it keeps throwing me an error... Could you please help? My fastq file's header looks like @E250038186L1C001R00903950969 CELL=17428_17704 UMI=3F8, and "CELL" is corresponding to cell barcodes and "UMI" is corresponding to UMI.

Actual Result

I got error message saying picocli.CommandLine$ExecutionException: Error while running command align com.milaboratory.o.gh$a: Unexpected motif character: "." .*CELL=(?P<cell>[0-9_]+).*UMI=(?P<umi>[A-Z0-9]+).*

Exact MiXCR commands

mixcr align --preset generic-ht-single-cell-fragmented-with-umi --species hsa --keep-non-CDR3-alignments -OallowPartialAlignments=true --trimming-quality-threshold 0 -OvParameters.geneFeatureToAlign="VGeneWithP" -OdParameters.geneFeatureToAlign="DRegionWithP" -OjParameters.geneFeatureToAlign="JRegionWithP" -OsaveOriginalReads=true --read-id-as-cell-tag CELL --tag-pattern "CELL=(?P<cell>[0-9_]+).*UMI=(?P<umi>[A-Z0-9]+)" name_of_file.fq name_of_file.vdjca -t 30 --assemble-contigs-by VDJRegion

MiXCR report files

picocli.CommandLine$ExecutionException: Error while running command align com.milaboratory.o.gh$a: Unexpected motif character: "." .*CELL=(?P<cell>[0-9_]+).*UMI=(?P<umi>[A-Z0-9]+).*

[mizraelson]

The issue is that --tag-pattern uses MiXCR's sequence-matching language (for nucleotide bases), which doesn't accept . or standard regex syntax. For tags in the FASTQ header, the right mechanism is headerExtractors inside a local preset.

Save the file below as header-tags-sc-fragmented.yaml in your working directory, then run:

  mixcr analyze \
    local:header-tags-sc-fragmented \
    --species hsa \
    --assemble-contigs-by VDJRegion \
    name_of_file.fq \
    output_prefix \

header-tags-sc-fragmented.yaml

[Nakyung210]

Thank you,

I've tested with the mixcr analyze command that you shared earlier. But I got no clone at the end, so I've been trying to run each step one by one instead of mixcr analyze so that I know exactly which part is causing the issue.

I've successfully run until mixcr align -> mixcr refineTagsAndSort -> mixcr assemblePartial -> mixcr extend steps. But at the mixcr assemble part, I don't know how to overwrite filtering part with cumulative frequency is 95% (red arrow in the image below):

Do you mind teach me how to overwrite when running the mixcr assemble with the CLI command line?

Thank you so much for the help in advance!

[mizraelson]

You should use the preset during the align step, as this will propagate the settings to the other steps as well. To find where the data is lost, you can check the reports generated by MiXCR analyze.

[Nakyung210]

I see, thank you.

Do you mind helping me creating a preset with following parameters for steps of alignment, assemblePartial, extend, and assemble? When I run this following parameters for following steps, I got more reads.

    # Alignment
    mixcr align ${fq} ${alignment_path}/${base}.vdjca \
        --species hsa \
        --keep-non-CDR3-alignments \
        -OallowPartialAlignments=true \
        --trimming-quality-threshold 0 \
        -OvParameters.geneFeatureToAlign="VGeneWithP" \
        -OdParameters.geneFeatureToAlign="DRegionWithP" \
        -OjParameters.geneFeatureToAlign="JRegionWithP" \
        -OsaveOriginalReads=true \
        --report ${alignment_path}/${base}.align.report.txt `

    # Partial assembly (twice)
    mixcr assemblePartial -f \
        ${alignment_path}/${base}.vdjca \
        ${alignment_path}/${base}.rec1.vdjca \
        -OminimalAssembleOverlap=15 \
        --report ${alignment_path}/${base}.assemblePartial1.report.txt 
        
    mixcr assemblePartial -f \
        ${alignment_path}/${base}.rec1.vdjca \
        ${alignment_path}/${base}.rec2.vdjca \
        -OminimalAssembleOverlap=15 \
        --report ${alignment_path}/${base}.assemblePartial2.report.txt
    
    # Entend
    mixcr extend -f -Xmx200g \
        ${alignment_path}/${base}.rec2.vdjca \
        ${alignment_path}/${base}.ext.vdjca \
        --report ${alignment_path}/${base}.extend.report.txt

    # Assemble
    mixcr assemble -f -Xmx200g \
        ${alignment_path}/${base}.ext.vdjca \
        ${assemble_path}/${base}.clna \
        -OassemblingFeatures='CDR3' \
        -OseparateByC=true \
        -a \
        --report ${assemble_path}/${base}.assemble.report.txt

Thank you!