mt-metadata 0.3.9__py2.py3-none-any.whl → 0.4.0__py2.py3-none-any.whl

mt_metadata/features/weights/base.py

@@ -0,0 +1,44 @@
+"""
+    The base class for a weighting kernel.
+
+"""
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from .standards import SCHEMA_FN_PATHS
+
+# attr_dict = get_schema("base", SCHEMA_FN_PATHS)
+
+
+class BaseWeightKernel(Base):
+    """
+    BaseWeightKernel
+
+    A base class for defining a weighting kernel that can be applied to a feature
+    to determine its contribution to a final weight value.
+
+    This class is not intended to be used directly but to be subclassed by
+    specific kernel types (e.g., MonotonicWeightKernel, CompositeWeightKernel).
+    """
+    # __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        #self.from_dict(kwargs)
+
+    def evaluate(self, 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 : np.ndarray or float
+            The resulting weight(s).
+        """
+        raise NotImplementedError("BaseWeightKernel cannot be evaluated directly.")
+
+

mt_metadata/features/weights/channel_weight_spec.py

@@ -0,0 +1,209 @@
+"""
+    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.
+"""
+
+
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from mt_metadata.features.weights.feature_weight_spec import FeatureWeightSpec
+from mt_metadata.features.weights.standards import SCHEMA_FN_PATHS
+from mt_metadata.helper_functions import cast_to_class_if_dict
+from mt_metadata.helper_functions import validate_setter_input
+from typing import List, Union
+
+import numpy as np
+import xarray as xr
+
+attr_dict = get_schema("channel_weight_spec", SCHEMA_FN_PATHS)
+
+class ChannelWeightSpec(Base):
+    """
+    ChannelWeightSpec
+
+    Defines a weighting model for one output channel (e.g., ex, ey, hz).
+    Combines multiple feature-based weighting specifications into a
+    single weight using the specified combination strategy.
+
+
+    """
+    __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+        super().__init__(attr_dict=attr_dict, **kwargs)
+        self._weights = None
+
+    @property
+    def feature_weight_specs(self) -> List[FeatureWeightSpec]:
+        """
+            Return feature_weight_specs.
+
+        """
+        return self._feature_weight_specs
+
+    @feature_weight_specs.setter
+    def feature_weight_specs(self, value: Union[List[Union[FeatureWeightSpec, dict]], FeatureWeightSpec]) -> None:
+        """
+        Set features. If any are in dict form, cast them to FeatureWeightSpec objects before setting.
+
+        :param value: FeatureWeightSpecs or equivalent dicts
+        :type value: Union[List[Union[FeatureWeightSpec, dict]]
+
+        """
+        values = validate_setter_input(value, FeatureWeightSpec)
+        fws_list = [cast_to_class_if_dict(obj, FeatureWeightSpec) for obj in values]
+        self._feature_weight_specs = fws_list
+
+    def evaluate(self, feature_values_dict):
+        """
+        Evaluate the channel weight by combining weights from all features.
+
+        Parameters
+        ----------
+        feature_values_dict : dict
+            Dictionary mapping feature names to their computed values.
+            e.g., {"coherence": ndarray, "multiple_coherence": ndarray}
+
+        Returns
+        -------
+        channel_weight : float or np.ndarray
+        """
+        import numpy as np
+
+        weights = []
+        for feature_weight_spec in self.feature_weight_specs:
+            fname = feature_weight_spec.feature.name
+            if fname not in feature_values_dict:
+                raise KeyError(f"Feature values missing for '{fname}'")
+
+            w = feature_weight_spec.evaluate(feature_values_dict[fname])
+            weights.append(w)
+
+        if not weights:
+            return 1.0
+
+        combo = self.combination_style
+        if combo == "multiplication":
+            return np.prod(weights, axis=0)
+        elif combo == "mean":
+            return np.mean(weights, axis=0)
+        elif combo == "minimum":
+            return np.min(weights, axis=0)
+        elif combo == "maximum":
+            return np.max(weights, axis=0)
+        else:
+            raise ValueError(f"Unknown combination style: {combo}")
+    
+
+    @property
+    def weights(self):
+        return self._weights
+
+    @weights.setter
+    def weights(self, value):
+        if not isinstance(value, (xr.DataArray, xr.Dataset, np.ndarray, None.__class__)):
+            raise TypeError("Data must be a numpy array or xarray.")
+        self._weights = value
+
+    def get_weights_for_band(self, band):
+        """
+        Extract weights for the frequency bin closest to the band's center frequency.
+        
+        TODO: Add tests.
+        Parameters
+        ----------
+        band : object
+            Should have a .center_frequency attribute (float, Hz).
+
+        Returns
+        -------
+        weights : np.ndarray or xarray.DataArray
+            Weights for the closest frequency bin.
+        """
+        if self.weights is None:
+            raise ValueError("No weights have been set.")
+
+        # Assume weights is an xarray.DataArray or Dataset with a 'frequency' dimension
+        freq_axis = None
+        if hasattr(self.weights, "dims"):
+            # Try to find the frequency dimension
+            for dim in self.weights.dims:
+                if "freq" in dim:
+                    freq_axis = dim
+                    break
+            if freq_axis is None:
+                raise ValueError("Could not find frequency dimension in weights.")
+
+            freqs = self.weights[freq_axis].values
+        elif isinstance(self.weights, np.ndarray):
+            # If it's a plain ndarray, assume first axis is frequency
+            freqs = np.arange(self.weights.shape[0])
+            freq_axis = 0
+        else:
+            raise TypeError("Weights must be an xarray.DataArray, Dataset, or numpy array.")
+
+        # Find index of closest frequency
+        idx = np.argmin(np.abs(freqs - band.center_frequency))
+
+        # Extract weights for that frequency
+        if hasattr(self.weights, "isel"):
+            # xarray: use isel
+            weights_for_band = self.weights.isel({freq_axis: idx})
+        else:
+            # numpy: index along first axis
+            weights_for_band = self.weights[idx]
+
+        return weights_for_band

mt_metadata/features/weights/feature_weight_spec.py

@@ -0,0 +1,194 @@
+"""
+FeatureWeightSpec is the next key layer of abstraction after WeightKernels.
+
+It ties together a feature (including its parameterization),
+and one or more weighting kernels (like MonotonicWeightKernel).
+
+This will let you do things like:
+- Evaluate "coherence" between ex and hy with a taper kernel
+- Apply multiple kernels to the same feature (e.g., low cut and high cut)
+- Plug this into a higher-level channel weighting model
+
+"""
+
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from mt_metadata.features.feature import Feature
+from mt_metadata.features.weights.monotonic_weight_kernel import MonotonicWeightKernel
+from mt_metadata.features.weights.monotonic_weight_kernel import ActivationMonotonicWeightKernel
+from mt_metadata.features.weights.monotonic_weight_kernel import TaperMonotonicWeightKernel
+from mt_metadata.features.weights.standards import SCHEMA_FN_PATHS
+import numpy as np
+
+
+attr_dict = get_schema("base", SCHEMA_FN_PATHS)
+# no need to add to attr dict if we have lists of mtmetadata objs.
+# attr_dict.add_dict(Feature()._attr_dict, "feature")
+
+class FeatureWeightSpec(Base):
+    """
+    FeatureWeightSpec
+
+    Defines how a particular feature is used to weight an output channel.
+    Includes parameters needed to compute the feature and one or more
+    weight kernels to evaluate its influence.
+    """
+    __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+        """
+            Consstuctor.
+        """
+        self._feature = None  # <-- initialize the backing variable directly
+        super().__init__(attr_dict=attr_dict, **kwargs)
+        weight_kernels = kwargs.get("weight_kernels", [])
+        self.weight_kernels = weight_kernels
+
+    # TODO: Remove this method after mt_metadata pydantic upgrade   
+    # This is a workaround to ensure the setter logic runs when feature is a dict
+    # This is needed because the setter logic is not automatically triggered
+    # when the object is created from a dict.
+    def post_from_dict(self):
+        """
+            If feature is a dict, force the setter logic to run
+        """
+        if isinstance(self.feature, dict):
+            self.feature = self.feature
+        # Optionally, do the same for weight_kernels if needed
+
+    def from_dict(self, d):
+        # If 'feature' is a dict, convert it to the correct object before base from_dict
+        if "feature" in d and isinstance(d["feature"], dict):
+            self.feature = d["feature"]  # This will use your property setter
+            d["feature"] = self.feature  # Now it's the correct object
+        super().from_dict(d)
+        self.post_from_dict()
+
+
+    @property
+    def feature(self):
+        return self._feature
+
+    @feature.setter
+    def feature(self, value):
+        """
+        Set the feature for this weight spec.
+        If a dict is provided, it will be used to initialize the feature object.
+        If an object is provided, it will be used directly.
+        Unwraps nested 'feature' keys if present.
+
+
+        TODO: FIXME (circular import)
+        Should be able to use a model like:
+        SUPPORTED_FEATURE_CLASS_MAP = {
+        "coherence": Coherence,
+        # "multiple_coherence": MultipleCoherence,
+        # Add more as needed
+        }
+        but that will result in a circular import if Coherence import at the top of module.
+
+        """
+        # Unwrap if wrapped in 'feature' repeatedly
+        while isinstance(value, dict) and "feature" in value and isinstance(value["feature"], dict):
+            value = value["feature"]
+        if isinstance(value, dict):
+            feature_name = value.get("name")
+            # Import here to avoid circular import at module level
+            print(f"Feature setter: feature_name={feature_name}, value={value}")  # DEBUG
+            if feature_name == "coherence":
+                from mt_metadata.features.coherence import Coherence
+                feature_cls = Coherence
+            elif feature_name == "striding_window_coherence":
+                from mt_metadata.features.coherence import StridingWindowCoherence
+                feature_cls = StridingWindowCoherence
+            else:
+                msg = f"feature_name {feature_name} not recognized -- resorting to base class"
+                self.logger.warning(msg)
+                from mt_metadata.features.feature import Feature
+                feature_cls = Feature
+            self._feature = feature_cls(**value)
+            print(f"Feature setter: instantiated {self._feature.__class__}")  # DEBUG
+        else:
+            self._feature = value
+            print(f"Feature setter: set directly to {type(value)}")  # DEBUG
+
+
+    @property
+    def weight_kernels(self):
+        return self._weight_kernels
+
+    @weight_kernels.setter
+    def weight_kernels(self, value):
+        """
+        Ensure weight_kernels are properly initialized.
+        """
+        self._weight_kernels = _unpack_weight_kernels(weight_kernels=value)
+
+    def evaluate(self, 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 : np.ndarray or float
+            The combined weight from all kernels (e.g., multiplied together).
+        """
+
+        weights = [kernel.evaluate(feature_values) for kernel in self.weight_kernels]
+        return np.prod(weights, axis=0) if weights else 1.0
+
+def _unpack_weight_kernels(weight_kernels):
+    """
+    Unpack weight kernels from a list of dictionaries or objects.
+    Determines the correct kernel class (Activation or Taper) based on keys.
+    """
+    result = []
+    for wk in weight_kernels:
+        # Unwrap if wrapped in "weight_kernel" (TODO: Delete, or revert after mt_metadata pydantic upgrade.)
+        if isinstance(wk, dict) and "weight_kernel" in wk:
+            wk = wk["weight_kernel"]
+        if isinstance(wk, dict):
+            if "activation_style" in wk or wk.get("style") == "activation":
+                result.append(ActivationMonotonicWeightKernel(**wk))
+            elif "half_window_style" in wk or wk.get("style") == "taper":
+                result.append(TaperMonotonicWeightKernel(**wk))
+            else:
+                result.append(MonotonicWeightKernel(**wk))
+        else:
+            result.append(wk)
+    return result
+
+def unwrap_known_wrappers(obj, known_keys=None):
+    """
+    Recursively unwraps dicts/lists for known single-key wrappers.
+    """
+    if known_keys is None:
+        known_keys = {"feature_weight_spec", "channel_weight_spec", "weight_kernel", "feature"}
+    if isinstance(obj, dict):
+        # If it's a single-key dict and the key is known, unwrap
+        while (
+            len(obj) == 1
+            and next(iter(obj)) in known_keys
+            and isinstance(obj[next(iter(obj))], (dict, list))
+        ):
+            obj = obj[next(iter(obj))]
+        # Recurse into dict values
+        return {k: unwrap_known_wrappers(v, known_keys) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [unwrap_known_wrappers(item, known_keys) for item in obj]
+    else:
+        return obj
+
+# Patch FeatureWeightSpec.from_dict to unwrap wrappers
+orig_from_dict = FeatureWeightSpec.from_dict
+
+def from_dict_unwrap(self, d):
+    d = unwrap_known_wrappers(d)
+    return orig_from_dict(self, d)
+
+FeatureWeightSpec.from_dict = from_dict_unwrap