mt_metadata.features.weights

Submodules

• mt_metadata.features.weights.activation_monotonic_weight_kernel
• mt_metadata.features.weights.base
• mt_metadata.features.weights.channel_weight_spec
• mt_metadata.features.weights.feature_weight_spec
• mt_metadata.features.weights.monotonic_weight_kernel
• mt_metadata.features.weights.taper_monotonic_weight_kernel
• mt_metadata.features.weights.taper_weight_kernel
• mt_metadata.features.weights.threshold_weight_kernel

Classes

ChannelWeightSpec	Base class for all metadata objects with Pydantic validation.
Base	Base class for all metadata objects with Pydantic validation.
MonotonicWeightKernel	MonotonicWeightKernel
TaperMonotonicWeightKernel	MonotonicWeightKernel
ThresholdWeightKernel	ThresholdWeightKernel
ActivationMonotonicWeightKernel	MonotonicWeightKernel
TaperWeightKernel	A composite weight kernel that multiplies a low-cut and a high-cut monotonic taper kernel.
FeatureWeightSpec	Base class for all metadata objects with Pydantic validation.

Package Contents

class mt_metadata.features.weights.ChannelWeightSpec(**data)

Bases: mt_metadata.base.MetadataBase

Base class for all metadata objects with Pydantic validation.

MetadataBase extends DotNotationBaseModel (which inherits from Pydantic’s BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

Notes

• All field assignments are validated automatically via Pydantic

• None values are converted to appropriate defaults (empty string or 0.0)

• Supports nested attribute access via dot notation

• Thread-safe for read operations after initialization

combination_style: Annotated[CombinationStyleEnum, Field(default='multiplication', description='How to combine multiple feature weights.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['multiplication']})]

output_channels: Annotated[list[str], Field(default_factory=list, description='list of tf ouput channels for which this weighting scheme will be applied', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['[ ex ey hz ]']})]

feature_weight_specs: Annotated[list[mt_metadata.features.weights.feature_weight_spec.FeatureWeightSpec], Field(default_factory=list, description='List of feature weighting schemes to use for TF processing.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['[]']})]

weights: Annotated[xarray.DataArray | xarray.Dataset | numpy.ndarray | None, Field(default=None, description='Weights computed for this channel weight spec. Should be set after evaluation.', json_schema_extra={'units': None, 'required': False, 'examples': ['null']})]

classmethod check_feature_weight_specs(value, info)

classmethod check_weights(value)

evaluate(feature_values_dict)

Evaluate the channel weight by combining weights from all features.

Parameters:

feature_values_dict (dict[str, np.ndarray | float]) – Dictionary mapping feature names to their computed values. e.g., {“coherence”: ndarray, “multiple_coherence”: ndarray}

Returns:

channel_weight

Return type:

float or np.ndarray

get_weights_for_band(band)

Extract weights for the frequency bin closest to the band’s center frequency.

TODO: Add tests. :param band: Should have a .center_frequency attribute (float, Hz). :type band: Band

Returns:

weights – Weights for the closest frequency bin.

Return type:

np.ndarray or xarray.DataArray

class mt_metadata.features.weights.Base(**data)

Bases: mt_metadata.base.MetadataBase

Base class for all metadata objects with Pydantic validation.

MetadataBase extends DotNotationBaseModel (which inherits from Pydantic’s BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

Notes

• All field assignments are validated automatically via Pydantic

• None values are converted to appropriate defaults (empty string or 0.0)

• Supports nested attribute access via dot notation

• Thread-safe for read operations after initialization

weight_type: Annotated[WeightTypeEnum, Field(default=WeightTypeEnum.monotonic, description='Type of weighting kernel (e.g., monotonic, learned, spatial).', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['monotonic']})]

description: Annotated[str | None, Field(default=None, description='Human-readable description of what this kernel is for.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['This kernel smoothly transitions between 0 and 1 in a monotonic way']})]

active: Annotated[bool | None, Field(default=None, description='If false, this kernel will be skipped during weighting.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['false']})]

abstractmethod evaluate(values)

Evaluate the kernel on the input feature values.

Parameters:

values (np.ndarray or float) – The feature values to apply the weight kernel to.

Returns:

weights – The resulting weight(s).

Return type:

np.ndarray or float

class mt_metadata.features.weights.MonotonicWeightKernel(**data)

Bases: mt_metadata.features.weights.base.Base

MonotonicWeightKernel

Base class for monotonic weight kernels. Handles bounds, normalization, and direction.

A weighting kernel that applies a monotonic activation/taper function between defined lower and upper bounds, based on a given threshold direction.

There are two main types of monotonic kernels: taper and activation. The taper function is used to smoothly transition between the lower and upper bounds over some finite interval, while the activation style offers options that asymptote to 0 or 1, such as sigmoid or tanh. Thus the activation style supports +/- infinity bounds, while the taper style requires finite bounds.

threshold: Annotated[ThresholdEnum, Field(default=ThresholdEnum.low_cut, description='Which side of a threshold should be downweighted.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['low cut']})]

style: Annotated[StyleEnum, Field(default=StyleEnum.taper, description='Tapering/activation function to use between transition bounds.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['activation']})]

transition_lower_bound: Annotated[float, Field(default=-1000000000.0, description='Start of the taper region (weight begins to change).', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['-inf']})]

transition_upper_bound: Annotated[float, Field(default=1000000000.0, description='End of the taper region (weight finishes changing).', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['+inf']})]

class mt_metadata.features.weights.TaperMonotonicWeightKernel(**data)

Bases: mt_metadata.features.weights.monotonic_weight_kernel.MonotonicWeightKernel

MonotonicWeightKernel

Base class for monotonic weight kernels. Handles bounds, normalization, and direction.

A weighting kernel that applies a monotonic activation/taper function between defined lower and upper bounds, based on a given threshold direction.

There are two main types of monotonic kernels: taper and activation. The taper function is used to smoothly transition between the lower and upper bounds over some finite interval, while the activation style offers options that asymptote to 0 or 1, such as sigmoid or tanh. Thus the activation style supports +/- infinity bounds, while the taper style requires finite bounds.

half_window_style: Annotated[HalfWindowStyleEnum, Field(default=HalfWindowStyleEnum.rectangle, description='Tapering/activation function to use between transition bounds.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['hann']})]

evaluate(values)

Evaluate the kernel on the input feature values.

Parameters:

values (np.ndarray or float) – The feature values to apply the weight kernel to.

Returns:

weights – The resulting weight(s).

Return type:

np.ndarray or float

class mt_metadata.features.weights.ThresholdWeightKernel(**data)

Bases: mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel

ThresholdWeightKernel

A special case of MonotonicWeightKernel where the transition region is a single value, resulting in a hard threshold (step function). This kernel outputs 0 or 1 depending on whether the input is above or below the threshold, according to the threshold_type.

Parameters:

• threshold (float) – The threshold value.

• threshold_type (str, optional) – “low cut” (default) or “high cut”. Determines which side is downweighted.

• **kwargs – Additional keyword arguments passed to MonotonicWeightKernel.

threshold_type: Annotated[str, Field(default='low cut', description='Which side of a threshold should be downweighted.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['low cut']})]

class mt_metadata.features.weights.ActivationMonotonicWeightKernel(**data)

Bases: mt_metadata.features.weights.monotonic_weight_kernel.MonotonicWeightKernel

MonotonicWeightKernel

Base class for monotonic weight kernels. Handles bounds, normalization, and direction.

A weighting kernel that applies a monotonic activation/taper function between defined lower and upper bounds, based on a given threshold direction.

There are two main types of monotonic kernels: taper and activation. The taper function is used to smoothly transition between the lower and upper bounds over some finite interval, while the activation style offers options that asymptote to 0 or 1, such as sigmoid or tanh. Thus the activation style supports +/- infinity bounds, while the taper style requires finite bounds.

threshold: Annotated[ThresholdEnum, Field(default=ThresholdEnum.low_cut, description='Which side of a threshold should be downweighted.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['low cut']})]

activation_style: Annotated[ActivationStyleEnum, Field(default=ActivationStyleEnum.sigmoid, description='Tapering/activation function to use between transition bounds.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['tanh']})]

steepness: Annotated[float, Field(default=1.0, description='Controls the sharpness of the activation transition.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['10']})]

evaluate(values)

Evaluate the activation function for the given input values.

Parameters:

values (NDArray) – Input values to be evaluated.

Returns:

Evaluated activation values.

Return type:

NDArray

Raises:

ValueError – If the activation style is not recognized.

class mt_metadata.features.weights.TaperWeightKernel(**data)

Bases: mt_metadata.features.weights.base.Base

A composite weight kernel that multiplies a low-cut and a high-cut monotonic taper kernel.

Parameters:

• low_cut (tuple[float, float]) – (lower_bound, upper_bound) for the low-cut transition region.

• high_cut (tuple[float, float]) – (lower_bound, upper_bound) for the high-cut transition region.

• style (str, optional) – The taper style to use (default is ‘hann’).

• **kwargs – Additional keyword arguments passed to BaseWeightKernel.

low_cut: Annotated[Tuple[float, float], Field(description='Low cut transition bounds', json_schema_extra={'units': None, 'required': True, 'examples': [[0.1, 0.5]]})]

high_cut: Annotated[Tuple[float, float], Field(description='High cut transition bounds', json_schema_extra={'units': None, 'required': True, 'examples': [[0.5, 1.0]]})]

style: Annotated[mt_metadata.processing.window.TypeEnum, Field(description='Taper style', json_schema_extra={'units': None, 'required': True, 'examples': ['hann', 'hamming', 'blackman']})]

property low_kernel: mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel

The low-cut taper kernel.

property high_kernel: mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel

The high-cut taper kernel.

evaluate(values)

Evaluate the composite taper weight kernel on the input values.

Parameters:

values (np.ndarray) – Input values to evaluate the kernel on.

Returns:

The product of the low-cut and high-cut kernel evaluations.

Return type:

np.ndarray

class mt_metadata.features.weights.FeatureWeightSpec(**data)

Bases: mt_metadata.base.MetadataBase

Base class for all metadata objects with Pydantic validation.

MetadataBase extends DotNotationBaseModel (which inherits from Pydantic’s BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

Notes

• All field assignments are validated automatically via Pydantic

• None values are converted to appropriate defaults (empty string or 0.0)

• Supports nested attribute access via dot notation

• Thread-safe for read operations after initialization

feature_name: Annotated[FeatureNameEnum, Field(default='', description='The name of the feature to evaluate (e.g., coherence, impedance_ratio).', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['coherence']})]

feature: Annotated[dict | mt_metadata.features.feature.Feature | mt_metadata.features.coherence.Coherence | mt_metadata.features.fc_coherence.FCCoherence | mt_metadata.features.striding_window_coherence.StridingWindowCoherence, Field(default_factory=Feature, description='The feature specification.', json_schema_extra={'units': None, 'required': True, 'examples': [{'type': 'coherence'}]})]

weight_kernels: Annotated[list[mt_metadata.features.weights.monotonic_weight_kernel.MonotonicWeightKernel | mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel | mt_metadata.features.weights.activation_monotonic_weight_kernel.ActivationMonotonicWeightKernel], Field(default_factory=list, description='List of weight kernel specification.', json_schema_extra={'units': None, 'required': True, 'examples': [{'type': 'monotonic'}]})]

classmethod pre_process_feature(data)

Pre-process the feature dict to ensure correct class is instantiated.

classmethod validate_feature(value, info)

Validate the feature field to ensure it matches the feature_name.

classmethod validate_weight_kernels(value, info)

Validate the weight_kernels field to ensure proper initialization.

evaluate(feature_values)

Evaluate this feature’s weighting based on the list of kernels.

Parameters:

feature_values (np.ndarray or float) – The computed values for this feature.

Returns:

combined_weight – The combined weight from all kernels (e.g., multiplied together).

Return type:

np.ndarray or float