public abstract class SequenceAlignmentDocument extends Object implements PluginDocument, PairedReads
isContig()) is how they are displayed to the user. At the code level
they are identical. Alignments and contigs may have a reference sequence (see getContigReferenceSequenceIndex())
Unless the alignment is editable (see isEditable()), the only methods that need to be implemented are getNumberOfSequences()
and getSequence(int).
To construct an alignment, it is recommended you use a DefaultAlignmentDocument
or to construct alignments that are too large to fit in memory, use a SequenceListOnDisk.Builder
| Modifier and Type | Class and Description |
|---|---|
static class |
SequenceAlignmentDocument.ReferencedSequence
Represents a reference to the original document that a sequence in this alignment was aligned from.
|
PluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProviderXMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypeFILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELDROOT_ELEMENT_NAME| Constructor and Description |
|---|
SequenceAlignmentDocument() |
| Modifier and Type | Method and Description |
|---|---|
void |
addSequence(SequenceDocument sequence)
Add a sequence to the end of the alignment.
|
Alignment |
asJeblAlignment(boolean silentlyStripDuplicates)
Get alignment as a Jebl alignment.
|
Alignment |
asJeblAlignmentIfMemoryAllows(boolean silentlyStripDuplicates)
This method calls #asJeblAlignment(boolean) and re-throws any OutOfMemoryError as a DocumentOperationException
|
boolean |
canAddAndRemoveSequences()
Check if this alignment supports adding and removing sequences.
|
boolean |
canSetAnnotations()
Returns true if this alignment can have its annotations on sequences (including the consensus sequence) edited alone via
setAnnotations(int, java.util.List, boolean)
and setAnnotationsOnConsensus(java.util.List)
Note that some alignment implementations may return true from isEditable() and allow updating their annotations via
updateSequence(int, CharSequence, java.util.List, NucleotideGraph, boolean) even if they return false from this method. |
boolean |
canSetAnnotationsOnConsensus() |
boolean |
canSetFieldValue(int sequenceIndex,
DocumentField field)
Returns true if this alignment supports updating field values using
setFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField, Object, boolean) |
boolean |
canSetSequenceNames()
Specifies whether this alignment supports changing the sequence names.
|
List<SequenceAnnotation> |
getAnnotationsOnConsensus()
Gets annotations that are associated with the consensus sequence.
|
int |
getCircularLength()
If this alignment is circular, returns the gapped length at which it wraps back to the start or 0 if this alignment is not circular.
|
int |
getContigReferenceSequenceIndex()
Get the index (if any) of the reference sequence in a contig.
|
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.
|
abstract int |
getNumberOfSequences()
Number of sequences in this alignment
|
static String |
getRealignedName(String name)
Given the name of an existing alignment, obtain a name that should
be used for a realignment of this alignment.
|
AnnotatedPluginDocument |
getReferencedDocument(int sequenceIndexInAlignment)
Get an original sequence document that this alignment was made from.
|
List<AnnotatedPluginDocument> |
getReferencedDocuments()
Return the results of
getReferencedDocument(int) for each sequence in the
alignment. |
SequenceAlignmentDocument.ReferencedSequence |
getReferencedSequence(int sequenceIndexInAlignment)
Get an original sequence document that this alignment was made from.
|
List<SequenceAlignmentDocument.ReferencedSequence> |
getReferencedSequences()
Return the results of
getReferencedSequence(int) for each sequence in the
alignment. |
static String |
getRefinedName(String name)
Given the name of an existing alignment, obtain a name that should
be used for a refinement of this alignment.
|
abstract SequenceDocument |
getSequence(int index)
Gets one row from the alignment as a
SequenceDocument. |
Sequence |
getSequenceAsJeblSequence(int index)
Gets a sequence as a jebl sequence
|
List<SequenceDocument> |
getSequences()
Get the alignment as a list of sequences (Convenience function).
|
List<SequenceDocument> |
getSequencesInImmutableList()
Gets an immutable list (whose elements will not change after returning from this method).
|
SequenceType |
getSequenceType()
Returns the sequence type of the first sequence in this alignment (which should be the same as all other sequences in the alignment)
|
boolean |
isContig()
Returns false by default.
|
boolean |
isEditable()
true if this alignment is editable.
|
boolean |
isFreeEndGapAlignment()
True if this alignment was built using free end gaps.
|
boolean |
isQueryCentricAlignment()
Returns true if this alignment is a query centric alignment.
|
boolean |
isReferencedDocumentReversed(int index)
Sequence direction.
|
void |
removeSequence(int index)
Removes the specified sequence from the alignment.
|
void |
reorderSequences(int[] ordering)
Adjusts the ordering of sequences in the alignment according to the ordering array.
|
void |
setAnnotations(int index,
List<SequenceAnnotation> annotations,
boolean allowModifyingReferencedDocuments)
Updates just the annotations on a sequence.
|
void |
setAnnotationsOnConsensus(List<SequenceAnnotation> annotations)
Sets the annotations on the consensus sequence that will be returned from a later call to
getAnnotationsOnConsensus(). |
void |
setFieldValue(int sequenceIndex,
DocumentField field,
Object fieldValue,
boolean allowModifyingOriginals)
Sets the value of a displayable field on one of the sequences in the alignment.
|
void |
setMates(int sequenceIndex,
int sequenceIndexOfMate,
int expectedMateDistance)
Records the 2nd sequence as being paired with the first sequence with the given distance.
|
boolean |
setReferencedDocument(int sequenceIndexInAlignment,
AnnotatedPluginDocument document)
Sets the sequence at the given sequenceIndexInAlignment in this alignment to refer to the given document as if it is the original source.
|
boolean |
setReferencedSequence(int sequenceIndexInAlignment,
SequenceAlignmentDocument.ReferencedSequence referencedSequence)
|
boolean |
setReferencedSequence(int sequenceIndexInAlignment,
SequenceAlignmentDocument.ReferencedSequence referencedSequence,
int referencedDocumentRevisionNumberSequenceWasCopiedFrom)
Sets the sequence at the given index in this alignment to refer to the given document as if it is the original source.
|
void |
setSequenceName(int index,
String newName,
boolean allowModifyingReferencedDocuments)
change the name of a sequence within the alignment.
|
String |
toHTML()
Provide a textual view of document.
|
void |
updateSequence(int index,
CharSequence sequence,
List<SequenceAnnotation> annotations,
NucleotideGraph graph,
boolean allowModifyingReferencedDocuments)
Set new residues and related data for one sequence.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitgetCreationDate, getDescription, getDisplayableFields, getFieldValue, getName, getURNfromXML, toXMLpublic abstract int getNumberOfSequences()
public abstract SequenceDocument getSequence(int index)
SequenceDocument. As this sequence
is an alignment row, it will normally contain gaps.
If implementation stores the URN of the original sequence document, see
the note in getReferencedDocument(int).index - between 0 and getNumberOfSequences()-1 inclusive.public List<SequenceDocument> getSequences()
getNumberOfSequences() and getSequence(int).getSequencesInImmutableList()public List<SequenceDocument> getSequencesInImmutableList()
ImmutableSequence.
Despite that, this method is still useful since if sequences are deleted, added or replaced in this alignment, the returned list will not change.
The default implementation of this method constructs a new list using getSequences() and returns it.ImmutableSequence.getSequences()public AnnotatedPluginDocument getReferencedDocument(int sequenceIndexInAlignment)
sequenceIndexInAlignment - the index of the sequence in the alignment to get the original document for. between 0 and getNumberOfSequences()-1 inclusive.getReferencedSequence(int)public SequenceAlignmentDocument.ReferencedSequence getReferencedSequence(int sequenceIndexInAlignment)
sequenceIndexInAlignment - the index of the sequence in the alignment to get the original document for. between 0 and getNumberOfSequences()-1 inclusive.getReferencedDocument(int).getReferencedDocument(int)public final List<AnnotatedPluginDocument> getReferencedDocuments()
getReferencedDocument(int) for each sequence in the
alignment. (Convenience function)
This list will be equal length to getNumberOfSequences() with null elements
for sequences with no referenced document. There may be a mixture of referenced and
unreferenced documents in an alignment.public final List<SequenceAlignmentDocument.ReferencedSequence> getReferencedSequences()
getReferencedSequence(int) for each sequence in the
alignment. (Convenience method)
This list will be equal length to getNumberOfSequences() with null elements
for sequences with no referenced document. There may be a mixture of referenced and
unreferenced documents in an alignment.public boolean isReferencedDocumentReversed(int index)
index - between 0 and getNumberOfSequences()-1 inclusive.getReferencedDocument(int) is not null and it is in the reverse direction of its sequence string in the alignment.public boolean isEditable()
reorderSequences(int[]), removeSequence(int) , updateSequence(int, CharSequence, java.util.List, NucleotideGraph, boolean), setReferencedDocument(int, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument) canSetAnnotations() to allow updating just the annotations via setAnnotations(int, java.util.List, boolean)public boolean canSetAnnotations()
setAnnotations(int, java.util.List, boolean)
and setAnnotationsOnConsensus(java.util.List)
Note that some alignment implementations may return true from isEditable() and allow updating their annotations via
updateSequence(int, CharSequence, java.util.List, NucleotideGraph, boolean) even if they return false from this method.setAnnotations(int, java.util.List, boolean)setAnnotations(int, java.util.List, boolean),
setAnnotationsOnConsensus(java.util.List),
canSetAnnotationsOnConsensus()public void reorderSequences(int[] ordering)
isEditable()ordering - Each integer between 0 and ordering.length - 1 inclusive should occur exactly once in this array.public void removeSequence(int index)
isEditable()index - the index of the sequence to be removed. between 0 and getNumberOfSequences() - 1public boolean canAddAndRemoveSequences()
addSequence(SequenceDocument),
removeSequence(int)public void addSequence(SequenceDocument sequence)
sequence should be the
gapped (aligned) sequence.sequence - sequence to addreorderSequences(int[]),
setReferencedDocument(int, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument)public void updateSequence(int index,
CharSequence sequence,
List<SequenceAnnotation> annotations,
NucleotideGraph graph,
boolean allowModifyingReferencedDocuments)
isEditable()
(otherwise, the method should throw UnsupportedOperationException).index - the index of the sequence to be updated. between 0 and getNumberOfSequences() - 1sequence - the new residuesannotations - a list of the annotationsgraph - Must be null if the original sequence at the specified index is not a NucleotideGraphSequenceDocument.
Otherwise (i.e. if the sequence was a NucleotideGraphSequenceDocument), specifies the new
graph to use for that sequence.allowModifyingReferencedDocuments - if the change being made to the sequence would affect the unaligned version of it
(for example, the sequence residues are changing rather than just the gaps)
and the alignment stores a reference an editable original SequenceDocument
(which can be determined by using getReferencedDocument(int)) then if this parameter is true
the original referenced sequence document will be modified.
If this parameter is not true and the change would have otherwise modified the original SequenceDocument,
then any reference to the original document will be discarded
and a copy of the original sequence stored internally within the alignment instead.UnsupportedOperationException - if isEditable() is false.public void setAnnotations(int index,
List<SequenceAnnotation> annotations,
boolean allowModifyingReferencedDocuments)
canSetAnnotations() returns true
This is used for updating non-track annotations only. Track annotations are handled via a different API. To update or add tracks check if
a sequence in the alignment implements SequenceTrack.Manager.Providerindex - the 0-based index of the sequence to set annotations on, or -1 to set annotations on the consensus sequence.annotations - the new annotations for this sequence, which will replace any existing annotations.allowModifyingReferencedDocuments - if this is true the original referenced sequence document will be modified to use these annotations
If this parameter is not true and then any reference to the original document will be discarded
and a copy of the original sequence stored internally within the alignment instead.public boolean setReferencedDocument(int sequenceIndexInAlignment,
AnnotatedPluginDocument document)
sequenceIndexInAlignment ,
with gap residues removed.
This method may be used when the user chooses to extract a sequence from an alignment, so the alignment
should now be updated to reference the extracted sequence.
Any alignment implementations may choose to not implement this method, in which case of the default implementation is used which always returns false.sequenceIndexInAlignment - the sequenceIndexInAlignment of the sequence referred to. between 0 and getNumberOfSequences() - 1document - the document to referencegetReferencedDocument(int) to check if it really worked.public boolean setReferencedSequence(int sequenceIndexInAlignment,
SequenceAlignmentDocument.ReferencedSequence referencedSequence,
int referencedDocumentRevisionNumberSequenceWasCopiedFrom)
sequenceIndexInAlignment ,
with gap residues removed.
This method may be used when the user chooses to extract a sequence from an alignment, so the alignment
should now be updated to reference the extracted sequence.
Any alignment implementations may choose to not implement this method, in which case of the default implementation is used which always returns false.sequenceIndexInAlignment - the sequenceIndexInAlignment of the sequence referred to. between 0 and getNumberOfSequences() - 1referencedSequence - the document to referencereferencedDocumentRevisionNumberSequenceWasCopiedFrom - normally an alignment document stores the most recent revision number it updated its local cache of the sequence from. In order to improve performance, if it is known what revision number (see AnnotatedPluginDocument.getRevisionNumber() the current alignment sequence was created from then it can be supplied here. Use -1 if unsure.public boolean setReferencedSequence(int sequenceIndexInAlignment,
SequenceAlignmentDocument.ReferencedSequence referencedSequence)
sequenceIndexInAlignment - the sequenceIndexInAlignment of the sequence referred to. between 0 and getNumberOfSequences() - 1referencedSequence - the document to referencepublic final Alignment asJeblAlignmentIfMemoryAllows(boolean silentlyStripDuplicates) throws DocumentOperationException
silentlyStripDuplicates - Unlike Geneious alignments, Jebl alignments cannot contain sequences
with the same names. If this parameter is true, duplicate sequences will be absent from the returned alignment.
if this parameter is false, sequences will be given unique names by appending "1", "2", etc .DocumentOperationException - if there is not enough memory to create the Jebl alignmentasJeblAlignment(boolean)public Alignment asJeblAlignment(boolean silentlyStripDuplicates)
silentlyStripDuplicates - Unlike Geneious alignments, Jebl alignments cannot contain sequences
with the same names. If this parameter is true, duplicate sequences will be absent from the returned alignment.
if this parameter is false, sequences will be given unique names by appending "1", "2", etc .
This function is implemented for all alignments. Sub-classes need not implement it, but may wish to
if they internally store their alignment in jebl format already.public Sequence getSequenceAsJeblSequence(int index)
index - the index of the sequence to get. between 0 and getNumberOfSequences() - 1RuntimeException - wrapping a DocumentOperationException if the referenced sequence of the alignment cannot be loaded.
This function is implemented for all alignments by converting the result of getSequence(int).
Sub-classes need not implement it, but may wish to
if they internally store their sequences in jebl format already.public String toHTML()
PluginDocument<html>toHTML in interface PluginDocumentpublic boolean isContig()
DefaultAlignmentDocument
then the document will not be given the contig icon (to set non default icons for
a document see DocumentType.OVERRIDE_DOCUMENT_TYPE_KEY.
Use DefaultAlignmentDocument.setContig(boolean)
to create a contig.DefaultAlignmentDocument.setContig(boolean)public boolean canSetSequenceNames()
setSequenceName(int, String, boolean)public void setSequenceName(int index,
String newName,
boolean allowModifyingReferencedDocuments)
canSetSequenceNames() returns true.index - index of the sequence name to changenewName - the new name for the sequence.allowModifyingReferencedDocuments - if the alignment stores a reference to an editable original SequenceDocument
(which can be determined by using getReferencedDocument(int)) then if this parameter is true
the original referenced sequence document will be renamed too.
Otherwise, any existing reference to the original SequenceDocument will be discarded
and a copy of the original sequence stored internally within the alignment instead.public boolean isFreeEndGapAlignment()
public static String getRefinedName(String name)
name - the name of the original alignmentgetRealignedName(String)public static String getRealignedName(String name)
name - the name of the original alignmentgetRefinedName(String)public int getContigReferenceSequenceIndex()
getNumberOfSequences()-1]) or -1 to if this contig has no reference sequence.public boolean isQueryCentricAlignment()
getContigReferenceSequenceIndex().public 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 PairedReadManager getImmutablePairedReadManager()
PairedReadsgetImmutablePairedReadManager in interface PairedReadspublic void setMates(int sequenceIndex,
int sequenceIndexOfMate,
int expectedMateDistance)
getMateExpectedDistance(int))sequenceIndex - the sequence to set the mate for.sequenceIndexOfMate - the index of its mate, or -1 if its mate is not in this contig.expectedMateDistance - the expected mate distance. See getMateExpectedDistance(int)IllegalArgumentException - if this sequence already has a different mate or if its mate is paired to a different sequence.UnsupportedOperationException - if this alignment does not support setting mates. All editable alignment implementations (see isEditable() for which getImmutablePairedReadManager().hasAnyPairedReads() returns true must not throw a UnsupportedOperationException.public boolean canSetAnnotationsOnConsensus()
setAnnotationsOnConsensus(java.util.List).setAnnotationsOnConsensus(java.util.List)public List<SequenceAnnotation> getAnnotationsOnConsensus()
public void setAnnotationsOnConsensus(List<SequenceAnnotation> annotations)
getAnnotationsOnConsensus().
It is only legal to call this method if canSetAnnotationsOnConsensus() returns true.annotations - the annotations to store on the consensus. Must not be null. This replaces any existing annotations on the consensus.getAnnotationsOnConsensus(),
canSetAnnotationsOnConsensus()public SequenceType getSequenceType()
public int getCircularLength()
RefSeq: -GATTACA----
Read 1: ----TACAAGA-
Read 2: -----ACA-GAT
public boolean canSetFieldValue(int sequenceIndex,
DocumentField field)
setFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField, Object, boolean)sequenceIndex - the index of a sequence in the alignmentfield - the field to updatesetFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField, Object, boolean)setFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField, Object, boolean)public void setFieldValue(int sequenceIndex,
DocumentField field,
Object fieldValue,
boolean allowModifyingOriginals)
canSetFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField) returns true.sequenceIndex - the index of a sequence in the alignment to update the field value onfield - the field to updatefieldValue - the new value for the field.allowModifyingOriginals - true if this field change may be propagated to a referenced sequence (if any). If this is false the sequence will be disconnected from its referenced document.canSetFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField)