A toolkit for working with phylogenetic data.
v0.18.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
JplaceReader Class Reference

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

Detailed Description

Read Jplace data.

This class provides facilities for reading Jplace files. It supports to read

Exemplary usage:

std::string infile = "path/to/file.jplace";
Sample smp = JplaceReader()
    .invalid_number_behaviour( InvalidNumberBehaviour::kCorrect )
    .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

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

Definition at line 90 of file jplace_reader.hpp.

Public Member Functions

 JplaceReader ()=default
 
 JplaceReader (JplaceReader const &)=default
 
 JplaceReader (JplaceReader &&)=default
 
 ~JplaceReader ()=default
 
Sample from_document (utils::JsonDocument &doc) const
 Take a JsonDocument and parse it as a Jplace document into a Sample. More...
 
Sample from_file (std::string const &fn) const
 Read a file and parse it as a Jplace document into a Sample. More...
 
SampleSet from_files (std::vector< std::string > const &fns) const
 Read a list of files and parse them as a Jplace document into a SampleSet. More...
 
void from_files (std::vector< std::string > const &fns, SampleSet &set) const
 Read a list of files and parse them as a Jplace document into a SampleSet. More...
 
Sample from_stream (std::istream &is) const
 Read jplace data from a stream into a Sample. More...
 
Sample from_string (std::string const &jplace) const
 Parse a string as a Jplace document into a Sample. More...
 
SampleSet from_strings (std::vector< std::string > const &jps) const
 Parse a list of strings as a Jplace document into a SampleSet. More...
 
void from_strings (std::vector< std::string > const &jps, SampleSet &set) const
 Parse a list of strings as a Jplace document into a SampleSet. More...
 
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
 

Static Public Member Functions

static bool check_version (size_t version)
 Checks whether the version of the jplace format works with this parser. More...
 
static bool check_version (std::string const &version)
 Checks whether the version of the jplace format works with this parser. More...
 
static std::string version ()
 Returns the version number that this class is written for. Currently, this is "3". More...
 

Public Types

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

Constructor & Destructor Documentation

JplaceReader ( )
default
~JplaceReader ( )
default
JplaceReader ( JplaceReader const &  )
default
JplaceReader ( JplaceReader &&  )
default

Member Function Documentation

bool check_version ( size_t  version)
static

Checks whether the version of the jplace format works with this parser.

This parser is intended for jplace versions 2 and 3. If while reading a different version tag is found, the reader will trigger a warning and try to continue anyway.

Definition at line 645 of file jplace_reader.cpp.

bool check_version ( std::string const &  version)
static

Checks whether the version of the jplace format works with this parser.

This parser is intended for jplace versions 2 and 3. If while reading a different version tag is found, the reader will trigger a warning and try to continue anyway.

Definition at line 650 of file jplace_reader.cpp.

Sample from_document ( utils::JsonDocument doc) const

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

Definition at line 106 of file jplace_reader.cpp.

Sample from_file ( std::string const &  fn) const

Read a file and parse it as a Jplace document into a Sample.

Definition at line 86 of file jplace_reader.cpp.

SampleSet from_files ( std::vector< std::string > const &  fns) const

Read a list of files and parse them as a Jplace document into a SampleSet.

Definition at line 128 of file jplace_reader.cpp.

void from_files ( std::vector< std::string > const &  fns,
SampleSet set 
) const

Read a list of files and parse them as a Jplace document into a SampleSet.

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

Definition at line 150 of file jplace_reader.cpp.

Sample from_stream ( std::istream &  is) const

Read jplace data from a stream into a Sample.

Definition at line 76 of file jplace_reader.cpp.

Sample from_string ( std::string const &  jplace) const

Parse a string as a Jplace document into a Sample.

Definition at line 96 of file jplace_reader.cpp.

SampleSet from_strings ( std::vector< std::string > const &  jps) const

Parse a list of strings as a Jplace document into a SampleSet.

Definition at line 139 of file jplace_reader.cpp.

void from_strings ( std::vector< std::string > const &  jps,
SampleSet set 
) const

Parse a list of strings as a Jplace document into a SampleSet.

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

Definition at line 184 of file jplace_reader.cpp.

JplaceReader::InvalidNumberBehaviour invalid_number_behaviour ( ) const

Return the currenlty set InvalidNumberBehaviour.

Definition at line 660 of file jplace_reader.cpp.

JplaceReader & invalid_number_behaviour ( InvalidNumberBehaviour  val)

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 665 of file jplace_reader.cpp.

JplaceReader& operator= ( JplaceReader const &  )
default
JplaceReader& operator= ( JplaceReader &&  )
default
std::string version ( )
static

Returns the version number that this class is written for. Currently, this is "3".

Definition at line 640 of file jplace_reader.cpp.

Member Enumeration Documentation

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.

kCorrect 

Correct 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.

kLogAndCorrect 

Combination of kLog and kCorrect.

kThrow 

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

Definition at line 245 of file jplace_reader.hpp.


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