info.bioinfweb.jphyloio.formats.nexus

Class NexusEventReader

java.lang.Object

info.bioinfweb.jphyloio.AbstractEventReader<P>

info.bioinfweb.jphyloio.formats.text.AbstractTextEventReader<NexusReaderStreamDataProvider>

info.bioinfweb.jphyloio.formats.nexus.NexusEventReader

All Implemented Interfaces:

NexusConstants, JPhyloIOEventReader, JPhyloIOFormatSpecificObject, ReadWriteConstants

public class NexusEventReader
extends AbstractTextEventReader<NexusReaderStreamDataProvider>
implements NexusConstants

Event based reader for Nexus files.

This reader as able to read data from the Nexus TAXA, CHARACTERS, UNALIGNED, DATA, TREES and SETS blocks, although not all commands of the SETS block are currently supported (see below). Furthermore it can read metadata provided in hot comments in trees and the eNexus network format as described in the documentation of NewickStringReader. Reading phylogenetic networks from one type of custom NETWORKS block is optionally also supported, if addENewickNetworksBlockSupport() is called after construction. It will also handle Nexus comments as comment events and optionally unknown commands as UnknownCommandEvents.

Supported sets

The commands for CHARSET, TAXSET and TREESET are currently supported both in standard and vector format. STATESET and CHANGESET are currently ignored, since Nexus state sets are currently not modeled by known other software and change sets are not part of the data model of JPhyloIO. For the same reason, the respective partition commands (e.g. CHARPARTITION that would allow to divide a character set into separate subsets) are currently not read as well.

Links between blocks

In addition to the core Nexus standards, this reader also supports the TITLE and LINK commands introduced by Mesquite e.g. to assign TAXA blocks to character or tree data, if more than one TAXA block is present.

Block linking is modeled on JPhyloIO using the LinkedLabeledIDEvent.getLinkedID() property. The information from TITLE and LINK commands is e.g. used to link tree groups to OTU lists, alignments to OTU lists, character sets to alignments or indirectly to link sequences and tree nodes to OTUs.

Note that this reader requires referenced blocks to occur before the block that contains the reference. Linking blocks that occur later in the file is not supported, since it would not allow direct event based parsing. If a LINK command is encountered that links a block that was not declared before (or not anywhere in the file), a JPhyloIOReaderException is be thrown.

If a block without a LINK command, that would usually link another block is encountered, the first block of the according type found in the file will be assumed as linked. If no according block was encountered before the LINK, nothing will be linked (LinkedLabeledIDEvent.getLinkedID() of the according event will return null).

Unsupported features

Currently this implementation (if used with the default command readers) does not support the following Nexus features and will throw an UnsupportedFormatFeatureException if one of them is encountered:

• Character matrices using the FORMAT subcommand TRANSPOSE, indicating that columns and rows are shifted can currently not be read by MatrixReader.
• Set definitions in a SETS block using the REMAINING keyword to indicate that they contain all elements that were not contained in a previous set are currently not supported by AbstractNexusSetReader and its descendants.

Note that this list only contains Nexus features that trigger an exception, if encountered. There may be additional featured (e.g. the NOTES block) that are currently not supported, but are just ignored by the reader without throwing an exception.

Extending this implementation

It is possible to extend the functionality of this reader by adding custom implementations of NexusBlockHandler or NexusCommandEventReader.

Recognized parameters

• ReadWriteParameterNames.KEY_EXPECT_E_NEWICK
• ReadWriteParameterNames.KEY_NEXUS_BLOCK_HANDLER_MAP
• ReadWriteParameterNames.KEY_NEXUS_COMMAND_READER_FACTORY
• ReadWriteParameterNames.KEY_CREATE_UNKNOWN_COMMAND_EVENTS
• ReadWriteParameterNames.KEY_MAXIMUM_TOKENS_TO_READ
• ReadWriteParameterNames.KEY_MAXIMUM_COMMENT_LENGTH
• ReadWriteParameterNames.KEY_REPLACE_MATCH_TOKENS

If custom or third parts block handlers are used together with an instance of this reader, these may support additional custom parameters.

Author:

Ben Stöver

