A toolkit for working with phylogenetic data.
v0.24.0
JplaceReader Class Reference

#include <genesis/placement/formats/jplace_reader.hpp>

Detailed Description

Read Jplace data.

This class provides facilities for reading jplace files into a Sample or SampleSet. Exemplary usage:

std::string infile = "path/to/file.jplace";
Sample smp = JplaceReader()
    .invalid_number_behaviour( InvalidNumberBehaviour::kFix )
    .read( from_file( infile ));

Using invalid_number_behaviour(), it is possible to change how the reader reacts to malformed jplace files. See InvalidNumberBehaviour for the valid options.

The Jplace format is described in the following publication:

Matsen FA, Hoffman NG, Gallagher A, Stamatakis A. 2012.
A Format for Phylogenetic Placements.
PLoS ONE 7(2): e31009. doi:10.1371/journal.pone.0031009
http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0031009

This parser is written according to the jplace standard version 3, as described in the above document, but also incorporates parsing of the previous versions 1 and 2. See http://matsen.github.io/pplacer/generated_rst/pplacer.html#json-format-specification for differences between the versions of the jplace standard.

See Sample and SampleSet for the data structures used to store the Pqueries and the reference Tree.

Definition at line 99 of file jplace_reader.hpp.

Public Member Functions

 JplaceReader ()=default
 
 JplaceReader (JplaceReader const &)=default
 
 JplaceReader (JplaceReader &&)=default
 
 ~JplaceReader ()=default
 
InvalidNumberBehaviour invalid_number_behaviour () const
 Return the currenlty set InvalidNumberBehaviour. More...
 
JplaceReaderinvalid_number_behaviour (InvalidNumberBehaviour val)
 Set the InvalidNumberBehaviour. More...
 
JplaceReaderoperator= (JplaceReader const &)=default
 
JplaceReaderoperator= (JplaceReader &&)=default
 
Sample read (std::shared_ptr< utils::BaseInputSource > source) const
 Read from an input source. More...
 
Sample read (utils::JsonDocument &doc) const
 Take a JsonDocument and parse it as a Jplace document into a Sample. More...
 
SampleSet read (std::vector< std::shared_ptr< utils::BaseInputSource >> sources) const
 Read from multiple sources and parse them as a Jplace documents into a SampleSet. More...
 
void read (std::vector< std::shared_ptr< utils::BaseInputSource >> sources, SampleSet &target) const
 Read from multiple sources and parse them as a Jplace documents into an existing SampleSet. More...
 

Public Types

enum  InvalidNumberBehaviour {
  kIgnore, kLog, kFix, kLogAndFix,
  kThrow
}
 Enum to determine the behaviour of the reader in case of invalid numbers. More...
 

Constructor & Destructor Documentation

◆ JplaceReader() [1/3]

JplaceReader ( )
default

◆ ~JplaceReader()

~JplaceReader ( )
default

◆ JplaceReader() [2/3]

JplaceReader ( JplaceReader const &  )
default

◆ JplaceReader() [3/3]

JplaceReader ( JplaceReader &&  )
default

Member Function Documentation

◆ invalid_number_behaviour() [1/2]

InvalidNumberBehaviour invalid_number_behaviour ( ) const
inline

Return the currenlty set InvalidNumberBehaviour.

Definition at line 291 of file jplace_reader.hpp.

◆ invalid_number_behaviour() [2/2]

JplaceReader& invalid_number_behaviour ( InvalidNumberBehaviour  val)
inline

Set the InvalidNumberBehaviour.

This setter controls the InvalidNumberBehaviour of the JplaceReader. The default value is InvalidNumberBehaviour::kIgnore. See InvalidNumberBehaviour for the valid options.

The function returns the JplaceReader object to allow for a fluent interface.

Definition at line 304 of file jplace_reader.hpp.

◆ operator=() [1/2]

JplaceReader& operator= ( JplaceReader const &  )
default

◆ operator=() [2/2]

JplaceReader& operator= ( JplaceReader &&  )
default

◆ read() [1/4]

Sample read ( std::shared_ptr< utils::BaseInputSource source) const

Read from an input source.

Use functions such as utils::from_file() and utils::from_string() to conveniently get an input source that can be used here.

Definition at line 74 of file jplace_reader.cpp.

◆ read() [2/4]

Sample read ( utils::JsonDocument doc) const

Take a JsonDocument and parse it as a Jplace document into a Sample.

Note that the JsonDocument is modified, in order to save memory.

Definition at line 81 of file jplace_reader.cpp.

◆ read() [3/4]

SampleSet read ( std::vector< std::shared_ptr< utils::BaseInputSource >>  sources) const

Read from multiple sources and parse them as a Jplace documents into a SampleSet.

Definition at line 116 of file jplace_reader.cpp.

◆ read() [4/4]

void read ( std::vector< std::shared_ptr< utils::BaseInputSource >>  sources,
SampleSet target 
) const

Read from multiple sources and parse them as a Jplace documents into an existing SampleSet.

The Samples are added to the SampleSet, so that existing Samples in the SampleSet are kept.

Definition at line 124 of file jplace_reader.cpp.

Member Enumeration Documentation

◆ InvalidNumberBehaviour

Enum to determine the behaviour of the reader in case of invalid numbers.

When reading from jplace files, the numerical fields of each placement can contain small deviations or inaccuracies. Those are due to numerical issues or floating point number to text conversions, which occur when storing the exact values in a textual representation.

Currently, the following checks are offered:

  • like_weight_ratio < 0.0
  • like_weight_ratio > 1.0
  • pendant_length < 0.0
  • proximal_length < 0.0
  • proximal_length > branch_length

This enum offers choices to decide how the JplaceReader reacts when facing those errors. See invalid_number_behaviour( InvalidNumberBehaviour ) to set the behaviour.

Enumerator
kIgnore 

Ignore invalid numbers.

Erroneous numbers are simply ignored, meaning, they are stored as-is in the data structure. This is the default.

kLog 

Log invalid numbers to LOG_WARN.

When encountering an erroneous number, a warning stating the error is logged. The number is stored as-is in the data structure.

kFix 

Fix invalid numbers to the next best correct number.

Erroneous numbers are silently corrected. This means, they are set to the nearest correct value. For example, a value that cannot be smaller than 0.0 will be set to 0.0.

kLogAndFix 

Combination of kLog and kFix.

kThrow 

Throw an std::runtime_error when encountering an invalid number.

Definition at line 252 of file jplace_reader.hpp.


The documentation for this class was generated from the following files: