C++ API

Note

• To include the whole library use #include <h5features.h>.

• The library is then available under the h5features namespace.

h5features::exception

class h5features::exception : public std::runtime_error

Defines an exception type to report errors from the h5features library.

Constructors

Constructs the exception with what as explanatory string

exception(const std::string &what)

exception(const char *what)

h5features::version

enum h5features::version

The different h5features format versions.

This is not the version of the h5features library but the available versions of the underlying file format.

Values:

enumerator v1_0

enumerator v1_1

enumerator v1_2

enumerator v2_0

constexpr version h5features::current_version = version::v2_0

Returns the current (latest) version.

version h5features::read_version(const hdf5::Group &group)

Look for a “version” attribute in the group and return its value.

Exceptions

• h5features::exception: If the “version” attribute is not found or is not valid.

void h5features::write_version(hdf5::Group &group, h5features::version version)

Writes the version to a HDF5 group

Writes to the “version” attribute of the group, create the attribute if non-existing, overwrite otherwise. The attribute is wrote as a string in the HDF5 file.

h5features::item

class h5features::item

Handles the features of a single item (e.g. a speech signal)

An item is made of 4 components:

• Its name,

• the features (h5features::features) consist a suite of vectors of constant dimension,

• the timestamps (h5features::times) associates a start and stop time to each features vector,

• optionnal properties (h5features::properties) attached to the features, e.g. algorithm parameters or other attributes.

  This class interfaces such an item between user code and an h5features file, supporting read and write operations.

Constructors

item(const std::string &name, const h5features::features &features, const h5features::times &times, const h5features::properties &properties = {}, bool check = true)

Instanciates an item from a name, features, times and optional properties

See

h5features::item::validate

Parameters

• name: The name of the item

• features: The item’s features

• times: The item’s timestamps

• properties: The item’s properties, if specified

• check: When true, ensures the item is valid

Exceptions

• h5features::exception: If check is true and the item is not valid

item(const std::string &name, h5features::features &&features, h5features::times &&times, h5features::properties &&properties, bool check = true)

Instanciates an item from a name, features, times and optional properties

See

h5features::item::validate

Parameters

• name: The name of the item

• features: The item’s features

• times: The item’s timestamps

• properties: The item’s properties, if specified

• check: When true, ensures the item is valid

Exceptions

• h5features::exception: If check is true and the item is not valid

Public Functions

~item() = default

Destructor.

item(const item&) = default

Copy constructor.

item(item&&) = default

Move constructor.

item &operator=(const item&) = default

Copy operator.

item &operator=(item&&) = default

Move operator.

std::size_t dim() const

Returns the dimension of the features.

std::size_t size() const noexcept

Returns the number of vectors in the features.

std::string name() const noexcept

Returns the item’s name.

bool has_properties() const noexcept

Returns true if the item has attached properties, false otherwise.

const h5features::features &features() const noexcept

Returns the item’s features.

const h5features::times &times() const noexcept

Returns the item’s timestamps.

const h5features::properties &properties() const noexcept

Returns the item’s properties.

bool operator==(const item &other) const noexcept

Returns true if the two items are equal.

bool operator!=(const item &other) const noexcept

Returns true if the two items are not equal.

void validate(bool deep = false) const

Ensures the item has a valid state.

An item is valid if an only if:

• It’s name is not empty

• It contains at least one features vector

• The features and timestamps have the same size

See

h5features::features::validate

h5features::times::validate

Parameters

• deep: When true ensure that the features and timestamps are valid as well by calling item.features().validate() and item.times().validate().

Exceptions

• h5features::exception: If the item is not valid

h5features::writer

class h5features::writer

The writer class dumps h5features::item instances to a HDF5 file.

A writer is non-copyable and is attached to an HDF5 file and a group within this file. Each item will then be written as a sub-group in this group.

Public Functions

~writer() = default

Destructor.

writer(writer&&) = default

Move constructor.

writer &operator=(writer&&) = default

Move operator.

writer(const std::string &filename, const std::string &group = "features", bool overwrite = false, bool compress = true, h5features::version version = h5features::current_version)

Instanciates a writer.

Parameters

• filename: The HDF5 file to write on

• group: The group in the file to write on

• overwrite: If true erase the file content if it is already existing. If false it will append new items to the existing group.

• compress: When true, compress the data

• version: The version of the file to write. Version 1.0 is not available to write, only read.

Exceptions

• h5features::exception: When overwrite is true, if the group already exists in the file and the version is not supported. Or if the requested version is not supported.

void write(const h5features::item &item)

Writes a h5features::item to disk.

Parameters

• item: The item to write

Exceptions

• h5features::exception: If the item name is already an existing object in the group or if the write operation failed.

template<class Iterator>
void write(Iterator &&first, Iterator &&last)

Writes a sequence of h5features::item to disk.

Parameters

• first: The begin iterator on the items to write

• last: The end iterator on the items to write

Exceptions

• h5features::exception: If one item is already an existing object in the group or if the write operation failed.

std::string filename() const

Returns the HDF5 file name.

