picocli.CommandLine$ExecutionException: Error while running command align java.lang.RuntimeException: Failed to override some parameter.

[Dingchunyuan]

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)

Hello,

I am writing to seek your assistance regarding an issue I encountered while running MixCR. I attempted to modify certain parameters, but unfortunately, an error occurred during the process.

Could you please provide guidance on how to correctly adjust these parameters to avoid such errors?

Thank you for your support.

Exact MiXCR commands

mixcr align \ --species hsa \ --library imgt \ -f \ -p generic-amplicon-with-umi \ -OvParameters.geneFeatureToAlign="VTranscriptWithP " \ -OallowNoCDR3PartAlignments=true \ -OallowPartialAlignments=true \ -OallowPartialAlignments=true \ --keep-non-CDR3-alignments \ --rigid-left-alignment-boundary \ --floating-right-alignment-boundary C\ --tag-pattern "^(R1:*)\\^(UMI:N{{16}})(R2:*)" \ --report results/FT100053139_L01_S009.report.txt \ --json-report results/FT100053139_L01_S009.report.json \ --assemble-clonotypes-by CDR3 \ --rna \ -OvParameters.relativeMinScore=0.7 \ -OjParameters.relativeMinScore=0.7 \ -OcParameters.relativeMinScore=0.7 \ -OvParameters.absoluteMinScore=30 \ -OjParameters.absoluteMinScore=30 \ -OcParameters.absoluteMinScore=30 \ /public/home/dingchunyuan/TCR/Rawdata/G99/FT100053139_100bp/FT100053139_L01_S009_1.fq.gz \ /public/home/dingchunyuan/TCR/Rawdata/G99/FT100053139_100bp/FT100053139_L01_S009_2.fq.gz \ ./results/FT100053139_L01_S009.vdjca
ERROR info
picocli.CommandLine$ExecutionException: Error while running command align java.lang.RuntimeException: Failed to override some parameter.

[mizraelson]

Hi, what kind of protocol do you have? What is the structure of the cDNA library?

[Dingchunyuan]

Thank you for your response. I have resolved the parameter errors. However, I have a few more questions: Which parameters can enhance the counts of each clonotype? Additionally, what is the difference between "readCount" and "uniqueMoleculeCount"? Because after I modified the parameters, the uniqueMoleculeCount only increased by 1.

Here is my code.

mixcr align \
    --species hsa \
    --library imgt \
    -f \
    -p generic-amplicon-with-umi \
    -OvParameters.geneFeatureToAlign="VTranscriptWithP" \
    -OallowNoCDR3PartAlignments=true \
    -OallowPartialAlignments=true \
    --keep-non-CDR3-alignments \
    --rigid-left-alignment-boundary \
    --floating-right-alignment-boundary C \
    --tag-pattern "^(R1:*)\^(UMI:N{16})(R2:*)" \
    --report results/FT100053139_L01_S009.report.txt \
    --json-report results/FT100053139_L01_S009.report.json \
    --assemble-clonotypes-by CDR3 \
    --rna \
    -OvParameters.parameters.relativeMinScore=0.3 \
    -OjParameters.parameters.relativeMinScore=0.3 \
    -OcParameters.parameters.relativeMinScore=0.3 \
    -OvParameters.parameters.absoluteMinScore=15 \
    -OjParameters.parameters.absoluteMinScore=15 \
    -OcParameters.parameters.absoluteMinScore=15 \
    -OvParameters.parameters.maxHits=3 \
    -OjParameters.parameters.maxHits=3 \
    -OcParameters.parameters.maxHits=3 \
    /public/home/dingchunyuan/TCR/Rawdata/G99/FT100053139_100bp/FT100053139_L01_S009_1.fq.gz \
    /public/home/dingchunyuan/TCR/Rawdata/G99/FT100053139_100bp/FT100053139_L01_S009_2.fq.gz \
    ./results/FT100053139_L01_S009.vdjca

mixcr refineTagsAndSort \
    -f \
    --report results/FT100053139_L01_S009.report.txt \
    --json-report results/FT100053139_L01_S009.report.json \
    results/FT100053139_L01_S009.vdjca \
    results/FT100053139_L01_S009.refined.vdjca

