mt_metadata.features.weights.channel_weight_spec

Container for weighting strategy to apply to a single tf estimation having a single output channel (usually one of “ex”, “ey”, “hz”).

candidate data structure is stored in test_helpers/channel_weight_specs_example.json

Candidate names: processing_weights, feature_weights, channel_weights_spec, channel_weighting

Notes, and doc for weights PR.

channel_weight_specs is a candidate name for the json block like the following: >>> diff processing_configuration_template.json test_processing_config_with_weights_block.json (Another candidate name could be processing_weights, or weights, but the final nomenclature can be sorted out after there is a functional prototype with the appropriate structure.)

This block is basically a dict that maps an output channel name to a ChannelWeightSpec (CWS) object.

There are at least three places we would like to be able to plug in such a dict to the processing flow. 1. At the frequency_band level, so that each band can be associated with a specialty CWS 2. At the decimation_level level, so that all bands in a GIB have a common, default. 3. At a high level, so that all processing uses them. TAI: In future, hopefully we could insert a custom CWS for a specific band, but leave all other bands to use the DecimationLevel default CWS, for example. i.e. the CWS can be defined for different scopes.

TODO FIXME: IN mt_metadata/transfer_functions/processing/auaora/processing.py when you output a json, it looks like the decimations level should be named: decimation_levels instead.

The general model I’ll try to follow will be to open an itearable of objects with a plural of the object name. For example, the processing block called “bands” follows with an itearble of: {

“band”: {

“center_averaging_type”: “geometric”, … “index_min”: 25

}

}

{

“band”: {

“center_averaging_type”: “geometric”, … “index_min”: 25

}

}

Will start by plugging this into the DecimationLevel.

TODO: Determine if this class, which represents a single element of a list of channel weight specs, which will be in the json, should have a wrapper or not.

In the same way that a DecimationLevel has Bands, it will also have ChannelWeightSpecs.

Classes

CombinationStyleEnum	str(object='') -> str
ChannelWeightSpec	Base class for all metadata objects with Pydantic validation.

Module Contents

class mt_metadata.features.weights.channel_weight_spec.CombinationStyleEnum

Bases: mt_metadata.common.enumerations.StrEnumerationBase

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

multiplication = 'multiplication'

minimum = 'minimum'

maximum = 'maximum'

mean = 'mean'

class mt_metadata.features.weights.channel_weight_spec.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