Manages the metrics calculations. More...

#include <hart_metric_query.hpp>

Public Types
using	SingleChannelMetricEvaluator = std::function< ValueType(size_t channel, Slice slice, Unit requestedUnit)>
	A lambda function (or a callable object) that calculates a specific metric for a given channel.

using	ChannelPairMetricEvaluator = std::function< ValueType(size_t channelA, size_t channelB, Slice slice, Unit requestedUnit)>
	A lambda function (or a callable object) that calculates a specific metric for a given pair of channels.

Public Member Functions
	MetricQuery (SingleChannelMetricEvaluator evaluator, size_t totalNumChannels, std::vector< size_t > &&defaultChannelsToProcess)
	Create a metric query object for a metric that operates on one channel at a time.

	MetricQuery (ChannelPairMetricEvaluator evaluator, size_t totalNumChannelsA, size_t totalNumChannelsB, std::vector< std::pair< size_t, size_t > > &&defaultChannelPairsToProcess)
	Create a metric query object for a metric that operates on pair of channels at a time.

MetricQuery	as (Unit requestedUnit) const
	Requests the metric to return its value(s) in a certain unit.

MetricQuery	ch (size_t channel) const
	Requests the metric to be applied to certain channel.

MetricQuery	ch (std::initializer_list< size_t > channels) const
	Requests the metric to be applied to certain channels.

MetricQuery	ch (std::initializer_list< std::pair< size_t, size_t > > channels) const
	Requests the metric to be applied to certain channel pairs.

MetricQuery	ch (const ChannelFlags &channelFlags) const
	Requests the metric to be applied to certain channels.

MetricQuery	at (Slice slice) const
	Requests to perform a metric on a specific range inside of data.

template<typename ReducerType >
auto	get (ReducerType reducer) const -> ReducerResultType< ReducerType, typename std::vector< ValueType >::const_iterator >
	Query a value of a calculated metric using a reducer.

ValueType	get () const
	Query a value of a calculated metric.

	operator ValueType () const
	Query a value of a calculated metric.

Detailed Description

template<typename ValueType>
class hart::MetricQuery< ValueType >

Manages the metrics calculations.

This object is meant to be created by metric functions, see Metrics. Usage examples:

const double resultA = samplePeak (monoBuffer);  // Default unit, implicit cast to double
const double resultB = samplePeak (monoBuffer).get();  // Default unit, explicit getter
const double resultC = samplePeak (monoBuffer).as (dB);  // Request to calculate in dB
const double resultD = samplePeak (monoBuffer).as (linear);  // Request to calculate in linear domain (as voltage, not dB)
const double resultE = samplePeak (monoBuffer).as (native);  // Request to calculate in metric's native unit
const double resultF = samplePeak (monoBuffer).slice (100, 200).get();  // Peak, observed between 100th (inclusive) and 200th (non-inclusive) frames
const double resultG = samplePeak (multiChannelBuffer).as (dB).get (max());  // Get peak of the loudest channel, in dB
const double resultH = samplePeak (multiChannelBuffer).as (linear).get (nth (4));  // Get peak of the 4th channel (zero-based), as a linear value
const double resultI = samplePeak (multiChannelBuffer).ch ({3, 0, 5}).get (max ());  // Peak, calculated only for channels 3, 0 and 5, max value (requested order of channels will be preserved for order-sensitive reducers)
const size_t resultJ = samplePeak (multiChannelBuffer).get (argmax());  // Get the index of the loudest channel
const vector<double> resultK = samplePeak (multiChannelBuffer).as (dB).get (collect());  // Get vector of per-channel peak values in dB

For a more detailed "how-to", see Using Metrics And Reducers.

If you create your own metric functions, it's strongly encouraged for them to return this class instance, rather that just a POD value, as this class handles multi-channel setups, slices etc.

Definition at line 42 of file hart_metric_query.hpp.

Member Typedef Documentation

◆ SingleChannelMetricEvaluator

template<typename ValueType >

