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

mt_metadata/transfer_functions/processing/aurora/frequency_bands.py

@@ -0,0 +1,230 @@
+"""
+Module containing FrequencyBands class representing a collection of Frequency Band objects.
+"""
+from typing import Literal, Optional, Generator, Union, List
+import pandas as pd
+import numpy as np
+import warnings
+from loguru import logger
+
+from . import Band
+
+
+class FrequencyBands:
+    """
+    Collection of Band objects, typically used at a single decimation level.
+
+    Attributes
+    ----------
+    _band_edges : pd.DataFrame
+        DataFrame with columns ['lower_bound', 'upper_bound'] containing
+        frequency band boundaries
+    """
+
+    def __init__(
+        self,
+        band_edges: Optional[Union[np.ndarray, pd.DataFrame]] = None,
+    ):
+        """
+        Parameters
+        ----------
+        band_edges : np.ndarray or pd.DataFrame, optional
+            If numpy array: 2D array with columns [lower_bound, upper_bound]
+            If DataFrame: Must have columns ['lower_bound', 'upper_bound']
+        """
+        if band_edges is not None:
+            self.band_edges = band_edges
+        else:
+            self._band_edges = pd.DataFrame(columns=['lower_bound', 'upper_bound'])
+
+    def __str__(self) -> str:
+        """Returns a Description of frequency bands"""
+        intro = "Frequency Bands:"
+        return f"{intro} \n{self._band_edges}"
+
+    def __repr__(self):
+        return self.__str__()
+
+    @property
+    def band_edges(self) -> pd.DataFrame:
+        """Get band edges as a DataFrame"""
+        return self._band_edges
+
+    @band_edges.setter
+    def band_edges(self, value: Union[np.ndarray, pd.DataFrame]) -> None:
+        """
+        Set band edges from either numpy array or DataFrame
+
+        Parameters
+        ----------
+        value : np.ndarray or pd.DataFrame
+            Band edge definitions
+        """
+        if isinstance(value, np.ndarray):
+            if value.ndim != 2 or value.shape[1] != 2:
+                raise ValueError("band_edges array must be 2D with shape (n_bands, 2)")
+            self._band_edges = pd.DataFrame(
+                value,
+                columns=['lower_bound', 'upper_bound']
+            )
+        elif isinstance(value, pd.DataFrame):
+            required_cols = ['lower_bound', 'upper_bound']
+            if not all(col in value.columns for col in required_cols):
+                raise ValueError(
+                    f"DataFrame must contain columns {required_cols}"
+                )
+            self._band_edges = value[required_cols].copy()
+        else:
+            raise TypeError(
+                "band_edges must be numpy array or DataFrame"
+            )
+
+        # Reset index to ensure 0-based integer indexing
+        self._band_edges.reset_index(drop=True, inplace=True)
+
+    @property
+    def number_of_bands(self) -> int:
+        """Number of frequency bands"""
+        return len(self._band_edges)
+
+    @property
+    def array(self) -> np.ndarray:
+        """Get band edges as numpy array"""
+        return self._band_edges.values
+
+    def sort(self, by: str = "center_frequency", ascending: bool = True) -> None:
+        """
+        Sort bands by specified criterion.
+
+        Parameters
+        ----------
+        by : str
+            Criterion to sort by:
+            - "lower_bound": Sort by lower frequency bound
+            - "upper_bound": Sort by upper frequency bound
+            - "center_frequency": Sort by geometric center frequency (default)
+        ascending : bool
+            If True, sort in ascending order, else descending
+        """
+        if by in ["lower_bound", "upper_bound"]:
+            self._band_edges.sort_values(by=by, ascending=ascending, inplace=True)
+        elif by == "center_frequency":
+            centers = self.band_centers()
+            self._band_edges = self._band_edges.iloc[
+                np.argsort(centers)[::(-1 if not ascending else 1)]
+            ].reset_index(drop=True)
+        else:
+            raise ValueError(
+                f"Invalid sort criterion: {by}. Must be one of: "
+                "'lower_bound', 'upper_bound', 'center_frequency'"
+            )
+
+    def bands(
+        self,
+        direction: str = "increasing_frequency",
+        sortby: Optional[str] = None,
+        rtype: str = "list"
+    ) -> Union[List[Band], Generator[Band, None, None]]:
+        """
+        Generate Band objects in specified order.
+
+        Parameters
+        ----------
+        direction : str
+            Order of iteration: "increasing_frequency" or "increasing_period"
+        sortby : str, optional
+            Sort bands before iteration:
+            - "lower_bound": Sort by lower frequency bound
+            - "upper_bound": Sort by upper frequency bound
+            - "center_frequency": Sort by geometric center frequency
+            If None, uses existing order
+        rtype : str
+            Return type: "list" or "generator". Default is "list" for easier reuse.
+            Use "generator" for memory efficiency when bands are only iterated once.
+
+        Returns
+        -------
+        Union[List[Band], Generator[Band, None, None]]
+            Band objects for each frequency band, either as a list or generator
+            depending on rtype parameter.
+        """
+        if sortby is not None or direction == "increasing_period":
+            # Create a copy to avoid modifying original
+            temp_bands = FrequencyBands(self._band_edges.copy())
+            temp_bands.sort(
+                by=sortby or "center_frequency",
+                ascending=(direction == "increasing_frequency")
+            )
+            bands_to_iterate = temp_bands
+        else:
+            bands_to_iterate = self
+
+        # Create generator
+        def band_generator():
+            for idx in range(bands_to_iterate.number_of_bands):
+                yield bands_to_iterate.band(idx)
+
+        # Return as requested type
+        if rtype == "generator":
+            return band_generator()
+        elif rtype == "list":
+            return list(band_generator())
+        else:
+            raise ValueError("rtype must be either 'list' or 'generator'")
+
+    def band(self, i_band: int) -> Band:
+        """
+        Get specific frequency band.
+
+        Parameters
+        ----------
+        i_band : int
+            Index of band to return (zero-based)
+
+        Returns
+        -------
+        Band
+            Frequency band object
+        """
+        row = self._band_edges.iloc[i_band]
+        return Band(
+            frequency_min=row['lower_bound'],
+            frequency_max=row['upper_bound']
+        )
+
+    def band_centers(self, frequency_or_period: str = "frequency") -> np.ndarray:
+        """
+        Calculate center frequencies/periods for all bands.
+
+        Parameters
+        ----------
+        frequency_or_period : str
+            Return values in "frequency" (Hz) or "period" (s)
+
+        Returns
+        -------
+        np.ndarray
+            Center frequencies/periods for each band
+        """
+        band_centers = np.array([
+            self.band(i).center_frequency
+            for i in range(self.number_of_bands)
+        ])
+
+        if frequency_or_period == "period":
+            band_centers = 1.0 / band_centers
+
+        return band_centers
+
+    def validate(self) -> None:
+        """
+        Validate and potentially reorder bands based on center frequencies.
+        """
+        band_centers = self.band_centers()
+
+        # Check if band centers are monotonically increasing
+        if not np.all(band_centers[1:] > band_centers[:-1]):
+            logger.warning(
+                "Band centers are not monotonic. Attempting to reorganize bands."
+            )
+            self.sort(by="center_frequency")

