net.sf.samtools
Class SAMRecord

java.lang.Object
  extended by net.sf.samtools.SAMRecord
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
BAMRecord

public class SAMRecord
extends Object
implements Cloneable

Author:
alecw@broadinstitute.org, mishali.naik@intel.com

Nested Class Summary
static class SAMRecord.SAMTagAndValue
          Tag name and value of an attribute, for getAttributes() method.
 
Field Summary
static int MAX_INSERT_SIZE
          abs(insertSize) must be <= this
protected  Integer mMateReferenceIndex
           
protected  Integer mReferenceIndex
           
static String NO_ALIGNMENT_CIGAR
          Cigar string for an unaligned read.
static int NO_ALIGNMENT_REFERENCE_INDEX
          If a read has this reference index, it is unaligned, but not all unaligned reads have this reference index (see above).
static String NO_ALIGNMENT_REFERENCE_NAME
          If a read has this reference name, it is unaligned, but not all unaligned reads have this reference name (see above).
static int NO_ALIGNMENT_START
          If a read has reference name "*", it will have this value for position.
static int NO_MAPPING_QUALITY
          Alignment score for an unaligned read.
static byte[] NULL_QUALS
          This should rarely be used, since all reads should have quality scores.
static String NULL_QUALS_STRING
           
static byte[] NULL_SEQUENCE
          This should rarely be used, since a read with no sequence doesn't make much sense.
static String NULL_SEQUENCE_STRING
           
static int UNKNOWN_MAPPING_QUALITY
          Alignment score for a good alignment, but where computing a Phred-score is not feasible.
 
Constructor Summary
SAMRecord(SAMFileHeader header)
           
 
Method Summary
 void clearAttributes()
          Removes all attributes.
 Object clone()
          Note that this does a shallow copy of everything, except for the attribute list, for which a copy of the list is made, but the attributes themselves are copied by reference.
protected  void eagerDecode()
          Force all lazily-initialized data members to be initialized.
 boolean equals(Object o)
           
 String format()
          Deprecated. This method is not guaranteed to return a valid SAM text representation of the SAMRecord. To get standard SAM text representation, use net.sf.samtools.SAMRecord#getSAMString().
 List<AlignmentBlock> getAlignmentBlocks()
          Returns blocks of the read sequence that have been aligned directly to the reference sequence.
 int getAlignmentEnd()
           
 int getAlignmentStart()
           
 Object getAttribute(short tag)
           
 Object getAttribute(String tag)
          Get the value for a SAM tag.
 List<SAMRecord.SAMTagAndValue> getAttributes()
           
 int getAttributesBinarySize()
          Depending on the concrete implementation, the binary file size of attributes may be known without computing them all.
 byte[] getBaseQualities()
          Do not modify the value returned by this method.
 String getBaseQualityString()
           
