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 &&)=default
	JplaceReader (JplaceReader const &)=default
	~JplaceReader ()=default
InvalidNumberBehaviour	invalid_number_behaviour () const
	Return the currenlty set InvalidNumberBehaviour. More...
JplaceReader &	invalid_number_behaviour (InvalidNumberBehaviour val)
	Set the InvalidNumberBehaviour. More...
JplaceReader &	operator= (JplaceReader &&)=default
JplaceReader &	operator= (JplaceReader const &)=default
Sample	read (std::shared_ptr< utils::BaseInputSource > source) const
	Read from an input source. 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...
Sample	read (utils::JsonDocument &doc) const
	Take a JsonDocument and parse it as a Jplace document into a Sample. 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 &&  )

default

operator=() [2/2]

JplaceReader& operator= ( JplaceReader const &  )

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]

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() [3/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.

read() [4/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.

Member Enumeration Documentation

InvalidNumberBehaviour

enum InvalidNumberBehaviour

strong

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:

• jplace_reader.hpp
• jplace_reader.cpp