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 `UnknownCommandEvent`s.

  ### 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

    All Methods Instance Methods Concrete Methods
    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 `UnknownCommandEvent`s 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 `SequenceTokensEvent`s.
    `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 `UnknownCommandEvent`s 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 `SequenceTokensEvent`s. 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`