protected  SAMBinaryTagAndValue getBinaryAttributes()
           
 byte[] getByteArrayAttribute(String tag)
          Will work for signed byte array, unsigned byte array, or old-style hex array
 Byte getByteAttribute(String tag)
          Get the tag value and attempt to coerce it into the requested type.
 Character getCharacterAttribute(String tag)
           
 Cigar getCigar()
          Do not modify the value returned by this method.
 int getCigarLength()
          This method is preferred over getCigar().getNumElements(), because for BAMRecord it may be faster.
 String getCigarString()
           
 boolean getDuplicateReadFlag()
          the read is either a PCR duplicate or an optical duplicate.
 SAMFileSource getFileSource()
          Gets the source of this SAM record -- both the reader that retrieved the record and the position on disk from whence it came.
 boolean getFirstOfPairFlag()
          the read is the first read in a pair.
 int getFlags()
          It is preferable to use the get*Flag() methods that handle the flag word symbolically.
 float[] getFloatArrayAttribute(String tag)
           
 Float getFloatAttribute(String tag)
           
 SAMFileHeader getHeader()
           
 int getInferredInsertSize()
           
 Integer getIntegerAttribute(String tag)
          Get the tag value and attempt to coerce it into the requested type.
 int getMappingQuality()
           
 int getMateAlignmentStart()
           
 boolean getMateNegativeStrandFlag()
          strand of the mate (false for forward; true for reverse strand).
 Integer getMateReferenceIndex()
           
 String getMateReferenceName()
           
 boolean getMateUnmappedFlag()
          the mate is unmapped.
 boolean getNotPrimaryAlignmentFlag()
          the alignment is not primary (a read having split hits may have multiple primary alignment records).
 byte[] getOriginalBaseQualities()
          If the original base quality scores have been store in the "OQ" tag will return the numeric score as a byte[]
 boolean getProperPairFlag()
          the read is mapped in a proper pair (depends on the protocol, normally inferred during alignment).
 byte[] getReadBases()
          Do not modify the value returned by this method.
 boolean getReadFailsVendorQualityCheckFlag()
          the read fails platform/vendor quality checks.
 SAMReadGroupRecord getReadGroup()
          Get the SAMReadGroupRecord for this SAMRecord.
 int getReadLength()
          This method is preferred over getReadBases().length, because for BAMRecord it may be faster.
 String getReadName()
           
 int getReadNameLength()
          This method is preferred over getReadName().length(), because for BAMRecord it may be faster.
 boolean getReadNegativeStrandFlag()
          strand of the query (false for forward; true for reverse strand).
 boolean getReadPairedFlag()
          the read is paired in sequencing, no matter whether it is mapped in a pair.
 String getReadString()
           
 boolean getReadUnmappedFlag()
          the query sequence itself is unmapped.
 Integer getReferenceIndex()
           
 String getReferenceName()
           
 int getReferencePositionAtReadPosition(int offset)
           
 String getSAMString()
          Returns the record in the SAM line-based text format.
 boolean getSecondOfPairFlag()
          the read is the second read in a pair.
 Short getShortAttribute(String tag)
          Get the tag value and attempt to coerce it into the requested type.
 byte[] getSignedByteArrayAttribute(String tag)
          Will work for signed byte array or old-style hex array
 int[] getSignedIntArrayAttribute(String tag)
           
 short[] getSignedShortArrayAttribute(String tag)
           
 String getStringAttribute(String tag)
           
 boolean getSupplementaryAlignmentFlag()
          the alignment is supplementary (TODO: further explanation?).
 int getUnclippedEnd()
           
 int getUnclippedStart()
           
 byte[] getUnsignedByteArrayAttribute(String tag)
           
 int[] getUnsignedIntArrayAttribute(String tag)
           
 short[] getUnsignedShortArrayAttribute(String tag)
           
 SAMFileReader.ValidationStringency getValidationStringency()
           
 byte[] getVariableBinaryRepresentation()
          If this record has a valid binary representation of the variable-length portion of a binary record stored, return that byte array, otherwise return null.
 int hashCode()
           
protected  void initializeCigar(Cigar cigar)
          For setting the Cigar string when BAMRecord has decoded it.
 boolean isSecondaryOrSupplementary()
          Tests if this record is either a secondary and/or supplementary alignment; equivalent to (getNotPrimaryAlignmentFlag() || getSupplementaryAlignmentFlag()).
 boolean isUnsignedArrayAttribute(String tag)
           
 List<SAMValidationError> isValid()
          Perform various validations of SAMRecord.
 void setAlignmentEnd(int value)
          Unsupported.
 void setAlignmentStart(int value)
           
protected  void setAttribute(short tag, Object value)
           
protected  void setAttribute(short tag, Object value, boolean isUnsignedArray)
           
 void setAttribute(String tag, Object value)
          Set a named attribute onto the SAMRecord.
