Skip to content

Commit

Permalink
Merge branch 'release/v1.7'
Browse files Browse the repository at this point in the history
  • Loading branch information
@dbolotin
dbolotin committed Dec 29, 2015
2 parents 0927da8 + 87dfdb8 commit 0225715
Show file tree
Hide file tree
Showing 95 changed files with 9,015 additions and 688 deletions.
20 changes: 20 additions & 0 deletions CHANGELOG
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,24 @@

MiXCR 1.7 (29 Dec 2015)
========================

-- New feature (#8 and #36) that allows to extract actual reads that were used in each clone (for
more details see documentation)
-- Import of custom gene segment sequences (`mixcr importSegments ...`)
-- Automated import of IMGT refenrence segment sequences (`mixcr importFromIMGT ...`)
-- Beta feature: new aligner with support of big gaps (see "New aligner" section in documentation).
-- Added new action `exportReads` which export initial reads aggregated by each clones to separate
.fastq files
-- Added new export options for `exportAlignments`: `-cloneId` (prints clone ID that aggregated
corresponding alignment) and `-mapping` (same, with additional info on mapping type)
-- Added new export option for `exportClones`: `-mapping` will pring all alignment IDs that were
aggreafated by clone
-- Added option `-n` (print only first n rows) to all `export` commands
-- Added new assembler option: minimal clonal sequence length (`-OminimalClonalSequenceLength=...`)
-- minor: minor improvements and bug fixes
-- minor: version information embedded into jar file (try `mixcr -v`)


MiXCR 1.6 ( 6 Oct 2015)
========================

Expand Down
70 changes: 67 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,71 @@
Detailed documentation can be found at https://mixcr.readthedocs.org/.
## Overview

---
MiXCR is a universal software for fast and accurate analysis of raw T- or B- cell receptor repertoire sequencing data.

*Please cite:*
## Installation

#### Using Homebrew on Mac OS X or Linux (linuxbrew)

brew tap milaboratory/all
brew install mixcr

#### Manual install (any OS)

* unzip the archive with MiXCR (see [release page](https://github.com/milaboratory/mixcr/releases))
* add extracted folder to your ``PATH`` variable
* or add symbolic link for ``mixcr`` script to your ``bin`` folder
* or use MiXCR directly by specifying full path to the executable script

#### Requiraments

* Any OS with Java support (Linux, Windows, Mac OS X, etc..)
* Java 1.7 or higher

## Usage

Here is a very simple example of analysis of raw RepSeq data:

mixcr align -r log.txt input_R1.fastq.gz input_R2.fastq.gz alignments.vdjca
mixcr assemble -r log.txt alignments.vdjca clones.clns
mixcr exportClones clones.clns clones.txt

this sequence of commands will produce a tab-delimited list of clones (`clones.txt`) assembled by their CDR3 sequences with extensive information on their abondancies, V, D and J genes etc.

For more details see documentation.

## Documentation

Detailed documentation can be found at https://mixcr.readthedocs.org/

## License

Copyright (c) 2014-2015, Bolotin Dmitry, Chudakov Dmitry, Shugay Mikhail
(here and after addressed as Inventors)
All Rights Reserved

Permission to use, copy, modify and distribute any part of this program for
educational, research and non-profit purposes, by non-profit institutions
only, without fee, and without a written agreement is hereby granted,
provided that the above copyright notice, this paragraph and the following
three paragraphs appear in all copies.

Those desiring to incorporate this work into commercial products or use for
commercial purposes should contact the Inventors using one of the following
email addresses: [email protected], [email protected]

IN NO EVENT SHALL THE INVENTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
ARISING OUT OF THE USE OF THIS SOFTWARE, EVEN IF THE INVENTORS HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE SOFTWARE PROVIDED HEREIN IS ON AN "AS IS" BASIS, AND THE INVENTORS HAS
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS. THE INVENTORS MAKES NO REPRESENTATIONS AND EXTENDS NO
WARRANTIES OF ANY KIND, EITHER IMPLIED OR EXPRESS, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE, OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY
PATENT, TRADEMARK OR OTHER RIGHTS.

## Cite

Bolotin, Dmitriy A., Stanislav Poslavsky, Igor Mitrophanov, Mikhail Shugay, Ilgar Z. Mamedov, Ekaterina V. Putintseva, and Dmitriy M. Chudakov. "MiXCR: software for comprehensive adaptive immunity profiling." *Nature methods* 12, no. 5 (**2015**): 380-381.
101 changes: 57 additions & 44 deletions doc/align.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
.. |br| raw:: html

<br />

.. _ref-align:

Alignment
Expand Down Expand Up @@ -28,46 +32,52 @@ Command line parameters

The following table contains description of command line options for ``align``:

+----------------------------------+----------------------------+------------------------------------------------------------+
| Option | Default value | Description |
+==================================+============================+============================================================+
| ``-h``, ``--help`` | | Print help message. |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-r``, ``--report`` | | Report file name. If this option is not |
| | | specified, no report file be produced. |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-l``, ``--loci`` | ``ALL`` | Target immunological loci list separated by "``,``". |
| | | Available values: ``IGH``, ``IGL``, ``IGK``, ``TRA``, |
| | | ``TRB``, ``TRG``, ``TRD``, ``IG`` (for all immunoglobulin |
| | | loci), ``TCR`` (for all T-cell receptor loci), ``ALL`` |
| | | (for all loci) . |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-s``, ``--species`` | ``HomoSapiens`` | Species (organism). Possible values: ``hsa`` (or |
| | | ``HomoSapiens``) and ``mmu`` (or ``MusMusculus``). |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-p``, ``--parameters`` | ``default`` | Preset of parameters. Possible values: ``default`` and |
| | | ``rna-seq``. The ``rna-seq`` preset are specifically |
| | | optimized for analysis of Rna-Seq data |
| | | :ref:`(see below) <ref-alignRNASeq>` |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-i``, ``--diff-loci`` | | Accept alignments with different loci of V and J genes |
| | | (by default such alignments are dropped). |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-t``, ``--threads`` | number of | Number of processing threads. |
| | available CPU cores | |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-n``, ``--limit`` | | Limit number of sequences that will be analysed (only |
| | | first ``-n`` sequences will be processed from input |
| | | file(s)). |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-a``, ``--save-description`` | | Copy read(s) description line from ``.fastq`` or |
| | | ``.fasta`` to ``.vdjca`` file (can be then exported with |
| | | ``-descrR1`` and ``-descrR2`` options in |
| | | :ref:`exportAlignments <ref-export>` action). |
+----------------------------------+----------------------------+------------------------------------------------------------+
| ``-Oparameter=value`` | | Overrides default value of aligner ``parameter`` |
| | | (see next subsection). |
+----------------------------------+----------------------------+------------------------------------------------------------+
+-------------------------------------+----------------------------+------------------------------------------------------------+
| Option | Default value | Description |
+=====================================+============================+============================================================+
| ``-h``, ``--help`` | | Print help message. |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-r {file}`` |br| | | Report file name. If this option is not |
| ``--report ...`` | | specified, no report file be produced. |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-l {loci}`` |br| | ``ALL`` | Target immunological loci list separated by "``,``". |
| ``--loci ...`` | | Available values: ``IGH``, ``IGL``, ``IGK``, ``TRA``, |
| | | ``TRB``, ``TRG``, ``TRD``, ``IG`` (for all immunoglobulin |
| | | loci), ``TCR`` (for all T-cell receptor loci), ``ALL`` |
| | | (for all loci) . |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-s {speciesName}`` |br| | ``HomoSapiens`` | Species (organism). Possible values: ``hsa`` (or |
| ``--species ...`` | | ``HomoSapiens``) and ``mmu`` (or ``MusMusculus``), or any |
| | | that was provided during import of segments (see |
| | | :ref:`import segments <ref-importSegments>`) |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-p {parameterName}`` |br| | ``default`` | Preset of parameters. Possible values: ``default`` and |
| ``--parameters ...`` | | ``rna-seq``. The ``rna-seq`` preset are specifically |
| | | optimized for analysis of Rna-Seq data |
| | | :ref:`(see below) <ref-alignRNASeq>` |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-i``, ``--diff-loci`` | | Accept alignments with different loci of V and J genes |
| | | (by default such alignments are dropped). |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-t {numberOfThreads}`` |br| | number of | Number of processing threads. |
| ``--threads ...`` | available CPU cores | |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-n {numberOfReads}`` |br| | | Limit number of sequences that will be analysed (only |
| ``--limit ...`` | | first ``-n`` sequences will be processed from input |
| | | file(s)). |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-a``, ``--save-description`` | | Copy read(s) description line from ``.fastq`` or |
| | | ``.fasta`` to ``.vdjca`` file (can be then exported with |
| | | ``-descrR1`` and ``-descrR2`` options in |
| | | :ref:`exportAlignments <ref-export>` action). |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-g``, ``--save-reads`` | | Copy read(s) from ``.fastq`` or ``.fasta`` to ``.vdjca`` |
| | | file (this is required for exporting reads aggregated by |
| | | clones; see :ref:`this section <ref-exporting-reads>`). |
+-------------------------------------+----------------------------+------------------------------------------------------------+
| ``-Oparameter=value`` | | Overrides default value of aligner ``parameter`` |
| | | (see next subsection). |
+-------------------------------------+----------------------------+------------------------------------------------------------+

All parameters are optional.

Expand Down Expand Up @@ -103,11 +113,14 @@ Other global aligner parameters are:
+------------------------------------+---------------+---------------------------------------------------------------------------------------+
| Parameter | Default value | Description |
+====================================+===============+=======================================================================================+
| ``minSumScore`` | ``120.0`` | Minimal total alignment score value of V and J genes. |
| ``minSumScore`` | ``120.0`` | Minimal total alignment score value of V and J genes. |
+------------------------------------+---------------+---------------------------------------------------------------------------------------+
| ``maxHits`` | ``5`` | Maximal number of hits for each gene type: if input sequence align to more than |
| ``maxHits`` | ``5`` | Maximal number of hits for each gene type: if input sequence align to more than |
| | | ``maxHits`` targets, then only top ``maxHits`` hits will be kept. |
+------------------------------------+---------------+---------------------------------------------------------------------------------------+
| ``minimalClonalSequenceLength`` | ``12`` | Minimal clonal sequence length (e.g. minimal sequence of CDR3 to be used for clone |
| | | assembly) |
+------------------------------------+---------------+---------------------------------------------------------------------------------------+
| ``vjAlignmentOrder`` | ``VThenJ`` | Order in which V and J genes aligned in target (possible values ``JThenV`` and |
| (*only for single-end* | | ``VThenJ``). Parameter affects only *single-read* alignments and alignments of |
| *analysis*) | | overlapped paired-end reads. Non-overlaping paired-end reads are always processed in |
Expand Down Expand Up @@ -194,8 +207,8 @@ parameters. It contains the following parameters:
| | | other elements equal to ``mismatch`` |
| | | - ``raw`` --- a complete set of 16 matrix elements should be specified; |
| | | for  example: |
| | | ``raw(5,-9,-9,-9,-9,5,-9,-9,-9,-9,5,-9,-9,-9,-9,5)`` |
| | | (*equivalent to the default value*) |
| | | ``raw(5,-9,-9,-9,-9,5,-9,-9,-9,-9,5,-9,-9,-9,-9,5)`` |
| | | (*equivalent to the default value*) |
+------------------+----------------------------------------+-----------------------------------------------------------------------------+
| ``gapPenalty`` | ``-12`` | Penalty for gap. |
+------------------+----------------------------------------+-----------------------------------------------------------------------------+
Expand Down
Loading

0 comments on commit 0225715

Please sign in to comment.