info.bioinfweb.jphyloio.dataadapters

Interface MatrixDataAdapter

All Superinterfaces:

AnnotatedDataAdapter, ElementDataAdapter<LinkedLabeledIDEvent>

All Known Implementing Classes:

NoCharDefsNoSetsMatrixDataAdapter, StoreMatrixDataAdapter

public interface MatrixDataAdapter
extends ElementDataAdapter<LinkedLabeledIDEvent>

Adapter interface used to provide any type of character matrix data to instances of JPhyloIOEventWriter, including token and character set definitions related to this matrix.

This interface also allows to provide unaligned data (e.g. for the UNALIGNED block in Nexus). In such cases implementations need to return an according value in getColumnCount(ReadWriteParameterMap).

Applications implementing this adapter may consider to inherit their implementation from EmptyAnnotatedDataAdapter or NoCharDefsNoSetsMatrixDataAdapter.

Author:

Ben Stöver

Method Summary

Modifier and Type	Method and Description
boolean	containsLongTokens(ReadWriteParameterMap parameters) Returns whether tokens longer than one character are contained in the matrix modeled by this instance.
ObjectListDataAdapter<CharacterDefinitionEvent>	getCharacterDefinitions(ReadWriteParameterMap parameters) Returns a list of character definitions for the matrix modeled by this instance.
ObjectListDataAdapter<LinkedLabeledIDEvent>	getCharacterSets(ReadWriteParameterMap parameters) Returns a list of character sets defined for the matrix modeled by this instance.
long	getColumnCount(ReadWriteParameterMap parameters) Returns the number of columns the modeled matrix has, if it contains aligned data or -1 if it contains unaligned data and each sequence may have a different length.
long	getSequenceCount(ReadWriteParameterMap parameters) Returns the number of sequences contained in this matrix.
java.util.Iterator<java.lang.String>	getSequenceIDIterator(ReadWriteParameterMap parameters) Returns an iterator returning the IDs of all sequences in the represented matrix.
long	getSequenceLength(ReadWriteParameterMap parameters, java.lang.String sequenceID) Returns the length for the specified sequence.
ObjectListDataAdapter<LinkedLabeledIDEvent>	getSequenceSets(ReadWriteParameterMap parameters) Returns a list of sequence sets defined for the matrix modeled by this instance.
LinkedLabeledIDEvent	getSequenceStartEvent(ReadWriteParameterMap parameters, java.lang.String sequenceID) Returns an event describing the sequence with the specified ID.
ObjectListDataAdapter<TokenSetDefinitionEvent>	getTokenSets(ReadWriteParameterMap parameters) Returns a list of token sets defined for the matrix modeled by this instance.
void	writeSequencePartContentData(ReadWriteParameterMap parameters, JPhyloIOEventReceiver receiver, java.lang.String sequenceID, long startColumn, long endColumn) Implementing classes must write a sequence of events here, that describe the sequence tokens present in the specified column range.

Methods inherited from interface info.bioinfweb.jphyloio.dataadapters.ElementDataAdapter

getStartEvent

Methods inherited from interface info.bioinfweb.jphyloio.dataadapters.AnnotatedDataAdapter

writeMetadata

Method Detail

getSequenceCount

long getSequenceCount(ReadWriteParameterMap parameters)

Returns the number of sequences contained in this matrix.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

the number of sequences that will be returned by getSequenceIDIterator(ReadWriteParameterMap)

getColumnCount

long getColumnCount(ReadWriteParameterMap parameters)

Returns the number of columns the modeled matrix has, if it contains aligned data or -1 if it contains unaligned data and each sequence may have a different length.

For some writers the return value of this method may also determine which type of sequence data is written. (A Nexus writer would e.g. use an UNALIGNED instead of a CHARACTERS block, if -1 is returned.)

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

the number of columns in the matrix or -1 if each sequence may have a different length

containsLongTokens

boolean containsLongTokens(ReadWriteParameterMap parameters)

Returns whether tokens longer than one character are contained in the matrix modeled by this instance. Some writers will use this information to determine, whether whitespace needs to be inserted to separate tokens.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