std::string groupname() const

Returns the HDF5 group name.

h5features::version version() const

Returns the h5features format version being writen.

h5features::reader

class h5features::reader

The reader class reads h5features::item from a HDF5 file.

A reader is non-copyable and is attached to an HDF5 file and a group within this file.

Public Functions

~reader() = default

Destructor.

reader(reader&&) = default

Move constructor.

reader &operator=(reader&&) = default

Move operator.

reader(const std::string &filename, const std::string &group)

Instanciates a reader.

Parameters

• filename: The HDF5 file to read from

• group: The group with the file to read items from

Exceptions

• h5features::exception: If the file cannot be opened or if the group does not exist in the file.

std::string filename() const

Returns the name of the file being read.

std::string groupname() const

Returns the name of the group being read in the file.

h5features::version version() const

Returns the version of the h5features data in the group.

std::vector<std::string> items() const

Returns the name of stored items.

The items can be retrieved with read_all or read_item

std::vector<h5features::item> read_all(bool ignore_properties = false) const

Returns all the items stored in the file.

Parameters

• ignore_properties: When true, do not read the item’sproperties

Exceptions

• h5features::exception: If the read operation failed.

h5features::item read_item(const std::string &name, bool ignore_properties = false) const

Reads and returns a h5features::item instance.

Parameters

• name: The name of the item to read

• ignore_properties: When true, do not read the item’sproperties

Exceptions

• h5features::exception: If the name group does not exist or if the read operation failed.

h5features::item read_item(const std::string &name, double start, double stop, bool ignore_properties = false) const

Partial Read of a h5features::item

The method allows to partially load the content of an item, by specifiying the time interval [start, stop] to load.

Parameters

• name: The name of the item to read

• start: The start time to read the item from

• stop: The stop time to read the item from

• ignore_properties: When true, do not read the item’s properties

Exceptions

• h5features::exception: If the name group does not exist or if the read operation failed.

h5features::times

class h5features::times

The times class handles the timestamps of an item.

The times are expressed in second as float64 values.

Each features frame in an item is associated to a timestamp. It can have one of the two following formats:

• times::format::simple where the timestamp is a single scalar and is interpreted as the center of the frame’s time window

• times::format::interval where the timestamp is a pair (tstart, tstop) interpreted as the begin and end of the frame’s time window.

Constructors

times(const std::vector<double> &data, format times_format, bool validate = true)

Constructs a times instance from raw data.

The times are expressed in seconds as float64 values.

• If times_format == times::format::simple, the timestamps have a single dimension and each timstamp is interpreted as the center time of its associated frame. In that case data[i] is the center time of the frame i.

• If times_format == times::format::interval there is two timestamps per frame, interpreted as the (tstart, tstop) times for each frame. Here data[2*i] and data[2*i+1] are the start and stop time of the frame i respectively.

See

h5features::times::validate

Parameters

• data: The timestamps data

• times_format: The actual format of the data

• validate: When true, ensures the timestamps are valid

Exceptions

• h5features::exception: When validate is true, if the timestamps are not valid.

times(std::vector<double> &&data, format times_format, bool validate = true)

Constructs a times instance from raw data.

The times are expressed in seconds as float64 values.

• If times_format == times::format::simple, the timestamps have a single dimension and each timstamp is interpreted as the center time of its associated frame. In that case data[i] is the center time of the frame i.

• If times_format == times::format::interval there is two timestamps per frame, interpreted as the (tstart, tstop) times for each frame. Here data[2*i] and data[2*i+1] are the start and stop time of the frame i respectively.

See

h5features::times::validate

Parameters

• data: The timestamps data

• times_format: The actual format of the data

• validate: When true, ensures the timestamps are valid

Exceptions

• h5features::exception: When validate is true, if the timestamps are not valid.

Public Types

enum format

The available times formats, simple is 1d and interval is 2d.

Values:

enumerator simple

enumerator interval

Public Functions

times(const times&) = default

Copy constructor.

times(times&&) = default

Move constructor.

times &operator=(const times&) = default

Copy operator.

times &operator=(times&&) = default

Move operator.

~times() = default

Destructor.

times(const std::vector<double> &start, const std::vector<double> &stop, bool validate = true)

Contructs a times instance from start and stop timestamps.

The built times instance has the times::format::interval format

See

h5features::times::validate

Parameters

• start: The start timestamps of each frame

• stop: The stop timestamps of each frame

• validate: When true, ensures the timestamps are valid

Exceptions

• h5features::exception: If start.size() != stop.size()

• h5features::exception: When validate is true, if the timestamps are not valid.

bool operator==(const times &other) const noexcept

Returns true if the two times instances are equal.

bool operator!=(const times &other) const noexcept

Returns true if the two times instances are not equal.

std::size_t size() const noexcept

Returns the size (number of frames) of the timestamps.

std::size_t dim() const noexcept

Returns the timestamps dimension (1 or 2)

const std::vector<double> &data() const noexcept

Returns the timestamps raw data.

double start() const

Returns the first timestamp.

