info.bioinfweb.jphyloio.formats.phyloxml

## Class PhyloXMLEventWriter

- java.lang.Object
- - info.bioinfweb.jphyloio.AbstractEventWriter<P>
  - - info.bioinfweb.jphyloio.formats.xml.AbstractXMLEventWriter<PhyloXMLWriterStreamDataProvider>
    - - info.bioinfweb.jphyloio.formats.phyloxml.PhyloXMLEventWriter

- All Implemented Interfaces:
    PhyloXMLConstants, PhyloXMLPrivateConstants, JPhyloIOXMLEventWriter, JPhyloIOEventWriter, JPhyloIOFormatSpecificObject

      public class PhyloXMLEventWriter
      extends AbstractXMLEventWriter<PhyloXMLWriterStreamDataProvider>
      implements PhyloXMLConstants, PhyloXMLPrivateConstants

  Event writer for the PhyloXML format.

  ### Phylogenetic trees or networks

  This writer supports writing phylogenetic trees and rooted networks. Phylogenetic networks are represented using the `clade_rel` tag in PhyloXML. To be able to write a hierarchical tree structure, the topology is reconstructed in the tool class `TreeTopologyExtractor` from the node and edge lists provided by `TreeNetworkDataAdapter`. This writer does not support writing phylogenetic networks with multiple roots due to the way topologies are reconstructed from the sequential lists of nodes and edges in JPhyloIO.

  ### Element IDs

  Some elements in a PhyloXML document have IDs given either via the `PhyloXMLConstants.ATTR_ID_SOURCE` or nested `ID` tags. These IDs are not necessarily identical with according JPhyloIO event IDs. If information about either type of ID is present in meta events with PhyloXML specific predicates, these IDs will be written to the file. All `id_ref` attributes (e.g. of a `clade_rel` tag) reference IDs given previously in an `id_source` attribute, never those from an `ID` tag. If a phylogeny has no previously specified ID, the according JPhyloIO event ID is written to the nested `ID` tag. If a `clade` tag has no previously specified ID, it is checked whether the JPhyloIO event ID was already used in another `id_source` attribute in the document (since all such values have to be unique docuemnt-wide). If so the ID is modified by adding a numerical suffix and then written to the file, otherwise the event ID is directly written.

  ### Simple literal metadata

  Metadata with literal values that belong to a tree, network, node or edge can be written to `property` tags nested under `phylogeny` or `clade`. Since these can not be nested in each other, the user can define a strategy to deal with nested meta-events with a parameter of the type `PhyloXMLMetadataTreatment`. This allows to e.g. write all meta-event values sequentially or ignore any nested metadata.

  ### PhyloXML-specific metadata

  PhyloXML specific metadata can be written using metadata events with respective predicates, which are declared in `PhyloXMLConstants`. The nesting of the tags to be written must be reflected in the nesting of the metadata events, where parent tags are modeled with `ResourceMetadataEvent`s using respective predicates and textual data of terminal tags and attribute values are modeled with `LiteralMetadataEvent`s also using respective predicates. If terminal tags have attributes, there is a predicate to be used for a parent resource metadata event and additional predicates for each attribute. The textual value nested in this tag has the form `XXX_VALUE`. (An example would be `PhyloXMLConstants.PREDICATE_NODE_ID_VALUE`, which would be nested under `PhyloXMLConstants.PREDICATE_NODE_ID` together with `PhyloXMLConstants.PREDICATE_NODE_ID_ATTR_PROVIDER`.)

  Since the PhyloXML schema defines a fixed order of tags, only meta-events with certain predicates are allowed in the content of different data elements and they also need to be in a specific order. Otherwise an `InconsistentAdapterDataException` will be thrown.

  #### Where to use which predicates

  In the following the allowed predicates nested under an event with a certain content type are listed. (Which predicates are allowed to be present in the content of these metadata events results from the information in the PhyloXML schema (version 1.10 and 1.20) and the accordingly named predicates declared in `PhyloXMLConstants`.)

  Predicates allowed nested under events with `EventContentType.TREE` or `EventContentType.NETWORK`:

  - `PhyloXMLConstants.PREDICATE_PHYLOGENY_ATTR_REROOTABLE`
  - `PhyloXMLConstants.PREDICATE_PHYLOGENY_ATTR_BRANCH_LENGTH_UNIT`
  - `PhyloXMLConstants.PREDICATE_PHYLOGENY_ATTR_TYPE`
  - `PhyloXMLConstants.PREDICATE_PHYLOGENY_DESCRIPTION`
  - `PhyloXMLConstants.PREDICATE_PHYLOGENY_DATE`
  - `PhyloXMLConstants.PREDICATE_CONFIDENCE`
  - `PhyloXMLConstants.PREDICATE_PROPERTY`

  Predicates allowed nested under events with `EventContentType.EDGE` or `EventContentType.ROOT_EDGE`:

  - `PhyloXMLConstants.PREDICATE_CONFIDENCE`,
  - `PhyloXMLConstants.PREDICATE_WIDTH`,
  - `PhyloXMLConstants.PREDICATE_COLOR`
  Predicates allowed nested under events with `EventContentType.NODE`:
