Merge branch 'release/v3.0'

milaboratory · Oct 23, 2018 · 8ed81e7 · 8ed81e7
2 parents 7f76643 + c65fbd4
commit 8ed81e7
Show file tree

Hide file tree

Showing 183 changed files with 15,738 additions and 6,699 deletions.
diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md
@@ -0,0 +1,28 @@
+---
+name: Issue
+about: General issue
+
+---
+
+## Checklist before submitting the issue:
+
+ - [ ] The issue is strongly related to the MiXCR software
+ - [ ] The issue can be reproduced with [the most recent version](https://github.com/milaboratory/mixcr/releases) of MiXCR
+ - [ ] There is no answer to the question in the [official documentation](http://mixcr.readthedocs.io/) and there is no duplicate issue in the [bug tracker](https://github.com/milaboratory/mixcr/issues)  
+ - [ ] Inspection of raw alignments with [exportAlignmentsPretty](http://mixcr.readthedocs.io/en/master/export.html#exporting-well-formatted-alignments-for-manual-inspection) 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
+
+*A description of what you wanted to happen*
+
+## Actual Result
+
+*A description of what actually happened*
+
+## Exact MiXCR commands 
+
+*Paste here __exact__ MiXCR commands you used (enclose it with single `` ` ``  for better formatting)*
+
+## MiXCR report files 
+
+*Paste here content of the report files produced by MiXCR (enclose it with triple ```` ``` ````  for better formatting)*
diff --git a/.travis.yml b/.travis.yml
@@ -1,4 +1,4 @@
-
+ 
 language: java
 
 sudo: false
@@ -20,7 +20,7 @@ script:
   - mvn test -B && ./itests.sh test
 
 jdk:
-  - openjdk7
+  - openjdk8
 
 before_cache:
   - rm -f $HOME/.m2/repository/io/repseqio/

diff --git a/CHANGELOG b/CHANGELOG
@@ -1,4 +1,35 @@
 
+MiXCR 3.0 (23 Oct 2018)
+========================
+
+-- New command ``assembleContigs`` for assembling longest possible contig TCR/IG receptor sequences 
+   from several intersecting sequences containing clonal sequence. E.g. assemble all possible sequence 
+   information outside CDR3.
+-- New command ``analyze`` for running optimized mixcr pipelines with one single command. Two 
+   pipelines which cover most practical cases are implemented ``analyze amplicon`` and ``analyze 
+   shotgun``.
+-- New file format ``.clna`` for storing clones with alignments including alignments <> clones 
+   mapping
+-- Complete refactoring of command line interface
+-- New option ``--resume`` for resuming aborted / partially completed execution
+-- Implemented ``-nFeatureImputed`` and ``-aaFeatureImputed`` to export gene feature sequences 
+   imputing unavailable regions from germline sequences up to the full feature sequecn (marking 
+   imputed regions lowercase)
+-- LZ4 based compression `.vdjca`/`.clna` files, 3 ~ 4 fold file size reduction (built into file 
+   formats, enabled by default)
+-- Species option ``--species`` is now mandatory #342
+-- Removed ``--chains`` option for `align` action #292
+-- Added export field ``-positionInReference``
+-- Now export fields like `-nMutationsRelative` supports alignment-attached gene features (e.g. 
+   this allows to export all mutations of V gene inside CDR3 sub-regions: `-nMutationsRelative 
+   VCDR3Part VRegionWithP`)
+-- Now `align` action prints library-level warnings and citation notice
+-- Refactored command line interface of `exportReadsForClones`
+-- Dropped support for Java 7
+-- minor: fixes for #292 #280 #279 #208 #203 #421
+-- minor: `--noMerge` option renamed to `--no-merge` in assemble action
+
+
 MiXCR 2.1.12 (22 Aug 2018)
 ========================
 

diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
 [![Build Status](https://travis-ci.org/milaboratory/mixcr.svg)](https://travis-ci.org/milaboratory/mixcr)
+[![image](https://readthedocs.org/projects/mixcr/badge/?version=latest)](https://mixcr.readthedocs.io)
+
 
 ## Overview
 
@@ -27,6 +29,8 @@ MiXCR is a universal software for fast and accurate analysis of raw T- or B- cel
 
 - Clonotypes can be assembled based on CDR3 sequence (default) as well as any other region, including *full-length* variable sequence (from beginning of FR1 to the end of FR4)
 
+- Assemble full TCR/Ig receptor sequences 
+
 - Provides exhaustive output information for clonotypes and per-read alignments:
   - nucleotide and amino acid sequences of all immunologically relevant regions (FR1, CDR1, ..., CDR3, etc..)
   - identified V, D, J, C genes
@@ -64,28 +68,7 @@ to upgrade already installed MiXCR to the newest version:
 
 ## Usage
 
-#### Enriched RepSeq Data
-
-Here is a very simple usage example that will extract repertoire data (in the form of clonotypes list) from raw sequencing data of enriched RepSeq library:
-
-    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 will produce a tab-delimited list of clones (`clones.txt`) assembled by their CDR3 sequences with extensive information on their abundances, V, D and J genes, mutations in germline regions, topology of VDJ junction etc.
-
-#### Repertoire extraction from RNA-Seq
-
-MiXCR is equally effective in extraction of repertoire information from non-enriched data, like RNA-Seq or WGS. This example illustrates usage for RNA-Seq:
-
-    mixcr align -p rna-seq -r log.txt input_R1.fastq.gz input_R2.fastq.gz alignments.vdjca
-    mixcr assemblePartial alignments.vdjca alignment_contigs.vdjca
-    mixcr assemble -r log.txt alignment_contigs.vdjca clones.clns
-    mixcr exportClones clones.clns clones.txt
-
-#### Further reading
-
-MiXCR pipeline is very flexible, and can be applied to raw data from broad spectrum of experimental setups. For detailed description of MiXCR features and options please see documentation.
+See usage examples in the official documentation https://mixcr.readthedocs.io/en/master/quickstart.html
 
 ## Documentation
 
@@ -95,7 +78,7 @@ If you haven't found the answer to your question in the docs, or have any sugges
 
 ## Build
 
-Dependancy:
+Requirements:
 
 - Maven 3 (https://maven.apache.org/)
 

diff --git a/doc/ExportFieldsClone.rst b/doc/ExportFieldsClone.rst
@@ -1,15 +1,13 @@
-+------------------------------------------+--------------------------------------------------------------------------------+
-| Field name                               | Description                                                                    |
-+==========================================+================================================================================+
-| ``-cloneId``                             | Unique clone identifier                                                        |
-+------------------------------------------+--------------------------------------------------------------------------------+
-| ``-count``                               | Clone count                                                                    |
-+------------------------------------------+--------------------------------------------------------------------------------+
-| ``-fraction``                            | Clone fraction                                                                 |
-+------------------------------------------+--------------------------------------------------------------------------------+
-| ``-sequence``                            | Aligned sequence (initial read), or 2 sequences in case of paired-end reads    |
-+------------------------------------------+--------------------------------------------------------------------------------+
-| ``-quality``                             | Initial read quality, or 2 qualities in case of paired-end reads               |
-+------------------------------------------+--------------------------------------------------------------------------------+
-| ``-readIds`` ``<index_file>``            | Read IDs aggregated by clone.                                                  |
-+------------------------------------------+--------------------------------------------------------------------------------+
++--------------------------+--------------------------------------------------------------------------------+
+| Field name               | Description                                                                    |
++==========================+================================================================================+
+| ``-cloneId``             | Unique clone identifier                                                        |
++--------------------------+--------------------------------------------------------------------------------+
+| ``-count``               | Clone count                                                                    |
++--------------------------+--------------------------------------------------------------------------------+
+| ``-fraction``            | Clone fraction                                                                 |
++--------------------------+--------------------------------------------------------------------------------+
+| ``-sequence``            | Aligned sequence (initial read), or 2 sequences in case of paired-end reads    |
++--------------------------+--------------------------------------------------------------------------------+
+| ``-quality``             | Initial read quality, or 2 qualities in case of paired-end reads               |
++--------------------------+--------------------------------------------------------------------------------+
diff --git a/doc/ExportFieldsVDJCAlignments.rst b/doc/ExportFieldsVDJCAlignments.rst
@@ -1,17 +1,25 @@
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| Field name                                              | Description                                                                                                                                |
-+=========================================================+============================================================================================================================================+
-| ``-readId``                                             | Id of read corresponding to alignment                                                                                                      |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-sequence``                                           | Aligned sequence (initial read), or 2 sequences in case of paired-end reads                                                                |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-quality``                                            | Initial read quality, or 2 qualities in case of paired-end reads                                                                           |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-descrR1``                                            | Description line from initial .fasta or .fastq file of the first read (only available if --save-description was used in align command)     |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-descrR2``                                            | Description line from initial .fasta or .fastq file of the second read (only available if --save-description was used in align command)    |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-cloneId`` ``<index_file>``                           | To which clone alignment was attached.                                                                                                     |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-cloneIdWithMappingType`` ``<index_file>``            | To which clone alignment was attached with additional info on mapping type.                                                                |
-+---------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| Field name                             | Description                                                                                                                                 |
++========================================+=============================================================================================================================================+
+| ``-readId``                            | Id of read corresponding to alignment (deprecated)                                                                                          |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-readIds``                           | Id(s) of read(s) corresponding to alignment                                                                                                 |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-sequence``                          | Aligned sequence (initial read), or 2 sequences in case of paired-end reads                                                                 |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-quality``                           | Initial read quality, or 2 qualities in case of paired-end reads                                                                            |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-descrR1``                           | Description line from initial .fasta or .fastq file (deprecated)                                                                            |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-descrR2``                           | Description line from initial .fasta or .fastq file (deprecated)                                                                            |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-descrsR1``                          | Description lines from initial .fasta or .fastq file for R1 reads (only available if -OsaveOriginalReads=true was used in align command)    |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-descrsR2``                          | Description lines from initial .fastq file for R2 reads (only available if -OsaveOriginalReads=true was used in align command)              |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-readHistory``                       | Read history                                                                                                                                |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-cloneId``                           | To which clone alignment was attached (make sure using .clna file as input for exportAlignments)                                            |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+| ``-cloneIdWithMappingType``            | To which clone alignment was attached with additional info on mapping type (make sure using .clna file as input for exportAlignments)       |
++----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+