protected  void setAttributes(SAMBinaryTagAndValue attributes)
          Replace any existing attributes with the given linked item.
 void setBaseQualities(byte[] value)
           
 void setBaseQualityString(String value)
           
 void setCigar(Cigar cigar)
           
 void setCigarString(String value)
           
 void setDuplicateReadFlag(boolean flag)
          the read is either a PCR duplicate or an optical duplicate.
protected  void setFileSource(SAMFileSource fileSource)
          Sets a marker providing the source reader for this file and the position in the file from which the read originated.
 void setFirstOfPairFlag(boolean flag)
          the read is the first read in a pair.
 void setFlags(int value)
           
 void setHeader(SAMFileHeader header)
          Setting header into SAMRecord facilitates conversion btw reference sequence names and indices
 void setInferredInsertSize(int inferredInsertSize)
           
 void setMappingQuality(int value)
           
 void setMateAlignmentStart(int mateAlignmentStart)
           
 void setMateNegativeStrandFlag(boolean flag)
          strand of the mate (false for forward; true for reverse strand).
 void setMateReferenceIndex(int referenceIndex)
           
 void setMateReferenceName(String mateReferenceName)
           
 void setMateUnmappedFlag(boolean flag)
          the mate is unmapped.
 void setNotPrimaryAlignmentFlag(boolean flag)
          the alignment is not primary (a read having split hits may have multiple primary alignment records).
 void setOriginalBaseQualities(byte[] oq)
          Sets the original base quality scores into the "OQ" tag as a String.
 void setProperPairFlag(boolean flag)
          the read is mapped in a proper pair (depends on the protocol, normally inferred during alignment).
 void setReadBases(byte[] value)
           
 void setReadFailsVendorQualityCheckFlag(boolean flag)
          the read fails platform/vendor quality checks.
 void setReadName(String value)
           
 void setReadNegativeStrandFlag(boolean flag)
          strand of the query (false for forward; true for reverse strand).
 void setReadPairedFlag(boolean flag)
          the read is paired in sequencing, no matter whether it is mapped in a pair.
 void setReadString(String value)
           
 void setReadUmappedFlag(boolean flag)
          Deprecated.  
 void setReadUnmappedFlag(boolean flag)
          the query sequence itself is unmapped.
 void setReferenceIndex(int referenceIndex)
           
 void setReferenceName(String value)
           
 void setSecondOfPairFlag(boolean flag)
          the read is the second read in a pair.
 void setSupplementaryAlignmentFlag(boolean flag)
          the alignment is supplementary (TODO: further explanation?).
 void setUnsignedArrayAttribute(String tag, Object value)
          Because Java does not support unsigned integer types, we think it is a bad idea to encode them in SAM files.
 void setValidationStringency(SAMFileReader.ValidationStringency validationStringency)
          Control validation of lazily-decoded elements.
 String toString()
          Simple toString() that gives a little bit of useful info about the read.
 List<SAMValidationError> validateCigar(long recordNumber)
          Run all validations of CIGAR.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

UNKNOWN_MAPPING_QUALITY

public static final int UNKNOWN_MAPPING_QUALITY
Alignment score for a good alignment, but where computing a Phred-score is not feasible.

See Also:
Constant Field Values

NO_MAPPING_QUALITY

public static final int NO_MAPPING_QUALITY
Alignment score for an unaligned read.

See Also:
Constant Field Values

NO_ALIGNMENT_REFERENCE_NAME

public static final String NO_ALIGNMENT_REFERENCE_NAME
If a read has this reference name, it is unaligned, but not all unaligned reads have this reference name (see above).

See Also:
Constant Field Values

NO_ALIGNMENT_REFERENCE_INDEX

public static final int NO_ALIGNMENT_REFERENCE_INDEX
If a read has this reference index, it is unaligned, but not all unaligned reads have this reference index (see above).

See Also:
Constant Field Values

NO_ALIGNMENT_CIGAR

public static final String NO_ALIGNMENT_CIGAR
Cigar string for an unaligned read.

See Also:
Constant Field Values

NO_ALIGNMENT_START

