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

mt_metadata/transfer_functions/processing/short_time_fourier_transform.py

@@ -0,0 +1,64 @@
+"""
+This module contains the metadata ShortTimeFourierTransform (STFT) metadata class.
+
+Development Notes:
+    This is part of a refactoring of the FCDecimation and aurora DecimationLevel
+
+    Both of those classes are essentially used to represent Spectrograms,
+    and in the Aurora DecimationLevel case, there are also information about processing included.
+
+    This class pulls out the metadata that are associated with the application of the STFT.
+
+    "harmonic_indices"
+    "method"
+    "min_num_stft_windows"
+    "per_window_detrend_type"
+    "pre_fft_detrend_type"
+    "prewhitening_type"
+    "recoloring"
+
+
+Created on Sat Dec 28 18:39:00 2024
+
+@author: kkappler
+
+"""
+
+# =============================================================================
+# Imports
+# =============================================================================
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from mt_metadata.transfer_functions.processing.window import Window
+from mt_metadata.transfer_functions.processing.standards import SCHEMA_FN_PATHS
+
+# =============================================================================
+attr_dict = get_schema("short_time_fourier_transform", SCHEMA_FN_PATHS)
+attr_dict.add_dict(Window()._attr_dict, "window")
+
+# =============================================================================
+
+
+class ShortTimeFourierTransform(Base):
+    """
+        The ShortTimeFourierTransform (STFT) class contains information about how to apply the STFT
+        to the time series.
+
+    """
+    __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+        """
+            Constructor.
+            :param kwargs: TODO: add description
+        """
+        self.window = Window()
+        super().__init__(attr_dict=attr_dict, **kwargs)
+
+
+def main():
+    stft = ShortTimeFourierTransform()
+
+
+if __name__ == "__main__":
+    main()

mt_metadata/transfer_functions/processing/standards/__init__.py

@@ -0,0 +1,6 @@
+# package file
+from pathlib import Path
+
+SCHEMA_PATH = Path(__file__).parent
+
+SCHEMA_FN_PATHS = list(SCHEMA_PATH.glob("*.json"))

mt_metadata/transfer_functions/processing/standards/short_time_fourier_transform.json

@@ -0,0 +1,94 @@
+{
+    "harmonic_indices": {
+        "type": "integer",
+        "required": true,
+        "style": "number list",
+        "units": null,
+        "description": "List of harmonics indices kept, if all use -1",
+        "options": [],
+        "alias": [],
+        "example": [0, 4, 8],
+		"default": [-1]
+    },
+    "method": {
+        "type": "string",
+        "required": true,
+        "style": "controlled vocabulary",
+        "units": null,
+        "description": "Fourier transform method",
+        "options": [
+            "fft",
+            "wavelet",
+            "other"
+        ],
+        "alias": [],
+        "example": "fft",
+        "default": "fft"
+    },
+    "min_num_stft_windows": {
+        "type": "integer",
+        "required": true,
+        "style": "number",
+        "units": null,
+        "description": "How many FFT windows must be available for the time series to valid for STFT.",
+        "options": [],
+        "alias": [],
+        "example": 4,
+        "default": 2
+    },
+    "per_window_detrend_type": {
+        "type": "string",
+        "required": true,
+        "style": "controlled vocabulary",
+        "units": null,
+        "description": "Additional detrending applied per window.  Not available for standard scipy spectrogram -- placholder for ARMA prewhitening.",
+        "options": [
+            "linear",
+            "constant",
+            ""
+        ],
+        "alias": [],
+        "example": "linear",
+        "default": ""
+    },
+    "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"
+    },
+    "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"
+    },
+    "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
+    }
+}

mt_metadata/transfer_functions/processing/{aurora/standards/decimation.json → standards/time_series_decimation.json}

@@ -4,7 +4,7 @@
         "required": true,
         "style": "number",
         "units": null,
-        "description": "Decimation level in sequential order",
+        "description": "Decimation level, must be a non-negative integer starting at 0",
         "options": [],
         "alias": [],
         "example": "0",
@@ -15,10 +15,10 @@
         "required": true,
         "style": "number",
         "units": null,
-        "description": "Decimation factor",
+        "description": "Decimation factor between parent sample rate and decimated time series sample rate.",
         "options": [],
         "alias": [],
-        "example": "1",
+        "example": "4.0",
 		"default": 1.0
     },
     "method": {
@@ -31,16 +31,27 @@
         "alias": [],
         "example": "default",
 		"default": "default"
-    },    
+    },
 	"sample_rate": {
         "type": "float",
         "required": true,
         "style": "number",
         "units": "samples per second",
-        "description": "Sample rate of the data after decimation.",
+        "description": "Sample rate of the decimation level data (after decimation).",
         "options": [],
         "alias": [],
         "example": "256",
 		"default": 1
+    },
+    "anti_alias_filter": {
+        "type": "string",
+        "required": true,
+        "style": "free form",
+        "units": null,
+        "description": "Type of anti alias filter for decimation.",
+        "options": [],
+        "alias": [],
+        "example": "default",
+		"default": "default"
     }
-}
+}

mt_metadata/transfer_functions/processing/{aurora/standards → standards}/window.json

@@ -33,7 +33,7 @@
 			"blackman",
 			"hamming",
 			"hann",
-			"bartlett", 
+			"bartlett",
 			"flattop",
 			"parzen",
 			"bohman",
@@ -74,5 +74,16 @@
       "alias": [],
       "example": "2020-02-01T09:23:45.453670+00:00",
       "default": "1980-01-01T00:00:00+00:00"
+    },
+    "normalized": {
+        "type": "bool",
+        "required": true,
+        "units": null,
+        "style": "free form",
+        "description": "True if the window shall be normalized so the sum of the coefficients is 1",
+        "options": [],
+        "alias": ["normalised"],
+        "example": false,
+        "default": true
     }
-}
+}