mt_metadata/transfer_functions/processing/aurora/processing.py

@@ -52,6 +52,7 @@ class Processing(Base):
         """
         dictionary of decimations levels
 
+        TODO: replace this convoluted setter with the model used for DecimationLevel.bands setter.
         :param value: dict of decimation levels
         :type value: dict
 
@@ -75,7 +76,6 @@ class Processing(Base):
             for obj in value:
                 if isinstance(value, DecimationLevel):
                     self._decimations.append(obj)
-
                 elif isinstance(obj, dict):
                     level = DecimationLevel()
                     level.from_dict(obj)
@@ -84,7 +84,7 @@ class Processing(Base):
                     raise TypeError(
                         f"List entry must be a DecimationLevel or dict object not {type(obj)}"
                     )
-
+        # TODO: Add some doc describing the role of this weird check for a long string
         elif isinstance(value, str):
             if len(value) > 4:
                 raise TypeError(f"Not sure what to do with {type(value)}")
@@ -216,7 +216,7 @@ class Processing(Base):
             )  # self.decimations_dict[key]
             decimation_obj.decimation.factor = d
             decimation_obj.decimation.sample_rate = sr
-            decimation_obj.window.num_samples = num_samples_window[i_level]
+            decimation_obj.stft.window.num_samples = num_samples_window[i_level]
             frequencies = decimation_obj.fft_frequencies
 
             for low, high in band_edges:

mt_metadata/transfer_functions/processing/aurora/run.py

@@ -1,8 +1,11 @@
 # -*- coding: utf-8 -*-
 """
