public class DefaultSequenceListDocument extends AbstractPluginDocument implements SequenceListDocument, PairedReads, XMLSerializableWithProgress, ExtendedEditableSequenceListDocument, Renamable, PluginDocument.SizeRequiredToLoadIntoMemoryProvider, XMLSerializable.OldVersionCompatible
SequenceListDocument.
The constructors provided for this class allow for the quick creation of DefaultSequenceListDocuments that fit entirely into memory. For constructing larger
SequenceListDocuments, see SequenceListOnDisk.BuilderXMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypePluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProviderROOT_ELEMENT_NAMEFILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELD| Constructor and Description |
|---|
DefaultSequenceListDocument()
XML deserialization constructor.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addAminoAcidSequence(AminoAcidSequenceDocument sequence)
Adds the given amino acid sequence to the end of the list of amino acid sequences in this document
Note that using this method will require loading the entire sequence list into memory, which
might not be possible on large sequence lists.
|
void |
addAminoAcidSequence(AnnotatedPluginDocument document)
Adds an amino acid sequence to this list that is wrapped inside an
AnnotatedPluginDocument. |
void |
addNucleotideSequence(AnnotatedPluginDocument document)
Adds a nucleotide sequence to this list that is wrapped inside an
AnnotatedPluginDocument. |
void |
addNucleotideSequence(NucleotideSequenceDocument sequence)
Adds the given nucleotide sequence to the end of the list of nucleotide sequences in this document
Note that using this method will require loading the entire sequence list into memory, which
might not be possible on large sequence lists.
|
DefaultSequenceListDocument |
createNewDocumentByTransformingSequences(SequenceDocument.Alphabet alphabet,
SequenceDocument.Transformer transformer,
ProgressListener progressListener)
|
DefaultSequenceListDocument |
createNewDocumentByTransformingSequences(SequenceDocument.Alphabet alphabet,
SequenceDocument.Transformer transformer,
ProgressListener progressListener,
boolean allowMultipleThreads)
Creates a new DefaultSequenceListDocument (whose sequences will be a
SequenceListOnDisk) by applying a transformation to each of the sequences in this list. |
static DefaultSequenceListDocument |
forAminoAcidSequences(List<AminoAcidSequenceDocument> aminoAcidSequences)
Construct a new DefaultSequenceListDocument.
|
static DefaultSequenceListDocument |
forBothSequenceTypes(List<? extends SequenceDocument> sequences,
ProgressListener progressListener)
Construct a new DefaultSequenceListDocument.
|
static DefaultSequenceListDocument |
forBothSequenceTypes(List<NucleotideSequenceDocument> nucleotideSequences,
List<AminoAcidSequenceDocument> aminoAcidSequences)
Construct a new DefaultSequenceListDocument.
|
static DefaultSequenceListDocument |
forBothSequenceTypes(List<NucleotideSequenceDocument> nucleotideSequences,
List<AminoAcidSequenceDocument> aminoAcidSequences,
ProgressListener progressListener)
Construct a new DefaultSequenceListDocument.
|
static DefaultSequenceListDocument |
forNucleotideSequences(List<NucleotideSequenceDocument> nucleotideSequences)
Construct a new DefaultSequenceListDocument.
|
void |
fromXML(org.jdom.Element root)
Restore the object from the JDOM Element returned by
XMLSerializable.toXML(). |
void |
fromXML(org.jdom.Element root,
ProgressListener progressListener)
Deserializes this document from XML
|
List<AminoAcidSequenceDocument> |
getAminoAcidSequences()
Gets the amino acid sequences in this document.
|
List<AnnotatedPluginDocument> |
getAnnotatedPluginDocumentsForAminoAcidSequences()
When a SequneceList is created for some existing sequences wrapped in
AnnotatedPluginDocument,
then the original AnnotatedPluginDocuments are stored in the sequence list. |
List<AnnotatedPluginDocument> |
getAnnotatedPluginDocumentsForNucleotideSequences()
When a SequneceList is created for some existing sequences wrapped in
AnnotatedPluginDocument,
then the original AnnotatedPluginDocuments are stored in the sequence list. |
String |
getDescription()
A human readable single line of text describing this document,
to appear in the description field in the document table.
|
PairedReadManager |
getImmutablePairedReadManager()
An immutable view of the paired reads managed by this list or alignment.
|
int |
getMateExpectedDistance(int sequenceIndex)
Gets the expected mate distance (also known as predicted median insert size) of this nucleotide sequence from its mate.
|
int |
getMateIndex(int sequenceIndex)
Gets the index of the mate (if any) of the nucleotide sequence at this index.
|
String |
getName()
A short name (preferably one or two words) for the document.
|
List<NucleotideSequenceDocument> |
getNucleotideSequences()
Gets the nucleotide sequences in this document.
|
int |
getOrderingRevisionNumber()
Return a revision number that is incremented each time sequences are reordered or removed from this sequence list.
|
long |
getSizeRequiredToLoadIntoMemory()
Return an estimate of the number of bytes required to load this document into memory.
|
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. |
void |
incrementOrderingRevisionNumber()
Increments the value returned from
getOrderingRevisionNumber() to indicate that alignments that reference sequences by index in this list should discard their reference. |
void |
removeAminoAcidSequence(int index)
Removes the amino acid sequence at the given index from this sequence list and shifts any subsequent sequences to the left (subtracts one from their indices).
|
void |
removeNucleotideSequence(int index)
Removes the nucleotide sequence at the given index from this sequence list and shifts any subsequent sequences to the left (subtracts one from their indices).
|
void |
reorderAminoAcidSequences(int[] ordering)
Adjusts the ordering of sequences in this list according to the ordering array.
|
void |
reorderNucleotideSequences(int[] ordering)
Adjusts the ordering of sequences in this list according to the ordering array.
|
void |
replaceAminoAcidSequence(int index,
AminoAcidSequenceDocument newSequence)
Replaces the amino acid sequence at this index with a new sequence.
|
void |
replaceContents(DefaultSequenceListDocument sequenceListToCopyContentsFrom)
Copies all the sequence data from another DefaultSequenceListDocument into this document.
|
void |
replaceNucleotideSequence(int index,
NucleotideSequenceDocument newSequence)
Replaces the nucleotide sequence at this index with a new sequence.
|
void |
setMates(int sequenceIndex,
int mateIndex,
int expectedMateDistance)
Sets 2 sequences as mates with the given expected mate distance.
|
void |
setName(String name)
Sets the name of this document.
|
void |
setPairedReadsManager(PairedReadManager pairedReadsManager)
Sets a paired read manager to correspond with the nucleotide sequences for this document.
|
String |
toHTML()
Provide a textual view of document.
|
org.jdom.Element |
toXML()
Convert object to a JDOM element.
|
org.jdom.Element |
toXML(Geneious.MajorVersion version,
ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
|
org.jdom.Element |
toXML(ProgressListener progressListener)
Convert object to a JDOM element.
|
addDisplayableField, addReferencedDocumentUrn, clearReferencedDocumentUrns, createFromBaseElement, getBaseElement, getBaseElementString, getCreationDate, getDisplayableFields, getFieldValue, getFieldValueCodes, getReferencedDocumentUrns, getURN, hasProperties, setBaseElement, setCreated, setFieldValue, setFieldValue, setFieldValues, setURNpublic DefaultSequenceListDocument()
forAminoAcidSequences(java.util.List) or forNucleotideSequences(java.util.List) or forBothSequenceTypes(java.util.List, java.util.List).public static DefaultSequenceListDocument forBothSequenceTypes(List<NucleotideSequenceDocument> nucleotideSequences, List<AminoAcidSequenceDocument> aminoAcidSequences)
SequenceListOnDisk.BuildernucleotideSequences - the nucleotide sequences that the created document will contain. This list may be empty but must not be null.aminoAcidSequences - the amino acid sequences that the created document will contain. This list may be empty but must not be null.public static DefaultSequenceListDocument forBothSequenceTypes(List<NucleotideSequenceDocument> nucleotideSequences, List<AminoAcidSequenceDocument> aminoAcidSequences, ProgressListener progressListener)
SequenceListOnDisk.BuildernucleotideSequences - the nucleotide sequences that the created document will contain. This list may be empty but must not be null.aminoAcidSequences - the amino acid sequences that the created document will contain. This list may be empty but must not be null.progressListener - for reporting progress and cancelling.public static DefaultSequenceListDocument forBothSequenceTypes(List<? extends SequenceDocument> sequences, ProgressListener progressListener)
SequenceListOnDisk.Buildersequences - all sequences, can be a mixture of nucleotide sequences and amino acid sequences.
This method will automatically put them in the right list.progressListener - for reporting progress and cancelling.public static DefaultSequenceListDocument forNucleotideSequences(List<NucleotideSequenceDocument> nucleotideSequences)
SequenceListOnDisk.BuildernucleotideSequences - the nucleotide sequences that the created document will contain. This list may be empty but must not be null.public static DefaultSequenceListDocument forAminoAcidSequences(List<AminoAcidSequenceDocument> aminoAcidSequences)
SequenceListOnDisk.BuilderaminoAcidSequences - the amino acid sequences that the created document will contain. This list may be empty but must not be null.public String getName()
PluginDocumentAnnotatedPluginDocument then this method
will be overridden and delegate back to AnnotatedPluginDocument.getName(). One way to look at it is
that when you call PluginDocument.getName() you will get the current name of the document. If you are implementing PluginDocument.getName() then you are
returning the default name for the document.getName in interface PluginDocumentpublic void setName(String name)
public String getDescription()
PluginDocumentgetDescription in interface PluginDocumentpublic String toHTML()
PluginDocument<html>toHTML in interface PluginDocumentpublic List<NucleotideSequenceDocument> getNucleotideSequences()
SequenceListDocumentEditableSequenceDocuments.
To add/delete/reorder sequences use EditableSequenceListDocument.
To modify individual sequences in the list, use ExtendedEditableSequenceListDocument.replaceNucleotideSequence(int, NucleotideSequenceDocument)
Note that using the editing methods will require loading the entire sequence list into memory, which
might not be possible on large sequence lists. See DefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.getNucleotideSequences in interface SequenceListDocumentpublic List<AminoAcidSequenceDocument> getAminoAcidSequences()
SequenceListDocumentEditableSequenceDocuments.
To add/delete/reorder sequences use EditableSequenceListDocument.
To modify individual sequences in the list, use ExtendedEditableSequenceListDocument.replaceAminoAcidSequence(int, AminoAcidSequenceDocument)getAminoAcidSequences in interface SequenceListDocumentpublic List<AnnotatedPluginDocument> getAnnotatedPluginDocumentsForNucleotideSequences()
AnnotatedPluginDocument,
then the original AnnotatedPluginDocuments are stored in the sequence list.getNucleotideSequences() but some or all entries in the list may be null) or potentially a null list if none of the nucleotide sequences have associated AnnotatedPluginDocuments.public List<AnnotatedPluginDocument> getAnnotatedPluginDocumentsForAminoAcidSequences()
AnnotatedPluginDocument,
then the original AnnotatedPluginDocuments are stored in the sequence list.getAminoAcidSequences() ()} but some or all entries in the list may be null) or potentially null if none of the amino acid sequences have associated AnnotatedPluginDocuments.public 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 XMLSerializabletoXML in class AbstractPluginDocumentpublic org.jdom.Element toXML(ProgressListener progressListener)
XMLSerializableWithProgressXMLSerializable.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 XMLSerializableWithProgressprogressListener - for reporting progress of the serialization. The implementation may return null if the progress listener requests that it cancel.public 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.OldVersionCompatiblegetVersionSupport in class AbstractPluginDocumentversionType - specifies which version property to returnpublic org.jdom.Element toXML(Geneious.MajorVersion version, 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.OldVersionCompatibletoXML in class AbstractPluginDocumentversion - 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 root)
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 XMLSerializablefromXML in class AbstractPluginDocumentroot - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - if the Element can't be converted into this type of objectpublic void fromXML(org.jdom.Element root,
ProgressListener progressListener)
throws XMLSerializationException
root - the element returned from a previous call to toXML()progressListener - for reporting progress and cancellingXMLSerializationException - if it cannot be deserialized.public void incrementOrderingRevisionNumber()
getOrderingRevisionNumber() to indicate that alignments that reference sequences by index in this list should discard their reference.getOrderingRevisionNumber()public void reorderNucleotideSequences(int[] ordering)
EditableSequenceListDocumentSequenceAlignmentDocument.reorderSequences(int[])
Note that using this method will require loading the entire sequence list into memory, which
might not be possible on large sequence lists. See DefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.reorderNucleotideSequences in interface EditableSequenceListDocumentordering - Each integer between 0 and ordering.length - 1 inclusive should occur exactly once in this array.EditableSequenceListDocument.reorderAminoAcidSequences(int[]),
SequenceAlignmentDocument.reorderSequences(int[])public void reorderAminoAcidSequences(int[] ordering)
EditableSequenceListDocumentDefaultAlignmentDocument.reorderSequences(int[])
Note that using this method will require loading the entire sequence list into memory, which
might not be possible on large sequence lists. See DefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.reorderAminoAcidSequences in interface EditableSequenceListDocumentordering - Each integer between 0 and ordering.length - 1 inclusive should occur exactly once in this array.EditableSequenceListDocument.reorderNucleotideSequences(int[]),
SequenceAlignmentDocument.reorderSequences(int[])public void removeNucleotideSequence(int index)
EditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.removeNucleotideSequence in interface EditableSequenceListDocumentindex - the index of the nucleotide sequence to remove.public void removeAminoAcidSequence(int index)
EditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.removeAminoAcidSequence in interface EditableSequenceListDocumentindex - the index of the amino acid sequence to remove.public void replaceNucleotideSequence(int index,
NucleotideSequenceDocument newSequence)
ExtendedEditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.replaceNucleotideSequence in interface ExtendedEditableSequenceListDocumentindex - the 0-based index of the sequence to replacenewSequence - the new sequence to replace it withpublic void replaceAminoAcidSequence(int index,
AminoAcidSequenceDocument newSequence)
ExtendedEditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.replaceAminoAcidSequence in interface ExtendedEditableSequenceListDocumentindex - the 0-based index of the sequence to replacenewSequence - the new sequence to replace it withpublic void addNucleotideSequence(AnnotatedPluginDocument document) throws DocumentOperationException
AnnotatedPluginDocument.document - the document containing the sequence.DocumentOperationException - if the sequence inside the document cannot be loadedIllegalArgumentException - of the PluginDocument inside document is not a nucleotide sequence.public void addNucleotideSequence(NucleotideSequenceDocument sequence)
EditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.addNucleotideSequence in interface EditableSequenceListDocumentsequence - the nucleotide sequence to addpublic void addAminoAcidSequence(AnnotatedPluginDocument document) throws DocumentOperationException
AnnotatedPluginDocument.document - the document containing the sequence.DocumentOperationException - if the sequence inside the document cannot be loadedIllegalArgumentException - of the PluginDocument inside document is not an amino acid sequence.public void addAminoAcidSequence(AminoAcidSequenceDocument sequence)
EditableSequenceListDocumentDefaultSequenceListDocument.replaceContents for a discussion on efficiently
handling editing large sequence lists.addAminoAcidSequence in interface EditableSequenceListDocumentsequence - the amino acid sequence to addpublic int getMateExpectedDistance(int sequenceIndex)
PairedReadsgetMateExpectedDistance in interface PairedReadssequenceIndex - the index of the nucleotide sequence for which to get the mate index of.PairedReads.getMateIndex(int) will be -1.PairedReads.getMateIndex(int)public int getMateIndex(int sequenceIndex)
PairedReadsgetMateIndex in interface PairedReadssequenceIndex - the index of the nucleotide sequence to get the mate index ofPairedReads.getMateExpectedDistance(int)public void setMates(int sequenceIndex,
int mateIndex,
int expectedMateDistance)
getMateExpectedDistance(int) for what the expected distance means.
If all mates are set interlaced (i.e 0 is paired with 1, 2 is paired with 3 etc) then
the implementation is more memory efficient.sequenceIndex - the sequence for which to set the mate distance for.mateIndex - the index of the mate of sequenceIndex. May be -1 to unpair this sequence from its mateexpectedMateDistance - the expected distance to its matePairedReads.getMateIndex(int),
PairedReads.getMateExpectedDistance(int)public void setPairedReadsManager(PairedReadManager pairedReadsManager)
pairedReadsManager - the new paired read manager, or null if the nucleotide sequences are not paired.public PairedReadManager getImmutablePairedReadManager()
PairedReadsgetImmutablePairedReadManager in interface PairedReadspublic DefaultSequenceListDocument createNewDocumentByTransformingSequences(SequenceDocument.Alphabet alphabet, SequenceDocument.Transformer transformer, ProgressListener progressListener) throws DocumentOperationException
createNewDocumentByTransformingSequences(alphabet, transformer, progressListener, true).DocumentOperationExceptionpublic DefaultSequenceListDocument createNewDocumentByTransformingSequences(SequenceDocument.Alphabet alphabet, SequenceDocument.Transformer transformer, ProgressListener progressListener, boolean allowMultipleThreads) throws DocumentOperationException
SequenceListOnDisk) by applying a transformation to each of the sequences in this list.
This method is useful in conjunction with replaceContents(DefaultSequenceListDocument).alphabet - specifies whether to transform the nucleotide or amino acid sequences in this document. If alphabet is null, both types of sequences will be transformed.transformer - the transformerprogressListener - for reporting progress and cancellingallowMultipleThreads - true if the transformer can be invoked from multiple threads simultaneously to improve performance. In this case, the transformer must be prepared to accept the sequences to be transformed in any order.DocumentOperationException - if the transformation cannot be completed for any reasonreplaceContents(DefaultSequenceListDocument)public void replaceContents(DefaultSequenceListDocument sequenceListToCopyContentsFrom)
getNucleotideSequences() and getAminoAcidSequences() remain valid
until this document is saved. This method is useful in conjunction with createNewDocumentByTransformingSequences(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument.Alphabet, com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument.Transformer, jebl.util.ProgressListener).
Sequence lists can contain a lot of sequences (e.g. over 100 million sequences). In these situations, the lists returned from SequenceListDocument.getNucleotideSequences()
or SequenceListDocument.getAminoAcidSequences() may be a SequenceListOnDisk. SequenceListOnDisks are immutable, so calling methods such as
addNucleotideSequence(NucleotideSequenceDocument), removeNucleotideSequence(int), replaceNucleotideSequence(int, NucleotideSequenceDocument)
on the SequenceListDocument that contains the SequenceListOnDisk will not
be efficient and may require loading the entire list into memory, which may not be possible. Instead it is best to either create a new SequenceListDocument (using SequenceListOnDisk.Builder),
and/or replace the contents of a SequenceListDocument in a single step using DefaultSequenceListDocument.replaceContents.sequenceListToCopyContentsFrom - the sequence list to copy data fromcreateNewDocumentByTransformingSequences(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument.Alphabet, com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument.Transformer, jebl.util.ProgressListener)public long getSizeRequiredToLoadIntoMemory()
PluginDocument.SizeRequiredToLoadIntoMemoryProviderAnnotatedPluginDocument.getSize().
Geneious caches the value returned from this method when the document is wrapped in an AnnotatedPluginDocument or when it is saved.getSizeRequiredToLoadIntoMemory in interface PluginDocument.SizeRequiredToLoadIntoMemoryProviderpublic int getOrderingRevisionNumber()
EditableSequenceListDocumentgetOrderingRevisionNumber in interface EditableSequenceListDocumentDocumentField.SEQUENCE_LIST_ORDERING_REVISION_NUMBER