public static final int NO_ALIGNMENT_START
If a read has reference name "*", it will have this value for position.

See Also:
Constant Field Values

NULL_SEQUENCE

public static final byte[] NULL_SEQUENCE
This should rarely be used, since a read with no sequence doesn't make much sense.


NULL_SEQUENCE_STRING

public static final String NULL_SEQUENCE_STRING
See Also:
Constant Field Values

NULL_QUALS

public static final byte[] NULL_QUALS
This should rarely be used, since all reads should have quality scores.


NULL_QUALS_STRING

public static final String NULL_QUALS_STRING
See Also:
Constant Field Values

MAX_INSERT_SIZE

public static final int MAX_INSERT_SIZE
abs(insertSize) must be <= this

See Also:
Constant Field Values

mReferenceIndex

protected Integer mReferenceIndex

mMateReferenceIndex

protected Integer mMateReferenceIndex
Constructor Detail

SAMRecord

public SAMRecord(SAMFileHeader header)
Method Detail

getReadName

public String getReadName()

getReadNameLength

public int getReadNameLength()
This method is preferred over getReadName().length(), because for BAMRecord it may be faster.

Returns:
length not including a null terminator.

setReadName

public void setReadName(String value)

getReadString

public String getReadString()
Returns:
read sequence as a string of ACGTN=.

setReadString

public void setReadString(String value)

getReadBases

public byte[] getReadBases()
Do not modify the value returned by this method. If you want to change the bases, create a new byte[] and call setReadBases() or call setReadString().

Returns:
read sequence as ASCII bytes ACGTN=.

setReadBases

public void setReadBases(byte[] value)

getReadLength

public int getReadLength()
This method is preferred over getReadBases().length, because for BAMRecord it may be faster.

Returns:
number of bases in the read.

getBaseQualityString

public String getBaseQualityString()
Returns:
Base qualities, encoded as a FASTQ string.

setBaseQualityString

public void setBaseQualityString(String value)

getBaseQualities

public byte[] getBaseQualities()
Do not modify the value returned by this method. If you want to change the qualities, create a new byte[] and call setBaseQualities() or call setBaseQualityString().

Returns:
Base qualities, as binary phred scores (not ASCII).

setBaseQualities

public void setBaseQualities(byte[] value)

getOriginalBaseQualities

public byte[] getOriginalBaseQualities()
If the original base quality scores have been store in the "OQ" tag will return the numeric score as a byte[]


setOriginalBaseQualities

public void setOriginalBaseQualities(byte[] oq)
Sets the original base quality scores into the "OQ" tag as a String. Supplied value should be as phred-scaled numeric qualities.


getReferenceName

public String getReferenceName()
Returns:
Reference name, or null if record has no reference.

setReferenceName

public void setReferenceName(String value)

getReferenceIndex

public Integer getReferenceIndex()
Returns:
index of the reference sequence for this read in the sequence dictionary, or -1 if read has no reference sequence set, or if a String reference name is not found in the sequence index..

setReferenceIndex

public void setReferenceIndex(int referenceIndex)
Parameters:
referenceIndex - Must either equal -1 (indicating no reference), or exist in the sequence dictionary in the header associated with this record.

getMateReferenceName

public String getMateReferenceName()
Returns:
Mate reference name, or null if one is not assigned.

setMateReferenceName

public void setMateReferenceName(String mateReferenceName)

getMateReferenceIndex

public Integer getMateReferenceIndex()
Returns:
index of the reference sequence for this read's mate in the sequence dictionary, or -1 if mate has no reference sequence set.

setMateReferenceIndex

public void setMateReferenceIndex(int referenceIndex)
Parameters:
referenceIndex - Must either equal -1 (indicating no reference), or exist in the sequence dictionary in the header associated with this record.

getAlignmentStart

public int getAlignmentStart()
Returns:
1-based inclusive leftmost position of the clipped sequence, or 0 if there is no position.

setAlignmentStart