+Module for `aurora` Run metadata container with useful built-in methods.
+
 Created on Thu Feb 17 14:15:20 2022
 
 @author: jpeacock
+
 """
 # =============================================================================
 # Imports
@@ -12,6 +15,7 @@ from mt_metadata.base import get_schema, Base
 from .standards import SCHEMA_FN_PATHS
 from mt_metadata.timeseries import TimePeriod
 from .channel import Channel
+from typing import Union
 
 # =============================================================================
 attr_dict = get_schema("run", SCHEMA_FN_PATHS)
@@ -20,6 +24,10 @@ class Run(Base):
     __doc__ = write_lines(attr_dict)
 
     def __init__(self, **kwargs):
+        """
+            Constructor.
+
+        """
         self._input = []
         self._output = []
         self._time_periods = []
@@ -27,16 +35,16 @@ class Run(Base):
         super().__init__(attr_dict=attr_dict, **kwargs)
 
     @property
-    def input_channel_names(self):
+    def input_channel_names(self) -> list:
         """list of channel names"""
         return [ch.id for ch in self._input]
 
     @property
-    def input_channels(self):
+    def input_channels(self) -> list:
         return self._input
 
     @input_channels.setter
-    def input_channels(self, values):
+    def input_channels(self, values: Union[list, str, Channel, dict]) -> None:
         self._input = []
         if not isinstance(values, list):
             values = [values]
@@ -90,17 +98,34 @@ class Run(Base):
         return self._time_periods
 
     @time_periods.setter
-    def time_periods(self, values):
+    def time_periods(self, values: Union[list, dict, TimePeriod]) -> None:
+        """
+            Sets self.time_periods
+
+        Parameters
+        ----------
+        values: Union[list, dict, TimePeriod]
+            If it is a list, the elements of the list must be TimePerid or dictionary representations of TimePeriods
+
+        """
         self._time_periods = []
         if not isinstance(values, list):
             values = [values]
 
         for item in values:
-            if not isinstance(item, TimePeriod):
+            if isinstance(item, TimePeriod):
+                self._time_periods.append(item)
+            elif isinstance(item, dict):
+                try:
+                    tp = TimePeriod()
+                    tp.from_dict(item)
+                    self._time_periods.append(tp)
+                except Exception as e:
+                    msg = f"Could not unpack dict to TimePeriod, got exception {e}"
+                    raise ValueError(msg)
+            else:
                 raise TypeError(f"not sure what to do with type {type(item)}")
 
-            self._time_periods.append(item)
-
     @property
     def channel_scale_factors(self):
         """

mt_metadata/transfer_functions/processing/aurora/standards/decimation_level.json