See Also:

Metadata demo application

Field Summary

Fields inherited from class info.bioinfweb.jphyloio.formats.text.AbstractTextEventReader

lineConsumed

Fields inherited from interface info.bioinfweb.jphyloio.formats.nexus.NexusConstants

ALTERNATIVE_END_COMMAND, BEGIN_COMMAND, BLOCK_NAME_CHARACTERS, BLOCK_NAME_DATA, BLOCK_NAME_NETWORKS, BLOCK_NAME_SETS, BLOCK_NAME_TAXA, BLOCK_NAME_TREES, BLOCK_NAME_UNALIGNED, CHARACTER_NAME_STATES_SEPARATOR, COMMAND_END, COMMAND_NAME_CHAR_LABELS, COMMAND_NAME_CHAR_SET, COMMAND_NAME_CHAR_STATE_LABELS, COMMAND_NAME_DIMENSIONS, COMMAND_NAME_FORMAT, COMMAND_NAME_LINK, COMMAND_NAME_MATRIX, COMMAND_NAME_NETWORK, COMMAND_NAME_TAX_LABELS, COMMAND_NAME_TAXON_SET, COMMAND_NAME_TITLE, COMMAND_NAME_TRANSLATE, COMMAND_NAME_TREE, COMMAND_NAME_TREE_SET, COMMENT_END, COMMENT_START, DIMENSIONS_SUBCOMMAND_NCHAR, DIMENSIONS_SUBCOMMAND_NEW_TAXA, DIMENSIONS_SUBCOMMAND_NTAX, ELEMENT_SEPARATOR, END_COMMAND, FIRST_LINE, FORMAT_NAME_STANDARD, FORMAT_NAME_VECTOR, FORMAT_SUBCOMMAND_DATA_TYPE, FORMAT_SUBCOMMAND_GAP_CHAR, FORMAT_SUBCOMMAND_INTERLEAVE, FORMAT_SUBCOMMAND_MATCH_CHAR, FORMAT_SUBCOMMAND_MISSING_CHAR, FORMAT_SUBCOMMAND_NO_LABELS, FORMAT_SUBCOMMAND_NO_TOKENS, FORMAT_SUBCOMMAND_SYMBOLS, FORMAT_SUBCOMMAND_TOKENS, FORMAT_SUBCOMMAND_TRANSPOSE, FORMAT_VALUE_CONTINUOUS_DATA_TYPE, FORMAT_VALUE_DNA_DATA_TYPE, FORMAT_VALUE_MIXED_DATA_TYPE, FORMAT_VALUE_NUCLEOTIDE_DATA_TYPE, FORMAT_VALUE_PROTEIN_DATA_TYPE, FORMAT_VALUE_RNA_DATA_TYPE, FORMAT_VALUE_STANDARD_DATA_TYPE, KEY_VALUE_SEPARATOR, MATRIX_POLYMORPHIC_TOKEN_END, MATRIX_POLYMORPHIC_TOKEN_START, MATRIX_UNCERTAINS_TOKEN_END, MATRIX_UNCERTAINS_TOKEN_START, NEXUS_FORMAT_NAME, NEXUS_NAMESPACE_PREFIX, NEXUS_PREDICATE_NAMESPACE, SET_END_INDEX_SYMBOL, SET_KEY_WORD_ALL, SET_KEY_WORD_REMAINING, SET_REGULAR_INTERVAL_SYMBOL, SET_TO_SYMBOL, SET_VECTOR_CONTAINED, SET_VECTOR_NOT_CONTAINED, UNTIL_WHITESPACE_COMMENT_COMMAND_EQUAL_PATTERN, UNTIL_WHITESPACE_COMMENT_COMMAND_PATTERN, VALUE_DELIMITER, WORD_DELIMITER

Fields inherited from interface info.bioinfweb.jphyloio.ReadWriteConstants

