SyntaxComplexityMeanDependencyLengthExtractor#

Defined in: voxatlas.features.syntax.complexity.mean_dependency_length

class voxatlas.features.syntax.complexity.mean_dependency_length.SyntaxComplexityMeanDependencyLengthExtractor[source]#

Bases: BaseExtractor

Extract the syntax.complexity.mean_dependency_length feature within the VoxAtlas pipeline.

This public extractor defines the reusable API for computing syntax.complexity.mean_dependency_length from VoxAtlas structured inputs. It consumes sentence units and produces values aligned to sentence units, making the extractor a stable pipeline node that can be cited independently of the surrounding execution machinery.

Algorithm#

The extractor converts token-level dependency annotations into sentence-level structural complexity statistics.

  1. Sentence partitioning The dependency table is split by sentence so each statistic is computed on a well-defined local parse.

  2. Tree construction VoxAtlas reconstructs a dependency tree rooted at the sentence head.

  3. Complexity computation Mean dependency length is computed as \(\mathrm{MDL} = \frac{1}{N}\sum_i |h_i - i|\) within each sentence.

  4. Packaging One scalar is returned per sentence, aligned to the sentence identifiers used elsewhere in the pipeline.

Notes

This extractor declares the upstream dependencies [‘syntax.dependencies’] and is executed only after those features are available in the pipeline feature store.

Examples

>>> import pandas as pd
>>> from voxatlas.features.feature_input import FeatureInput
>>> from voxatlas.features.feature_output import TableFeatureOutput
>>> from voxatlas.features.syntax.complexity.mean_dependency_length import SyntaxComplexityMeanDependencyLengthExtractor
>>> from voxatlas.pipeline.feature_store import FeatureStore
>>> deps = pd.DataFrame({"token_id": [1, 2], "head_id": [2, 0], "dep_label": ["nsubj", "root"], "sentence_id": [0, 0]})
>>> store = FeatureStore()
>>> store.add("syntax.dependencies", TableFeatureOutput(feature="syntax.dependencies", unit="token", values=deps))
>>> out = SyntaxComplexityMeanDependencyLengthExtractor().compute(FeatureInput(audio=None, units=None, context={"feature_store": store}), {})
>>> float(out.values.loc[0])
1.0
name: str = 'syntax.complexity.mean_dependency_length'#
input_units: str | None = 'sentence'#
output_units: str | None = 'sentence'#
dependencies: list[str] = ['syntax.dependencies']#
default_config: dict = {}#
compute(feature_input, params)[source]#

Compute the extractor output for a single pipeline invocation.

This method is the reusable execution entry point for the extractor. It receives the standard FeatureInput bundle, applies the configured algorithm, and returns feature values aligned to the extractor output units for storage in the pipeline feature store.

Parameters:

  • feature_input (object) – Structured extractor input bundling audio, hierarchical units, and execution context for this feature computation.

  • params (object) – Resolved feature configuration for this invocation. Keys are feature-specific and merged from defaults and pipeline settings.

Returns:

Structured output aligned to the sentence unit level when applicable.

Return type:

FeatureOutput

Examples

>>> import pandas as pd
>>> from voxatlas.features.feature_input import FeatureInput
>>> from voxatlas.features.feature_output import TableFeatureOutput
>>> from voxatlas.features.syntax.complexity.mean_dependency_length import SyntaxComplexityMeanDependencyLengthExtractor
>>> from voxatlas.pipeline.feature_store import FeatureStore
>>> deps = pd.DataFrame({"token_id": [1], "head_id": [0], "dep_label": ["root"], "sentence_id": [0]})
>>> store = FeatureStore()
>>> store.add("syntax.dependencies", TableFeatureOutput(feature="syntax.dependencies", unit="token", values=deps))
>>> result = SyntaxComplexityMeanDependencyLengthExtractor().compute(FeatureInput(audio=None, units=None, context={"feature_store": store}), {})
>>> result.unit
'sentence'