mixcr assemble \
    -f \
    -OassemblingFeatures="CDR3" \
    -OseparateByJ=true \
    -OseparateByV=true \
    --report results/FT100053139_L01_S009.report.txt \
    --json-report results/FT100053139_L01_S009.report.json \
    results/FT100053139_L01_S009.refined.vdjca \
    results/FT100053139_L01_S009.clns

mixcr exportClones \
    -f \
    -c TRB \
    -uniqueTagCount UMI \
    results/FT100053139_L01_S009.clns \
    results/FT100053139_L01_S009.clones.TRB.tsv

mixcr exportReports \
    -f \
    results/FT100053139_L01_S009.clns \
    results/FT100053139_L01_S009.report.txt

Here is the report.
FT100053139_L01_S009.report.txt

[mizraelson]

Hi,
The counts of each clonotype are influenced by multiple variables, as sequences undergo different levels of filtering and correction. The correct approach here is to review the reports and identify where significant data loss occurs. readCount represents the number of reads, and uniqueMoleculeCount refers to the number of UMI groups supporting each clonotype.

The parameters below, while potentially increasing the number of aligned reads, will not significantly affect the number of clonotypes. These parameters include partial alignments (those that do not fully cover or only partially cover the CDR3), but the lack of CDR3 means they cannot be used during the assembly step.

-OallowNoCDR3PartAlignments=true \ -OallowPartialAlignments=true \ --keep-non-CDR3-alignments \
From the report, I see:

Successfully aligned reads: 1345215 (29.32%)
Alignment failed: no hits (not TCR/IG?): 3242137 (70.67%)

This indicates that 70% of reads did not align to the reference at all. You can export these reads by adding:
--not-aligned-R1 r1.not-aligned.fastq.gz --not-aligned-R2 r2.not-aligned.fastq.gz

Then you can manually inspect the reads to determine why they do not align to the reference.

If you can share the raw file, I can take a look. You can send the link to the file to [email protected].

[Dingchunyuan]

thank you.

I have sent the email with the subject: Raw Data for GitHub Issue #1821.

The email address is [email protected]

[mizraelson]

Thanks for sharing the data. I see that you used the new kit, and UMIs are actually 14-18bp. You can manually check this by looking at R2, where the UMI is everything before the “atgcattggagtcct” adapter sequence.

To run the correct preset, you should use the latest develop version the command below. For debugging purposes, I’ve added two parameters: --keep-non-CDR3-alignments, which allows viewing alignments that are missing the CDR3 region, and --output-not-used-reads to export non-aligned reads.

mixcr analyze qiagen-human-rna-tcr-umi-targeted-qiaseq \
--keep-non-CDR3-alignments \
--output-not-used-reads \
FT100053139_L01_S008_{{R}}.fq.gz result /
result/

The alignment report looks like this:

Total sequencing reads: 2904260
Successfully aligned reads: 630376 (21.71%)
Coverage (percent of successfully aligned):
  CDR3: 104252 (16.54%)
  FR3_TO_FR4: 103842 (16.47%)
  CDR2_TO_FR4: 103842 (16.47%)
  FR2_TO_FR4: 37975 (6.02%)
  CDR1_TO_FR4: 2557 (0.41%)
  VDJRegion: 1 (0%)
Alignment failed: no hits (not TCR/IG?): 2076145 (71.49%)
Alignment failed after alignment-aided overlap: 321 (0.01%)
Alignment failed: absent barcode: 197418 (6.8%)
Overlapped: 2496492 (85.96%)
Overlapped and aligned: 627050 (21.59%)
Overlapped and not aligned: 1869442 (64.37%)
Alignment-aided overlaps, percent of overlapped and aligned: 0 (0%)
No CDR3 parts alignments, percent of successfully aligned: 408446 (64.79%)
Partial aligned reads, percent of successfully aligned: 117678 (18.67%)

The main source of data loss is “Alignment failed: no hits (not TCR/IG?)”, which affects 2,076,145 reads (71.49%). These reads are exported into a separate FASTQ file for manual inspection. A brief check shows that many of these reads are either completely non-specific, such as:

@FT100053139L1C001R00100010352/1
CGATAGGCAGCGACCTTGGGTGGGAACACCCCTCAGGTATTTGTCGGTGAGGATTCCCTGAGCCAACGGAGAGAAACAGATGATGCCCATCCCCTCCTGCTCACAGGTATCGACGAGACCATCCTCAATCCATCGATCAAACATGTTGTAACGCGGCTGGTGGATGAGTAACGGGGTGCCAAGGTCACGCGCAATGGTGGCAGCACGTTCTGTCTCCTTGGGATCGTATGAGGAAATACCTGCATACAAGGCACGACCTGATCGCACGATCCGGTCGAGAGCAGGACTCCAATGCATGGA
+
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII

This sequence matches Cutibacterium acnes with 99% similarity.

Or reads like this, which seem to originate from DNA:

ACTATGGTCAGCGACCTCGGGTGGGAACACGTTTTTCAGGTCCTCTGGAAAGGGAAGAGGTAATGGGGCTAGGGTTGCTCTAAGAGCTGTCTGGTCCTGGTAGGGGCTCCGTGTATGTGTGAGAGAGAAGGCCGGGAAAGGACCATAATGAAGCACAATTATGTTACTAGGTCCTCCTTGCTTTGGGGTCACCAGCCTATTCCTCTTTGATGGTTCTACCCCTTCCTTGCCTGTCTTTTGTATCCACCCTATGGGTTGGCACTGCCCATTGTCTGTCCATCCCCCAGTTAGGCAGGACTC

You can see how the read starts from the TRBC gene but includes DNA that should be spliced in normal TCR mRNA.

A brief random search did not reveal any reads that were mistakenly classified as not aligned.

The majority of successfully aligned reads (when using --keep-non-CDR3-alignments) are those that only partially or do not cover the CDR3 region. You can inspect this with the following command:

mixcr exportAlignmentsPretty -s 1000 -n 20 result/alignments.vdjca

-s 1000 skips 1000 alignments from the beginning of the file, and -n sets the number of alignments to export.

In many cases, like the one below, parts of the V gene do not align at all, even when BLASTed:

GCCAACAGAACTTTTTGCCACTTTCTCTTATACACATCTGACGCTGCCGACGACCGTTCTCCTGTGTAGATCTCGGTGGTCGCCGTATCATTCAAGCAGAAGACAGCATACGAGATCCAAGTAGATGTCTCGTGGGCTCGGAGATGTGTATAAGAGACAGATTTACCCTGCTACCGATGCATTGGAGTCCTGGA

In some reads, the V gene is present but starts with a random sequence, preventing proper alignment. To address this, you can use --floating-left-alignment-boundary, which tells MiXCR not to force alignment on the left side, like in the example below:

Thus the command would be:

mixcr analyze qiagen-human-rna-tcr-umi-targeted-qiaseq \
--keep-non-CDR3-alignments \
--output-not-used-reads \
--floating-left-alignment-boundary \
FT100053139_L01_S008_{{R}}.fq.gz \
result/ 

We can see the align report looks a bit better in this case:

No CDR3 parts alignments, percent of successfully aligned: 12889 (5.52%)
Partial aligned reads, percent of successfully aligned: 61523 (26.34%)

That’s all I have for now. The main issue seems to be with reads that are not aligned at all. You can manually inspect these, and let me know if you find anything that should align to the TCR reference so I can investigate further.

[Dingchunyuan]

Thank you for your response. I tried running the code you recommended with the new version, but I encountered the following error.I confirm that the file is in the current working directory.
error

Unknown point: ./FT100053139_L01_S008_{{R}}.fq.gz

The steps I took to download the software were: downloading and unzip the software, then adding the environment variable and running it directly.There is additional information.

Run command : mixcr -version

MiXCR v4.7.0-112-develop (built Tue Oct 15 11:37:18 CST 2024; rev=b05aaeb00f; branch=develop; host=fv-az1121-409)
RepSeq.IO v2.5.0 (rev=06fa1852ee)
MiLib v3.5.0-3-mitool-tag-types (rev=7d638011d4)
Built-in V/D/J/C library: repseqio.v5.1

Library search path:
- built-in libraries
- /public/home/dingchunyuan/TCR/Resultdata/Mixcr/G99/S008/

[mizraelson]

Can you share the exact command that you tried?

[Dingchunyuan]

Of course, here is the code I ran.

mixcr analyze qiagen-human-rna-tcr-umi-targeted-qiaseq \
--keep-non-CDR3-alignments \
--output-not-used-reads \
--floating-left-alignment-boundary \
/FT100053139_L01_S008_{{R}}.fq.gz \
result/

[mizraelson]

and the files are located in the root directory?