HilbertVariability#

Defined in: voxatlas.features.acoustic.envelope.variability

class voxatlas.features.acoustic.envelope.variability.HilbertVariability#

Bases: BaseExtractor

Extract a frame-aligned variability summary from an upstream envelope contour.

This public extractor turns a dependency contour into a dispersion statistic that can be attached to every frame. In VoxAtlas terms, it makes a global summary of envelope variation available as a reusable pipeline node rather than forcing each downstream feature to recompute it.

Algorithm#

The variability computation is defined directly on the upstream contour.

  1. Dependency retrieval The base contour \(x_t\) is loaded from the feature store using the configured envelope dependency.

  2. Dispersion estimate VoxAtlas computes the population standard deviation

    \[\sigma_x = \sqrt{\frac{1}{T}\sum_{t=1}^{T}(x_t-\bar{x})^2}.\]

  3. Broadcasting and packaging The scalar value \(\sigma_x\) is repeated across the original frame grid so the feature remains directly alignable with other frame-level contours.

Notes

This extractor depends on one upstream envelope representation and returns a VectorFeatureOutput on frame units.

name#

Registry key for this extractor. This is derived from the chosen dependency and has the form "{dependency}.variability" (for example, "acoustic.envelope.oganian.variability").

Type:

str

input_units#

Required input unit level. None means this extractor does not require linguistic units and instead consumes dependency outputs from the feature store.

Type:

str | None

output_units#

Output alignment unit ("frame").

Type:

str | None

dependencies#

Exactly one upstream contour ([dependency_name]), such as "acoustic.envelope.oganian" for OganianVariability.

Type:

list[str]

default_config#

Default runtime parameters: frame_length=0.025, frame_step=0.01, peak_threshold=0.1, smoothing=1.

Type:

dict

Examples

from voxatlas.features.acoustic.envelope.variability import OganianVariability from voxatlas.features.feature_input import FeatureInput

# Assumes the upstream dependency (acoustic.envelope.oganian) # has already been computed and is available in the feature store. extractor = OganianVariability() feature_input = FeatureInput(audio=audio, units=units, context={“feature_store”: feature_store}) output = extractor.compute(feature_input, {}) print(output)

compute(feature_input, params)#

Compute the feature output for a single stream.

This method is called by the pipeline after dependency resolution has completed. It receives the prepared feature input object together with the resolved feature-specific configuration.

Parameters:

  • feature_input (FeatureInput) – Container with audio, unit tables, and pipeline context.

  • params (dict) – Resolved configuration dictionary for the extractor.

Returns:

Structured VoxAtlas feature output.

Return type:

object

Raises:

ValueError – Raised when required inputs are unavailable for the feature.

Notes

Implementations should remain side-effect free and should read dependency outputs from feature_input.context['feature_store'] when needed.

Examples

Usage example:

extractor = type(self)()
output = extractor.compute(feature_input, params)
print(output)
default_config: dict = {'frame_length': 0.025, 'frame_step': 0.01, 'peak_threshold': 0.1, 'smoothing': 1}#
dependencies: list[str] = ['acoustic.envelope.hilbert']#
input_units: str | None = None#
name: str = 'acoustic.envelope.hilbert.variability'#
output_units: str | None = 'frame'#