ATTRIBUTE_STRING_KEY, ATTRIBUTES_NAMESPACE_FOLDER, DATA_TYPE_NAMESPACE_FOLDER, DATA_TYPE_SIMPLE_VALUE_LIST, DEFAULT_CHAR_SET_ID_PREFIX, DEFAULT_CHARACTER_DEFINITION_ID_PREFIX, DEFAULT_EDGE_ID_PREFIX, DEFAULT_GENERAL_ID_PREFIX, DEFAULT_MATRIX_ID_PREFIX, DEFAULT_MAX_COMMENT_LENGTH, DEFAULT_MAX_TOKENS_TO_READ, DEFAULT_META_ID_PREFIX, DEFAULT_NETWORK_ID_PREFIX, DEFAULT_NODE_EDGE_SET_ID_PREFIX, DEFAULT_NODE_ID_PREFIX, DEFAULT_OTU_ID_PREFIX, DEFAULT_OTU_LIST_ID_PREFIX, DEFAULT_OTU_SET_ID_PREFIX, DEFAULT_SEQUENCE_ID_PREFIX, DEFAULT_SEQUENCE_SET_ID_PREFIX, DEFAULT_TOKEN_DEFINITION_ID_PREFIX, DEFAULT_TOKEN_SET_ID_PREFIX, DEFAULT_TREE_ID_PREFIX, DEFAULT_TREE_NETWORK_GROUP_ID_PREFIX, DEFAULT_TREE_NETWORK_SET_ID_PREFIX, JPHYLOIO_ATTRIBUTES_NAMESPACE, JPHYLOIO_ATTRIBUTES_PREFIX, JPHYLOIO_DATA_TYPE_NAMESPACE, JPHYLOIO_DATA_TYPE_PREFIX, JPHYLOIO_FORMATS_NAMESPACE_PREFIX, JPHYLOIO_GENERAL_NAMESPACE, JPHYLOIO_NAMESPACE_PREFIX, JPHYLOIO_PREDICATE_NAMESPACE, JPHYLOIO_PREDICATE_PREFIX, PREDICATE_CHARACTER_COUNT, PREDICATE_EDGE_LENGTH, PREDICATE_EDGE_SOURCE_NODE, PREDICATE_EDGE_TARGET_NODE, PREDICATE_HAS_CUSTOM_XML, PREDICATE_HAS_LITERAL_METADATA, PREDICATE_HAS_RESOURCE_METADATA, PREDICATE_IS_CROSSLINK, PREDICATE_NAMESPACE_FOLDER, PREDICATE_PART_SEPERATOR, PREDICATE_SEQUENCE_COUNT, RESERVED_ID_PREFIX

Constructor Summary

Constructors

Constructor and Description
NexusEventReader(java.io.File file, ReadWriteParameterMap parameters) Creates a new instance of this class with a default block handler map and command reader factory.
NexusEventReader(java.io.InputStream stream, ReadWriteParameterMap parameters) Creates a new instance of this class.
NexusEventReader(PeekReader reader, ReadWriteParameterMap parameters) Creates a new instance of this class with a default block handler map and command reader factory.
NexusEventReader(java.io.Reader reader, ReadWriteParameterMap parameters) Creates a new instance of this class with a default block handler map and command reader factory.

Method Summary

