DOCSEARCHbyAlgolia
Submit Docs

MiXCR Documentation

repository·develop·Indexed 18 days ago

https://github.com/milaboratory/mixcr

A universal software suite for fast and accurate analysis of T- or B-cell receptor repertoire sequencing data, supporting bulk, single-cell, and RNA-Seq data. The documentation covers installation via Homebrew, Conda, Docker, and manual methods, license activation, and advanced features such as custom gene segment reference library building with buildLibrary, sample sheet analysis, and robust filtering for single-cell and molecular barcoded data.

Tokens
39.1K
Snippets
115
Records
178
Agent score
56%

What's inside MiXCR

  1. Combine Heavy and Light SHM trees in findShmTrees

    develop

    In findShmTrees, a special step now combines heavy and light Somatic Hypermutation (SHM) trees by utilizing information from the groupClones command. The resulting tree nodes contain both light and heavy chains. If a companion chain connection to a clone is missing, a reconstructed sequence is added.

    To disable this behavior and reconstruct separate heavy and light SHM trees, use the --dont-combine-tree-by-cells option.

    findShmTrees --dont-combine-tree-by-cells

  2. Use the new `assembleCells` command (formerly `groupClones`)

    develop
    The command groupClones has been renamed to assembleCells. While the old name still works, it is now hidden from the help menu. Consequently, report and output file names in the analyze step have also been renamed to reflect this change.

  3. Resolve sample barcodes from multiple sources

    develop

    MiXCR v4.2.0 supports analyzing multiple patient samples simultaneously by resolving sample barcodes from several possible sources:

    1. Input file names: Using the file name expansion mechanism.
    2. Index files: Extracting barcodes from I1 and I2 FASTQ files.
    3. Sequence headers: Extracting information from the FASTQ header lines.
    4. Tag patterns: Using a defined tag pattern to extract sequences.

    To facilitate this, you can use the following mixin options:

    • --sample-table: Allows defining a sample table in a tab-delimited format.
    • --infer-sample-table: Automatically infers the sample table for sample tags based on file name expansion.

    Multi-variant patterns (separated by ||) can be used to support complex sample files, such as those in the MiGEC style.

  5. Use new group filter operators for universal filtering strategies

    develop
    MiXCR v4.3.0 introduced new group filter operators that allow you to mix thresholds from multiple operators. You can specify whether to take the lowest or highest value from multiple operators and then apply it. This is designed to create more robust filtering strategies that can handle edge cases like undersequencing of barcodes.

  6. Use tag aliases in filters

    develop

    Instead of specifying multiple tags of the same type individually (e.g., CELL1+CELL2+CELL3), you can now use convenient aliases to simplify filter expressions. This is particularly useful for creating generic base presets for single-cell or UMI filtering strategies.

    Common aliases include:

    • allTags:Cell
    • allTags:Molecule

  7. Migrate from tag name to tag type semantics

    develop

    MiXCR has migrated from using <tag_name> to <tag_type> semantics for certain operations. This change affects:

    • Export columns
    • The --split-by-tag option

    Ensure your command arguments and export configurations reflect the expected tag type rather than specific tag names where applicable.

  8. Process multiple samples using different splitting strategies

    develop

    When analyzing multiplexed data, you can choose between two principal modes for handling sample barcodes:

    1. Split at align stage: Data is split by samples during the align command and processed into separate .vdjca files. This is useful for isolating samples early in the pipeline.
    2. Split at exportClones stage: All samples are processed as a single set of sequences and only separated during the final exportClones step.

    New mixin options to control this behavior include:

    • --add-export-clone-table-splitting / --reset-export-clone-table-splitting
    • --add-export-clone-grouping / --reset-export-clone-grouping (allows normalizing values like -readFraction to specific compartments instead of the whole dataset).

  10. Install MiXCR via Homebrew (macOS or Linux)

    develop

    To install MiXCR on macOS or Linux using Homebrew (or linuxbrew), use the following commands:

    brew install milaboratory/all/mixcr

    To upgrade an existing installation to the latest version:

    brew update
brew upgrade mixcr
    brew install milaboratory/all/mixcr

  11. Migrate to new MiXCR assembly presets

    develop

    In version 4.4.0, many MiXCR presets were deprecated and replaced with more unified or vendor-specific naming conventions. Key changes include:

    • kAligner2: Now uses a single preset for both TCR and BCR data. The previous distinction between cdr3 and full-length is deprecated; presets now default to the longest possible assembling feature based on the protocol.
    • Generic Amplicons: generic-tcr-amplicon, generic-bcr-amplicon, generic-tcr-amplicon-umi, and generic-bcr-amplicon-umi are replaced by generic-amplicon and generic-amplicon-with-umi.
    • 10x Genomics: 10x-vdj-tcr, 10x-vdj-tcr-full-length, 10x-vdj-bcr, and 10x-vdj-bcr-full-length are replaced by 10x-sc-xcr-vdj. To replicate full-length behavior, use the --assemble-contigs-by VDJRegion parameter.
    • 10x 5' GEX: 10x-5gex-cdr3 and 10x-5gex-full-length are replaced by 10x-sc-5gex. Use --assemble-contigs-by VDJRegion to replicate full-length behavior.
    • BD Rhapsody: Various BD Rhapsody presets are now consolidated. Human presets use bd-human-sc-xcr-rhapsody-cdr3 and mouse presets use bd-mouse-sc-xcr-rhapsody-cdr3. All BD Rhapsody presets now report CELLID numbers according to BD Rhapsody standards.

  12. Perform multi-chain clone assembly for single-cell data

    develop

    MiXCR can now calculate combined Heavy-Light antibody or Alpha-Beta/Gamma-Delta TCR clones for single-cell data.

    To enable this functionality, use the following workflow:

    1. Use the groupClones command to calculate multi-chain clones from assembled clonotypes. This command writes results in a binary format.
    2. Use the exportCloneGroups command to export information about these combined clonotypes.

    Note: All single-cell presets automatically produce combined multi-chain output in both binary and textual formats. Textual outputs follow the *.clone.groups.tsv naming pattern in the output folder.

    # Example workflow concept
# 1. Calculate multi-chain clones
groupClones ...

# 2. Export combined clonotype information
exportCloneGroups ...