public void setAlignmentStart(int value)
Parameters:
value - 1-based inclusive leftmost position of the clipped sequence, or 0 if there is no position.

getAlignmentEnd

public int getAlignmentEnd()
Returns:
1-based inclusive rightmost position of the clipped sequence, or 0 read if unmapped.

getUnclippedStart

public int getUnclippedStart()
Returns:
the alignment start (1-based, inclusive) adjusted for clipped bases. For example if the read has an alignment start of 100 but the first 4 bases were clipped (hard or soft clipped) then this method will return 96. Invalid to call on an unmapped read.

getUnclippedEnd

public int getUnclippedEnd()
Returns:
the alignment end (1-based, inclusive) adjusted for clipped bases. For example if the read has an alignment end of 100 but the last 7 bases were clipped (hard or soft clipped) then this method will return 107. Invalid to call on an unmapped read.

getReferencePositionAtReadPosition

public int getReferencePositionAtReadPosition(int offset)
Returns:
1-based inclusive reference position of the unclipped sequence at a given offset, or 0 if there is no position. For example, given the sequence NNNAAACCCGGG, cigar 3S9M, and an alignment start of 1, and a (1-based)offset 10 (start of GGG) it returns 7 (1-based offset starting after the soft clip. For example: given the sequence AAACCCGGGTTT, cigar 4M1D6M, an alignment start of 1, an offset of 4 returns reference position 4, an offset of 5 returns reference position 6. Another example: given the sequence AAACCCGGGTTT, cigar 4M1I6M, an alignment start of 1, an offset of 4 returns reference position 4, an offset of 5 returns 0.

setAlignmentEnd

public void setAlignmentEnd(int value)
Unsupported. This property is derived from alignment start and CIGAR.


getMateAlignmentStart

public int getMateAlignmentStart()
Returns:
1-based inclusive leftmost position of the clipped mate sequence, or 0 if there is no position.

setMateAlignmentStart

public void setMateAlignmentStart(int mateAlignmentStart)

getInferredInsertSize

public int getInferredInsertSize()
Returns:
insert size (difference btw 5' end of read & 5' end of mate), if possible, else 0. Negative if mate maps to lower position than read.

setInferredInsertSize

public void setInferredInsertSize(int inferredInsertSize)

getMappingQuality

public int getMappingQuality()
Returns:
phred scaled mapping quality. 255 implies valid mapping but quality is hard to compute.

setMappingQuality

public void setMappingQuality(int value)

getCigarString

public String getCigarString()

setCigarString

public void setCigarString(String value)

getCigar

public Cigar getCigar()
Do not modify the value returned by this method. If you want to change the Cigar, create a new Cigar and call setCigar() or call setCigarString()

Returns:
Cigar object for the read, or null if there is none.

getCigarLength

public int getCigarLength()
This method is preferred over getCigar().getNumElements(), because for BAMRecord it may be faster.

Returns:
number of cigar elements (number + operator) in the cigar string.

setCigar

public void setCigar(Cigar cigar)

initializeCigar

protected void initializeCigar(Cigar cigar)
For setting the Cigar string when BAMRecord has decoded it. Use this rather than setCigar() so that indexing bin doesn't get clobbered.


getReadGroup

public SAMReadGroupRecord getReadGroup()
Get the SAMReadGroupRecord for this SAMRecord.

Returns:
The SAMReadGroupRecord from the SAMFileHeader for this SAMRecord, or null if 1) this record has no RG tag, or 2) the header doesn't contain the read group with the given ID.
Throws:
NullPointerException - if this.getHeader() returns null.
ClassCastException - if RG tag does not have a String value.

getFlags

public int getFlags()
It is preferable to use the get*Flag() methods that handle the flag word symbolically.


setFlags

public void setFlags(int value)

getReadPairedFlag

public boolean getReadPairedFlag()
the read is paired in sequencing, no matter whether it is mapped in a pair.


getProperPairFlag