true if tokens longer than one character may occur, or false if all tokens are exactly one character long

getCharacterDefinitions

ObjectListDataAdapter<CharacterDefinitionEvent> getCharacterDefinitions(ReadWriteParameterMap parameters)

Returns a list of character definitions for the matrix modeled by this instance.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

a (possibly empty) list of character definitions

getCharacterSets

ObjectListDataAdapter<LinkedLabeledIDEvent> getCharacterSets(ReadWriteParameterMap parameters)

Returns a list of character sets defined for the matrix modeled by this instance.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

a (possibly empty) list of character sets

getTokenSets

ObjectListDataAdapter<TokenSetDefinitionEvent> getTokenSets(ReadWriteParameterMap parameters)

Returns a list of token sets defined for the matrix modeled by this instance.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

a (possibly empty) list of token sets

getSequenceSets

ObjectListDataAdapter<LinkedLabeledIDEvent> getSequenceSets(ReadWriteParameterMap parameters)

Returns a list of sequence sets defined for the matrix modeled by this instance.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

a (possibly empty) list of sequence sets

getSequenceIDIterator

java.util.Iterator<java.lang.String> getSequenceIDIterator(ReadWriteParameterMap parameters)

Returns an iterator returning the IDs of all sequences in the represented matrix.

Note that the returned iterator will be in ongoing use while other methods (e.g. #writeSequencePartContent(JPhyloIOEventReceiver, String, long, long)) are called. Therefore implementing classes should make sure, that the source of the iterator is not modified while a JPhyloIO writer is in use. (The iterator should not throw a ConcurrentModificationException before writing the target document is finished.)

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

Returns:

an iterator returning the edge IDs (Must return at least one element.)

getSequenceStartEvent

LinkedLabeledIDEvent getSequenceStartEvent(ReadWriteParameterMap parameters,
                                           java.lang.String sequenceID)

Returns an event describing the sequence with the specified ID.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

sequenceID - the ID of the sequence to be described

Returns:

an linked OTU event describing the specified sequence

getSequenceLength

long getSequenceLength(ReadWriteParameterMap parameters,
                       java.lang.String sequenceID)
                throws java.lang.IllegalArgumentException

Returns the length for the specified sequence. If getColumnCount(ReadWriteParameterMap) returns does not return -1, this method should return the same value as getColumnCount(ReadWriteParameterMap) for each sequence. Otherwise it may return different values for each sequence.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

sequenceID - the ID of the sequence which defined the length

Returns:

the length of the according sequence

Throws:

java.lang.IllegalArgumentException - if an unknown sequence ID was specified

writeSequencePartContentData

void writeSequencePartContentData(ReadWriteParameterMap parameters,
                                  JPhyloIOEventReceiver receiver,
                                  java.lang.String sequenceID,
                                  long startColumn,
                                  long endColumn)
                           throws java.io.IOException,
                                  java.lang.IllegalArgumentException

Implementing classes must write a sequence of events here, that describe the sequence tokens present in the specified column range. A valid event sequence corresponds to the grammar node SequencePartContent in the documentation of JPhyloIOEventReader.

Note that (according to the grammar definition) metadata related to the sequence as a whole can also be passed to the receiver in this method. In most cases it makes sense to pass the respective metaevents at the beginning of this sequence, i.e., if this method is called with startColumn = 0 the first events written should be the metaevents for the whole sequence. (Note that the grammar in principle allows such metaevents also between sequence token events, but not all formats (not all writers) support metadata at such a position.) The same applies to comment events. (See the documentation of the single writers for further details on supported data.)

Note that column indices in JPhyloIO start with 0.

Parameters:

parameters - the parameter map of the calling writer that provides context information for the data request

receiver - the receiver to write the events to

sequenceID - the ID of the sequence from which a part shall be written

startColumn - the first column of the sequence part to be written (inclusive)

endColumn - the last column of the sequence part to be written (exclusive)

Throws:

java.io.IOException - if a I/O error occurs while writing the data

java.lang.IllegalArgumentException - if an unknown sequence ID was specified