public abstract class ImmutableSequence extends SequenceCharSequence implements SequenceDocument
SequenceDocument that is immutable
and has very low memory usage. Generally it is only advantageous to use ImmutableSequences when dealing with lots
of sequences. ImmutableSequences have a very low memory usage overhead per sequence, and lots of ImmutableSequences
constructed with an ImmutableSequence.Builder
that have names which have a common pattern will have low memory usage for storing their names.
As of Geneious 5.0, this class is unable to store annotations and sequence descriptions but these may be supported in future versions.
Data that is currently supported by this class includes
NucleotideGraphSequenceDocument), but not chromatogram trace data)
ImmutableSequence, use
createImmutableSequence(SequenceDocument, boolean)
or to achieve even lower memory usage when constructing many sequences which have a common pattern to their names, use
ImmutableSequence.Builder| Modifier and Type | Class and Description |
|---|---|
static class |
ImmutableSequence.Builder
Provides a system for building a list of ImmutableSequence which are even more compact than normal by analyzing patterns
in the names of sequences.
|
SequenceDocument.Alphabet, SequenceDocument.TransformerPluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProviderXMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypeEMPTYGENOME_SEQUENCE_THRESHOLDFILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELDROOT_ELEMENT_NAME| Modifier and Type | Method and Description |
|---|---|
abstract ImmutableSequence |
asDna()
Creates a new sequence that is identical to this sequence except with U replaced with T
|
abstract ImmutableSequence |
asRna()
Creates a new sequence that is identical to this sequence except with T replaced with U
|
static void |
compactAminoAcidSequences(List<AminoAcidSequenceDocument> sequences,
ProgressListener progressListener)
Attempts to compact the memory usage of as many sequences in the given list of sequences as possible
by replacing them with ImmutableSequence instances.
|
static void |
compactNucleotideSequences(List<NucleotideSequenceDocument> sequences,
ProgressListener progressListener)
Attempts to compact the memory usage of as many sequences in the given list of sequences as possible
by replacing them with ImmutableSequence instances.
|
abstract ImmutableSequence |
createCopyWithNameSuffix(String nameSuffix)
Creates a new sequence identical to this once except with a different name.
|
abstract ImmutableSequence |
createCopyWithNewName(String newName)
Creates a new sequence identical to this once except with a different name.
|
static ImmutableSequence |
createImmutableSequence(SequenceDocument sequence)
Creates an ImmutableSequence copy of another sequence if possible.
|
static ImmutableSequence |
createImmutableSequence(SequenceDocument sequence,
boolean failIfContainsNonStorableData)
Creates an ImmutableSequence copy of another sequence.
|
abstract ImmutableSequence |
delete(int deletionBegin,
int deletionEnd)
Returns a copy of this SequenceCharSequence where the characters at positions deletionBegin inclusive
to deletionEnd exclusive have been removed.
|
abstract int |
getCharAndQualityAtIgnoringEndGaps(int characterIndex)
Provides both the sequence character and the quality in a single method call, which is almost twice
as fast as requesting the 2 values separately.
|
abstract void |
getData(int internalStartIndex,
int sizeOfDataToGet,
byte[] characters,
byte[] qualities,
int startingOffsetIntoDataArrays)
Provides sequence character and qualities for multiple positions in a single method call,
which is much faster than requesting the values separately.
|
abstract int |
getLeadingTrimLength()
Gets the number of bases and non-end gaps at the start of this sequence flagged as trimmed (equivalent to annotations of type
SequenceAnnotation.TYPE_TRIMMED). |
abstract int |
getMappingQuality() |
abstract int |
getNumberOfIntegersOfStorage()
Returns the number of integers needed to store this document on disk and/or load it into memory
|
abstract int |
getNumberOfMappedLocations() |
abstract int |
getTrailingTrimLength()
Gets the number of bases and non-end gaps at the end of this sequence flagged as trimmed (equivalent to annotations of type
SequenceAnnotation.TYPE_TRIMMED) |
Geneious.MajorVersion |
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Implements
XMLSerializable.OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
but note that SequenceCharSequence is guaranteed to be able to always serialize to Geneious.MajorVersion#Version6_0 |
static ImmutableSequence |
immutableSequenceFromXML(org.jdom.Element element)
Recreates this sequence from XML returned from a previous call to
toXML(boolean). |
abstract ImmutableSequence |
insert(int index,
CharSequence charSequence)
Creates a copy of this SequenceCharSequence with the specified CharSequence inserted
at the specified index.
|
abstract ImmutableSequence |
insertGaps(int leadingGapsLength,
int trailingGapsLength,
int[] internalGapPositions,
int[] internalGapSizes)
Creates a new sequence identical to this one except with some gaps inserted.
|
abstract boolean |
isReversed()
Determine if this sequence is reversed (i.e.
|
static ImmutableSequence |
readObject(GeneiousObjectInputStream in)
Reads a instance of an
ImmutableSequence that
was previously written using SequenceCharSequence.writeObject(GeneiousObjectOutputStream, jebl.util.ProgressListener) |
abstract ImmutableSequence |
removeGaps()
Creates a new sequence identical to this once except all gaps (both end and internal) have been removed.
|
abstract ImmutableSequence |
reverse()
Create a new sequence that is the reverse of this sequence.
|
abstract ImmutableSequence |
reverseComplement()
Create a new sequence that is the reverse complement of this sequence.
|
String |
subString(int startIndex,
int endIndex)
Returns the characters between the 2 given indices as a string
|
org.jdom.Element |
toXML(boolean allowFileData)
Serializes this SequenceCharSequence to XML into an element named
XMLSerializable.ROOT_ELEMENT_NAME. |
org.jdom.Element |
toXML(Geneious.MajorVersion version,
ProgressListener progressListener,
boolean allowFileData)
Serializes this SequenceCharSequence to XML into an element named
XMLSerializable.ROOT_ELEMENT_NAME. |
abstract ImmutableSequence |
withMappingQuality(int mappingQuality)
Creates a new sequence identical to this one, except with a different value for
getMappingQuality() |
abstract ImmutableSequence |
withNumberOfMappedLocations(int numberOfMappedLocations)
Creates a new sequence identical to this one, except with a different value for
getNumberOfMappedLocations() |
abstract ImmutableSequence |
withTrimLengths(int leadingTrimLength,
int trailingTrimLength)
Creates a new sequence identical to this one, except with different leading and trailing trim lengths.
|
void |
writeObject(DataOutput out,
ProgressListener progressListener)
Writes this sequence to a DataOutput.
|
void |
writeObject(Geneious.MajorVersion version,
DataOutput out,
ProgressListener progressListener)
Writes this sequence to a DataOutput.
|
charAt, charAtIgnoringEndGaps, compareTo, contains, containsInvalidResidues, count, countGaps, equals, equalsIgnoreCase, fromXml, fromXML, getInternalCharSequence, getInternalSequenceLength, getLeadingGapsLength, getTrailingGapsLength, getTrailingGapsStartIndex, getUngappedLength, hashCode, indexOf, indexOf, isAllGaps, isEndGap, isGap, readObject, subSequence, toString, toXML, toXML, valueOf, withOnlyGaps, withTerminalGaps, writeObjectclone, finalize, getClass, notify, notifyAll, wait, wait, waitgetCharSequence, getSequenceAnnotations, getSequenceLength, getSequenceString, isCirculargetCreationDate, getDescription, getDisplayableFields, getFieldValue, getName, getURN, toHTMLfromXML, toXMLlengthpublic static ImmutableSequence createImmutableSequence(SequenceDocument sequence, boolean failIfContainsNonStorableData)
sequence - the sequence to create a copy offailIfContainsNonStorableData - if this is true, and the sequence to copy contains data that cannot be stored in an ImmutableSequence (for example annotations)
then this method will throw an IllegalArgumentException. If this is false and the sequence to copy contains data that cannot be stored in an ImmutableSequence then a sequence with that information missing is returnedIllegalArgumentException - if failIfContainsNonStorableData is true and the seuqnece to copy contains data that cannot be stored in an ImmutableSequence (for example annotations)createImmutableSequence(SequenceDocument)public static ImmutableSequence createImmutableSequence(SequenceDocument sequence)
sequence - the sequence to create a copy ofcreateImmutableSequence(SequenceDocument, boolean)public abstract int getLeadingTrimLength()
SequenceAnnotation.TYPE_TRIMMED).public abstract int getTrailingTrimLength()
SequenceAnnotation.TYPE_TRIMMED)public abstract int getNumberOfMappedLocations()
DocumentField.NUMBER_OF_MAPPED_LOCATIONSpublic abstract int getMappingQuality()
DocumentField.MAPPING_QUALITYpublic abstract ImmutableSequence insert(int index, CharSequence charSequence)
SequenceCharSequenceinsertions
and deletions, and its length will be longer than this sequence's by
charSequence.length().
In order to obey the contract of SequenceCharSequence that it is immutable,
the length of charSequence and the characters retured from charSequence must not change after calling this method.insert in class SequenceCharSequenceindex - The position where to insert csq. All existing characters at or to the right of this position will be moved to the right by charSequence.length().charSequence - A CharSequence to insert at the specified index. The length of charSequence and the characters retured from charSequence must not change after calling this method.public abstract ImmutableSequence delete(int deletionBegin, int deletionEnd)
SequenceCharSequenceinsertions
and deletions, and its length will be shorter than this sequence's by
deletionEnd - deletionBegin.delete in class SequenceCharSequencedeletionBegin - Deletion start index, inclusivedeletionEnd - Deletion end index, exclusivepublic abstract ImmutableSequence withTrimLengths(int leadingTrimLength, int trailingTrimLength)
leadingTrimLength - the leading trim length as defined by getLeadingTrimLength()trailingTrimLength - the trailing trim length as defined by getTrailingTrimLength()public abstract ImmutableSequence withNumberOfMappedLocations(int numberOfMappedLocations)
getNumberOfMappedLocations()numberOfMappedLocations - the new number of mapped locationsgetNumberOfMappedLocations()public abstract ImmutableSequence withMappingQuality(int mappingQuality)
getMappingQuality()mappingQuality - the new mapping quality. -1 for no quality, or between 0 and 254 inclusive for a valid mapping qualitygetMappingQuality()public abstract ImmutableSequence insertGaps(int leadingGapsLength, int trailingGapsLength, int[] internalGapPositions, int[] internalGapSizes)
leadingGapsLength - the number of additional leading gaps to add to this sequencetrailingGapsLength - the number of additional trailing gaps to add to this sequenceinternalGapPositions - the positions of internal gaps to insert into this sequence. All values must be in the range 1 through to the internal sequence length-1 inclusive and indicate that a gap should be inserted before the current character at that index. This array may be null which is equivalent to an empty array.internalGapSizes - the sizes of corresponding internal gaps to insert into this sequence. This array must be equal in length to internalGapPositions. Each size must be positive. This array may be null which is equivalent to an empty array.NucleotideSequenceDocument the returned sequence will also be a NucleotideSequenceDocument. If this sequence is an AminoAcidSequenceDocument the returned sequence will also be a AminoAcidSequenceDocumentpublic abstract ImmutableSequence removeGaps()
NucleotideSequenceDocument the returned sequence will also be a NucleotideSequenceDocument. If this sequence is an AminoAcidSequenceDocument the returned sequence will also be a AminoAcidSequenceDocumentpublic abstract ImmutableSequence createCopyWithNewName(String newName)
newName - the name of the new sequence to createNucleotideSequenceDocument the returned sequence will also be a NucleotideSequenceDocument. If this sequence is an AminoAcidSequenceDocument the returned sequence will also be a AminoAcidSequenceDocumentpublic abstract ImmutableSequence createCopyWithNameSuffix(String nameSuffix)
nameSuffix - a suffix to append to the name. If the current name ends with " (reversed)" then the suffix will be appended immediately prior to the reversed suffix.NucleotideSequenceDocument the returned sequence will also be a NucleotideSequenceDocument. If this sequence is an AminoAcidSequenceDocument the returned sequence will also be a AminoAcidSequenceDocumentpublic abstract boolean isReversed()
SequenceExtractionUtilities.REVERSED_NAME_SUFFIX)public abstract ImmutableSequence reverseComplement()
SequenceExtractionUtilities.REVERSED_NAME_SUFFIX either appended or removedNucleotideSequenceDocumentIllegalStateException - if this is not a NucleotideSequenceDocument. You should instead use reverse()reverse()public abstract ImmutableSequence reverse()
AminoAcidSequenceDocumentIllegalStateException - if this is not a AminoAcidSequenceDocument. You should instead use reverseComplement()reverseComplement()public abstract ImmutableSequence asDna()
NucleotideSequenceDocumentIllegalStateException - if this is not a NucleotideSequenceDocument.public abstract ImmutableSequence asRna()
NucleotideSequenceDocumentIllegalStateException - if this is not a NucleotideSequenceDocument.public abstract int getCharAndQualityAtIgnoringEndGaps(int characterIndex)
characterIndex - the index of the character to get, relative to the leadingGapsLength.SequenceCharSequence.charAtIgnoringEndGaps(int)+quality*256.public abstract void getData(int internalStartIndex,
int sizeOfDataToGet,
byte[] characters,
byte[] qualities,
int startingOffsetIntoDataArrays)
internalStartIndex - the index of the first character to get, relative to the leadingGapsLength. (e.g. 0 to get the first non-end-gap character)sizeOfDataToGet - the number of characters of data to get. internalStartIndex+sizeOfDataToGet must not be greater than SequenceCharSequence.getInternalSequenceLength()characters - an array to copy the sequence characters into.qualities - an optional array to copy the sequence quality into. This may be null to not retrieve quality data. If this array is not null, and this sequence has no quality, quality values of 0 will be set. If any quality values exceed 255, they will be capped at 255.startingOffsetIntoDataArrays - the index in 'characters' and 'qualities' to start copying data into.public void writeObject(DataOutput out, ProgressListener progressListener) throws IOException
SequenceCharSequenceSequenceCharSequence.readObject(java.io.DataInput)writeObject in class SequenceCharSequenceout - the DataOutput to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public void writeObject(Geneious.MajorVersion version, DataOutput out, ProgressListener progressListener) throws IOException
SequenceCharSequenceSequenceCharSequence.readObject(java.io.DataInput)writeObject in class SequenceCharSequenceversion - the version number of Geneious that must be able to deserialize this.out - the DataOutput to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public static ImmutableSequence readObject(GeneiousObjectInputStream in) throws XMLSerializationException
ImmutableSequence that
was previously written using SequenceCharSequence.writeObject(GeneiousObjectOutputStream, jebl.util.ProgressListener)in - the stream to read fromXMLSerializationException - if something goes wrongpublic static void compactNucleotideSequences(List<NucleotideSequenceDocument> sequences, ProgressListener progressListener)
sequences - the sequences which should be compacted if possible.progressListener - a progress listener for reporting progress and providing the ability to cancelpublic static void compactAminoAcidSequences(List<AminoAcidSequenceDocument> sequences, ProgressListener progressListener)
sequences - the sequences which should be compacted if possible.progressListener - a progress listener for reporting progress and providing the ability to cancelpublic Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
SequenceCharSequenceXMLSerializable.OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
but note that SequenceCharSequence is guaranteed to be able to always serialize to Geneious.MajorVersion#Version6_0getVersionSupport in interface XMLSerializable.OldVersionCompatiblegetVersionSupport in class SequenceCharSequenceversionType - specifies which version property to returnpublic org.jdom.Element toXML(boolean allowFileData)
throws XMLSerializationException
SequenceCharSequenceXMLSerializable.ROOT_ELEMENT_NAME.
Deserialization can be done via the SequenceCharSequence.fromXml(org.jdom.Element).toXML in class SequenceCharSequenceallowFileData - true to allow the sequence to potentially serialize to a file if it is large enough, using PluginDocument.FILE_DATA_ATTRIBUTE_NAME.XMLSerializationExceptionpublic org.jdom.Element toXML(Geneious.MajorVersion version, ProgressListener progressListener, boolean allowFileData) throws XMLSerializationException
SequenceCharSequenceXMLSerializable.ROOT_ELEMENT_NAME.
Deserialization can be done via the SequenceCharSequence.fromXml(org.jdom.Element).toXML in class SequenceCharSequenceversion - the version number of Geneious that must be able to deserialize thisprogressListener - for reporting progress and cancellingallowFileData - true to allow the sequence to potentially serialize to a file if it is large enough, using PluginDocument.FILE_DATA_ATTRIBUTE_NAME.XMLSerializationExceptionpublic static ImmutableSequence immutableSequenceFromXML(org.jdom.Element element) throws XMLSerializationException
toXML(boolean).
Generally this method should not be used as it is slow and memory intensive. Binary serialization
using SequenceCharSequence.writeObject(GeneiousObjectOutputStream, jebl.util.ProgressListener) and readObject(GeneiousObjectInputStream) are preferable.element - the element to deserialzide from.XMLSerializationException - if anything goes wrongpublic String subString(int startIndex, int endIndex)
startIndex - inclusive start index ( the index of the first character to get)endIndex - exclusive end index (the index after the last character to get)public abstract int getNumberOfIntegersOfStorage()