public final class SequenceListSummary extends Object implements XMLSerializable, XMLSerializable.OldVersionCompatible
SequenceListDocument.getNucleotideSequences() or SequenceListDocument.getAminoAcidSequences() may optionally implement the interface
SequenceListSummary.Provider to provide a summary of the information contained within it. DefaultAlignmentDocument.getSummary
also provides a summary if it stores its non-reference sequences on disk instead of in memory.
This class is not thread safe while being constructed, but once finishedAddingSequences(jebl.util.ProgressListener) has been called this class becomes immutable and thread safe.
Instances of this class created using SequenceListSummary(org.jdom.Element) are thread safe since they are immutable.| Modifier and Type | Class and Description |
|---|---|
static class |
SequenceListSummary.Coverage
Represents the coverage (number of sequences covering a column in an alignment)
|
static class |
SequenceListSummary.PairwiseSimilarity
Immutable value class representing the number of identical and non-identical
pairs of bases/residues in an alignment column.
|
static interface |
SequenceListSummary.Provider
An interface that lists of sequences (e.g.
|
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypeROOT_ELEMENT_NAME| Constructor and Description |
|---|
SequenceListSummary(org.jdom.Element element)
Creates a summary from a previously serialized summary
|
SequenceListSummary(List<SequenceDocument> sequences,
boolean allowGaps,
ProgressListener progressListener)
A convenience constructor which just calls
addSequence(SequenceDocument) for each sequence in the list and then calls finishedAddingSequences(jebl.util.ProgressListener) |
SequenceListSummary(SequenceDocument.Alphabet alphabet,
int numberOfSequencesIfGapsAllowed)
Constructs a new summary.
|
SequenceListSummary(SequenceDocument.Alphabet alphabet,
int numberOfSequencesIfGapsAllowed,
int circularAlignmentLength)
Constructs a new summary.
|
SequenceListSummary(SequenceDocument.Alphabet alphabet,
int numberOfSequencesIfGapsAllowed,
int circularAlignmentLength,
boolean createMultipleThreads)
Constructs a new summary.
|
SequenceListSummary(SequenceListSummary summary1,
SequenceListSummary summary2)
Constructs a new SequenceListSummary by combining 2 other summaries.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addSequence(SequenceDocument sequence)
Adds a new sequence for this summary.
|
void |
finishedAddingSequences(ProgressListener progressListener)
Indicates that
addSequence(SequenceDocument) will no longer be called, and builds and sorts the summary data. |
void |
fromXML(org.jdom.Element element)
Restore the object from the JDOM Element returned by
XMLSerializable.toXML(). |
int |
getAlignmentNumberOfColumns()
If this summary is for an alignment, returns the number of columns in the alignment
|
SequenceListSummary.PairwiseSimilarity |
getAlignmentPairwiseSimilarity(boolean freeEndGaps)
Get the pairwise similarity if this summary is for an alignment
|
Set<String> |
getAnnotationTypes()
Gets a set consisting of each annotation type that is present in at least 1 of the sequences.
|
BitSet |
getColumnsWithGapsOverPercentage(double percentage)
If this summary is for an alignment gets a BitSet indicating which columns contain over the given percentage of gaps.
|
int |
getCoverage(int residueIndex)
If this summary is for an alignment, gets the total number of sequences covering this position.
|
SequenceListSummary.Coverage |
getCoverage(int minResidueIndex,
int maxResidueIndexExclusive)
If this summary is for an alignment, gets an approximate coverage for the given range.
|
double |
getCoverageAsDouble(int residueIndex)
If this summary is for an alignment, gets the total number of sequences covering this position.
|
int |
getCoverageMaximum()
Returns the maximum coverage in this alignment.
|
double |
getCoverageMaximumAsDouble()
Returns the maximum coverage in this alignment.
|
double |
getCoverageMean()
Returns the mean coverage in this alignment.
|
double |
getCoverageStandardDeviation()
Returns the standard deviation of coverage in this alignment.
|
long |
getFrequency(char character)
Gets the number of occurrences of the given character
|
long |
getNumberOfAnnotations()
Get the total number of
SequenceAnnotations present on the sequences. |
long |
getNumberOfAnnotationsOfType(String annotationType)
Get the total number of annotations of the given type present on the sequences.
|
long |
getNumberOfCharactersExcludingGaps()
returns the total number of characters (nucleotides or residues) in all the sequences, excluding gaps
|
long |
getNumberOfCharactersIncludingInternalGaps()
returns the total number of characters (nucleotides or residues) in all the sequences, including internal gaps, but excluding end gaps.
|
long |
getNumberOfCircularSequences()
Returns the number of sequences in the list for which
SequenceDocument.isCircular() is true |
long |
getNumberOfImmutableSequenceTrimmedRegions()
Returns the number of trimmed regions in
ImmutableSequences. |
long |
getNumberOfNucleotideGraphs()
returns the number of sequences that are
NucleotideGraphs |
long |
getNumberOfReversedSequences()
Returns the number of sequences whose name ends with
SequenceExtractionUtilities.REVERSED_NAME_SUFFIX |
long |
getNumberOfSequences()
Returns the number of sequences which this summary is for
|
long |
getNumberOfSequencesWithAnnotationsOfType(String annotationType)
Get the total number of sequences that have annotations of the given type present.
|
long |
getNumberOfSequencesWithQuality()
returns the number of sequences that are
NucleotideGraphs and return true from NucleotideGraph.hasSequenceQualities() |
long |
getNumberOfTrimmedSequences()
Gets the total number of sequences that either have an annotation of type
SequenceAnnotation.TYPE_TRIMMED or have ImmutableSequence.getLeadingTrimLength() or ImmutableSequence.getTrailingTrimLength() greater than 0. |
double |
getPercentGC() |
ValueAndFrequencyDistribution |
getQualitiesExcludingGaps()
Returns the distribution of quality values (those returned from
NucleotideGraph.getSequenceQuality(int)) across all nucleotides that are non-gaps in all sequences. |
ValueAndFrequencyDistribution |
getQualitiesExcludingGapsTrimmed()
Returns the distribution of quality values (those returned from
NucleotideGraph.getSequenceQuality(int)) across all non-gap non-trimmed nucleotides in all sequences. |
int |
getReferenceSequenceBases() |
int |
getReferenceSequenceBasesCovered() |
ValueAndFrequencyDistribution |
getSequenceLengthsExcludingGaps()
Gets the distribution of ungapped sequence lengths of all sequences managed by this summary.
|
ValueAndFrequencyDistribution |
getSequenceLengthsExcludingGapsTrimmed()
Gets the distribution of ungapped sequence lengths of all sequences managed by this summary after trim annotations have been applied.
|
Geneious.MajorVersion |
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Gets either the latest version this class can serialize to via
XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener)
or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener) last changed. |
Boolean |
hasAnyReadsMappedToMultipleLocations() |
org.jdom.Element |
toXML()
Convert object to a JDOM element.
|
org.jdom.Element |
toXML(Geneious.MajorVersion majorVersion,
ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
|
public SequenceListSummary(SequenceDocument.Alphabet alphabet, int numberOfSequencesIfGapsAllowed) throws IOException
finishedAddingSequences(jebl.util.ProgressListener) has been called.alphabet - specifies whether this summary is for nucleotide or amino acid sequencesnumberOfSequencesIfGapsAllowed - if this is not negative then gaps will be allowed, and this must be the number of sequences that will be added.IOException - if we can't write data to disk.public SequenceListSummary(SequenceDocument.Alphabet alphabet, int numberOfSequencesIfGapsAllowed, int circularAlignmentLength) throws IOException
finishedAddingSequences(jebl.util.ProgressListener) has been called.alphabet - specifies whether this summary is for nucleotide or amino acid sequencesnumberOfSequencesIfGapsAllowed - if this is not negative then gaps will be allowed, and this must be the number of sequences that will be added.circularAlignmentLength - the circular length of the alignment (if gaps allowed) as defined by SequenceAlignmentDocument.getCircularLength()IOException - if we can't write data to disk.public SequenceListSummary(SequenceDocument.Alphabet alphabet, int numberOfSequencesIfGapsAllowed, int circularAlignmentLength, boolean createMultipleThreads) throws IOException
finishedAddingSequences(jebl.util.ProgressListener) has been called.alphabet - specifies whether this summary is for nucleotide or amino acid sequencesnumberOfSequencesIfGapsAllowed - if this is not negative then gaps will be allowed, and this must be the number of sequences that will be added.circularAlignmentLength - the circular length of the alignment (if gaps allowed) as defined by SequenceAlignmentDocument.getCircularLength()createMultipleThreads - true to allow creating multiple threads when building the summary to improve performanceIOException - if we can't write data to disk.public SequenceListSummary(SequenceListSummary summary1, SequenceListSummary summary2) throws IOException
summary1 - the first summary to combinesummary2 - the second summary to combineIOException - if there is a problem writing to diskIllegalArgumentException - if the summaries are different sequence types (DNA vs Protein) or if one allows gaps while the other doesn'tpublic SequenceListSummary(List<SequenceDocument> sequences, boolean allowGaps, ProgressListener progressListener) throws IOException
addSequence(SequenceDocument) for each sequence in the list and then calls finishedAddingSequences(jebl.util.ProgressListener)sequences - the sequences to create a summary ofallowGaps - true if gaps are allowed in the sequencesprogressListener - for reporting progress and cancelling.IOException - if we can't write the summary to diskpublic SequenceListSummary(org.jdom.Element element)
throws XMLSerializationException
element - an element returned from toXML()XMLSerializationException - if we can't deserialize itpublic org.jdom.Element toXML()
XMLSerializableXMLSerializable.fromXML(org.jdom.Element) can completely
restore the objects representation.
It is recommended that the returned element use XMLSerializable.ROOT_ELEMENT_NAME as its name,
in which case it must not define an attribute called "type". In this case,
fromXML, will be called with an element whose name may differ from the element
return from this function. This recommendation allows a more compact representation
of the XML can be stored.
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally.
PluginDocument implementations of this method may choose to throw an XMLSerializationException,
enclosed in a RuntimeException.toXML in interface XMLSerializablepublic Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
XMLSerializable.OldVersionCompatibleXMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener)
or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener) last changed.getVersionSupport in interface XMLSerializable.OldVersionCompatibleversionType - specifies which version property to returnpublic org.jdom.Element toXML(Geneious.MajorVersion majorVersion, ProgressListener progressListener)
XMLSerializable.OldVersionCompatibleXMLSerializable.toXML() for a more
detailed description of what it means to serialize to XML.
All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to
this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.toXML in interface XMLSerializable.OldVersionCompatiblemajorVersion - the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version
returned greater or equal to a version returned from
getVersionSupport(VersionSupportType.OldestVersionSerializableTo)
and must never be greater than the current version (Geneious.getMajorVersion())progressListener - for reporting progress and cancellingpublic void fromXML(org.jdom.Element element)
throws XMLSerializationException
XMLSerializableXMLSerializable.toXML().
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classFromXML(org.jdom.Element)
or XMLSerializer.classFromXML(org.jdom.Element, Class)
which calls this method internally.
It is optional to implement this method. Instead of implementing an empty constructor and implementing
this method properly, the implementation may instead
throw an UnsupportedOperationException and implement a constructor
that takes a single Element as a parameter.
This allows for cleaner code such as support for final fields in the XMLSerializable class.
The element parameter should not be modified since it may be reused. If you need a modified version of it,
take a copy with Element.clone().fromXML in interface XMLSerializableelement - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - if the Element can't be converted into this type of objectpublic void addSequence(SequenceDocument sequence) throws IOException
finishedAddingSequences(jebl.util.ProgressListener) must be called after all sequences have been added.sequence - the sequence to add to the summaryIOException - if we can't write the summary to diskIllegalStateException - if finishedAddingSequences(jebl.util.ProgressListener) has already been calledIllegalArgumentException - if sequence doesn't contain valid nucleotide or amino acid characters or contains gaps when not allowed (as specified by the constructor)public void finishedAddingSequences(ProgressListener progressListener) throws IOException
addSequence(SequenceDocument) will no longer be called, and builds and sorts the summary data. Once this method
has finished, this class becomes immutable and thread safe.progressListener - for reporting progress and cancellingIOException - if we can't write the summary to diskIllegalStateException - if this method is called more than oncepublic long getNumberOfSequences()
public long getNumberOfCharactersIncludingInternalGaps()
getNumberOfCharactersExcludingGaps(),
getFrequency(char)public long getNumberOfCharactersExcludingGaps()
getNumberOfCharactersIncludingInternalGaps(),
getFrequency(char)public long getNumberOfImmutableSequenceTrimmedRegions()
ImmutableSequences.
(i.e. the number of sequences that returned a non-zero value from ImmutableSequence.getLeadingTrimLength() plus the
number of sequences that returned a non-zero value from ImmutableSequence.getTrailingTrimLength())ImmutableSequences.public long getFrequency(char character)
character - the character to get the frequency of. The character is case sensitive. If this character is '-' then this counts internal gaps only - end gaps are not counted.getNumberOfCharactersExcludingGaps(),
getNumberOfCharactersIncludingInternalGaps()public double getPercentGC()
IllegalStateException - if this summary is for amino acid sequencespublic long getNumberOfSequencesWithQuality()
NucleotideGraphs and return true from NucleotideGraph.hasSequenceQualities()NucleotideGraphs and return true from NucleotideGraph.hasSequenceQualities()getNumberOfNucleotideGraphs()public long getNumberOfNucleotideGraphs()
NucleotideGraphsNucleotideGraphsgetNumberOfSequencesWithQuality()public long getNumberOfAnnotations()
SequenceAnnotations present on the sequences.SequenceAnnotations present on the sequences.getNumberOfAnnotationsOfType(String)public Set<String> getAnnotationTypes()
public long getNumberOfAnnotationsOfType(String annotationType)
getNumberOfSequencesWithAnnotationsOfType(String)annotationType - the type of annotation (e.g. SequenceAnnotation.TYPE_CDS)getNumberOfAnnotations(),
getNumberOfSequencesWithAnnotationsOfType(String)public long getNumberOfSequencesWithAnnotationsOfType(String annotationType)
getNumberOfAnnotationsOfType(String)annotationType - the type of annotation (e.g. SequenceAnnotation.TYPE_CDSgetNumberOfAnnotations(),
getNumberOfAnnotationsOfType(String)public long getNumberOfTrimmedSequences()
SequenceAnnotation.TYPE_TRIMMED or have ImmutableSequence.getLeadingTrimLength() or ImmutableSequence.getTrailingTrimLength() greater than 0.public ValueAndFrequencyDistribution getSequenceLengthsExcludingGaps()
finishedAddingSequences(jebl.util.ProgressListener) has been called.IllegalStateException - if finishedAddingSequences(jebl.util.ProgressListener) has not yet been called.getSequenceLengthsExcludingGapsTrimmed()public ValueAndFrequencyDistribution getSequenceLengthsExcludingGapsTrimmed()
getSequenceLengthsExcludingGaps().
For example if a sequence is "--GATT--ACA----" and it has a trim annotation covering the "GA" then its ungapped trimmed length is 5.
This method can not be called until finishedAddingSequences(jebl.util.ProgressListener) has been called.IllegalStateException - if finishedAddingSequences(jebl.util.ProgressListener) has not yet been called.getSequenceLengthsExcludingGaps()public ValueAndFrequencyDistribution getQualitiesExcludingGaps()
NucleotideGraph.getSequenceQuality(int)) across all nucleotides that are non-gaps in all sequences.IllegalStateException - if finishedAddingSequences(jebl.util.ProgressListener) has not yet been called.getQualitiesExcludingGapsTrimmed()public ValueAndFrequencyDistribution getQualitiesExcludingGapsTrimmed()
NucleotideGraph.getSequenceQuality(int)) across all non-gap non-trimmed nucleotides in all sequences.IllegalStateException - if finishedAddingSequences(jebl.util.ProgressListener) has not yet been called.getQualitiesExcludingGaps()public long getNumberOfCircularSequences()
SequenceDocument.isCircular() is trueSequenceDocument.isCircular() is truepublic int getCoverage(int residueIndex)
residueIndex - the 0-based index of the position to get the coverage forIllegalStateException - if this summary is not for an alignmentpublic double getCoverageAsDouble(int residueIndex)
residueIndex - the 0-based index of the position to get the coverage forIllegalStateException - if this summary is not for an alignmentpublic SequenceListSummary.Coverage getCoverage(int minResidueIndex, int maxResidueIndexExclusive)
minResidueIndex - the first 0-based index of the position to get the coverage formaxResidueIndexExclusive - the final 0-based index (exclusive) of the position to get the coverage forIllegalStateException - if this summary is not for an alignmentpublic BitSet getColumnsWithGapsOverPercentage(double percentage)
percentage - the percentageBitSet.get(int) is true for each column that contains over the given percentage of gaps, or null if this information is unavailable.IllegalStateException - if this summary is not for an alignmentpublic int getCoverageMaximum()
IllegalStateException - if this summary is not for an alignmentpublic double getCoverageMaximumAsDouble()
IllegalStateException - if this summary is not for an alignmentpublic double getCoverageMean()
IllegalStateException - if this summary is not for an alignmentpublic double getCoverageStandardDeviation()
IllegalStateException - if this summary is not for an alignmentpublic SequenceListSummary.PairwiseSimilarity getAlignmentPairwiseSimilarity(boolean freeEndGaps)
freeEndGaps - true end gaps should contribute towards the similarityIllegalStateException - if this summary is not for an alignmentpublic int getAlignmentNumberOfColumns()
IllegalStateException - if this summary is not for an alignment.public long getNumberOfReversedSequences()
SequenceExtractionUtilities.REVERSED_NAME_SUFFIXSequenceExtractionUtilities.REVERSED_NAME_SUFFIXpublic int getReferenceSequenceBases()
IllegalStateException - if this summary is not for an alignmentgetReferenceSequenceBasesCovered()public int getReferenceSequenceBasesCovered()
IllegalStateException - if this summary is not for an alignmentgetReferenceSequenceBases()public Boolean hasAnyReadsMappedToMultipleLocations()
DocumentField.NUMBER_OF_MAPPED_LOCATIONS, false if not.