HilbertPeakRate#

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

class voxatlas.features.acoustic.envelope.peak_rate.HilbertPeakRate#

Bases: BaseExtractor

Extract a frame-level peak-rate contour from an upstream envelope representation.

This public extractor measures how densely sharp positive envelope changes occur over time. Within the VoxAtlas feature graph it is a reusable event-density representation derived from a dependency contour such as RMS, log energy, Hilbert envelope, or Praat intensity.

Algorithm#

The peak-rate computation proceeds in three explicit stages.

  1. Differencing The upstream contour \(x_t\) is converted to a derivative

    \[d_t = x_t - x_{t-1}.\]

  2. Peak detection Local maxima of \(d_t\) are retained only when they exceed the configured threshold \(\theta\). These accepted peaks form the event set \(P\).

  3. Rate encoding The returned contour is an impulse-like rate series

    \[y_t = f_{\mathrm{frame}}\mathbf{1}[t \in P],\]

    where \(f_{\mathrm{frame}}\) is the effective frame sampling rate inferred from the dependency time axis.

Notes

This extractor depends on a single upstream envelope contour and returns a VectorFeatureOutput aligned to frame units.

name#

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

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

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.peak_rate import OganianPeakRate 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 = OganianPeakRate() 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.peak_rate'#
output_units: str | None = 'frame'#