The layout. More...

#include <hibf/layout/layout.hpp>

Classes
struct	diagnostic
	A finding of seqan::hibf::layout::layout::validate. More...

struct	max_bin

struct	user_bin

Public Member Functions
void	clear ()

size_t	number_of_levels () const
	Returns the number of levels of the described HIBF.

bool	operator== (layout const &) const =default

void	read_from (std::istream &stream)

void	write_to (std::ostream &stream) const

Public Attributes
std::vector< max_bin >	max_bins {}

size_t	top_level_max_bin_id {}

std::vector< user_bin >	user_bins {}

Validation
using	diagnostic_handler = std::function<void(diagnostic const &)>
	Receives the findings of seqan::hibf::layout::layout::validate.

bool	validate (config const &config, diagnostic_handler const &handler=throw_on_error) const
	Checks whether the layout describes a consistent HIBF for the given configuration.

static void	throw_on_error (diagnostic const &finding)
	The default diagnostic handler of seqan::hibf::layout::layout::validate.

Detailed Description

The layout.

Member Typedef Documentation

◆ diagnostic_handler

using seqan::hibf::layout::layout::diagnostic_handler = std::function<void(diagnostic const &)>

Receives the findings of seqan::hibf::layout::layout::validate.

The handler is called once per finding, in the order the checks run. Checking stops at the first error, so a handler receives at most one error, and warnings and notes only if there is no error. A handler may throw to abort the check; the layout is not modified.

seqan::hibf::layout::layout::validate uses seqan::hibf::layout::layout::throw_on_error by default. With an empty handler, it reports nothing and only returns whether the layout is valid.

seqan::hibf::layout::layout::throw_on_error only uses seqan::hibf::layout::layout::diagnostic::level and seqan::hibf::layout::layout::diagnostic::message. The other members are meant for user-defined handlers, for example, to filter by seqan::hibf::layout::layout::diagnostic::code or to locate the affected IBF.

Custom handlers

Collect all findings:

    std::vector<diagnostic> diagnostics{};
    bool const valid = layout.validate(config,
                                       [&diagnostics](diagnostic const & finding)
                                       {
                                           diagnostics.push_back(finding);
                                       });
    std::cout << "valid: " << valid << ", findings: " << diagnostics.size() << '\n'; // valid: 1, findings: 2

Print all findings:

    auto print = [](diagnostic const & finding)
    {
        std::cout << finding << '\n'; // [HIBF LAYOUT <SEVERITY>] <message>
    };
    if (layout.validate(config, print))
        std::cout << "valid\n";

Ignore a kind of finding:

    auto ignore_empty_technical_bins = [](diagnostic const & finding)
    {
        if (finding.what != diagnostic::code::empty_technical_bins)
            std::cout << finding << '\n';
    };
    if (layout.validate(config, ignore_empty_technical_bins))
        std::cout << "valid\n";

Treat warnings as errors:

    auto warnings_as_errors = [](diagnostic const & finding)
    {
        if (finding.level >= diagnostic::severity::warning)
            throw std::invalid_argument{finding.message};
    };
 
    try
    {
        if (layout.validate(config, warnings_as_errors))
            std::cout << "valid\n";
    }
    catch (std::invalid_argument const & exception)
    {
        std::cout << "rejected: " << exception.what() << '\n';
    }

Locate the affected IBF, user bin and technical bin:

    auto locate = [](diagnostic const & finding)
    {
        std::cout << "IBF:";
        if (!finding.ibf.has_value())
            std::cout << " none"; // the finding concerns no particular IBF
        else if (finding.ibf->empty())
            std::cout << " Root-IBF";
        else
            for (size_t const technical_bin : *finding.ibf) // the merged bins on the path to the IBF
                std::cout << ' ' << technical_bin;
        if (finding.user_bin.has_value())
            std::cout << ", user bin: " << *finding.user_bin;
        if (finding.technical_bin.has_value())
            std::cout << ", technical bin: " << *finding.technical_bin;
        std::cout << '\n';
    };
    if (layout.validate(config, locate))
        std::cout << "valid\n";

Member Function Documentation

◆ number_of_levels()

size_t seqan::hibf::layout::layout::number_of_levels ( ) const

Returns the number of levels of the described HIBF.

Returns: 0 if there are no user bins, 1 if there is only the top-level IBF, and so on.

Only the user bins are considered.

◆ throw_on_error()

static void seqan::hibf::layout::layout::throw_on_error ( diagnostic const & finding )

static

The default diagnostic handler of seqan::hibf::layout::layout::validate.

Parameters

[in] finding The finding to handle.

Exceptions

std::invalid_argument if finding is an error. The description is std::format("{}", finding).

Prints warnings to std::cerr. Prints notes to std::cerr in debug builds of the library (without NDEBUG).

◆ validate()

bool seqan::hibf::layout::layout::validate	(	config const &	config,
		diagnostic_handler const &	handler = throw_on_error ) const

Checks whether the layout describes a consistent HIBF for the given configuration.

Parameters

[in]	config	The configuration the layout was or will be used with.
[in]	handler	Called for each finding. May be empty.

Returns: true if there is no error, false otherwise.

Exceptions

std::invalid_argument describing the first error, if handler is the default, seqan::hibf::layout::layout::throw_on_error.

The layout must contain each user bin index in [0, config.number_of_user_bins) exactly once. The user bins may be in any order.

The errors are checked first, roughly in the order of seqan::hibf::layout::layout::diagnostic::code. Checking stops at the first error. Warnings and notes are only reported if there is no error. They are reported per IBF, so a note about one IBF may precede a warning about another IBF. The build rounds the technical bins of each IBF, plus the empty bins for config.empty_bin_fraction, up to a multiple of 64. This number is compared to config.tmax, unless config.tmax is 0. The technical bins after the last used technical bin must be exactly the empty bins config.empty_bin_fraction implies, i.e., none if it is 0.

Example

    try
    {
        layout.validate(seqan::hibf::config{.number_of_user_bins = 4u}); // user bin 3 is missing
    }
    catch (std::invalid_argument const & exception)
    {
        std::cout << exception.what() << '\n';
    }

The documentation for this struct was generated from the following file:

layout.hpp

Classes

Public Member Functions

Public Attributes

Validation