Modifier and Type	Method and Description
void	addENewickNetworksBlockSupport() Adds an instance of ENewickNetworksBlockHandler and ENewickNetworkReader to the maps of this instance in order to be able to read custom NETWORK blocks containing phylogenetic networks in the eNewick format.
protected void	consumeWhiteSpaceAndComments() Calls AbstractTextEventReader.consumeWhiteSpaceAndComments(char, char) with according parameters and ensures visibility for NexusReaderStreamDataProvider.
protected NexusReaderStreamDataProvider	createStreamDataProvider() This method is called in the constructor of AbstractEventReader to initialize the stream data provider that will be returned by AbstractEventReader.getStreamDataProvider().
protected boolean	getCreateUnknownCommandEvents() Specifies whether UnknownCommandEvents will be fired for all Nexus commands with no according reader stored in the factory.
java.lang.String	getCurrentBlockName() Returns the name of the current Nexus block (e.g.
java.lang.String	getFormatID() Returns a string ID uniquely identifying the target format of this instance.
protected LongIDManager	getIDManager()
protected SequenceTokensEventManager	getSequenceTokensEventManager() Returns the manager object used by this instance to create SequenceTokensEvents.
protected void	readComment() Calls AbstractTextEventReader.readComment(char, char) with according parameters and ensures visibility for NexusReaderStreamDataProvider.
protected KeyValueInformation	readKeyValueMetaInformation()
protected void	readNextEvent() Method to be implemented be inherited classes that adds at least one additional event (determined from the underlying data source) to the event queue.
protected java.lang.String	readNexusWord()
protected long	readPositiveInteger(long startOrEndIndex) Tries to read a positive integer from the current position of the underlying stream-

Methods inherited from class info.bioinfweb.jphyloio.formats.text.AbstractTextEventReader

close, consumeWhiteSpaceAndComments, createTokenList, getReader, readCharacters, readCharacters, readComment, readKeyValueInformation, readToken

Methods inherited from class info.bioinfweb.jphyloio.AbstractEventReader

addEventListener, fireEvent, getCurrentEventCollection, getLastNonCommentEvent, getParameters, getParentInformation, getPreviousEvent, getStreamDataProvider, getUpcomingEvents, hasNextEvent, hasSpecialEventCollection, isBeforeFirstAccess, next, nextOfType, peek, removeEventListener, resetCurrentEventCollection, setCurrentEventCollection

Methods inherited from class java.lang.Object

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

Constructor Detail

NexusEventReader

public NexusEventReader(java.io.File file,
                        ReadWriteParameterMap parameters)
                 throws java.io.IOException

Creates a new instance of this class with a default block handler map and command reader factory. These contain all handlers and command readers available in the core module of JPhyloIO.

Parameters:

file - the Nexus file to be read

parameters - the parameter map for this reader instance

Throws:

java.io.IOException - if an I/O exception occurs while parsing the first event

NexusEventReader

public NexusEventReader(java.io.InputStream stream,
                        ReadWriteParameterMap parameters)
                 throws java.io.IOException

Creates a new instance of this class.

Parameters:

stream - the stream providing the Nexus data to be read

parameters - the parameter map for this reader instance

Throws:

java.io.IOException - if an I/O exception occurs while parsing the first event

NexusEventReader

public NexusEventReader(PeekReader reader,
                        ReadWriteParameterMap parameters)
                 throws java.io.IOException

Creates a new instance of this class with a default block handler map and command reader factory. These contain all handlers and command readers available in the core module of JPhyloIO.

Parameters:

reader - the reader providing the Nexus data to be read

parameters - the parameter map for this reader instance

Throws:

java.io.IOException - if an I/O exception occurs while parsing the first event

NexusEventReader

public NexusEventReader(java.io.Reader reader,
                        ReadWriteParameterMap parameters)
                 throws java.io.IOException

Creates a new instance of this class with a default block handler map and command reader factory. These contain all handlers and command readers available in the core module of JPhyloIO.

Parameters:

reader - the reader providing the Nexus data to be read

parameters - the parameter map for this reader instance

Throws:

java.io.IOException - if an I/O exception occurs while parsing the first event

Method Detail

addENewickNetworksBlockSupport

public void addENewickNetworksBlockSupport()

Adds an instance of ENewickNetworksBlockHandler and ENewickNetworkReader to the maps of this instance in order to be able to read custom NETWORK blocks containing phylogenetic networks in the eNewick format.

Both maps (ReadWriteParameterNames#KEY_NEXUS_BLOCK_HANDLER_MAP and ReadWriteParameterNames#KEY_NEXUS_COMMAND_READER_FACTORY) are contained in the parameters map of this instance and may also be modified there.

Note that calling this method or not affects id NETWORK blocks are processed, while the ReadWriteParameterNames.KEY_EXPECT_E_NEWICK parameter determines whether eNewick strings are expected in the TREE commands of TREES blocks. Both features can be used independently.

This method should not be called more than once on each instance.

See Also:

ENewickNetworksBlockHandler, ENewickNetworkReader, ReadWriteParameterNames.KEY_EXPECT_E_NEWICK, ReadWriteParameterNames.KEY_NEXUS_BLOCK_HANDLER_MAP, ReadWriteParameterNames.KEY_NEXUS_COMMAND_READER_FACTORY

getFormatID

public java.lang.String getFormatID()

Description copied from interface: JPhyloIOFormatSpecificObject

Returns a string ID uniquely identifying the target format of this instance. Additional information on the format can be retrieved by passing the returned ID to JPhyloIOReaderWriterFactory.getFormatInfo(String).

Third party developers that create readers or writers for additional formats must make sure to use a globally unique format ID. It is strongly recommended to use owned reverse domain names for this (e.g. org.example.additionalformat).

Specified by:

getFormatID in interface JPhyloIOFormatSpecificObject

Returns:

the ID of the target format of this instance

See Also:

JPhyloIOReaderWriterFactory.getFormatInfo(String)

createStreamDataProvider

protected NexusReaderStreamDataProvider createStreamDataProvider()

Description copied from class: AbstractEventReader

This method is called in the constructor of AbstractEventReader to initialize the stream data provider that will be returned by AbstractEventReader.getStreamDataProvider(). Inherit classes that use their own stream data provider implementation should overwrite this method.

This default implementation creates a new instance of ReaderStreamDataProvider.

Overrides:

createStreamDataProvider in class AbstractTextEventReader<NexusReaderStreamDataProvider>

Returns:

the stream data provider to be used with this instance

getCreateUnknownCommandEvents

protected boolean getCreateUnknownCommandEvents()

Specifies whether UnknownCommandEvents will be fired for all Nexus commands with no according reader stored in the factory. The key will be the name of the command and the value will be its contents.

Note that e.g. FormatReader will fire additional Nexus specific meta events, even if this property is set to false.

Returns:

true if unknown command events will be fired, false otherwise

getCurrentBlockName

public java.lang.String getCurrentBlockName()

Returns the name of the current Nexus block (e.g. TAXA). Note that this is different from a possible title of this block.

Returns:

the current block name or null if the reader is currently not located inside a block

getIDManager

protected LongIDManager getIDManager()

Overrides:

getIDManager in class AbstractEventReader<NexusReaderStreamDataProvider>

getSequenceTokensEventManager

protected SequenceTokensEventManager getSequenceTokensEventManager()

Description copied from class: AbstractEventReader

Returns the manager object used by this instance to create SequenceTokensEvents. Such events should always be created using the returned object by inherited classes and never directly.

Overrides:

getSequenceTokensEventManager in class AbstractEventReader<NexusReaderStreamDataProvider>

Returns:

the character event manager used by this instance (never null)

consumeWhiteSpaceAndComments

protected void consumeWhiteSpaceAndComments()
                                     throws java.io.IOException

Calls AbstractTextEventReader.consumeWhiteSpaceAndComments(char, char) with according parameters and ensures visibility for NexusReaderStreamDataProvider.

Throws:

java.io.IOException - if an I/O error occurs during the read operation

readNexusWord

protected java.lang.String readNexusWord()
                                  throws java.io.IOException

Throws:

java.io.IOException

readPositiveInteger

protected long readPositiveInteger(long startOrEndIndex)
                            throws java.io.IOException

Tries to read a positive integer from the current position of the underlying stream-

Parameters:

startOrEndIndex - the value to be returned, if '.' is encountered (It is used as a placeholder for the highest possible index in some commands.)

Returns:

the read positive integer or startOrEndIndex or -2 if neither a positive integer nor '.' was found

Throws:

java.io.IOException

readComment

protected void readComment()
                    throws java.io.IOException

Calls AbstractTextEventReader.readComment(char, char) with according parameters and ensures visibility for NexusReaderStreamDataProvider.

Throws:

java.io.IOException - if an I/O error occurs during the read operation

readKeyValueMetaInformation

protected KeyValueInformation readKeyValueMetaInformation()
                                                   throws java.io.IOException

Throws:

java.io.IOException

readNextEvent

protected void readNextEvent()
                      throws java.io.IOException

Description copied from class: AbstractEventReader

Method to be implemented be inherited classes that adds at least one additional event (determined from the underlying data source) to the event queue.

Specified by:

readNextEvent in class AbstractEventReader<NexusReaderStreamDataProvider>

Throws:

java.io.IOException