C++ API

Note

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

  • The library is then available under the h5features namespace.

h5features::exception

class exception : public std::runtime_error

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

Public Functions

template<typename String>
inline explicit exception(String &&what)

Constructs the exception with what as explanatory string.

h5features::version

enum class 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.

Throws:

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 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,

  • optional 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)

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

See also

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

Throws:

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)

Public Functions

virtual ~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 also

h5features::features::validate

See also

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().

Throws:

h5features::exception – If the item is not valid

h5features::writer

class 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

virtual ~writer() = default

Destructor.

writer(writer&&) = default

Move constructor.

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

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

Throws:

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

Throws:

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

template<class Iterator>
inline 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

Throws:

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

h5features::reader

class 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

virtual ~reader() = default

Destructor.

reader(reader&&) = default

Move constructor.

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

Instantiates a reader.

Parameters:

  • filename – The HDF5 file to read from

  • group – The group within the file to read items from

Throws:

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

Throws:

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

Throws:

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 specifying 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

Throws:

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

Public Static Functions

static std::vector<std::string> list_groups(const std::string &filename)

Returns the list of groups in the specified HDF5 file.

Parameters:

filename – The HDF5 file to list the groups from

Throws:

h5features::exception – If the file cannot be opened

h5features::times

class 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 timestamp 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 also

h5features::times::validate

Parameters:

  • data – The timestamps data

  • times_format – The actual format of the data

  • validate – When true, ensures the timestamps are valid

Throws:

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

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

Public Types

enum class 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.

virtual ~times() = default

Destructor.

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

Constructs a times instance from start and stop timestamps.

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

See also

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

Throws:

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

Throws:

h5features::exception – If times is empty

double stop() const

Returns the last timestamp.

Throws:

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 \((t_\text{start})_i \leq (t_\text{stop})_i\) for each frame \(i\)

Throws:

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 also

h5features::reader

Parameters:

  • start – The start time to get the index from

  • stop – The stop time to get the index from

Throws:

  • 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

Throws:

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

Public Static Functions

static format get_format(const std::size_t &dim)

Returns the times format from its dimension.

h5features::features

class 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 also

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

Throws:

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

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

Public Functions

virtual ~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

Throws:

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

Public Types

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

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.

virtual ~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>
inline 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

Throws:

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

template<class T>
inline 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.

Throws:

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

inline auto begin() const

Returns an iterator on the beginning of the stored properties.

inline auto end() const

Returns an iterator at the end of the stored properties.