info.bioinfweb.jphyloio.formats.nexus

## Class NexusEventWriter

- java.lang.Object
- - info.bioinfweb.jphyloio.AbstractEventWriter<P>
  - - info.bioinfweb.jphyloio.formats.text.AbstractTextEventWriter<NexusWriterStreamDataProvider>
    - - info.bioinfweb.jphyloio.formats.nexus.NexusEventWriter

- All Implemented Interfaces:
    NexusConstants, JPhyloIOEventWriter, JPhyloIOFormatSpecificObject

      public class NexusEventWriter
      extends AbstractTextEventWriter<NexusWriterStreamDataProvider>
      implements NexusConstants

  Event based writer for the Nexus format.

  This writer is able to write OTU, sequence and tree data to Nexus formatted streams. It will ignore any data for phylogenetic networks that are provided by `DocumentDataAdapter#getTreeNetworkIterator(ReadWriteParameterMap)`, because the Nexus format only supports trees.

  ### Comments and metadata

  Comments nested in any of the supported elements will usually be written. Metadata is only supported nested in tree node or edge definitions and is written into hot comments as they are supported by `NewickStringWriter`. Metadata nested into other elements will be ignored.

  ### Labels and IDs

  Note that the Nexus format does not differentiate between labels and IDs and because of this, labels of OTUs and labels of sequences or nodes linked to them must have identical names in Nexus. Therefore this writer will always use the OTU label of the linked OTU, also for writing sequences and nodes. Labels of sequences and nodes will be ignored (which does not make a difference, of they are identical with the labels of their linked OTUs).

  Sequence labels will be used though, if no OTU is linked. In such cases the `NEWTAXA` subcommand will be specified in the `DIMENSIONS` command.

  If an OTU event without a defined label is provided by the data adapter, this writer will use the OTU ID as the taxon name in Nexus instead. If two OTUs with identical labels are provided, the Nexus name of the second will be a combination of the ID and the label, while the first will be represented as the unchanged label as usual. If additional conflicts occur (e.g. if an ID of an OTU without a label is equal to the label of a previous OTU) an index will be added to the end of the label, until it is unique labels. The elements (ID, label, index) of edited Nexus names will be separated by `AbstractEventWriter.EDITED_LABEL_SEPARATOR`.

  The Nexus names that have actually been used in the output can be obtained from the `LabelEditingReporter` added to the parameter map using `ReadWriteParameterMap.getLabelEditingReporter()`. (A reference to the parameter map passed to one of the `#writeDocument()` methods must be kept by the application code, in order to access the label editing reporter after the document has been written.)

  ### Token sets

  Note that this writer (and the Nexus format) does not support multiple token sets for a single matrix. If multiple sets are provided, only the first one will be considered to determine the symbols to be declared in the `FORMAT` command. According warnings will be logged, if multiple token sets are found.

  `NexusEventReader` supports an extension of the Nexus format introduced by MrBayes but this writer currently does not make use of that, since the output would not be conform with the Nexus standard and some applications may not be able to read it.

  ### Recognized parameters

  - `ReadWriteParameterNames.KEY_WRITER_INSTANCE`
  - `ReadWriteParameterNames.KEY_LOGGER`
  - `ReadWriteParameterNames.KEY_APPLICATION_NAME`
  - `ReadWriteParameterNames.KEY_APPLICATION_VERSION`
  - `ReadWriteParameterNames.KEY_APPLICATION_URL`
  - `ReadWriteParameterNames.KEY_LINE_SEPARATOR`
  - `ReadWriteParameterNames.KEY_SEQUENCE_EXTENSION_TOKEN`
  - `ReadWriteParameterNames.KEY_MAXIMUM_NAME_LENGTH` (If this parameter is omitted, any name length is possible.)
  - `ReadWriteParameterNames.KEY_ALWAYS_WRITE_NEXUS_NODE_LABELS`
  - `ReadWriteParameterNames.KEY_GENERATE_NEXUS_TRANSLATION_TABLE`
  - `ReadWriteParameterNames.KEY_LABEL_EDITING_REPORTER`
  - `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`
  Since:
    0.0.0
  Author:
    Ben Stöver
  See Also:
    Metadata demo application

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class info.bioinfweb.jphyloio.AbstractEventWriter

      `AbstractEventWriter.NoEditUniqueLabelHandler, AbstractEventWriter.UniqueLabelHandler`

  - ### Field Summary

    - ### Fields inherited from class info.bioinfweb.jphyloio.AbstractEventWriter

      `EDITED_LABEL_SEPARATOR`

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NexusEventWriter()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected NexusWriterStreamDataProvider` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventWriter` to initialize the stream data provider that will be returned by `AbstractEventWriter.getStreamDataProvider()`.
    `protected void` | `doWriteDocument(DocumentDataAdapter document, java.io.Writer writer, ReadWriteParameterMap parameters)`
    `static java.lang.String` | `formatToken(java.lang.String token)`
    `java.lang.String` | `getFormatID()` Returns a string ID uniquely identifying the target format of this instance.
    `protected ApplicationLogger` | `getLogger()`
    `protected java.util.Map<java.lang.String,NexusMatrixWriteResult>` | `getMatrixIDToBlockTypeMap()`
    `protected ReadWriteParameterMap` | `getParameters()`
    `protected void` | `writeBlockEnd()`
    `protected void` | `writeBlockStart(java.lang.String name)`
    `protected void` | `writeCommandEnd()`
    `static void` | `writeKeyValueExpression(java.io.Writer writer, java.lang.String key, java.lang.String value)`
    `protected void` | `writeLineStart(java.io.Writer writer, java.lang.String text)`
    `protected void` | `writeLinkCommand(java.lang.String linkedID, java.lang.String linkedBlockName, EventContentType linkedContentType)`

    - ### Methods inherited from class info.bioinfweb.jphyloio.formats.text.AbstractTextEventWriter

      `getWriter`

    - ### Methods inherited from class info.bioinfweb.jphyloio.AbstractEventWriter

      `createUniqueLabel, createUniqueLabel, createUniqueLabel, createUniqueLinkedOTULabel, decreaseIndention, determineMaxSequenceLength, extendSequence, getFileStartInfo, getIndention, getLabeledIDName, getLinkedOTUNameOTUFirst, getLinkedOTUNameOwnFirst, getReferencedOTUList, getStreamDataProvider, increaseIndention, logIngnoredOTULists, writeDocument, writeDocument, writeDocument, writeLineBreak`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### NexusEventWriter

          public NexusEventWriter()

  - ### Method Detail

    - #### 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 NexusWriterStreamDataProvider createStreamDataProvider()

      Description copied from class: `AbstractEventWriter`
      This method is called in the constructor of `AbstractEventWriter` to initialize the stream data provider that will be returned by `AbstractEventWriter.getStreamDataProvider()`. Inheriting classes that use their own stream data provider implementation should overwrite this method.

      This default implementation creates a new instance of `WriterStreamDataProvider`.

      Overrides:
        `createStreamDataProvider` in class `AbstractEventWriter<NexusWriterStreamDataProvider>`
      Returns:
        the stream data provider to be used with this instance

    - #### getParameters

          protected ReadWriteParameterMap getParameters()

    - #### getLogger

          protected ApplicationLogger getLogger()

    - #### getMatrixIDToBlockTypeMap

          protected java.util.Map<java.lang.String,NexusMatrixWriteResult> getMatrixIDToBlockTypeMap()

    - #### writeLineStart

          protected void writeLineStart(java.io.Writer writer,
                                        java.lang.String text)
                                 throws java.io.IOException

      Overrides:
        `writeLineStart` in class `AbstractEventWriter<NexusWriterStreamDataProvider>`
      Throws:
        `java.io.IOException`

    - #### formatToken

          public static java.lang.String formatToken(java.lang.String token)

    - #### writeCommandEnd

          protected void writeCommandEnd()
                                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### writeBlockStart

          protected void writeBlockStart(java.lang.String name)
                                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### writeBlockEnd

          protected void writeBlockEnd()
                                throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### writeKeyValueExpression

          public static void writeKeyValueExpression(java.io.Writer writer,
                                                     java.lang.String key,
                                                     java.lang.String value)
                                              throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### writeLinkCommand

          protected void writeLinkCommand(java.lang.String linkedID,
                                          java.lang.String linkedBlockName,
                                          EventContentType linkedContentType)
                                   throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### doWriteDocument

          protected void doWriteDocument(DocumentDataAdapter document,
                                         java.io.Writer writer,
                                         ReadWriteParameterMap parameters)
                                  throws java.io.IOException

      Overrides:
        `doWriteDocument` in class `AbstractTextEventWriter<NexusWriterStreamDataProvider>`
      Throws:
        `java.io.IOException`