Exceptions

• h5features::exception: If times is empty

double stop() const

Returns the last timestamp.

Exceptions

• h5features::exception: If times is empty

void validate() const

Throws a h5features::exception if the timestamps are not valid.

The timestamps are valid if and only if:

• size() != 0

• sorted in increasing order

• when times::format::interval, we have \(tstart_i \leq tstop_i\) for each frame \(i\)

Exceptions

• h5features::exception: If the timestamps are not valid

std::pair<std::size_t, std::size_t> get_indices(double start, double stop) const

Returns the indices [i, j] of the closest timestamps to [start, stop]

This method is used by h5features::item for partial reads of features.

See

h5features::reader

Parameters

• start: The start time to get the index from

• stop: The stop time to get the index from

Exceptions

• h5features::exception: If start is greater than stop

• h5features::exception: If there is not valid indices for the requested interval

times select(const std::size_t &start, const std::size_t &stop) const

Returns a subset of those timestamps from start to stop

Parameters

• start: The first index of the returned times

• stop: The last index of the returned times

Exceptions

• h5features::exception: If start > stop or stop > size()

Public Static Functions

format get_format(const std::size_t &dim)

Returns the times format from its dimension.

h5features::features

class h5features::features

The features class stores the features vectors of a h5features::item

Each item’s timestamp is associated to a features vector of constant dimension. Features are stored as float64 values.

Constructors

features(const std::vector<double> &data, std::size_t dim, bool check = true)

Constructs a features instance from features vectors.

See

h5features::features::validate

Parameters

• data: A vector of size * dim scalars, with size frames of dim scalars each

• dim: The dimension of each frame

• check: When true, ensures the features are valid

Exceptions

• h5features::exception: If check is true and the features are not valid

features(std::vector<double> &&data, std::size_t dim, bool check = true)

Constructs a features instance from features vectors.

See

h5features::features::validate

Parameters

• data: A vector of size * dim scalars, with size frames of dim scalars each

• dim: The dimension of each frame

• check: When true, ensures the features are valid

Exceptions

• h5features::exception: If check is true and the features are not valid

Public Functions

~features() = default

Destructor.

features(const features&) = default

Copy constructor.

features(features&&) = default

Move constructor.

features &operator=(const features&) = default

Copy operator.

features &operator=(features&&) = default

Move operator.

bool operator==(const features &other) const noexcept

Returns true if the two features instances are equal.

bool operator!=(const features &other) const noexcept

Returns true if the two features instances are not equal.

std::size_t dim() const

Returns the dimension of a features vector.

std::size_t size() const noexcept

Returns the number of features vectors.

void validate() const

Throws a h5features::exception if the features are not valid.

The features are valid if and only if:

• it is non empty (at least one features vector)

• all the vectors have the same dimension

Exceptions

• h5features::exception: If the features are not valid

const std::vector<double> &data() const noexcept

Returns the features data.

The returned data is such as data[i * dim() + j] the \(j^{th}\) dimension of the \(i^{th}\) frame.

h5features::properties

class h5features::properties

Handles the properties attached to a h5features::item

Properties are a set of (name, value) pairs. It can be used to store attributes attached to features, such as generation parameters.

• A h5features::properties instance is created empty.

• A (name, value) pair is added to it with set() and accessed with get().

• The name must be a std::string.

• The value type must be one specified by properties::value_type.

Public Types

using value_type = boost::variant<boost::recursive_wrapper<properties>, bool, int, double, std::string, std::vector<int>, std::vector<double>, std::vector<std::string>>

The types a property value can take.

Its value can be a scalar (bool, int, double or std::string), a vector (of int, double or std::string) or another h5features::properties.

Public Functions

properties() = default

Constructor.

~properties() = default

Destructor.

properties(const properties&) = default

Copy constructor.

properties(properties&&) = default

Move constructor.

properties &operator=(const properties&) = default

Copy operator.

properties &operator=(properties&&) = default

Move operator.

bool operator==(const properties &other) const

Returns true if the two properties are equal.

bool operator!=(const properties &other) const

Returns true if the two properties are not equal.

std::size_t size() const

Returns the number of (name, value) pairs stored.

std::set<std::string> names() const

Returns the names of the stored properties.

bool contains(const std::string &name) const

Returns true if a value attached to name is stored, false otherwise.

void erase(const std::string &name)

Deletes the given name from the properties if present.

template<class T>
void set(const std::string &name, const T &value)

Adds a new (name, value) pair in the properties.

The added value must of one of the types specified by properties::value_type.

Parameters

• name: The name of the property

• value: The value of the property

Exceptions

• h5features::exception: If a property with the specified name already exist

template<class T>
T get(const std::string &name) const

Returns the value of a property given its name and type T

The returned value must of one of the types specified by value_type.

Parameters

• name: The name of the property to read.

Exceptions

• h5features::exception: If the property with the specified name does not exist or if the specified type T does not match the property value.

auto begin() const

Returns an iterator on the beginning of the stored properties.

auto end() const

Returns an iterator at the end of the stored properties.