Merge branch 'release/v2.0.1'

.gitignore

@@ -5,3 +5,4 @@ target
 doc/_build
 .floo
 .flooignore
+out

CHANGELOG

@@ -1,4 +1,20 @@
 
+MiXCR 2.0.1 ( 8 Nov 2016)
+========================
+
+-- Fixes problem with absent library search folders
+-- Added action `exportClonesPretty`, that prints well-formatted alignments for segments and clonal 
+   sequence
+-- Human readable report for assemblePartial action
+-- Additional micro-filtering step for alignment hits to exclude wrong chain hits
+-- RepSeq.IO: fixes bug when MIXCR fails to resolve partial library name for files without .gz 
+   extension
+-- Print warning when using java version <= 7 
+-- minor: Statistics about chains usage is added to `align` and `assemble` reports
+-- minor: Added chains (`--chains` or `-c` option) filter for `exportAlignments` 
+-- minor: Execution time is now printed in reports
+
+
 MiXCR 2.0 (13 Sep 2016)
 ========================
 

README.md

@@ -6,9 +6,8 @@ MiXCR is a universal software for fast and accurate analysis of raw T- or B- cel
 
 #### Using Homebrew on Mac OS X or Linux (linuxbrew)
 
-    brew tap milaboratory/all
-    brew install mixcr
-
+    brew install milaboratory/all/mixcr
+
 to upgrade already installed MiXCR to the newest version:
 
     brew update

doc/appendix.rst

@@ -126,7 +126,7 @@ Consider the following BLAST-like alignments encoded in MiXCR notation:
       3 GTGCTGACAGATACC 17
 
       MiXCR alignment:
-      0|15|17|3|18||75.0
+      2|17|19|3|18||75.0
       </pre>
 
 subsequence from ``target`` (from nucleotide 0 to nucleotide 15) was
@@ -147,7 +147,7 @@ nucleotide 18).
       3 GTGCT-ATAGACTACC 17
 
       MiXCR alignment:
-      0|15|17|3|18|DG7SC9TI13C|41.0
+      2|17|19|3|18|DG7SC9TI13C|41.0
       </pre>
 
 so, to obtain subseqeunce from **query sequence** from 3 to 18 we need

mixcr

@@ -4,12 +4,17 @@ java="java"
 
 sedString="s/.*1\.\(.*\)\..*/\1/"
 jVersion=$($java -version 2>&1 | grep version | awk '{ print $3 }' | sed $sedString)
-if [[ $jVersion -lt 8 ]];
+if [[ $jVersion -lt 7 ]];
 then
-    echo "Wrong version of java. Please use Java 8 or higher."
+    echo "Wrong version of java. Please use Java 7 or higher."
     exit 1
 fi
 