mt_metadata/transfer_functions/processing/time_series_decimation.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""
+This module contains the metadata TimeSeriesDecimation class.
+
+Development Notes:
+    This is part of a refactoring that seeks to separate the FCDecimation and aurora DecimationLevel
+    from the time series decimation.
+
+    The previous version of this class was in processing/aurora/decimation.py and had attrs
+    ["level", "factor", "method", "sample_rate", "anti_alias_filter"],
+
+    TODO: Consider adding a parent_sample_rate attribute to this class
+
+Created on Thu Dec 26 12:00:00 2024
+
+@author: kkappler
+
+"""
+# =============================================================================
+# Imports
+# =============================================================================
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from mt_metadata.transfer_functions.processing.standards import SCHEMA_FN_PATHS
+
+# =============================================================================
+attr_dict = get_schema("time_series_decimation", SCHEMA_FN_PATHS)
+# =============================================================================
+
+
+class TimeSeriesDecimation(Base):
+    """
+        The decimation class contains information about how to decimaate a time series as well
+         as attributes to describe it's place in the mth5 hierarchy.
+         Key pieces of information:
+        1. The decimation level, an integer that tells the sequential order in a decimation scheme.
+        2. The decimation factor.  This is normally an integer, but the decimation.json does allow for floating point values.
+
+        Development Notes:
+        -
+    """
+    __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+
+        super().__init__(attr_dict=attr_dict, **kwargs)
+
+    # TODO: add this logic to __init__ and a test
+    # if self.level == 0:
+    #     self.anti_alias_filter = None

mt_metadata/transfer_functions/processing/window.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Thu Feb 17 14:15:20 2022
+
+    Updated 2025-01-02: kkappler, adding methods to generate taper values.  In future this class
+    can replace ApodizationWindow in aurora.
+
+@author: jpeacock
+"""
+# =============================================================================
+# Imports
+# =============================================================================
+from mt_metadata.base.helpers import write_lines
+from mt_metadata.base import get_schema, Base
+from .standards import SCHEMA_FN_PATHS
+
+import numpy as np
+import scipy.signal as ssig
+
+# =============================================================================
+attr_dict = get_schema("window", SCHEMA_FN_PATHS)
+# =============================================================================
+
+
+class Window(Base):
+    __doc__ = write_lines(attr_dict)
+
+    def __init__(self, **kwargs):
+        super().__init__(attr_dict=attr_dict, **kwargs)
+        self.additional_args = kwargs.get("additional_args", {})
+        self._taper = None
+
+    @property
+    def additional_args(self) -> dict:
+        return self._additional_args
+
+    @additional_args.setter
+    def additional_args(self, args):
+        if not isinstance(args, dict):
+            raise TypeError("additional_args must be a dictionary")
+        self._additional_args = args
+
+    @property
+    def num_samples_advance(self):
+        return self.num_samples - self.overlap
+
+    def fft_harmonics(self, sample_rate: float) -> np.ndarray:
+        """
+            Returns the frequencies for an fft..
+        :param sample_rate:
+        :return:
+        """
+        return get_fft_harmonics(
+            samples_per_window=self.num_samples,
+            sample_rate=sample_rate
+        )
+
+    def taper(self) -> np.ndarray:
+        """
+            Get's the window coeffcients. via wrapper call to scipy.signal
+
+            Note: see scipy.signal.get_window for a description of what is expected in args[1:]. http://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.get_window.html
+
+        Returns
+        -------
+
+        """
+        if self._taper is None:
+            # Repackaging the args so that scipy.signal.get_window() accepts all cases
+            window_args = [v for k, v in self.additional_args.items()]
+            window_args.insert(0, self.type)
+            window_args = tuple(window_args)
+
+            taper = ssig.get_window(window_args, self.num_samples)
+
+            if self.normalized:
+                taper /= np.sum(taper)
+
+            self._taper = taper
+
+        return self._taper
+
+
+
+def get_fft_harmonics(
+    samples_per_window: int,
+    sample_rate: float
+) -> np.ndarray:
+    """
+    Works for odd and even number of points.
+
+    Development notes:
+    - Could be modified with arguments to support one_sided, two_sided, ignore_dc
+    ignore_nyquist, and etc.  Consider taking FrequencyBands as an argument.
+    - This function was in decimation_level, but there were circular import issues.
+    The function needs only a window length and sample rate, so putting it here for now.
+    - TODO: switch to using np.fft.rfftfreq
+
+    Parameters
+    ----------
+    samples_per_window: int
+        Number of samples in a window that will be Fourier transformed.
+    sample_rate: float
+            Inverse of time step between samples; Samples per second in Hz.
+
+    Returns
+    -------
+    harmonic_frequencies: numpy array
+        The frequencies that the fft will be computed.
+        These are one-sided (positive frequencies only)
+        Does _not_ return Nyquist
+        Does return DC component
+    """
+    delta_t = 1.0 / sample_rate
+    harmonic_frequencies = np.fft.fftfreq(samples_per_window, d=delta_t)
+    n_fft_harmonics = int(samples_per_window / 2)  # no bin at Nyquist,
+    harmonic_frequencies = harmonic_frequencies[0:n_fft_harmonics]
+    return harmonic_frequencies

mt_metadata/transfer_functions/tf/station.py

@@ -12,6 +12,7 @@ Created on Wed Dec 23 21:30:36 2020
 # Imports
 # =============================================================================
 import numpy as np
+import copy
 from collections import OrderedDict
 from mt_metadata.base.helpers import write_lines
 from mt_metadata.base import get_schema, Base
@@ -30,6 +31,7 @@ from . import (
     Run,
     TransferFunction,
 )
+
 from mt_metadata.utils.list_dict import ListDict
 
 # =============================================================================
@@ -56,13 +58,17 @@ attr_dict.add_dict(
 )
 
 attr_dict.add_dict(get_schema("time_period", TS_SCHEMA_FN_PATHS), "time_period")