public boolean getProperPairFlag()
the read is mapped in a proper pair (depends on the protocol, normally inferred during alignment).


getReadUnmappedFlag

public boolean getReadUnmappedFlag()
the query sequence itself is unmapped.


getMateUnmappedFlag

public boolean getMateUnmappedFlag()
the mate is unmapped.


getReadNegativeStrandFlag

public boolean getReadNegativeStrandFlag()
strand of the query (false for forward; true for reverse strand).


getMateNegativeStrandFlag

public boolean getMateNegativeStrandFlag()
strand of the mate (false for forward; true for reverse strand).


getFirstOfPairFlag

public boolean getFirstOfPairFlag()
the read is the first read in a pair.


getSecondOfPairFlag

public boolean getSecondOfPairFlag()
the read is the second read in a pair.


getNotPrimaryAlignmentFlag

public boolean getNotPrimaryAlignmentFlag()
the alignment is not primary (a read having split hits may have multiple primary alignment records).


getSupplementaryAlignmentFlag

public boolean getSupplementaryAlignmentFlag()
the alignment is supplementary (TODO: further explanation?).


getReadFailsVendorQualityCheckFlag

public boolean getReadFailsVendorQualityCheckFlag()
the read fails platform/vendor quality checks.


getDuplicateReadFlag

public boolean getDuplicateReadFlag()
the read is either a PCR duplicate or an optical duplicate.


setReadPairedFlag

public void setReadPairedFlag(boolean flag)
the read is paired in sequencing, no matter whether it is mapped in a pair.


setProperPairFlag

public void setProperPairFlag(boolean flag)
the read is mapped in a proper pair (depends on the protocol, normally inferred during alignment).


setReadUmappedFlag

public void setReadUmappedFlag(boolean flag)
Deprecated. 

the query sequence itself is unmapped. This method name is misspelled. Use setReadUnmappedFlag instead.


setReadUnmappedFlag

public void setReadUnmappedFlag(boolean flag)
the query sequence itself is unmapped.


setMateUnmappedFlag

public void setMateUnmappedFlag(boolean flag)
the mate is unmapped.


setReadNegativeStrandFlag

public void setReadNegativeStrandFlag(boolean flag)
strand of the query (false for forward; true for reverse strand).


setMateNegativeStrandFlag

public void setMateNegativeStrandFlag(boolean flag)
strand of the mate (false for forward; true for reverse strand).


setFirstOfPairFlag

public void setFirstOfPairFlag(boolean flag)
the read is the first read in a pair.


setSecondOfPairFlag

public void setSecondOfPairFlag(boolean flag)
the read is the second read in a pair.


setNotPrimaryAlignmentFlag

public void setNotPrimaryAlignmentFlag(boolean flag)
the alignment is not primary (a read having split hits may have multiple primary alignment records).


setSupplementaryAlignmentFlag

public void setSupplementaryAlignmentFlag(boolean flag)
the alignment is supplementary (TODO: further explanation?).


setReadFailsVendorQualityCheckFlag

public void setReadFailsVendorQualityCheckFlag(boolean flag)
the read fails platform/vendor quality checks.


setDuplicateReadFlag

public void setDuplicateReadFlag(boolean flag)
the read is either a PCR duplicate or an optical duplicate.


isSecondaryOrSupplementary

public boolean isSecondaryOrSupplementary()
Tests if this record is either a secondary and/or supplementary alignment; equivalent to (getNotPrimaryAlignmentFlag() || getSupplementaryAlignmentFlag()).


getValidationStringency

public SAMFileReader.ValidationStringency getValidationStringency()

setValidationStringency

public void setValidationStringency(SAMFileReader.ValidationStringency validationStringency)
Control validation of lazily-decoded elements.


getAttribute

public Object getAttribute(String tag)
Get the value for a SAM tag. WARNING: Some value types (e.g. byte[]) are mutable. It is dangerous to change one of these values in place, because some SAMRecord implementations keep track of when attributes have been changed. If you want to change an attribute value, call setAttribute() to replace the value.

