Package com.biomatters.geneious.publicapi.implementations

Class DefaultPhylogenyDocument

java.lang.Object

com.biomatters.geneious.publicapi.documents.sequence.SequenceAlignmentDocument

com.biomatters.geneious.publicapi.implementations.DefaultAlignmentDocument

com.biomatters.geneious.publicapi.documents.types.PhylogenyDocument

com.biomatters.geneious.publicapi.implementations.DefaultPhylogenyDocument

All Implemented Interfaces:

ExportableDocument, PluginDocument, PluginDocument.SizeRequiredToLoadIntoMemoryProvider, Renamable, PairedReads, SequenceListSummary.Provider, EditableSameTaxaTreesDocument, SameTaxaTreesDocument, TreeDocument, XMLSerializable, XMLSerializable.OldVersionCompatible, XMLSerializableWithProgress, SequenceTrack.Manager.Provider

public class DefaultPhylogenyDocument
extends PhylogenyDocument
implements ExportableDocument, EditableSameTaxaTreesDocument, XMLSerializable.OldVersionCompatible

An implementation of a Phylogeny document.

Nested Class Summary

Nested classes/interfaces inherited from class com.biomatters.geneious.publicapi.documents.sequence.SequenceAlignmentDocument

SequenceAlignmentDocument.ReferencedSequence

Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.ExportableDocument

ExportableDocument.Format

Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument

PluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProvider

Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable

XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType

Field Summary

Fields

Modifier and Type	Field	Description
static final String	KEY_DOCUMENT_SIZE
static final String	KEY_NEXUS_TREE_DISTANCE_MATRIX
static final String	KEY_SEQUENCE_RESIDUES

Fields inherited from class com.biomatters.geneious.publicapi.implementations.DefaultAlignmentDocument

KEY_ALIGNMENT_OPTIONS, KEY_ALIGNMENT_SCORE, KEY_MATCH_REGIONS

Fields inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument

FILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELD

Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable

ROOT_ELEMENT_NAME

Constructor Summary

Constructors

Constructor	Description
DefaultPhylogenyDocument()	XML deserialization constructor.
DefaultPhylogenyDocument(List<? extends Tree> trees, List<Sequence> inAlignedSequences, String name, String summary, AnnotatedPluginDocument alignmentDocument, boolean standardTranslation)
DefaultPhylogenyDocument(List<? extends Tree> trees, List<Sequence> inAlignedSequences, String name, String summary, AnnotatedPluginDocument alignmentDocument, boolean standardTranslation, boolean allTreesWritable)
DefaultPhylogenyDocument(org.jdom.Element element)	XML deserialization constructor.
DefaultPhylogenyDocument(org.jdom.Element element, ProgressListener progressListener)	Construct a new DefaultPhylogenyDocument from XML.

Method Summary

Modifier and Type	Method	Description
void	addSequence(SequenceDocument sequence)	Add a sequence to the end of the alignment.
boolean	areAllTreesWritable()	True if the tree viewer should allow the user to modify all trees in this document (if false, only the first tree will be writable)
boolean	canAddAndRemoveSequences()	Check if this alignment supports adding and removing sequences.
boolean	canExport(ExportableDocument.Format format)	Check if a format is supported by document.
boolean	export(ExportableDocument.Format format, OutputStream to)	Export a document.
void	fromXML(org.jdom.Element doc)	Restore the object from the JDOM Element returned by XMLSerializable.toXML().
void	fromXML(org.jdom.Element doc, ProgressListener progressListener)	Deserializes this document with progress.
String	getDescription()	A human readable single line of text describing this document, to appear in the description field in the document table.
List<? extends Tree>	getTrees()	Get tree set.
Geneious.MajorVersion	getVersionSupport(XMLSerializable.VersionSupportType versionType)	Gets either the latest version this class can serialize to via XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) last changed.
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	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	setNexusSource(String fileText, int nexusBlockNumber)	Set source of document in nexus format.
void	setSequenceName(int index, String newName, boolean allowModifyingOriginals)	change the name of a sequence within the alignment.
void	setTrees(List<? extends Tree> newTrees)	Set some trees.
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.
void	updateSequence(int index, CharSequence sequence, List<SequenceAnnotation> annotations, NucleotideGraph graph, boolean allowModifyingOriginals)	Set new residues and related data for one sequence.