- `PhyloXMLConstants.PREDICATE_NODE_ID`
- `PhyloXMLConstants.PREDICATE_TAXONOMY`
- `PhyloXMLConstants.PREDICATE_SEQUENCE`
- `PhyloXMLConstants.PREDICATE_EVENTS`
- `PhyloXMLConstants.PREDICATE_BINARY_CHARACTERS`
- `PhyloXMLConstants.PREDICATE_DISTRIBUTION`
- `PhyloXMLConstants.PREDICATE_DATE`
- `PhyloXMLConstants.PREDICATE_REFERENCE`
- `PhyloXMLConstants.PREDICATE_PROPERTY`

### Custom XML annotations

Custom XML can be written nested under the `clade` and the `phylogeny` tag if it does not consist of character data that is not nested under any tags or tags that are already defined in PhyloXML. XML metadata not fulfilling these conditions will be ignored.

Namespaces used or declared in custom XML elements are managed according to `ReadWriteParameterNames.KEY_CUSTOM_XML_NAMESPACE_HANDLING`. More information about this can be found in the documentation of `XMLReadWriteUtils#manageLiteralContentMetaNamespaces()`.

### Recognized parameters

- `ReadWriteParameterNames.KEY_WRITER_INSTANCE`
- `ReadWriteParameterNames.KEY_LOGGER`
- `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`
- `ReadWriteParameterNames.KEY_APPLICATION_NAME`
- `ReadWriteParameterNames.KEY_APPLICATION_VERSION`
- `ReadWriteParameterNames.KEY_APPLICATION_URL`
- `ReadWriteParameterNames.KEY_PHYLOXML_METADATA_TREATMENT`
- `ReadWriteParameterNames.KEY_CUSTOM_XML_NAMESPACE_HANDLING`

Since:
  0.0.0
Author:
  Sarah Wiechers, Ben Stöver