Parameters:
tag - Two-character tag name.
Returns:
Appropriately typed tag value, or null if the requested tag is not present.

getIntegerAttribute

public Integer getIntegerAttribute(String tag)
Get the tag value and attempt to coerce it into the requested type.

Parameters:
tag - The requested tag.
Returns:
The value of a tag, converted into an Integer if possible.
Throws:
RuntimeException - If the value is not an integer type, or will not fit in an Integer.

getShortAttribute

public Short getShortAttribute(String tag)
Get the tag value and attempt to coerce it into the requested type.

Parameters:
tag - The requested tag.
Returns:
The value of a tag, converted into a Short if possible.
Throws:
RuntimeException - If the value is not an integer type, or will not fit in a Short.

getByteAttribute

public Byte getByteAttribute(String tag)
Get the tag value and attempt to coerce it into the requested type.

Parameters:
tag - The requested tag.
Returns:
The value of a tag, converted into a Byte if possible.
Throws:
RuntimeException - If the value is not an integer type, or will not fit in a Byte.

getStringAttribute

public String getStringAttribute(String tag)

getCharacterAttribute

public Character getCharacterAttribute(String tag)

getFloatAttribute

public Float getFloatAttribute(String tag)

getByteArrayAttribute

public byte[] getByteArrayAttribute(String tag)
Will work for signed byte array, unsigned byte array, or old-style hex array


getUnsignedByteArrayAttribute

public byte[] getUnsignedByteArrayAttribute(String tag)

getSignedByteArrayAttribute

public byte[] getSignedByteArrayAttribute(String tag)
Will work for signed byte array or old-style hex array


getUnsignedShortArrayAttribute

public short[] getUnsignedShortArrayAttribute(String tag)

getSignedShortArrayAttribute

public short[] getSignedShortArrayAttribute(String tag)

getUnsignedIntArrayAttribute

public int[] getUnsignedIntArrayAttribute(String tag)

getSignedIntArrayAttribute

public int[] getSignedIntArrayAttribute(String tag)

getFloatArrayAttribute

public float[] getFloatArrayAttribute(String tag)

isUnsignedArrayAttribute

public boolean isUnsignedArrayAttribute(String tag)
Returns:
True if this tag is an unsigned array, else false.
Throws:
SAMException - if the tag is not present.

getAttribute

public Object getAttribute(short tag)
Parameters:
tag - Binary representation of a 2-char String tag as created by SAMTagUtil.
See Also:
getAttribute(java.lang.String)

setAttribute

public void setAttribute(String tag,
                         Object value)
Set a named attribute onto the SAMRecord. Passing a null value causes the attribute to be cleared.

Parameters:
tag - two-character tag name. See http://samtools.sourceforge.net/SAM1.pdf for standard and user-defined tags.
value - Supported types are String, Char, Integer, Float, byte[], short[]. int[], float[]. If value == null, tag is cleared. Byte and Short are allowed but discouraged. If written to a SAM file, these will be converted to Integer, whereas if written to BAM, getAttribute() will return as Byte or Short, respectively. Long with value between 0 and MAX_UINT is allowed for BAM but discouraged. Attempting to write such a value to SAM will cause an exception to be thrown. To set unsigned byte[], unsigned short[] or unsigned int[] (which is discouraged because of poor Java language support), setUnsignedArrayAttribute() must be used instead of this method. String values are not validated to ensure that they conform to SAM spec.

setUnsignedArrayAttribute

public void setUnsignedArrayAttribute(String tag,
                                      Object value)
Because Java does not support unsigned integer types, we think it is a bad idea to encode them in SAM files. If you must do so, however, you must call this method rather than setAttribute, because calling this method is the way to indicate that, e.g. a short array should be interpreted as unsigned shorts.

Parameters:
value - must be one of byte[], short[], int[]

