Deprecate 'not-primary' in favor of secondary along HTSJDK

src/main/java/htsjdk/samtools/NotPrimarySkippingIterator.java

@@ -24,39 +24,17 @@
 package htsjdk.samtools;
 
 import htsjdk.samtools.util.CloseableIterator;
-import htsjdk.samtools.util.PeekIterator;
 
 /**
  * Wrapper around SAMRecord iterator that skips over non-primary elements.
  * This iterator conflates a filtering iterator and a peekable iterator.  It would be cleaner to
  * handle those concerns separately.
+ * @deprecated use {@link SecondarySkippingIterator} instead.
  */
-public class NotPrimarySkippingIterator {
-    private final PeekIterator<SAMRecord> it;
+@Deprecated
+public class NotPrimarySkippingIterator extends SecondarySkippingIterator {
 
-    public NotPrimarySkippingIterator(final CloseableIterator<SAMRecord> underlyingIt) {
-        it = new PeekIterator<SAMRecord>(underlyingIt);
-        skipAnyNotprimary();
-    }
-
-    public boolean hasCurrent() {
-        return it.hasNext();
-    }
-
-    public SAMRecord getCurrent() {
-        assert(hasCurrent());
-        return it.peek();
-    }
-
-    public boolean advance() {
-        it.next();
-        skipAnyNotprimary();
-        return hasCurrent();
-    }
-
-    private void skipAnyNotprimary() {
-        while (it.hasNext() && it.peek().getNotPrimaryAlignmentFlag()) {
-            it.next();
-        }
+    public NotPrimarySkippingIterator(CloseableIterator<SAMRecord> underlyingIt) {
+        super(underlyingIt);
     }
 }

src/main/java/htsjdk/samtools/SAMFlag.java

@@ -39,6 +39,9 @@ public enum SAMFlag {
     MATE_REVERSE_STRAND(            0x20,   "SEQ of the next segment in the template being reverse complemented"),
     FIRST_OF_PAIR(                  0x40,   "The first segment in the template"),
     SECOND_OF_PAIR(                 0x80,   "The last segment in the template"),
+    SECONDARY_ALIGNMENT(            0x100,  "Secondary alignment"),
+    /** @deprecated use {@link #SECONDARY_ALIGNMENT} instead. */
+    @Deprecated
     NOT_PRIMARY_ALIGNMENT(          0x100,  "Secondary alignment"),
     READ_FAILS_VENDOR_QUALITY_CHECK(0x200,  "Not passing quality controls"),
     DUPLICATE_READ(                 0x400,  "PCR or optical duplicate"), 

src/main/java/htsjdk/samtools/SAMRecord.java

@@ -967,11 +967,21 @@ private boolean getSecondOfPairFlagUnchecked() {
 
     /**
      * the alignment is not primary (a read having split hits may have multiple primary alignment records).
+     * @deprecated use {@link #getSecondaryAlignmentFlag()} instead.
      */
+    @Deprecated
     public boolean getNotPrimaryAlignmentFlag() {
-        return (mFlags & SAMFlag.NOT_PRIMARY_ALIGNMENT.flag) != 0;
+        return getSecondaryAlignmentFlag();
+    }
+
+    /**
+     * the alignment is secondary (a read having slipt hits have multiple alignment records).
+     */
+    public boolean getSecondaryAlignmentFlag() {
+        return (mFlags & SAMFlag.SECONDARY_ALIGNMENT.flag) != 0;
     }
 
+
     /**
      * the alignment is supplementary (TODO: further explanation?).
      */
@@ -1063,9 +1073,18 @@ public void setSecondOfPairFlag(final boolean flag) {
 
     /**
      * the alignment is not primary (a read having split hits may have multiple primary alignment records).
+     * @deprecated use {@link #setSecondaryAlignmentFlag(boolean)} instead.
      */
+    @Deprecated
     public void setNotPrimaryAlignmentFlag(final boolean flag) {
-        setFlag(flag, SAMFlag.NOT_PRIMARY_ALIGNMENT.flag);
+        setSecondaryAlignmentFlag(flag);
+    }
+
+    /**
+     * the alignment is secondary (a read having slipt hits have multiple alignment records).
+     */
+    public void setSecondaryAlignmentFlag(final boolean flag) {
+        setFlag(flag, SAMFlag.SECONDARY_ALIGNMENT.flag);
     }
 
     /**
@@ -1094,7 +1113,7 @@ public void setDuplicateReadFlag(final boolean flag) {
      * equivalent to {@code (getNotPrimaryAlignmentFlag() || getSupplementaryAlignmentFlag())}.
      */
     public boolean isSecondaryOrSupplementary() {
-        return getNotPrimaryAlignmentFlag() || getSupplementaryAlignmentFlag();
+        return getSecondaryAlignmentFlag() || getSupplementaryAlignmentFlag();
     }
 
     private void setFlag(final boolean flag, final int bit) {
@@ -1947,9 +1966,9 @@ public List<SAMValidationError> isValid(final boolean firstOnly) {
             if (firstOnly) return ret;
         }
         if (getReadUnmappedFlag()) {
-            if (getNotPrimaryAlignmentFlag()) {
+            if (getSecondaryAlignmentFlag()) {
                 if (ret == null) ret = new ArrayList<>();
-                ret.add(new SAMValidationError(SAMValidationError.Type.INVALID_FLAG_NOT_PRIM_ALIGNMENT, "Not primary alignment flag should not be set for unmapped read.", getReadName()));
+                ret.add(new SAMValidationError(SAMValidationError.Type.INVALID_FLAG_NOT_PRIM_ALIGNMENT, "Secondary alignment flag should not be set for unmapped read.", getReadName()));
                 if (firstOnly) return ret;
             }
             if (getSupplementaryAlignmentFlag()) {
@@ -2023,7 +2042,7 @@ public List<SAMValidationError> isValid(final boolean firstOnly) {
             if (firstOnly) return ret;
         }
         // TODO(mccowan): Is this asking "is this the primary alignment"?
-        if (this.getReadLength() == 0 && !this.getNotPrimaryAlignmentFlag()) {
+        if (this.getReadLength() == 0 && !this.getSecondaryAlignmentFlag()) {
             final Object fz = getAttribute(SAMTagUtil.getSingleton().FZ);
             if (fz == null) {
                 final String cq = (String)getAttribute(SAMTagUtil.getSingleton().CQ);

src/main/java/htsjdk/samtools/SAMRecordQueryNameComparator.java

@@ -51,8 +51,8 @@ public int compare(final SAMRecord samRecord1, final SAMRecord samRecord2) {
         if (samRecord1.getReadNegativeStrandFlag() != samRecord2.getReadNegativeStrandFlag()) {
             return (samRecord1.getReadNegativeStrandFlag()? 1: -1);
         }
-        if (samRecord1.getNotPrimaryAlignmentFlag() != samRecord2.getNotPrimaryAlignmentFlag()) {
-            return samRecord2.getNotPrimaryAlignmentFlag()? -1: 1;
+        if (samRecord1.getSecondaryAlignmentFlag() != samRecord2.getSecondaryAlignmentFlag()) {
+            return samRecord2.getSecondaryAlignmentFlag()? -1: 1;
         }
         if (samRecord1.getSupplementaryAlignmentFlag() != samRecord2.getSupplementaryAlignmentFlag()) {
             return samRecord2.getSupplementaryAlignmentFlag() ? -1 : 1;

src/main/java/htsjdk/samtools/SAMRecordSetBuilder.java

@@ -287,7 +287,7 @@ public SAMRecord addFrag(final String name, final int contig, final int start, f
                              final boolean recordUnmapped, final String cigar, final String qualityString,
                              final int defaultQuality, final boolean isSecondary) throws SAMException {
         final htsjdk.samtools.SAMRecord rec = createReadNoFlag(name, contig, start, negativeStrand, recordUnmapped, cigar, qualityString, defaultQuality);
-        if (isSecondary) rec.setNotPrimaryAlignmentFlag(true);
+        if (isSecondary) rec.setSecondaryAlignmentFlag(true);
         this.records.add(rec);
         return rec;
     }
@@ -300,7 +300,7 @@ public SAMRecord addFrag(final String name, final int contig, final int start, f
                              final boolean recordUnmapped, final String cigar, final String qualityString,
                              final int defaultQuality, final boolean isSecondary, final boolean isSupplementary) throws SAMException {
         final htsjdk.samtools.SAMRecord rec = createReadNoFlag(name, contig, start, negativeStrand, recordUnmapped, cigar, qualityString, defaultQuality);
-        if (isSecondary) rec.setNotPrimaryAlignmentFlag(true);
+        if (isSecondary) rec.setSecondaryAlignmentFlag(true);
         if (isSupplementary) rec.setSupplementaryAlignmentFlag(true);
         this.records.add(rec);
         return rec;
@@ -434,11 +434,11 @@ public List<SAMRecord> addPair(final String name, final int contig1, final int c
         end2.setReadPairedFlag(true);
         end2.setSecondOfPairFlag(true);
 
-        if (record1NonPrimary) end1.setNotPrimaryAlignmentFlag(true);
-        if (record2NonPrimary) end2.setNotPrimaryAlignmentFlag(true);
+        if (record1NonPrimary) end1.setSecondaryAlignmentFlag(true);
+        if (record2NonPrimary) end2.setSecondaryAlignmentFlag(true);
 
-        if (record1NonPrimary) end1.setNotPrimaryAlignmentFlag(true);
-        if (record2NonPrimary) end2.setNotPrimaryAlignmentFlag(true);
+        if (record1NonPrimary) end1.setSecondaryAlignmentFlag(true);
+        if (record2NonPrimary) end2.setSecondaryAlignmentFlag(true);
 
         // set mate info
         SamPairUtil.setMateInfo(end1, end2, true);

src/main/java/htsjdk/samtools/SAMUtils.java

@@ -580,7 +580,7 @@ public static void makeReadUnmapped(final SAMRecord rec) {
         rec.setCigarString(SAMRecord.NO_ALIGNMENT_CIGAR);
         rec.setMappingQuality(SAMRecord.NO_MAPPING_QUALITY);
         rec.setInferredInsertSize(0);
-        rec.setNotPrimaryAlignmentFlag(false);
+        rec.setSecondaryAlignmentFlag(false);
         rec.setSupplementaryAlignmentFlag(false);
         rec.setProperPairFlag(false);
         rec.setReadUnmappedFlag(true);

src/main/java/htsjdk/samtools/SamFlagField.java

@@ -111,7 +111,7 @@ public String format(final int flag) {
             if ((flag & SAMFlag.FIRST_OF_PAIR.flag) != 0)                   value.append('1');
             if ((flag & SAMFlag.SECOND_OF_PAIR.flag) != 0)                  value.append('2');
 
-            if ((flag & SAMFlag.NOT_PRIMARY_ALIGNMENT.flag) != 0)           value.append('s');
+            if ((flag & SAMFlag.SECONDARY_ALIGNMENT.flag) != 0)           value.append('s');
             if ((flag & SAMFlag.SUPPLEMENTARY_ALIGNMENT.flag) != 0)         value.append('S');
             if ((flag & SAMFlag.READ_FAILS_VENDOR_QUALITY_CHECK.flag) != 0) value.append('x');
             if ((flag & SAMFlag.DUPLICATE_READ.flag) != 0)                  value.append('d');
@@ -138,7 +138,7 @@ protected int parseWithoutValidation(final String flag) {
                     case 'R':  value |= SAMFlag.MATE_REVERSE_STRAND.flag;  break;
                     case '1':  value |= SAMFlag.FIRST_OF_PAIR.flag;  break;
                     case '2':  value |= SAMFlag.SECOND_OF_PAIR.flag;  break;
-                    case 's':  value |= SAMFlag.NOT_PRIMARY_ALIGNMENT.flag;  break;
+                    case 's':  value |= SAMFlag.SECONDARY_ALIGNMENT.flag;  break;
                     case 'x':  value |= SAMFlag.READ_FAILS_VENDOR_QUALITY_CHECK.flag;  break;
                     case 'd':  value |= SAMFlag.DUPLICATE_READ.flag;  break;
                     case 'S':  value |= SAMFlag.SUPPLEMENTARY_ALIGNMENT.flag;  break;

src/main/java/htsjdk/samtools/SecondaryOrSupplementarySkippingIterator.java

@@ -6,7 +6,7 @@
 /**
  * Wrapper around SAMRecord iterator that skips over secondary and supplementary elements.
  * This iterator conflates a filtering iterator and a peekable iterator.  It would be cleaner to
- * handle those concerns separately. This class should be viewed as a replacement for NotPrimarySkippingIterator,
+ * handle those concerns separately. This class should be viewed as a replacement for SecondarySkippingIterator,
  * in that we did not want to change the functionality of NPSI to no longer match its name
  */
 public class SecondaryOrSupplementarySkippingIterator {

src/main/java/htsjdk/samtools/SecondarySkippingIterator.java

@@ -0,0 +1,62 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2009 The Broad Institute
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package htsjdk.samtools;
+
+import htsjdk.samtools.util.CloseableIterator;
+import htsjdk.samtools.util.PeekIterator;
+
+/**
+ * Wrapper around SAMRecord iterator that skips over secondary elements.
+ * This iterator conflates a filtering iterator and a peekable iterator.  It would be cleaner to
+ * handle those concerns separately.
+ */
+public class SecondarySkippingIterator {
+    private final PeekIterator<SAMRecord> it;
+
+    public SecondarySkippingIterator(final CloseableIterator<SAMRecord> underlyingIt) {
+        it = new PeekIterator<>(underlyingIt);
+        skipAnySecondary();
+    }
+
+    public boolean hasCurrent() {
+        return it.hasNext();
+    }
+
+    public SAMRecord getCurrent() {
+        assert(hasCurrent());
+        return it.peek();
+    }
+
+    public boolean advance() {
+        it.next();
+        skipAnySecondary();
+        return hasCurrent();
+    }
+
+    private void skipAnySecondary() {
+        while (it.hasNext() && it.peek().getSecondaryAlignmentFlag()) {
+            it.next();
+        }
+    }
+}

src/main/java/htsjdk/samtools/cram/build/Cram2SamRecordFactory.java

@@ -108,7 +108,7 @@ private static void copyFlags(final CramCompressionRecord cramRecord, final SAMR
         samRecord.setReadNegativeStrandFlag(cramRecord.isNegativeStrand());
         samRecord.setFirstOfPairFlag(cramRecord.isFirstSegment());
         samRecord.setSecondOfPairFlag(cramRecord.isLastSegment());
-        samRecord.setNotPrimaryAlignmentFlag(cramRecord.isSecondaryAlignment());
+        samRecord.setSecondaryAlignmentFlag(cramRecord.isSecondaryAlignment());
         samRecord.setReadFailsVendorQualityCheckFlag(cramRecord.isVendorFiltered());
         samRecord.setDuplicateReadFlag(cramRecord.isDuplicate());
         samRecord.setSupplementaryAlignmentFlag(cramRecord.isSupplementary());

src/main/java/htsjdk/samtools/cram/build/Sam2CramRecordFactory.java

@@ -93,7 +93,7 @@ public CramCompressionRecord createCramRecord(final SAMRecord record) {
         cramRecord.setNegativeStrand(record.getReadNegativeStrandFlag());
         cramRecord.setFirstSegment(record.getReadPairedFlag() && record.getFirstOfPairFlag());
         cramRecord.setLastSegment(record.getReadPairedFlag() && record.getSecondOfPairFlag());
-        cramRecord.setSecondaryAlignment(record.getNotPrimaryAlignmentFlag());
+        cramRecord.setSecondaryAlignment(record.getSecondaryAlignmentFlag());
         cramRecord.setVendorFiltered(record.getReadFailsVendorQualityCheckFlag());
         cramRecord.setDuplicate(record.getDuplicateReadFlag());
         cramRecord.setSupplementary(record.getSupplementaryAlignmentFlag());

src/main/java/htsjdk/samtools/filter/NotPrimaryAlignmentFilter.java

@@ -23,34 +23,13 @@
  */
 package htsjdk.samtools.filter;
 
-import htsjdk.samtools.SAMRecord;
-
 /**
  * Filter out SAMRecords with NotPrimaryAlignment flag set
  *
  * $Id$
+ * @deprecated use {@link SecondaryAlignmentFilter} instead.
  */
-public class NotPrimaryAlignmentFilter implements SamRecordFilter {
-    /**
-     * @param record the SAMRecord to evaluate
-     * @return true if the SAMRecord matches the filter, otherwise false
-     */
-    @Override
-    public boolean filterOut(final SAMRecord record) {
-        return record.getNotPrimaryAlignmentFlag();
-    }
+@Deprecated
+public class NotPrimaryAlignmentFilter extends SecondaryAlignmentFilter {
 
-    /**
-     * Determines whether a pair of SAMRecord matches this filter
-     *
-     * @param first  the first SAMRecord to evaluate
-     * @param second the second SAMRecord to evaluate
-     *
-     * @return true if the SAMRecords matches the filter, otherwise false
-     */
-    @Override
-    public boolean filterOut(final SAMRecord first, final SAMRecord second) {
-        // if either fails, exclude them both
-        return (first.getNotPrimaryAlignmentFlag() || second.getNotPrimaryAlignmentFlag());
-    }
 }

src/main/java/htsjdk/samtools/filter/SecondaryAlignmentFilter.java

@@ -10,13 +10,13 @@ public class SecondaryAlignmentFilter implements SamRecordFilter {
      * Returns true if the read is marked as secondary.
      */
     @Override
-    public boolean filterOut(final SAMRecord record) { return record.getNotPrimaryAlignmentFlag(); }
+    public boolean filterOut(final SAMRecord record) { return record.getSecondaryAlignmentFlag(); }
 
     /**
      * Returns true if either read is marked as secondary.
      */
     @Override
     public boolean filterOut(final SAMRecord first, final SAMRecord second) {
-        return first.getNotPrimaryAlignmentFlag() || second.getNotPrimaryAlignmentFlag();
+        return first.getSecondaryAlignmentFlag() || second.getSecondaryAlignmentFlag();
     }
 }

src/main/java/htsjdk/samtools/filter/SecondaryOrSupplementaryFilter.java

@@ -3,8 +3,8 @@
 import htsjdk.samtools.SAMRecord;
 
 /**
- * Filter out SAMRecords with NotPrimaryAlignment or Supplementary flag set
- * This class should be viewed as a replacement for NotPrimarySkippingIterator,
+ * Filter out SAMRecords with Secondary or Supplementary flag set
+ * This class should be viewed as a replacement for {@link htsjdk.samtools.NotPrimarySkippingIterator},
  * in that we did not want to change the functionality of NPSI to no longer match its name
  * $Id$
  */