Methods inherited from class com.biomatters.geneious.publicapi.implementations.DefaultAlignmentDocument

addContigReferenceSequence, addUrnVisibleByDefaultTrack, calculateScore, canSetAnnotations, canSetAnnotationsOnConsensus, canSetFieldValue, canSetSequenceNames, fromJeblAlignment, getAlignmentDataForSequencesNotInMemory, getAnnotationsOnConsensus, getCircularLength, getContigReferenceSequenceIndex, getCreationDate, getDescription, getDisplayableFields, getFieldValue, getImmutablePairedReadManager, getMateExpectedDistance, getMateIndex, getName, getNumberOfSequences, getReferencedDocument, getReferencedSequence, getScore, getSequence, getSequences, getSequencesInImmutableList, getSequenceType, getSizeRequiredToLoadIntoMemory, getSummary, getTrackManager, getURN, getUrnsForVisibleByDefaultTracks, isContig, isEditable, isFreeEndGapAlignment, isQueryCentricAlignment, isReferencedDocumentReversed, setAlignmentDataForSequencesNotInMemory, setAlignmentOptions, setAnnotations, setAnnotationsOnConsensus, setCircularLength, setContig, setContigReferenceSequenceIndex, setCreationDate, setFreeEndGapAlignment, setMatchRegions, setMates, setName, setNumberOfDifferentMappedReads, setQueryCentricAlignment, setReferencedDocument, setReferencedSequence, setReferencedSequenceListDocument, setScore, toXML, updateSequence

Methods inherited from class com.biomatters.geneious.publicapi.documents.sequence.SequenceAlignmentDocument

asJeblAlignment, asJeblAlignmentIfMemoryAllows, getRealignedName, getReferencedDocuments, getReferencedSequences, getRefinedName, getSequenceAsJeblSequence, setReferencedSequence

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument

getCreationDate, getDisplayableFields, getFieldValue, getName, getURN

Field Details

KEY_NEXUS_TREE_DISTANCE_MATRIX

public static final String KEY_NEXUS_TREE_DISTANCE_MATRIX

See Also:

• Constant Field Values

KEY_DOCUMENT_SIZE

public static final String KEY_DOCUMENT_SIZE

See Also:

• Constant Field Values

KEY_SEQUENCE_RESIDUES

public static final String KEY_SEQUENCE_RESIDUES

See Also:

• Constant Field Values

Constructor Details

DefaultPhylogenyDocument

public DefaultPhylogenyDocument()

XML deserialization constructor. See XMLSerializable

DefaultPhylogenyDocument

public DefaultPhylogenyDocument(org.jdom.Element element,
 ProgressListener progressListener)
                         throws XMLSerializationException

Construct a new DefaultPhylogenyDocument from XML. This constructor can be cancelled through the use of the progress listener. Cancellation is currently only supported by Nexus document types.

Parameters:

element - A serialized form of a DefaultPhylogenyDocument

progressListener - A progress listener

Throws:

XMLSerializationException - If the progress listener is cancelled during instantiation.

Since:

API 4.202600 (Geneious 2026.0.0)

DefaultPhylogenyDocument

public DefaultPhylogenyDocument(org.jdom.Element element)
                         throws XMLSerializationException

XML deserialization constructor. See XMLSerializable

Parameters:

element - the previously serialized element returned from toXML().

Throws:

XMLSerializationException - if deserialization fails

DefaultPhylogenyDocument