+if [[ $jVersion -lt 8 ]];
+then
+    echo "WARNING: Several issues have been detected while using Java 7. Please consider updateing to Java 8 or higher."
+fi
+
 # Linux readlink -f alternative for Mac OS X
 function readlinkUniversal() {
     targetFile=$1

pom.xml

@@ -32,7 +32,7 @@
 
     <groupId>com.milaboratory</groupId>
     <artifactId>mixcr</artifactId>
-    <version>2.0</version>
+    <version>2.0.1</version>
     <packaging>jar</packaging>
     <name>MiXCR</name>
 
@@ -44,14 +44,14 @@
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <milib.version>1.5</milib.version>
+        <milib.version>1.5.1</milib.version>
     </properties>
 
     <dependencies>
         <dependency>
             <groupId>io.repseq</groupId>
             <artifactId>repseqio</artifactId>
-            <version>1.2.0</version>
+            <version>1.2.2</version>
         </dependency>
 
         <dependency>
@@ -179,7 +179,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-shade-plugin</artifactId>
-                <version>2.3</version>
+                <version>2.4</version>
                 <executions>
                     <execution>
                         <phase>pre-integration-test</phase>

src/main/java/com/milaboratory/mixcr/assembler/CloneAssembler.java

@@ -181,11 +181,13 @@ public VoidProcessor<VDJCAlignments> getInitialAssembler() {
     }
 
     public boolean beginMapping() {
+        globalLogger.end(totalAlignments.get());
         if (!parameters.isMappingEnabled())
-            throw new IllegalStateException("No mapping is needed for this parameters.");
+            return false;
+
         if (deferredAlignmentsLogger != null)
             throw new IllegalStateException();
-        globalLogger.end(totalAlignments.get());
+
         if (!deferredExists)
             return false;
         deferredAlignmentsLogger = new AssemblerEventLogger();

src/main/java/com/milaboratory/mixcr/assembler/CloneAssemblerRunner.java

@@ -81,30 +81,28 @@ public void run() {
                 throw new RuntimeException(e);
             }
         }
-        //run mapping
-        if (assembler.parameters.isMappingEnabled()) {
+        // run mapping if required
+        if (assembler.beginMapping()) {
             synchronized (this) {
                 stage = "Preparing for mapping of low quality reads";
                 innerProgress = null;
             }
-            if (assembler.beginMapping()) {
-                try (OutputPortCloseable<VDJCAlignments> alignmentsPort = alignmentsProvider.create()) {
-                    synchronized (this) {
-                        stage = "Mapping low quality reads";
-                        if (alignmentsPort instanceof CanReportProgress)
-                            innerProgress = (CanReportProgress) alignmentsPort;
-                    }
-                    try {
-                        CUtils.processAllInParallel(CUtils.buffered(
-                                        new FilteringPort<>(alignmentsPort,
-                                                assembler.getDeferredAlignmentsFilter()), 128),
-                                assembler.getDeferredAlignmentsMapper(), threads);
-                    } catch (InterruptedException e) {
-                        throw new RuntimeException(e);
-                    }
+            try (OutputPortCloseable<VDJCAlignments> alignmentsPort = alignmentsProvider.create()) {
+                synchronized (this) {
+                    stage = "Mapping low quality reads";
+                    if (alignmentsPort instanceof CanReportProgress)
+                        innerProgress = (CanReportProgress) alignmentsPort;
+                }
+                try {
+                    CUtils.processAllInParallel(CUtils.buffered(
+                            new FilteringPort<>(alignmentsPort,
+                                    assembler.getDeferredAlignmentsFilter()), 128),
+                            assembler.getDeferredAlignmentsMapper(), threads);
+                } catch (InterruptedException e) {
+                    throw new RuntimeException(e);
                 }
-                assembler.endMapping();
             }
+            assembler.endMapping();
         }
         assembler.preClustering();
         //run clustering

src/main/java/com/milaboratory/mixcr/basictypes/CloneSet.java

@@ -128,7 +128,7 @@ public Iterator<Clone> iterator() {
     }
 
     /**
-     * WARNING: in will be destroyed
+     * WARNING: current object will be destroyed
      */
     public static CloneSet transform(CloneSet in, Filter<Clone> filter) {
         List<Clone> newClones = new ArrayList<>(in.size());

src/main/java/com/milaboratory/mixcr/basictypes/VDJCAlignments.java

@@ -106,19 +106,6 @@ public NSequenceWithQuality[] getOriginalSequences() {
         return originalSequences;
     }
 
-    public final boolean isChimera() {
-        Chains chains = Chains.ALL;
-        for (GeneType gt : GeneType.VJC_REFERENCE) {
-            Chains c = getAllChains(gt);
-            if (c == null)
-                continue;
-            chains = chains.intersection(c);
-            if (chains.isEmpty())
-                return true;
-        }
-        return false;
-    }
-
     /**
      * Returns {@code true} if at least one V and one J hit among first {@code top} hits have same chain and false
      * otherwise (first {@code top} V hits have different chain from those have first {@code top} J hits).

src/main/java/com/milaboratory/mixcr/basictypes/VDJCAlignmentsFormatter.java

@@ -44,23 +44,27 @@
 import java.util.List;
 
 public class VDJCAlignmentsFormatter {
-    public static MultiAlignmentHelper getTargetAsMultiAlignment(VDJCAlignments vdjcaAlignments, int targetId) {
-        NSequenceWithQuality target = vdjcaAlignments.getTarget(targetId);
+    public static MultiAlignmentHelper getTargetAsMultiAlignment(VDJCObject vdjcObject, int targetId) {
+        return getTargetAsMultiAlignment(vdjcObject, targetId, false);
+    }
+
+    public static MultiAlignmentHelper getTargetAsMultiAlignment(VDJCObject vdjcObject, int targetId, boolean addHitScore) {
+        NSequenceWithQuality target = vdjcObject.getTarget(targetId);
         NucleotideSequence targetSeq = target.getSequence();
-        SequencePartitioning partitioning = vdjcaAlignments.getPartitionedTarget(targetId).getPartitioning();
+        SequencePartitioning partitioning = vdjcObject.getPartitionedTarget(targetId).getPartitioning();
 
         List<Alignment<NucleotideSequence>> alignments = new ArrayList<>();
         List<String> alignmentLeftComments = new ArrayList<>();
         List<String> alignmentRightComments = new ArrayList<>();
         for (GeneType gt : GeneType.values())
-            for (VDJCHit hit : vdjcaAlignments.getHits(gt)) {
+            for (VDJCHit hit : vdjcObject.getHits(gt)) {
                 Alignment<NucleotideSequence> alignment = hit.getAlignment(targetId);
                 if (alignment == null)
                     continue;
                 alignment = alignment.invert(targetSeq);
                 alignments.add(alignment);
                 alignmentLeftComments.add(hit.getGene().getName());
-                alignmentRightComments.add(" " + hit.getAlignment(targetId).getScore());
+                alignmentRightComments.add(" " + (int) (hit.getAlignment(targetId).getScore()) + (addHitScore ? " (" + (int) (hit.getScore()) + ")" : ""));
             }
 
         MultiAlignmentHelper helper = MultiAlignmentHelper.build(MultiAlignmentHelper.DEFAULT_SETTINGS,
@@ -71,7 +75,7 @@ public static MultiAlignmentHelper getTargetAsMultiAlignment(VDJCAlignments vdjc
 
         helper.addSubjectQuality("Quality", target.getQuality());
         helper.setSubjectLeftTitle("Target" + targetId);
-        helper.setSubjectRightTitle(" Score");
+        helper.setSubjectRightTitle(" Score" + (addHitScore ? " (hit score)" : ""));
         for (int i = 0; i < alignmentLeftComments.size(); i++) {
             helper.setQueryLeftTitle(i, alignmentLeftComments.get(i));
             helper.setQueryRightTitle(i, alignmentRightComments.get(i));

src/main/java/com/milaboratory/mixcr/basictypes/VDJCObject.java

@@ -100,6 +100,40 @@ public Chains getAllChains(GeneType geneType) {
         return allChains.get(geneType);
     }
 
+    public final boolean isChimera() {
+        return commonChains().isEmpty();
+    }
+
+    public final Chains commonChains() {
+        Chains chains = Chains.ALL;
+        boolean notNull = false;
+        for (GeneType gt : GeneType.VJC_REFERENCE) {
+            Chains c = getAllChains(gt);
+            if (c == null)
+                continue;
+            notNull = true;//for safety
+            chains = chains.intersection(c);
+        }
+        if (!notNull)//all null
+            return Chains.EMPTY;
+        return chains;
+    }
+
+    public final Chains commonTopChains() {
+        Chains chains = Chains.ALL;
+        boolean notNull = false;
+        for (GeneType gt : GeneType.VJC_REFERENCE) {
+            VDJCHit bestHit = getBestHit(gt);
+            if (bestHit == null)
+                continue;
+            notNull = true;//for safety
+            chains = chains.intersection(bestHit.getGene().getChains());
+        }
+        if (!notNull)//all null
+            return Chains.EMPTY;
+        return chains;
+    }
+
     public final int numberOfTargets() {
         return targets.length;
     }

src/main/java/com/milaboratory/mixcr/cli/ActionAlign.java

@@ -165,6 +165,8 @@ public void go(ActionHelper helper) throws Exception {
         AlignerReport report = new AlignerReport();
         aligner.setEventsListener(report);
 
+        ChainUsageStats chainsStatistics = new ChainUsageStats();
+
         try (SequenceReaderCloseable<? extends SequenceRead> reader = actionParameters.createReader();
 
              VDJCAlignmentsWriter writer = actionParameters.getOutputName().equals(".") ? null : new VDJCAlignmentsWriter(actionParameters.getOutputName());
@@ -215,6 +217,8 @@ public long getIndex(VDJCAlignmentResult o) {
                     }
                 }
 
+                chainsStatistics.put(alignment);
+
                 if (alignment.isChimera())
                     report.onChimera();
 
@@ -235,11 +239,11 @@ public long getIndex(VDJCAlignmentResult o) {
 
         // Writing report to stout
         System.out.println("============= Report ==============");
-        Util.writeReportToStdout(report, time);
+        Util.writeReportToStdout(time, report, chainsStatistics);
 
         if (actionParameters.report != null)
             Util.writeReport(actionParameters.getInputForReport(), actionParameters.getOutputName(),
-                    helper.getCommandLineArguments(), actionParameters.report, report, time);
+                    helper.getCommandLineArguments(), actionParameters.report, time, report, chainsStatistics);
     }
 
     public static String[] extractDescriptions(SequenceRead r) {

src/main/java/com/milaboratory/mixcr/cli/ActionAssemble.java

@@ -38,6 +38,7 @@
 import com.milaboratory.cli.ActionHelper;
 import com.milaboratory.cli.ActionParametersWithOutput;
 import com.milaboratory.mixcr.assembler.*;
+import com.milaboratory.mixcr.basictypes.Clone;
 import com.milaboratory.mixcr.basictypes.CloneSet;
 import com.milaboratory.mixcr.basictypes.CloneSetIO;
 import com.milaboratory.mixcr.basictypes.VDJCAlignmentsReader;
@@ -100,12 +101,12 @@ public void go(ActionHelper helper) throws Exception {
         }
 
         // Performing assembly
-        try (CloneAssembler assembler = new CloneAssembler(assemblerParameters, false, genes)) {
+        try (CloneAssembler assembler = new CloneAssembler(assemblerParameters,
+                actionParameters.readsToClonesMapping != null, genes)) {
             // Creating event listener to collect run statistics
             CloneAssemblerReport report = new CloneAssemblerReport();
             assembler.setListener(report);
 
-
             // Running assembler
             CloneAssemblerRunner assemblerRunner = new CloneAssemblerRunner(
                     alignmentsProvider,
@@ -116,6 +117,10 @@ public void go(ActionHelper helper) throws Exception {
             // Getting results
             final CloneSet cloneSet = assemblerRunner.getCloneSet();
 
+            ChainUsageStats chainsStatistics = new ChainUsageStats();
+            for (Clone clone : cloneSet)
+                chainsStatistics.put(clone);
+
             // Writing results
             try (CloneSetIO.CloneSetWriter writer = new CloneSetIO.CloneSetWriter(cloneSet, actionParameters.getOutputFileName())) {
                 SmartProgressReporter.startProgressReport(writer);
@@ -131,11 +136,11 @@ public void go(ActionHelper helper) throws Exception {
 
             // Writing report to stout
             System.out.println("============= Report ==============");
-            Util.writeReportToStdout(report, time);
+            Util.writeReportToStdout(time, report, chainsStatistics);
 
             if (actionParameters.report != null)
                 Util.writeReport(actionParameters.getInputFileName(), actionParameters.getOutputFileName(),
-                        helper.getCommandLineArguments(), actionParameters.report, report, time);
+                        helper.getCommandLineArguments(), actionParameters.report, time, report, chainsStatistics);
 
             // Writing raw events (not documented feature)
             if (actionParameters.events != null)

src/main/java/com/milaboratory/mixcr/cli/ActionAssemblePartialAlignments.java

@@ -27,6 +27,8 @@ public final class ActionAssemblePartialAlignments implements Action {
 
     @Override
     public void go(ActionHelper helper) throws Exception {
+        // Saving initial timestamp
+        long beginTimestamp = System.currentTimeMillis();
         PartialAlignmentsAssemblerParameters assemblerParameters = PartialAlignmentsAssemblerParameters.getDefault();
 
         if (!parameters.overrides.isEmpty()) {
@@ -51,8 +53,14 @@ public void go(ActionHelper helper) throws Exception {
 
             if (parameters.report != null)
                 Util.writeReport(parameters.getInputFileName(), parameters.getOutputFileName(),
-                        helper.getCommandLineArguments(), parameters.report, assembler,
-                        System.currentTimeMillis() - start);
+                        helper.getCommandLineArguments(), parameters.report, System.currentTimeMillis() - start, assembler
+                );
+
+            long time = System.currentTimeMillis() - beginTimestamp;
+
+            // Writing report to stout
+            System.out.println("============= Report ==============");
+            Util.writeReportToStdout(time, assembler);
         }
     }