mt_metadata.features.weights ============================ .. py:module:: mt_metadata.features.weights Submodules ---------- .. toctree:: :maxdepth: 1 /source/api/mt_metadata/features/weights/activation_monotonic_weight_kernel/index /source/api/mt_metadata/features/weights/base/index /source/api/mt_metadata/features/weights/channel_weight_spec/index /source/api/mt_metadata/features/weights/feature_weight_spec/index /source/api/mt_metadata/features/weights/monotonic_weight_kernel/index /source/api/mt_metadata/features/weights/taper_monotonic_weight_kernel/index /source/api/mt_metadata/features/weights/taper_weight_kernel/index /source/api/mt_metadata/features/weights/threshold_weight_kernel/index Classes ------- .. autoapisummary:: mt_metadata.features.weights.ChannelWeightSpec mt_metadata.features.weights.Base mt_metadata.features.weights.MonotonicWeightKernel mt_metadata.features.weights.TaperMonotonicWeightKernel mt_metadata.features.weights.ThresholdWeightKernel mt_metadata.features.weights.ActivationMonotonicWeightKernel mt_metadata.features.weights.TaperWeightKernel mt_metadata.features.weights.FeatureWeightSpec Package Contents ---------------- .. py:class:: ChannelWeightSpec(**data) Bases: :py:obj:`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. .. attribute:: _skip_equals Private attribute listing fields to skip in equality comparisons :type: list[str] .. attribute:: _fields Private attribute caching field information :type: dict[str, Any] .. rubric:: 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 .. py:attribute:: combination_style :type: Annotated[CombinationStyleEnum, Field(default='multiplication', description='How to combine multiple feature weights.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['multiplication']})] .. py:attribute:: output_channels :type: 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 ]']})] .. py:attribute:: feature_weight_specs :type: 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': ['[]']})] .. py:attribute:: weights :type: 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']})] .. py:method:: check_feature_weight_specs(value, info) :classmethod: .. py:method:: check_weights(value) :classmethod: .. py:method:: evaluate(feature_values_dict) Evaluate the channel weight by combining weights from all features. :param feature_values_dict: Dictionary mapping feature names to their computed values. e.g., {"coherence": ndarray, "multiple_coherence": ndarray} :type feature_values_dict: dict[str, np.ndarray | float] :returns: **channel_weight** :rtype: float or np.ndarray .. py:method:: 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. :rtype: np.ndarray or xarray.DataArray .. py:class:: Base(**data) Bases: :py:obj:`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. .. attribute:: _skip_equals Private attribute listing fields to skip in equality comparisons :type: list[str] .. attribute:: _fields Private attribute caching field information :type: dict[str, Any] .. rubric:: 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 .. py:attribute:: weight_type :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']})] .. py:attribute:: description :type: 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']})] .. py:attribute:: active :type: 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']})] .. py:method:: evaluate(values) :abstractmethod: Evaluate the kernel on the input feature values. :param values: The feature values to apply the weight kernel to. :type values: np.ndarray or float :returns: **weights** -- The resulting weight(s). :rtype: np.ndarray or float .. py:class:: MonotonicWeightKernel(**data) Bases: :py:obj:`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. .. py:attribute:: threshold :type: 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']})] .. py:attribute:: style :type: 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']})] .. py:attribute:: transition_lower_bound :type: 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']})] .. py:attribute:: transition_upper_bound :type: 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']})] .. py:class:: TaperMonotonicWeightKernel(**data) Bases: :py:obj:`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. .. py:attribute:: half_window_style :type: 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']})] .. py:method:: evaluate(values) Evaluate the kernel on the input feature values. :param values: The feature values to apply the weight kernel to. :type values: np.ndarray or float :returns: **weights** -- The resulting weight(s). :rtype: np.ndarray or float .. py:class:: ThresholdWeightKernel(**data) Bases: :py:obj:`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. :param threshold: The threshold value. :type threshold: float :param threshold_type: "low cut" (default) or "high cut". Determines which side is downweighted. :type threshold_type: str, optional :param \*\*kwargs: Additional keyword arguments passed to MonotonicWeightKernel. .. py:attribute:: threshold_type :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']})] .. py:class:: ActivationMonotonicWeightKernel(**data) Bases: :py:obj:`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. .. py:attribute:: threshold :type: 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']})] .. py:attribute:: activation_style :type: 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']})] .. py:attribute:: steepness :type: 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']})] .. py:method:: evaluate(values) Evaluate the activation function for the given input values. :param values: Input values to be evaluated. :type values: NDArray :returns: Evaluated activation values. :rtype: NDArray :raises ValueError: If the activation style is not recognized. .. py:class:: TaperWeightKernel(**data) Bases: :py:obj:`mt_metadata.features.weights.base.Base` A composite weight kernel that multiplies a low-cut and a high-cut monotonic taper kernel. :param low_cut: (lower_bound, upper_bound) for the low-cut transition region. :type low_cut: tuple[float, float] :param high_cut: (lower_bound, upper_bound) for the high-cut transition region. :type high_cut: tuple[float, float] :param style: The taper style to use (default is 'hann'). :type style: str, optional :param \*\*kwargs: Additional keyword arguments passed to BaseWeightKernel. .. py:attribute:: low_cut :type: Annotated[Tuple[float, float], Field(description='Low cut transition bounds', json_schema_extra={'units': None, 'required': True, 'examples': [[0.1, 0.5]]})] .. py:attribute:: high_cut :type: Annotated[Tuple[float, float], Field(description='High cut transition bounds', json_schema_extra={'units': None, 'required': True, 'examples': [[0.5, 1.0]]})] .. py:attribute:: style :type: Annotated[mt_metadata.processing.window.TypeEnum, Field(description='Taper style', json_schema_extra={'units': None, 'required': True, 'examples': ['hann', 'hamming', 'blackman']})] .. py:property:: low_kernel :type: mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel The low-cut taper kernel. .. py:property:: high_kernel :type: mt_metadata.features.weights.taper_monotonic_weight_kernel.TaperMonotonicWeightKernel The high-cut taper kernel. .. py:method:: evaluate(values) Evaluate the composite taper weight kernel on the input values. :param values: Input values to evaluate the kernel on. :type values: np.ndarray :returns: The product of the low-cut and high-cut kernel evaluations. :rtype: np.ndarray .. py:class:: FeatureWeightSpec(**data) Bases: :py:obj:`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. .. attribute:: _skip_equals Private attribute listing fields to skip in equality comparisons :type: list[str] .. attribute:: _fields Private attribute caching field information :type: dict[str, Any] .. rubric:: 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 .. py:attribute:: feature_name :type: 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']})] .. py:attribute:: feature :type: 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'}]})] .. py:attribute:: weight_kernels :type: 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'}]})] .. py:method:: pre_process_feature(data) :classmethod: Pre-process the feature dict to ensure correct class is instantiated. .. py:method:: validate_feature(value, info) :classmethod: Validate the feature field to ensure it matches the feature_name. .. py:method:: validate_weight_kernels(value, info) :classmethod: Validate the weight_kernels field to ensure proper initialization. .. py:method:: evaluate(feature_values) Evaluate this feature's weighting based on the list of kernels. :param feature_values: The computed values for this feature. :type feature_values: np.ndarray or float :returns: **combined_weight** -- The combined weight from all kernels (e.g., multiplied together). :rtype: np.ndarray or float