public DefaultPhylogenyDocument(List<? extends Tree> trees,
 List<Sequence> inAlignedSequences,
 String name,
 String summary,
 AnnotatedPluginDocument alignmentDocument,
 boolean standardTranslation)

Parameters:

trees - One or more trees whose tips are sequences of the alignment; must not be null or empty

inAlignedSequences - List of aligned sequences. Can be null if alignmentDocument is given.

name - document name

summary - document summary

alignmentDocument - Alignment document which is the origin of alignedSequences (optional, i.e. may be null)

standardTranslation - when true, taxa on tree is in fact ("1", "2", ...) and so a conversion to the actual taxa name (from the sequences) has to be applied when appropriate.

Throws:

IllegalArgumentException - if trees is null or empty

DefaultPhylogenyDocument

public DefaultPhylogenyDocument(List<? extends Tree> trees,
 List<Sequence> inAlignedSequences,
 String name,
 String summary,
 AnnotatedPluginDocument alignmentDocument,
 boolean standardTranslation,
 boolean allTreesWritable)

Parameters:

trees - One or more trees whose tips are sequences of the alignment; must not be null or empty

inAlignedSequences - List of aligned sequences. Can be null if alignmentDocument is given.

name - document name

summary - document summary

alignmentDocument - Alignment document which is the origin of alignedSequences (optional, i.e. may be null)

standardTranslation - when true, taxa on tree is in fact ("1", "2", ...) and so a conversion to the actual taxa name (from the sequences) has to be applied when appropriate.

allTreesWritable - True if the tree viewer should allow the user to modify all trees in this document (if false, only the first tree will be writable)

Throws:

IllegalArgumentException - if trees is null or empty

Method Details

setNexusSource

public void setNexusSource(String fileText,
 int nexusBlockNumber)

Set source of document in nexus format. Used to preserve the full content of an imported nexus file such as comments and unhandled sections.

Parameters:

fileText - text in nexus format

nexusBlockNumber - block number (or -1 for the first one)

Throws:

org.jdom.IllegalDataException - if fileText is not legal XML character data, as determined by Verifier.checkCharacterData(String).

IllegalStateException - if standardTranslationForTaxa was used.

getTrees

public List<? extends Tree> getTrees()

Description copied from interface: SameTaxaTreesDocument

Get tree set.

Specified by:

getTrees in interface SameTaxaTreesDocument

Returns:

the trees

areAllTreesWritable

public boolean areAllTreesWritable()

True if the tree viewer should allow the user to modify all trees in this document (if false, only the first tree will be writable)

Returns:

True if the tree viewer should allow the user to modify all trees in this document (if false, only the first tree will be writable)

canExport

public boolean canExport(ExportableDocument.Format format)

Description copied from interface: ExportableDocument

Check if a format is supported by document.

Specified by:

canExport in interface ExportableDocument

Parameters:

format - export format

Returns:

true if format is supported.

export

public boolean export(ExportableDocument.Format format,
 OutputStream to)
               throws IOException

Description copied from interface: ExportableDocument

Export a document.

Specified by:

export in interface ExportableDocument

Parameters:

format - format to export

to - output document to this stream.

Returns:

true when file exported successfully, false otherwise.

Throws:

IOException - if the OutputStream can't be written to for any reason

toXML

public org.jdom.Element toXML()

Description copied from interface: XMLSerializable

Convert object to a JDOM element. The representation should be complete so that XMLSerializable.fromXML(org.jdom.Element) can completely restore the object's 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.

Specified by:

toXML in interface XMLSerializable

Overrides:

toXML in class DefaultAlignmentDocument

Returns:

object encoded as a JDOM element

getVersionSupport

public Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)

Description copied from interface: XMLSerializable.OldVersionCompatible

Gets either the latest version this class can serialize to via XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) last changed.

Example implementation:

 switch (versionType) {
   case FormatLastExtended:
     //added a new tag to xml in 10.0 that can be safely ignored by older versions
     return Geneious.MajorVersion.Version10_0;
   case FormatLastChanged:
     //renamed a tag in 9.1 meaning that older versions can no longer read the xml from 9.1
     return Geneious.MajorVersion.Version9_1;
   case OldestVersionSerializableTo:
     //this document class can export xml that is compatible with 9.0
     return Geneious.MajorVersion.Version9_0;
   default:
     throw new IllegalArgumentException("Unrecognized VersionSupportType");
 }
 

Specified by:

getVersionSupport in interface XMLSerializable.OldVersionCompatible

Overrides:

getVersionSupport in class DefaultAlignmentDocument

Parameters:

versionType - specifies which version property to return

Returns:

the major version of Geneious corresponding to the versionType for this classes toXML method.

toXML

public org.jdom.Element toXML(Geneious.MajorVersion version,
 ProgressListener progressListener)

Description copied from interface: XMLSerializable.OldVersionCompatible

Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious. It is acceptable for the XML to include unnecessary tags that will be ignored by the earlier version. For example if the implementation has only extended the XML since the earlier version, then the XML returned may be identical to the XML returned for the current version.

See XMLSerializable.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.

Specified by:

toXML in interface XMLSerializable.OldVersionCompatible

Overrides:

toXML in class DefaultAlignmentDocument

Parameters:

version - 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 cancelling

Returns:

object encoded as a JDOM element

setTrees

public void setTrees(List<? extends Tree> newTrees)

Description copied from interface: EditableSameTaxaTreesDocument

Set some trees.

Specified by:

setTrees in interface EditableSameTaxaTreesDocument

Parameters:

newTrees - A list of new trees. A null entry means no change and the existing tree is taken.

reorderSequences

public void reorderSequences(int[] ordering)

Description copied from class: SequenceAlignmentDocument

Adjusts the ordering of sequences in the alignment according to the ordering array. If ordering[i]==j, then the sequence at index 'i' should be the sequence previously at index 'j' For example, if ordering = {0,1,3,4,2} Then: sequence at index 2 is moved to index 4 sequence at index 3 is moved to index 2 sequence at index 4 is moved to index 3 This function may only be called on alignments that return true from SequenceAlignmentDocument.isEditable()

Overrides:

reorderSequences in class DefaultAlignmentDocument

Parameters:

ordering - Each integer between 0 and ordering.length - 1 inclusive should occur exactly once in this array.

setSequenceName

public void setSequenceName(int index,
 String newName,
 boolean allowModifyingOriginals)

Description copied from class: SequenceAlignmentDocument

change the name of a sequence within the alignment. This method may only be called if SequenceAlignmentDocument.canSetSequenceNames() returns true.

Overrides:

setSequenceName in class DefaultAlignmentDocument

Parameters:

index - index of the sequence name to change

newName - the new name for the sequence.