using SingleChannelMetricEvaluator = std::function<ValueType (size_t channel, Slice slice, Unit requestedUnit)>

A lambda function (or a callable object) that calculates a specific metric for a given channel.

Arguments:

channel - number of channel to calculate metric (for metrics that operate per channel), see ch()
sliceStart, sliceStop - the range of data to calculate the metric on, see slice()
requestedUnit - the unit that the metric should be calculated in, see as()

Definition at line 50 of file hart_metric_query.hpp.

◆ ChannelPairMetricEvaluator

template<typename ValueType >

using ChannelPairMetricEvaluator = std::function<ValueType (size_t channelA, size_t channelB, Slice slice, Unit requestedUnit)>

A lambda function (or a callable object) that calculates a specific metric for a given pair of channels.

Arguments:

channelA - number of left-hand-side channel to calculate metric (for metrics that operate per channel), see ch()
channelB - number of right-hand-side channel to calculate metric (for metrics that operate per channel), see ch()
sliceStart, sliceStop - the range of data to calculate the metric on, see slice()
requestedUnit - the unit that the metric should be calculated in, see as()

Definition at line 58 of file hart_metric_query.hpp.

Constructor & Destructor Documentation

◆ MetricQuery() [1/2]

template<typename ValueType >

MetricQuery	(	SingleChannelMetricEvaluator	evaluator,
		size_t	totalNumChannels,
		std::vector< size_t > &&	defaultChannelsToProcess
	)

inline

Create a metric query object for a metric that operates on one channel at a time.

This ctor in meant to be invoked by the metric functions, as they return an object of this type.

Parameters

evaluator	A callable object that calculates a specific metric, created by the metric function
totalNumChannels	Total number of channels in the received AudioBuffer or other container, observed by the metric function
totalLength	Total length of the container (for one channel) passed to the metric function, observed by the metric function. For instance, number of frames in an AudioBuffer, or number of bins in a Spectrum, per one channel.
defaultChannelsToProcess	Subset of channels to process by default, if `ch()` wasn't called.

Definition at line 68 of file hart_metric_query.hpp.

◆ MetricQuery() [2/2]

template<typename ValueType >

MetricQuery	(	ChannelPairMetricEvaluator	evaluator,
		size_t	totalNumChannelsA,
		size_t	totalNumChannelsB,
		std::vector< std::pair< size_t, size_t > > &&	defaultChannelPairsToProcess
	)

inline

Create a metric query object for a metric that operates on pair of channels at a time.

This ctor in meant to be invoked by the metric functions, as they return an object of this type.

Parameters

evaluator	A callable object that calculates a specific metric, created by the metric function
totalNumChannelsA	Total number of channels in the received left-hand-side AudioBuffer or other container, observed by the metric function
totalNumChannelsB	Total number of channels in the received right-hand-side AudioBuffer or other container, observed by the metric function. If metric requires pairs of channels, but operates on a single container, it's expected to be equal to totalNumChannelsA.
totalLength	Total length of the container (for one channel) passed to the metric function, observed by the metric function. For instance, number of frames in an AudioBuffer, or number of bins in a Spectrum, per one channel. Left-hand-side and right-hand-side containers are typically expected to be equal in size (per each channel).
defaultChannelPairsToProcess	Subset of channel pairs to process by default, if `ch()` wasn't called.

Definition at line 94 of file hart_metric_query.hpp.

Member Function Documentation

◆ as()

template<typename ValueType >

MetricQuery as ( Unit requestedUnit ) const

inline

Requests the metric to return its value(s) in a certain unit.

Parameters

requestedUnit A desired unit that the metric should return. Refer to the documentation of a specific metric for supported units. If unsupported unit is requested, the metric is expected to throw a hart::UnitError exception.

Definition at line 115 of file hart_metric_query.hpp.

◆ ch() [1/4]

template<typename ValueType >

MetricQuery ch ( size_t channel ) const

inline

Requests the metric to be applied to certain channel.

If this method is not called, the channel subset will be defined by a specific metric.