-attr_dict.add_dict(TransferFunction()._attr_dict, "transfer_function")
+attr_dict.add_dict(
+    copy.deepcopy(TransferFunction()._attr_dict), "transfer_function"
+)
 attr_dict.add_dict(get_schema("copyright", TS_SCHEMA_FN_PATHS), None)
 attr_dict["release_license"]["required"] = False
 attr_dict.add_dict(
     get_schema("citation", TS_SCHEMA_FN_PATHS), None, keys=["doi"]
 )
 attr_dict["doi"]["required"] = False
+
+
 # =============================================================================
 class Station(Base):
     __doc__ = write_lines(attr_dict)
@@ -78,7 +84,17 @@ class Station(Base):
         self.time_period = TimePeriod()
         self.transfer_function = TransferFunction()
         self.runs = ListDict()
+
         super().__init__(attr_dict=attr_dict, **kwargs)
+        # for now this is a hack.  Somewhere processing paramters is being
+        # set globally.  This will reset to default of empty list
+        self.transfer_function.processing_parameters = []
+        try:
+            self.transfer_function.processing_parameters = kwargs[
+                "transfer_function.processing_parameters"
+            ]
+        except KeyError:
+            pass
 
     def __add__(self, other):
         if isinstance(other, Station):

mt_metadata/utils/mttime.py

@@ -7,16 +7,32 @@ Created on Wed May 13 19:10:46 2020
 # =============================================================================
 # IMPORTS
 # =============================================================================
+from copy import deepcopy
 import datetime
 from dateutil.parser import parse as dtparser
-from copy import deepcopy
 import numpy as np
 import pandas as pd
 from pandas._libs.tslibs import OutOfBoundsDatetime
 
+from typing import Optional, Union  # Self is importable in python 3.11+
 
 from loguru import logger
 
+DATETIME_HINT = Union[
+    float,
+    int,
+    np.datetime64,
+    pd.Timestamp,
+    str,
+    datetime.datetime,
+]
+
+try:
+    from obspy.core.utcdatetime import UTCDateTime  # for type hinting
+    DATETIME_HINT = Union[DATETIME_HINT, UTCDateTime]
+except ImportError:
+    pass
+
 # =============================================================================
 #  Get leap seconds
 # =============================================================================
@@ -387,7 +403,10 @@ class MTime:
 
         return t_min_max, pd_timestamp
 