allowModifyingOriginals - if the alignment stores a reference to an editable original SequenceDocument (which can be determined by using SequenceAlignmentDocument.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.

updateSequence

public void updateSequence(int index,
 CharSequence sequence,
 List<SequenceAnnotation> annotations,
 NucleotideGraph graph,
 boolean allowModifyingOriginals)

Description copied from class: SequenceAlignmentDocument

Set new residues and related data for one sequence. This function may only be called on alignments that return true from SequenceAlignmentDocument.isEditable() (otherwise, the method should throw UnsupportedOperationException).

Overrides:

updateSequence in class DefaultAlignmentDocument

Parameters:

index - the index of the sequence to be updated. between 0 and SequenceAlignmentDocument.getNumberOfSequences() - 1

sequence - the new residues

annotations - a list of the annotations

graph - 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.

allowModifyingOriginals - 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 SequenceAlignmentDocument.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.

removeSequence

public void removeSequence(int index)

Description copied from class: SequenceAlignmentDocument

Removes the specified sequence from the alignment. All other sequences should maintain their original ordering. This function may only be called on alignments that return true from SequenceAlignmentDocument.isEditable()

Overrides:

removeSequence in class DefaultAlignmentDocument

Parameters:

index - the index of the sequence to be removed. between 0 and SequenceAlignmentDocument.getNumberOfSequences() - 1

addSequence

public void addSequence(SequenceDocument sequence)

Description copied from class: SequenceAlignmentDocument

Add a sequence to the end of the alignment. sequence should be the gapped (aligned) sequence.

Overrides:

addSequence in class DefaultAlignmentDocument

Parameters:

sequence - sequence to add

See Also:

• SequenceAlignmentDocument.reorderSequences(int[])
• SequenceAlignmentDocument.setReferencedDocument(int, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument)

canAddAndRemoveSequences

public boolean canAddAndRemoveSequences()

Description copied from class: SequenceAlignmentDocument

Check if this alignment supports adding and removing sequences.

Overrides:

canAddAndRemoveSequences in class DefaultAlignmentDocument

Returns:

true if adding and removing sequences is supported, false otherwise.

See Also:

• SequenceAlignmentDocument.addSequence(SequenceDocument)
• SequenceAlignmentDocument.removeSequence(int)

fromXML

public void fromXML(org.jdom.Element doc)
             throws XMLSerializationException

Description copied from interface: XMLSerializable

Restore the object from the JDOM Element returned by XMLSerializable.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().

Specified by:

fromXML in interface XMLSerializable

Overrides:

fromXML in class DefaultAlignmentDocument

Parameters:

doc - representation from a previous call to XMLSerializable.toXML()

Throws:

XMLSerializationException - if the Element can't be converted into this type of object

fromXML

public void fromXML(org.jdom.Element doc,
 ProgressListener progressListener)
             throws XMLSerializationException

Description copied from class: DefaultAlignmentDocument

Deserializes this document with progress. See XMLSerializableWithProgress

Overrides:

fromXML in class DefaultAlignmentDocument

Throws:

XMLSerializationException

getDescription

public String getDescription()

Description copied from interface: PluginDocument

A human readable single line of text describing this document, to appear in the description field in the document table.

Specified by:

getDescription in interface PluginDocument

Overrides:

getDescription in class DefaultAlignmentDocument

Returns:

a one line simple text description of the document, or null if no description is available.

toHTML

public String toHTML()

Description copied from interface: PluginDocument

Provide a textual view of document. The contents should be at most 30K-60K characters. One reason is that this text is rendered using JTextPane, which is horrendously slow when handling large text. The more fundamental reason is that large amounts of text are generally not useful for a user. The whole idea of using a tool such as Geneious is to provide specialized viewers which make the large amount of bioinformatics data perceivable and comprehensible to a human user.

Return an HTML body fragment (i.e. a fragment which sits inside a <body></body> tag). (Header,stylesheet and annotations are automatically added by GENEious code).

Can optionally return an entire html tag set, as long as the first six characters are <html>

Specified by:

toHTML in interface PluginDocument

Overrides:

toHTML in class SequenceAlignmentDocument

Returns:

an HTML fragment of tag set, or null to have no text view.

setFieldValue

public void setFieldValue(int sequenceIndex,
 DocumentField field,
 Object fieldValue,
 boolean allowModifyingOriginals)

Description copied from class: SequenceAlignmentDocument

Sets the value of a displayable field on one of the sequences in the alignment. This method may only be called if SequenceAlignmentDocument.canSetFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField) returns true.

Overrides:

setFieldValue in class DefaultAlignmentDocument

Parameters:

sequenceIndex - the index of a sequence in the alignment to update the field value on

field - the field to update

fieldValue - 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.

See Also:

• SequenceAlignmentDocument.canSetFieldValue(int, com.biomatters.geneious.publicapi.documents.DocumentField)