@@ -1,87 +1,21 @@
 {
-    "anti_alias_filter": {
-        "type": "string",
-        "required": true,
-        "style": "controlled vocabulary",
-        "units": null,
-        "description": "Name of anti alias filter to be applied",
-        "options": ["deafult", "other"],
-        "alias": [],
-        "example": "default",
-		"default": "default"
-    },
-    "recoloring": {
-        "type": "bool",
-        "required": true,
-        "style": "free form",
-        "units": null,
-        "description": "Whether the data are recolored [True] or not [False].",
-        "options": [],
-        "alias": [],
-        "example": true,
-		"default": true
-    },
-    "min_num_stft_windows": {
+	"bands": {
         "type": "integer",
         "required": true,
-        "style": "number",
+        "style": "name list",
         "units": null,
-        "description": "How many FFT windows must be available for the time series to valid for STFT.",
+        "description": "List of bands",
         "options": [],
         "alias": [],
-        "example": 4,
-		"default": 2
-    },
-    "method": {
-        "type": "string",
-        "required": true,
-        "style": "controlled vocabulary",
-        "units": null,
-        "description": "Fourier transform method",
-        "options": ["fft", "wavelet", "other"],
-        "alias": [],
-        "example": "fft",
-		"default": "fft"
-    },
-	"prewhitening_type": {
-        "type": "string",
-        "required": true,
-        "style": "controlled vocabulary",
-        "units": null,
-        "description": "Prewhitening method to be applied",
-        "options": ["first difference", "other"],
-        "alias": [],
-        "example": "first difference",
-		"default": "first difference"
-    },
-	"extra_pre_fft_detrend_type": {
-        "type": "string",
-        "required": true,
-        "style": "controlled vocabulary",
-        "units": null,
-        "description": "Extra Pre FFT detrend method to be applied",
-        "options": ["linear", "other"],
-        "alias": [],
-        "example": "linear",
-		"default": "linear"
-    },
-    	"pre_fft_detrend_type": {
-        "type": "string",
-        "required": true,
-        "style": "controlled vocabulary",
-        "units": null,
-        "description": "Pre FFT detrend method to be applied",
-        "options": ["linear", "other"],
-        "alias": [],
-        "example": "linear",
-		"default": "linear"
+        "example": "[]",
+		"default": null
     },
-	"bands": {
+    "channel_weight_specs": {
         "type": "integer",
         "required": true,
         "style": "name list",
         "units": null,
-        "description": "List of bands",
+        "description": "List of weighting schemes to use for TF processing for each output channel",
         "options": [],
         "alias": [],
         "example": "[]",

mt_metadata/transfer_functions/processing/aurora/stations.py

@@ -4,6 +4,9 @@ Created on Thu Feb 24 13:58:07 2022
 
 @author: jpeacock
 """
+from loguru import logger
+from typing import Union
+
 import pandas as pd
 
 # =============================================================================
@@ -49,15 +52,40 @@ class Stations(Base):
         return return_list
 
     @remote.setter
-    def remote(self, rr_station):
+    def remote(self, rr_station: Union[list, dict]):
+        """
+            Method for unpacking rr_station info into mt_metadata object.
+
+            Developmnent Notes:
+            This function was raising an exception when trying to populate an aurora.Processing object
+            from a json.loads() dict.
+            TODO: add a description of input variable and use cases, ... it seems that we may not want
+            to support multiple rr stations yet.
+
+        Parameters
+        ----------
+        rr_station
+
+        Returns
+        -------
+
+        """
         self._remote = []
         if isinstance(rr_station, list):
             for item in rr_station:
-                if not isinstance(item, Station):
+                if isinstance(item, Station):
+                    self._remote.append(item)
+                elif isinstance(item, dict):
+                    try:
+                        remote = Station()
+                        remote.from_dict(item)
+                        self._remote.append(remote)
+                    except Exception as e:
+                        raise ValueError("could not unpack dict to a Station object")
+                else:
                     raise TypeError(
                         f"list item must be Station object not {type(item)}"
                     )
-                self._remote.append(item)
 
         elif isinstance(rr_station, dict):
             remote = Station()
@@ -69,9 +97,10 @@ class Stations(Base):
             rr_station.remote = True
             self._remote.append(rr_station)
 
-        elif isinstance(rr_station, str):
+        elif isinstance(rr_station, str):  # TODO: Add doc; what is this doing? This does not affect self._remote.
             if len(rr_station) > 4:
                 raise ValueError(f"not sure to do with {type(rr_station)}")
+            # TODO: Add doc explaining what happens when rr_station is str of length 3.
 
         else:
             raise ValueError(f"not sure to do with {type(rr_station)}")