Parameters

channel Zero-based channel index to measure. You may use values from hart::Channel or hart::MidSideChannel where appropriate.

Definition at line 129 of file hart_metric_query.hpp.

◆ ch() [2/4]

template<typename ValueType >

MetricQuery ch ( std::initializer_list< size_t > channels ) const

inline

Requests the metric to be applied to certain channels.

If this method is not called, the channel subset will be defined by a specific metric.

Parameters

channels List of zero-based channel indices to measure. You may use values from hart::Channel or hart::MidSideChannel where appropriate. The order of values handed to the reducer matches the order of channel indices in channels.

Definition at line 155 of file hart_metric_query.hpp.

◆ ch() [3/4]

template<typename ValueType >

MetricQuery ch ( std::initializer_list< std::pair< size_t, size_t > > channels ) const

inline

Requests the metric to be applied to certain channel pairs.

If this method is not called, the channel pair subset will be defined by a specific metric.

Parameters

channels List of pairs of zero-based channel indices to measure. You may use values from hart::Channel or hart::MidSideChannel wherever appropriate. The order of values handed to the reducer matches the order of channel indices in channels.

Definition at line 185 of file hart_metric_query.hpp.

◆ ch() [4/4]

template<typename ValueType >

MetricQuery ch ( const ChannelFlags & channelFlags ) const

inline

Requests the metric to be applied to certain channels.

This method is meant to be called by the matchers, as the selected channels are stored in a ChannelFrags object.

Parameters

channelFlags set of per-channel flags. Channels marked as true will be included, ones marked as false will be skipped.

Definition at line 204 of file hart_metric_query.hpp.

◆ at()

template<typename ValueType >

MetricQuery at ( Slice slice ) const

inline

Requests to perform a metric on a specific range inside of data.

Parameters

slice Slice representing a range of data, see hart::Slice

Exceptions

hart::SizeError If the the slice is empty

Definition at line 234 of file hart_metric_query.hpp.

◆ get() [1/2]

template<typename ValueType >

template<typename ReducerType >

auto get ( ReducerType reducer ) const -> ReducerResultType<ReducerType, typename std::vector<ValueType>::const_iterator>

inline

Query a value of a calculated metric using a reducer.

Typically, metrics are calculated per channel, which result in a vector of per-channel values. And in most cases, you just want one scalar, like a max, min, mean etc. You can choose how to reduce a vector to one scalar, by providing a reducer. There's a good chance one the built-in reducers will do what you're looking for, see Reducers. Reducer can also be a lambda or a callable object. Reducers usually return just one scalar value, but not always - for example, hart::collect() will just forward the per-channel vector of values.

Parameters

reducer Callable reducer that accepts two iterators over per-channel metric values

Definition at line 258 of file hart_metric_query.hpp.

◆ get() [2/2]

template<typename ValueType >

ValueType get ( ) const

inline

Query a value of a calculated metric.

This overload is useful for mono signals, or metrics that calculate a scalar value, rather than calculating a per-channel vector of values. For metrics that are calculated per channel, use an overload of this method that takes a reducer callable.

Definition at line 270 of file hart_metric_query.hpp.

◆ operator ValueType()

template<typename ValueType >

operator ValueType ( ) const

inline

Query a value of a calculated metric.

This cast is useful for mono signals, or metrics that calculate a scalar value, rather than calculating a per-channel vector of values. For metrics that are calculated per channel, use an overload of this method that takes a reducer callable.

Definition at line 280 of file hart_metric_query.hpp.

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

include/metrics/hart_metric_query.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ SingleChannelMetricEvaluator

◆ ChannelPairMetricEvaluator

Constructor & Destructor Documentation

◆ MetricQuery() [1/2]

◆ MetricQuery() [2/2]

Member Function Documentation

◆ as()

◆ ch() [1/4]

◆ ch() [2/4]

◆ ch() [3/4]

◆ ch() [4/4]

◆ at()

◆ get() [1/2]

◆ get() [2/2]

◆ operator ValueType()