setAttribute

protected void setAttribute(short tag,
                            Object value)
Parameters:
tag - Binary representation of a 2-char String tag as created by SAMTagUtil.
See Also:
setAttribute(java.lang.String, java.lang.Object)

setAttribute

protected void setAttribute(short tag,
                            Object value,
                            boolean isUnsignedArray)

clearAttributes

public void clearAttributes()
Removes all attributes.


setAttributes

protected void setAttributes(SAMBinaryTagAndValue attributes)
Replace any existing attributes with the given linked item.


getBinaryAttributes

protected SAMBinaryTagAndValue getBinaryAttributes()
Returns:
Pointer to the first of the tags. Returns null if there are no tags.

getAttributes

public List<SAMRecord.SAMTagAndValue> getAttributes()
Returns:
list of {tag, value} tuples

getHeader

public SAMFileHeader getHeader()

setHeader

public void setHeader(SAMFileHeader header)
Setting header into SAMRecord facilitates conversion btw reference sequence names and indices

Parameters:
header - contains sequence dictionary for this SAMRecord

getVariableBinaryRepresentation

public byte[] getVariableBinaryRepresentation()
If this record has a valid binary representation of the variable-length portion of a binary record stored, return that byte array, otherwise return null. This will never be true for SAMRecords. It will be true for BAMRecords that have not been eagerDecoded(), and for which none of the data in the variable-length portion has been changed.


getAttributesBinarySize

public int getAttributesBinarySize()
Depending on the concrete implementation, the binary file size of attributes may be known without computing them all.

Returns:
binary file size of attribute, if known, else -1

format

public String format()
Deprecated. This method is not guaranteed to return a valid SAM text representation of the SAMRecord. To get standard SAM text representation, use net.sf.samtools.SAMRecord#getSAMString().

Returns:
String representation of this.

eagerDecode

protected void eagerDecode()
Force all lazily-initialized data members to be initialized. If a subclass overrides this method, typically it should also call super method.


getAlignmentBlocks

public List<AlignmentBlock> getAlignmentBlocks()
Returns blocks of the read sequence that have been aligned directly to the reference sequence. Note that clipped portions of the read and inserted and deleted bases (vs. the reference) are not represented in the alignment blocks.


validateCigar

public List<SAMValidationError> validateCigar(long recordNumber)
Run all validations of CIGAR. These include validation that the CIGAR makes sense independent of placement, plus validation that CIGAR + placement yields all bases with M operator within the range of the reference.

Parameters:
recordNumber - For error reporting. -1 if not known.
Returns:
List of errors, or null if no errors.

equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

isValid

public List<SAMValidationError> isValid()
Perform various validations of SAMRecord. Note that this method deliberately returns null rather than Collections.emptyList() if there are no validation errors, because callers tend to assume that if a non-null list is returned, it is modifiable.

Returns:
null if valid. If invalid, returns a list of error messages.

getFileSource

public SAMFileSource getFileSource()
Gets the source of this SAM record -- both the reader that retrieved the record and the position on disk from whence it came.

Returns:
The file source. Note that the reader will be null if not activated using SAMFileReader.enableFileSource().

setFileSource

protected void setFileSource(SAMFileSource fileSource)
Sets a marker providing the source reader for this file and the position in the file from which the read originated.

Parameters:
fileSource - source of the given file.

clone

public Object clone()
             throws CloneNotSupportedException
Note that this does a shallow copy of everything, except for the attribute list, for which a copy of the list is made, but the attributes themselves are copied by reference. This should be safe because callers should never modify a mutable value returned by any of the get() methods anyway.

Overrides:
clone in class Object
Throws:
CloneNotSupportedException

toString

public String toString()
Simple toString() that gives a little bit of useful info about the read.

Overrides:
toString in class Object

getSAMString

public String getSAMString()
Returns the record in the SAM line-based text format. Fields are separated by '\t' characters, and the String is terminated by '\n'.