See Also:
  `PhyloXMLConstants`, `PhyloXMLMetadataTreatment`, 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.phyloxml.PhyloXMLConstants

      `APPLIES_TO_ANNOTATION, APPLIES_TO_CLADE, APPLIES_TO_NODE, APPLIES_TO_OTHER, APPLIES_TO_PARENT_BRANCH, APPLIES_TO_PHYLOGENY, ATTR_ABSENT_COUNT, ATTR_ALT_UNIT, ATTR_APPLIES_TO, ATTR_BRANCH_LENGTH, ATTR_BRANCH_LENGTH_UNIT, ATTR_COLLAPSE, ATTR_COMMENT, ATTR_CONFIDENCE, ATTR_DATATYPE, ATTR_DESC, ATTR_DISTANCE, ATTR_DOI, ATTR_EVIDENCE, ATTR_FROM, ATTR_GAINED_COUNT, ATTR_GEO_DATUM, ATTR_ID, ATTR_ID_PROVIDER, ATTR_ID_REF, ATTR_ID_REF_0, ATTR_ID_REF_1, ATTR_ID_SOURCE, ATTR_IS_ALIGNED, ATTR_LENGTH, ATTR_LOST_COUNT, ATTR_PRESENT_COUNT, ATTR_REF, ATTR_REROOTABLE, ATTR_ROOTED, ATTR_SOURCE, ATTR_STANDARD_DEVIATION, ATTR_TO, ATTR_TYPE, ATTR_UNIT, DATA_TYPE_BRANCH_COLOR, DATA_TYPE_EVENTTYPE, DATA_TYPE_RANK, DATA_TYPE_SEQUENCE_SYMBOL, DATA_TYPE_TAXONOMY_CODE, JPHYLOIO_PHYLOXML_NAMESPACE, PHYLOXML_DATA_TYPE_NAMESPACE, PHYLOXML_DEFAULT_PRE, PHYLOXML_FORMAT_NAME, PHYLOXML_NAMESPACE, PHYLOXML_PREDICATE_NAMESPACE, PHYLOXML_SCHEMA_LOCATION_URI, PREDICATE_ANNOTATION, PREDICATE_ANNOTATION_ATTR_EVIDENCE, PREDICATE_ANNOTATION_ATTR_REF, PREDICATE_ANNOTATION_ATTR_SOURCE, PREDICATE_ANNOTATION_ATTR_TYPE, PREDICATE_ANNOTATION_CONFIDENCE, PREDICATE_ANNOTATION_CONFIDENCE_ATTR_TYPE, PREDICATE_ANNOTATION_CONFIDENCE_VALUE, PREDICATE_ANNOTATION_DESC, PREDICATE_ANNOTATION_PROPERTY, PREDICATE_ANNOTATION_PROPERTY_ATTR_APPLIES_TO, PREDICATE_ANNOTATION_PROPERTY_ATTR_DATATYPE, PREDICATE_ANNOTATION_PROPERTY_ATTR_ID_REF, PREDICATE_ANNOTATION_PROPERTY_ATTR_UNIT, PREDICATE_ANNOTATION_URI, PREDICATE_ANNOTATION_URI_ATTR_DESC, PREDICATE_ANNOTATION_URI_ATTR_TYPE, PREDICATE_ANNOTATION_URI_VALUE, PREDICATE_ATTR_COLLAPSE, PREDICATE_ATTR_ID_SOURCE, PREDICATE_BINARY_CHARACTERS, PREDICATE_BINARY_CHARACTERS_ABSENT, PREDICATE_BINARY_CHARACTERS_ABSENT_BC, PREDICATE_BINARY_CHARACTERS_ATTR_ABSENT_COUNT, PREDICATE_BINARY_CHARACTERS_ATTR_GAINED_COUNT, PREDICATE_BINARY_CHARACTERS_ATTR_LOST_COUNT, PREDICATE_BINARY_CHARACTERS_ATTR_PRESENT_COUNT, PREDICATE_BINARY_CHARACTERS_ATTR_TYPE, PREDICATE_BINARY_CHARACTERS_GAINED, PREDICATE_BINARY_CHARACTERS_GAINED_BC, PREDICATE_BINARY_CHARACTERS_LOST, PREDICATE_BINARY_CHARACTERS_LOST_BC, PREDICATE_BINARY_CHARACTERS_PRESENT, PREDICATE_BINARY_CHARACTERS_PRESENT_BC, PREDICATE_CLADE_REL, PREDICATE_CLADE_REL_ATTR_DISTANCE, PREDICATE_CLADE_REL_ATTR_IDREF0, PREDICATE_CLADE_REL_ATTR_IDREF1, PREDICATE_CLADE_REL_ATTR_TYPE, PREDICATE_COLOR, PREDICATE_COLOR_ALPHA, PREDICATE_COLOR_BLUE, PREDICATE_COLOR_GREEN, PREDICATE_COLOR_RED, PREDICATE_CONFIDENCE, PREDICATE_CONFIDENCE_ATTR_STDDEV, PREDICATE_CONFIDENCE_ATTR_TYPE, PREDICATE_CONFIDENCE_VALUE, PREDICATE_DATE, PREDICATE_DATE_ATTR_UNIT, PREDICATE_DATE_DESC, PREDICATE_DATE_MAXIMUM, PREDICATE_DATE_MINIMUM, PREDICATE_DATE_VALUE, PREDICATE_DISTRIBUTION, PREDICATE_DISTRIBUTION_DESC, PREDICATE_DISTRIBUTION_POINT, PREDICATE_DISTRIBUTION_POINT_ALT, PREDICATE_DISTRIBUTION_POINT_ATTR_ALT_UNIT, PREDICATE_DISTRIBUTION_POINT_ATTR_GEODETIC_DATUM, PREDICATE_DISTRIBUTION_POINT_LAT, PREDICATE_DISTRIBUTION_POINT_LONG, PREDICATE_DISTRIBUTION_POLYGON, PREDICATE_DISTRIBUTION_POLYGON_POINT, PREDICATE_DISTRIBUTION_POLYGON_POINT_ALT, PREDICATE_DISTRIBUTION_POLYGON_POINT_ATTR_ALT_UNIT, PREDICATE_DISTRIBUTION_POLYGON_POINT_ATTR_GEODETIC_DATUM, PREDICATE_DISTRIBUTION_POLYGON_POINT_LAT, PREDICATE_DISTRIBUTION_POLYGON_POINT_LONG, PREDICATE_DOMAIN_ARCHITECTURE, PREDICATE_DOMAIN_ARCHITECTURE_ATTR_LENGTH, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN_ATTR_CONFIDENCE, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN_ATTR_FROM, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN_ATTR_ID, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN_ATTR_TO, PREDICATE_DOMAIN_ARCHITECTURE_DOMAIN_VALUE, PREDICATE_EVENTS, PREDICATE_EVENTS_CONFIDENCE, PREDICATE_EVENTS_CONFIDENCE_ATTR_TYPE, PREDICATE_EVENTS_CONFIDENCE_VALUE, PREDICATE_EVENTS_DUPLICATIONS, PREDICATE_EVENTS_LOSSES, PREDICATE_EVENTS_SPECIATIONS, PREDICATE_EVENTS_TYPE, PREDICATE_NODE_ID, PREDICATE_NODE_ID_ATTR_PROVIDER, PREDICATE_NODE_ID_VALUE, PREDICATE_PHYLOGENY_ATTR_BRANCH_LENGTH_UNIT, PREDICATE_PHYLOGENY_ATTR_REROOTABLE, PREDICATE_PHYLOGENY_ATTR_TYPE, PREDICATE_PHYLOGENY_DATE, PREDICATE_PHYLOGENY_DESCRIPTION, PREDICATE_PHYLOGENY_ID, PREDICATE_PHYLOGENY_ID_ATTR_PROVIDER, PREDICATE_PHYLOGENY_ID_VALUE, PREDICATE_PROPERTY, PREDICATE_PROPERTY_ATTR_APPLIES_TO, PREDICATE_PROPERTY_ATTR_ID_REF, PREDICATE_PROPERTY_ATTR_UNIT, PREDICATE_REFERENCE, PREDICATE_REFERENCE_ATTR_DOI, PREDICATE_REFERENCE_DESC, PREDICATE_REFERENCE_VALUE, PREDICATE_SEQ_REL, PREDICATE_SEQ_REL_ATTR_DISTANCE, PREDICATE_SEQ_REL_ATTR_IDREF0, PREDICATE_SEQ_REL_ATTR_IDREF1, PREDICATE_SEQ_REL_ATTR_TYPE, PREDICATE_SEQ_REL_CONFIDENCE, PREDICATE_SEQ_REL_CONFIDENCE_ATTR_TYPE, PREDICATE_SEQ_REL_CONFIDENCE_VALUE, PREDICATE_SEQUENCE, PREDICATE_SEQUENCE_ACCESSION, PREDICATE_SEQUENCE_ACCESSION_ATTR_COMMENT, PREDICATE_SEQUENCE_ACCESSION_ATTR_SOURCE, PREDICATE_SEQUENCE_ACCESSION_VALUE, PREDICATE_SEQUENCE_ATTR_ID_REF, PREDICATE_SEQUENCE_ATTR_TYPE, PREDICATE_SEQUENCE_CROSS_REFERENCES, PREDICATE_SEQUENCE_CROSS_REFERENCES_ACCESSION, PREDICATE_SEQUENCE_CROSS_REFERENCES_ACCESSION_ATTR_COMMENT, PREDICATE_SEQUENCE_CROSS_REFERENCES_ACCESSION_ATTR_SOURCE, PREDICATE_SEQUENCE_CROSS_REFERENCES_ACCESSION_VALUE, PREDICATE_SEQUENCE_GENE_NAME, PREDICATE_SEQUENCE_LOCATION, PREDICATE_SEQUENCE_MOL_SEQ, PREDICATE_SEQUENCE_MOL_SEQ_ATTR_IS_ALIGNED, PREDICATE_SEQUENCE_MOL_SEQ_VALUE, PREDICATE_SEQUENCE_NAME, PREDICATE_SEQUENCE_SYMBOL, PREDICATE_SEQUENCE_URI, PREDICATE_SEQUENCE_URI_ATTR_DESC, PREDICATE_SEQUENCE_URI_ATTR_TYPE, PREDICATE_SEQUENCE_URI_VALUE, PREDICATE_TAXONOMY, PREDICATE_TAXONOMY_AUTHORITY, PREDICATE_TAXONOMY_CODE, PREDICATE_TAXONOMY_COMMON_NAME, PREDICATE_TAXONOMY_ID, PREDICATE_TAXONOMY_ID_ATTR_PROVIDER, PREDICATE_TAXONOMY_ID_VALUE, PREDICATE_TAXONOMY_RANK, PREDICATE_TAXONOMY_SCIENTIFIC_NAME, PREDICATE_TAXONOMY_SYNONYM, PREDICATE_TAXONOMY_URI, PREDICATE_TAXONOMY_URI_ATTR_DESC, PREDICATE_TAXONOMY_URI_ATTR_TYPE, PREDICATE_TAXONOMY_URI_VALUE, PREDICATE_WIDTH, TAG_ABSENT, TAG_ACCESSION, TAG_ALPHA, TAG_ALT, TAG_ANNOTATION, TAG_AUTHORITY, TAG_BC, TAG_BINARY_CHARACTERS, TAG_BLUE, TAG_BRANCH_COLOR, TAG_BRANCH_LENGTH, TAG_BRANCH_WIDTH, TAG_CLADE, TAG_CLADE_RELATION, TAG_CODE, TAG_COMMON_NAME, TAG_CONFIDENCE, TAG_CROSS_REFERENCES, TAG_DATE, TAG_DESC, TAG_DESCRIPTION, TAG_DISTRIBUTION, TAG_DOMAIN, TAG_DOMAIN_ARCHITECTURE, TAG_DUPLICATIONS, TAG_EVENTS, TAG_GAINED, TAG_GENE_NAME, TAG_GREEN, TAG_ID, TAG_LAT, TAG_LOCATION, TAG_LONG, TAG_LOSSES, TAG_LOST, TAG_MAXIMUM, TAG_MINIMUM, TAG_MOL_SEQ, TAG_NAME, TAG_NODE_ID, TAG_PHYLOGENY, TAG_POINT, TAG_POLYGON, TAG_PRESENT, TAG_PROPERTY, TAG_RANK, TAG_RED, TAG_REFERENCE, TAG_ROOT, TAG_SCI_NAME, TAG_SEQUENCE, TAG_SEQUENCE_RELATION, TAG_SPECIATIONS, TAG_SYMBOL, TAG_SYNONYM, TAG_TAXONOMY, TAG_TYPE, TAG_URI, TAG_VALUE, TYPE_NETWORK_EDGE`

    - ### Fields inherited from interface info.bioinfweb.jphyloio.formats.phyloxml.PhyloXMLPrivateConstants

      `IDENTIFIER_ANY_PREDICATE, IDENTIFIER_CUSTOM_XML, IDENTIFIER_EDGE, IDENTIFIER_NODE, IDENTIFIER_PHYLOGENY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PhyloXMLEventWriter()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected PhyloXMLWriterStreamDataProvider` | `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()`
    `java.lang.String` | `getFormatID()` Returns a string ID uniquely identifying the target format of this instance.

    - ### Methods inherited from class info.bioinfweb.jphyloio.formats.xml.AbstractXMLEventWriter

      `createMetaXMLEventWriter, createMetaXMLStreamWriter, doWriteDocument, getDocument, getLogger, getNamespaceContext, getParameters, getXMLWriter`

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

    - ### Methods inherited from interface info.bioinfweb.jphyloio.JPhyloIOEventWriter

      `writeDocument, writeDocument, writeDocument`

- - ### Constructor Detail

    - #### PhyloXMLEventWriter

          public PhyloXMLEventWriter()

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

    - #### doWriteDocument

          protected void doWriteDocument()
                                  throws java.io.IOException,
                                         javax.xml.stream.XMLStreamException

      Specified by:
        `doWriteDocument` in class `AbstractXMLEventWriter<PhyloXMLWriterStreamDataProvider>`
      Throws:
        `java.io.IOException`
        `javax.xml.stream.XMLStreamException`