info.bioinfweb.jphyloio.formats.newick

## Class NewickStringReader

- java.lang.Object
- - info.bioinfweb.jphyloio.formats.newick.NewickStringReader

- All Implemented Interfaces:
    NewickConstants, ReadWriteConstants

      public class NewickStringReader
      extends java.lang.Object
      implements ReadWriteConstants, NewickConstants

  Implementation to read Newick tree definitions to be used by `NewickEventReader` and `TreeReader`. Any whitespace, as well as comments contained in `'['` and `']'` is allowed between all tokens.

  ### Metadata from hot comments

  This reader is able to parse hot comments associated with nodes or edges as metadata as they are used in the output of TreeAnnotator or MrBayes. (See here for a definition.) The following format of hot comments is recognized by this reader:

       [&numericValue1=1.05, numericValue2 = 2.76e-5, stringValue1="12", stringValue2=ABC, arrayValue={18, "AB C"}]

  Each hot comment needs to start with an `'&'` and can contain one or more key/value pairs separated by `','`. Each value can either be a numeric value, a string value or an array value. Arrays are indicated by braces and array elements are separated by `','`, as shown in the example above. Array elements maybe any numeric or string value in any combination. Whitespace between tokens of a hot comment is allowed but not necessary.

  In addition, NHX hot comments can be read and are associated with according PhyloXML predicates, of possible. Note that the NHX key is not converted, since there is no directly equivalent PhyloXML predicate.

  Hot comments following a node name or a subtree are considered a metadata attached to a node and hot comments following a branch length definition are considered to be attached to an edge (branch). Subsequent hot comments are combined, with the exception that a branch length definition is omitted. In such a case, the first hot comment is considered to attached to the node and all subsequent hot comments are considered to be attached to the edge.

  ### Phylogenetic networks in eNewick format

  If the parameter `ReadWriteParameterNames.KEY_EXPECT_E_NEWICK` is set to `true` this reader will assume an eNewick (or extended Newick) file containing special Newick strings that define phylogenetic networks. As a consequence all trees (no matter if they really contain network edges or not) will be enclosed between events of the type `EventContentType.NETWORK` if this parameter is set to `true`. Special eNewick will be parsed and the actual label is extracted. The edge type of each edge leading to a network node will be represented by literal metadata events with the predicate `NewickConstants.PREDICATE_E_NEWICK_EDGE_TYPE` and a string value. (Possible values as defined in Cardona et al. (2008) are also declared as constants in `NewickConstants.E_NEWICK_EDGE_TYPE_HYBRIDIZATION`, `NewickConstants.E_NEWICK_EDGE_TYPE_RECOMBINATION` and `NewickConstants.E_NEWICK_EDGE_TYPE_LATERAL_GENE_TRANSFER`.)

  In the current version JPhyloIO will treat all nodes containing a '#' as eNewick labels, no matter if they are enclosed in quotations or not. Therefore it is not possible to use '#' within actual labels as long as the `ReadWriteParameterNames.KEY_EXPECT_E_NEWICK` option is activated.

  Note that additional metadata definitions separated by additional ':' as defined in the Rich Newick format used by PhyloNet are not supported, but PhyloNet allows to omit these with its "-di" option.

  Author:
    Ben Stöver

- - ### Field Summary

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

    - ### Fields inherited from interface info.bioinfweb.jphyloio.formats.newick.NewickConstants

      `ALLOCATION_SEPARATOR_SYMBOL, ALLOCATION_SYMBOL, ALTERNATIVE_NAME_DELIMITER, COMMENT_END, COMMENT_START, DATA_TYPE_NEWICK_ARRAY, E_NEWICK_EDGE_TYPE_HYBRIDIZATION, E_NEWICK_EDGE_TYPE_LATERAL_GENE_TRANSFER, E_NEWICK_EDGE_TYPE_RECOMBINATION, E_NEWICK_NAMESPACE_PREFIX, E_NEWICK_NETWORK_DATA_SEPARATOR, ELEMENT_SEPERATOR, FIELD_END_SYMBOL, FIELD_START_SYMBOL, FIELD_VALUE_SEPARATOR_SYMBOL, FREE_NAME_BLANK, HOT_COMMENT_START_SYMBOL, INDEX_END_SYMBOL, INDEX_START_SYMBOL, LENGTH_SEPERATOR, NAME_DELIMITER, NEWICK_DATA_TYPE_NAMESPACE, NEWICK_FORMAT_NAME, NEWICK_NAMESPACE_PREFIX, NHX_KEY_CONFIDENCE, NHX_KEY_EVENT, NHX_KEY_GENE_NAME, NHX_KEY_PREFIX, NHX_KEY_SCIENTIFIC_NAME, NHX_KEY_SEQUENCE_ACCESSION, NHX_KEY_TAXONOMY_ID, NHX_START, NHX_VALUE_SEPARATOR_SYMBOL, PREDICATE_E_NEWICK_EDGE_TYPE, ROOTED_HOT_COMMENT, SUBTREE_END, SUBTREE_START, TERMINAL_SYMBOL, UNROOTED_HOT_COMMENT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NewickStringReader(TextReaderStreamDataProvider<?> streamDataProvider, java.lang.String treeID, java.lang.String treeLabel, NewickReaderNodeLabelProcessor nodeLabelProcessor, boolean expectENewick)` Creates a new instance of this class.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addNextEvents()` Creates the next JPhyloIO event(s) from the Newick string provided by the underlying reader.

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

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

- - ### Constructor Detail

    - #### NewickStringReader

          public NewickStringReader(TextReaderStreamDataProvider<?> streamDataProvider,
                                    java.lang.String treeID,
                                    java.lang.String treeLabel,
                                    NewickReaderNodeLabelProcessor nodeLabelProcessor,
                                    boolean expectENewick)

      Creates a new instance of this class.
      Parameters:
        `streamDataProvider` - the stream data provider that allows this reader to access the necessary event reader properties
        `treeLabel` - the label of the tree to be read (This parameter also determines whether one or more trees shall be read from the underlying reader. If a string is specified, only one tree is read and the specified label is used for it. If `null` is specified, multiple trees are read until the end of the file is reached. None of them gets a defined label.)
        `nodeLabelProcessor` - the node label processor to be used to possibly translate node labels in Newick strings
      Throws:
        `java.lang.NullPointerException` - if `streamDataProvider` or `nodeLabelProcessor` are `null`

  - ### Method Detail

    - #### addNextEvents

          public boolean addNextEvents()
                                throws java.io.IOException

      Creates the next JPhyloIO event(s) from the Newick string provided by the underlying reader.
      Returns:
        `true` if more events were add to the queue or `false` if reading of the current tree(s) is finished.
      Throws:
        `java.io.IOException`