-    def parse(self, dt_str):
+    def parse(
+        self,
+        dt_str: Optional[DATETIME_HINT] = None
+    ) -> None:  # TODO: add Self as s typehint 3.11
         """
         Parse a date-time string using dateutil.parser
 
@@ -441,7 +460,7 @@ class MTime:
 
         else:
             try:
-                stamp = t_min_max, stamp = self._check_timestamp(
+                t_min_max, stamp = self._check_timestamp(
                     pd.Timestamp(dt_str)
                 )
             except (ValueError, TypeError, OutOfBoundsDatetime, OverflowError):

mt_metadata/utils/validators.py

@@ -64,9 +64,11 @@ def validate_header(header, attribute=False):
     else:
         required_keys = [key for key in REQUIRED_KEYS if key != "attribute"]
         if sorted(header) != sorted(required_keys):
+            missing_keys = [x for x in required_keys if x not in header]
             msg = (
-                f"Keys is not correct, must include {required_keys}"
-                + f". Currently has {header}"
+                f"Keys is not correct, must include {required_keys}\n"
+                + f". Currently has {header}\n"
+                +  f"Need to add keys: {missing_keys}"
             )
             raise MTValidatorError(msg)
     return header

{mt_metadata-0.3.9.dist-info → mt_metadata-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
-Name: mt-metadata
-Version: 0.3.9
+Metadata-Version: 2.2
+Name: mt_metadata
+Version: 0.4.0
 Summary: Metadata for magnetotelluric data
 Home-page: https://github.com/kujaku11/mt_metadata
 Author: Jared Peacock
@@ -22,13 +22,29 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.rst
 Requires-Dist: numpy
+Requires-Dist: scipy
 Requires-Dist: pandas
-Requires-Dist: obspy
 Requires-Dist: matplotlib
 Requires-Dist: xarray
 Requires-Dist: loguru
-
-# mt_metadata version 0.3.9
+Provides-Extra: obspy
+Requires-Dist: obspy; extra == "obspy"
+Provides-Extra: test
+Requires-Dist: pytest>=3; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# mt_metadata version 0.4.0
  Standard MT metadata
 
 [![PyPi version](https://img.shields.io/pypi/v/mt_metadata.svg)](https://pypi.python.org/pypi/mt-metadata)
@@ -43,11 +59,11 @@ Requires-Dist: loguru
 
 MT Metadata is a project led by [IRIS-PASSCAL MT Software working group](https://www.iris.edu/hq/about_iris/governance/mt_soft>) and USGS to develop tools that standardize magnetotelluric metadata, well, at least create tools for standards that are generally accepted.  This include the two main types of magnetotelluric data
 
-- **Time Series** 
+- **Time Series**
     - Structured as:
         - Experiment -> Survey -> Station -> Run -> Channel
     - Supports translation to/from **StationXML**
-        
+
 - **Transfer Functions**
     - Supports (will support) to/from:
         - **EDI** (most common format)
@@ -58,11 +74,12 @@ MT Metadata is a project led by [IRIS-PASSCAL MT Software working group](https:/
 
 Most people will be using the transfer functions, but a lot of that metadata comes from the time series metadata.  This module supports both and has tried to make them more or less seamless to reduce complication.
 
-* **Version**: 0.3.9
+* **Version**: 0.4.0
 * **Free software**: MIT license
 * **Documentation**: https://mt-metadata.readthedocs.io.
 * **Examples**: Click the `Binder` badge above and Jupyter Notebook examples are in **mt_metadata/examples/notebooks** and **docs/source/notebooks**
 * **Suggested Citation**: Peacock, J. R., Kappler, K., Ronan, T., Heagy, L.,  Kelbert, A., Frassetto, A. (2022) MTH5: An archive and exchangeable data format for magnetotelluric time series data, *Computers & Geoscience*, **162**, doi:10.1016/j.cageo.2022.105102
+* **IPDS**: IP-138156
 
 
 # Installation
@@ -71,20 +88,27 @@ Most people will be using the transfer functions, but a lot of that metadata com
 
 `git clone https://github.com/kujaku11/mt_metadata.git`
 
-`python setup.py install`
+`pip install .`
 
-You can add the flag `-e` if you want to change the code.
+You can add the flag `-e` if you want to install the source repository in an editable state.
 
 ## PIP
 `pip install mt_metadata`
 
+> You can install with optional packages by appending `[option_name]` to the package name during the
+> `pip` install command. E.g:
+>
+> `pip install mt_metadata[obspy]`
+>
+> or `pip install .[obspy]` if building from source.
+
 ## Conda
 
 `conda install mt_metadata`
 
 # Standards
 
-Each metadata keyword has an associated standard that goes with it.  These are stored internally in JSON file.  The JSON files are read in when the package is loaded to initialize the standards.  Each keyword is described by:  
+Each metadata keyword has an associated standard that goes with it.  These are stored internally in JSON file.  The JSON files are read in when the package is loaded to initialize the standards.  Each keyword is described by:
 
 - **type** - How the value should be represented based on very basic types
 
@@ -100,7 +124,7 @@ Each metadata keyword has an associated standard that goes with it.  These are s
     - *Controlled Vocabulary* only certain values are allowed according to **options**
     - *Date* a date and/or time string in ISO format
     - *Number* a float or integer
-    - *Boolean* the value can only be True or False 
+    - *Boolean* the value can only be True or False
 
 - **units** - Units of the value
 - **description** - Full description of what the metadata key is meant to convey.
@@ -117,7 +141,7 @@ Each metadata object is based on a Base class that has methods:
 - to_from_dict
 - attribute_information
 
-And each object has a doc string that describes the standard: 
+And each object has a doc string that describes the standard:
 
 
 | **Metadata Key**                             | **Description**                               | **Example**    |
@@ -230,7 +254,7 @@ print(x.to_xml(string=True))
 Credits
 -------
 
-This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program. 
+This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program.
 
 
 History