info.bioinfweb.jphyloio.formats.phylip

## Class PhylipEventWriter

- java.lang.Object
- - info.bioinfweb.jphyloio.AbstractEventWriter<P>
  - - info.bioinfweb.jphyloio.formats.text.AbstractTextEventWriter<P>
    - - info.bioinfweb.jphyloio.AbstractSingleMatrixEventWriter<TextWriterStreamDataProvider<PhylipEventWriter>>
      - - info.bioinfweb.jphyloio.formats.phylip.PhylipEventWriter

- All Implemented Interfaces:
    PhylipConstants, JPhyloIOEventWriter, JPhyloIOFormatSpecificObject

      public class PhylipEventWriter
      extends AbstractSingleMatrixEventWriter<TextWriterStreamDataProvider<PhylipEventWriter>>
      implements PhylipConstants

  Event based writer for the Phylip format.

  This write is able to write sequence data to Phylip formatted streams. It will ignore any data for phylogenetic trees and networks that are provided by `DocumentDataAdapter#getTreeNetworkIterator(ReadWriteParameterMap)`, because the Phylip format does not support such data.

  Note that sequence names may have to be edited according to the (length) constrains the Phylip format imposes. According edits can be obtained using the `LabelEditingReporter` which is returned via the parameters map (using `ReadWriteParameterNames.KEY_LABEL_EDITING_REPORTER`).

  Since Phylip does not support OTU or taxon lists as well, such a list (if provided by `DocumentDataAdapter.getOTUListIterator(ReadWriteParameterMap)`) will also not be written. OTU definitions (if present) will though be used, if a sequence with a linked OTU ID but without a label is specified. In such cases `OTUListDataAdapter#getOTUStartEvent(String)` will be used to determine the according OTU label. If that OTU label is also `null`, the sequence ID will be used as the sequence name in Phylip.

  Comments and metadata nested in any of the supported elements will be ignored.

  Recognized parameters:

  - `ReadWriteParameterNames.KEY_SEQUENCE_EXTENSION_TOKEN`
  - `ReadWriteParameterNames.KEY_MAXIMUM_NAME_LENGTH`
  - `ReadWriteParameterNames.KEY_LABEL_EDITING_REPORTER`
  - `ReadWriteParameterNames.KEY_LOGGER`
  - `ReadWriteParameterNames.KEY_LINE_SEPARATOR`
  - `ReadWriteParameterNames.KEY_MAXIMUM_NAME_LENGTH` (If this parameter is omitted, `PhylipConstants.DEFAULT_NAME_LENGTH` will be used.)
  - `ReadWriteParameterNames.KEY_LABEL_EDITING_REPORTER`
  Since:
    0.0.0
  Author:
    Ben Stöver

- - ### 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.phylip.PhylipConstants

      `DEFAULT_NAME_LENGTH, PHYLIP_FORMAT_NAME, PREMATURE_NAME_END_CHARACTER, RELAXED_PHYLIP_NAME_PATTERN, SEQUENTIAL_PHYLIP_FORMAT_NAME`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PhylipEventWriter()` Creates a new instance of this class.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected TextWriterStreamDataProvider<PhylipEventWriter>` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventWriter` to initialize the stream data provider that will be returned by `AbstractEventWriter.getStreamDataProvider()`.
    `java.lang.String` | `getFormatID()` Returns a string ID uniquely identifying the target format of this instance.
    `protected java.lang.String` | `maskReservedLabelCharacters(java.lang.String label)`
    `static java.lang.String` | `maskReservedPhylipLabelCharacters(java.lang.String label)` Replaces characters that may not occur in Phylip labels according to this definition.
    `protected void` | `writeSingleMatrix(DocumentDataAdapter document, MatrixDataAdapter matrix, java.util.Iterator<java.lang.String> sequenceIDIterator, ReadWriteParameterMap parameters)` Implementations of this method should write a single matrix to their target format.

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

      `doWriteDocument, editSequenceOrNodeLabel`

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

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

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

- - ### Constructor Detail

    - #### PhylipEventWriter

          public PhylipEventWriter()

      Creates a new instance of this class. (Instances may be reused for different documents in subsequent calls of the different `#writeDocument()` methods.)

  - ### 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 TextWriterStreamDataProvider<PhylipEventWriter> 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<TextWriterStreamDataProvider<PhylipEventWriter>>`
      Returns:
        the stream data provider to be used with this instance

    - #### maskReservedPhylipLabelCharacters

          public static java.lang.String maskReservedPhylipLabelCharacters(java.lang.String label)

      Replaces characters that may not occur in Phylip labels according to this definition.

      The following replacements are performed:

      - `'('` → `'<'`
      - `')'` → `'>'`
      - `'['` → `'<'`
      - `']'` → `'>'`
      - `':'` → `'|'`
      - `';'` → `'|'`
      - `','` → `'|'`
      Parameters:
        `label` - the label to be edited
      Returns:
        the edited label (not containing any reserved characters anymore)

    - #### maskReservedLabelCharacters

          protected java.lang.String maskReservedLabelCharacters(java.lang.String label)

      Specified by:
        `maskReservedLabelCharacters` in class `AbstractSingleMatrixEventWriter<TextWriterStreamDataProvider<PhylipEventWriter>>`

    - #### writeSingleMatrix

          protected void writeSingleMatrix(DocumentDataAdapter document,
                                           MatrixDataAdapter matrix,
                                           java.util.Iterator<java.lang.String> sequenceIDIterator,
                                           ReadWriteParameterMap parameters)
                                    throws java.io.IOException

      Description copied from class: `AbstractSingleMatrixEventWriter`
      Implementations of this method should write a single matrix to their target format.
      Specified by:
        `writeSingleMatrix` in class `AbstractSingleMatrixEventWriter<TextWriterStreamDataProvider<PhylipEventWriter>>`
      Parameters:
        `document` - the document containing the matrix
        `matrix` - the (non-empty) matrix to be written
        `sequenceIDIterator` - an iterator oder all sequences in `matrix` positioned before the first sequence
        `parameters` - the parameter map for the writer implementation
      Throws:
        `java.io.IOException`