mt-metadata 0.3.3__py2.py3-none-any.whl → 0.3.5__py2.py3-none-any.whl

mt_metadata/__init__.py

@@ -39,7 +39,7 @@ you should only have to changes these dictionaries.
 
 __author__ = """Jared Peacock"""
 __email__ = "jpeacock@usgs.gov"
-__version__ = "0.3.3"
+__version__ = "0.3.5"
 
 # =============================================================================
 # Imports
@@ -82,6 +82,14 @@ REQUIRED_KEYS = [
     "default",
 ]
 
+DEFAULT_CHANNEL_NOMENCLATURE = {
+    "hx": "hx",
+    "hy": "hy",
+    "hz": "hz",
+    "ex": "ex",
+    "ey": "ey",
+}
+
 # =============================================================================
 # Initiate loggers
 # =============================================================================
@@ -152,19 +160,13 @@ TF_POOR_XML = DATA_DIR.joinpath("data/transfer_functions/tf_poor_xml.xml")
 TF_XML_MULTIPLE_ATTACHMENTS = DATA_DIR.joinpath(
     "data/transfer_functions/tf_xml_multiple_attachments.xml"
 )
-TF_EDI_PHOENIX = DATA_DIR.joinpath(
-    "data/transfer_functions/tf_edi_phoenix.edi"
-)
-TF_EDI_EMPOWER = DATA_DIR.joinpath(
-    "data/transfer_functions/tf_edi_empower.edi"
-)
+TF_EDI_PHOENIX = DATA_DIR.joinpath("data/transfer_functions/tf_edi_phoenix.edi")
+TF_EDI_EMPOWER = DATA_DIR.joinpath("data/transfer_functions/tf_edi_empower.edi")
 TF_EDI_METRONIX = DATA_DIR.joinpath(
     "data/transfer_functions/tf_edi_metronix.edi"
 )
 TF_EDI_CGG = DATA_DIR.joinpath("data/transfer_functions/tf_edi_cgg.edi")
-TF_EDI_QUANTEC = DATA_DIR.joinpath(
-    "data/transfer_functions/tf_edi_quantec.edi"
-)
+TF_EDI_QUANTEC = DATA_DIR.joinpath("data/transfer_functions/tf_edi_quantec.edi")
 TF_EDI_RHO_ONLY = DATA_DIR.joinpath(
     "data/transfer_functions/tf_edi_rho_only.edi"
 )

mt_metadata/base/metadata.py

@@ -2,7 +2,7 @@
 """
 Created on Wed Dec 23 20:41:16 2020
 
-:copyright: 
+:copyright:
     Jared Peacock (jpeacock@usgs.gov)
 
 :license: MIT
@@ -113,14 +113,25 @@ class Base:
                 try:
                     other_value = other_dict[key]
                     if isinstance(value, np.ndarray):
+                        if value.size != other_value.size:
+                            msg = f"Array sizes for {key} differ: {value.size} != {other_value.size}"
+                            self.logger.info(msg)
+                            fail=True
+                            continue
                         if not (value == other_value).all():
                             msg = f"{key}: {value} != {other_value}"
                             self.logger.info(msg)
                             fail = True
-                    elif value != other_value:
-                        msg = f"{key}: {value} != {other_value}"
-                        self.logger.info(msg)
-                        fail = True
+                    elif isinstance(value, (float, int, complex)):
+                        if not np.isclose(value, other_value):
+                            msg = f"{key}: {value} != {other_value}"
+                            self.logger.info(msg)
+                            fail = True
+                    else:
+                        if value != other_value:
+                            msg = f"{key}: {value} != {other_value}"
+                            self.logger.info(msg)
+                            fail = True
                 except KeyError:
                     msg = "Cannot find {0} in other".format(key)
                     self.logger.info(msg)
@@ -289,7 +300,7 @@ class Base:
             self.logger.exception(error)
             raise MTSchemaError(error)
 
-    def _validate_option(self, name, option_list):
+    def _validate_option(self, name, value, option_list):
         """
         validate the given attribute name agains possible options and check
         for aliases
@@ -304,21 +315,21 @@ class Base:
         :rtype: TYPE
 
         """
-        if name is None:
+        if value is None:
             return True, False, None
         options = [ss.lower() for ss in option_list]
         other_possible = False
         if "other" in options:
             other_possible = True
-        if name.lower() in options:
+        if value.lower() in options:
             return True, other_possible, None
-        elif name.lower() not in options and other_possible:
+        elif value.lower() not in options and other_possible:
             msg = (
-                "{0} not found in options list {1}, but other options"
-                + " are allowed.  Allowing {2} to be set to {0}."
+                f"Value '{value}' not found for metadata field '{name}' in options list {option_list}, but other options"
+                + f" are allowed.  Allowing {option_list} to be set to {value}."
             )
             return True, other_possible, msg
-        return False, other_possible, "{0} not found in options list {1}"
+        return False, other_possible, f"Value '{value}' for metadata field '{name}' not found in options list {option_list}"
 
     def __setattr__(self, name, value):
         """
@@ -388,7 +399,7 @@ class Base:
                 # check options
                 if v_dict["style"] == "controlled vocabulary":
                     options = v_dict["options"]
-                    accept, other, msg = self._validate_option(value, options)
+                    accept, other, msg = self._validate_option(name, value, options)
                     if not accept:
                         self.logger.error(msg.format(value, options))
                         raise MTSchemaError(msg.format(value, options))

mt_metadata/data/transfer_functions/tf_zmm.zmm

@@ -1,5 +1,5 @@
  TRANSFER FUNCTIONS IN MEASUREMENT COORDINATES
- ********** WITH FULL ERROR COVARINCE*********
+ ********** WITH FULL ERROR COVARIANCE*********
                                                                                 
 300                 
 coordinate    34.727  -115.735 declination    13.10

mt_metadata/timeseries/channel.py

@@ -2,7 +2,7 @@
 """
 Created on Wed Dec 23 21:30:36 2020
 
-:copyright: 
+:copyright:
     Jared Peacock (jpeacock@usgs.gov)
 
 :license: MIT
@@ -16,7 +16,7 @@ from mt_metadata.base.helpers import write_lines
 from mt_metadata.base import get_schema, Base
 from .standards import SCHEMA_FN_PATHS
 from . import DataQuality, Filtered, Location, TimePeriod, Instrument, Fdsn
-from mt_metadata.timeseries.filters import ChannelResponseFilter
+from mt_metadata.timeseries.filters import ChannelResponse
 
 # =============================================================================
 attr_dict = get_schema("channel", SCHEMA_FN_PATHS)
@@ -79,4 +79,9 @@ class Channel(Base):
                 self.logger.error(msg)
                 continue
         # compute instrument sensitivity and units in/out
-        return ChannelResponseFilter(filters_list=mt_filter_list)
+        return ChannelResponse(filters_list=mt_filter_list)
+
+    @property
+    def unit_object(self):
+        from mt_metadata.utils.units import get_unit_object
+        return get_unit_object(self.units)

mt_metadata/timeseries/filters/__init__.py

@@ -3,7 +3,7 @@ from .fir_filter import FIRFilter
 from .pole_zero_filter import PoleZeroFilter
 from .time_delay_filter import TimeDelayFilter
 from .frequency_response_table_filter import FrequencyResponseTableFilter
-from .channel_response_filter import ChannelResponseFilter
+from .channel_response import ChannelResponse
 
 
 __all__ = [
@@ -12,5 +12,5 @@ __all__ = [
     "PoleZeroFilter",
     "TimeDelayFilter",
     "FrequencyResponseTableFilter",
-    "ChannelResponseFilter",
+    "ChannelResponse",
 ]

mt_metadata/timeseries/filters/{channel_response_filter.py → channel_response.py}

@@ -3,11 +3,11 @@
 Channel Response Filter
 ==========================
 
-Combines all filters for a given channel into a total response that can be used in 
+Combines all filters for a given channel into a total response that can be used in
 the frequency domain.
 
-.. note:: Time Delay filters should be applied in the time domain 
-    otherwise bad things can happen.   
+.. note:: Time Delay filters should be applied in the time domain
+    otherwise bad things can happen.
 """
 # =============================================================================
 # Imports
@@ -24,6 +24,7 @@ from mt_metadata.timeseries.filters import (
     FrequencyResponseTableFilter,
     FIRFilter,
 )
+from mt_metadata.timeseries.filters.filter_base import FilterBase
 from mt_metadata.utils.units import get_unit_object
 from mt_metadata.timeseries.filters.plotting_helpers import plot_response
 from obspy.core import inventory
@@ -33,9 +34,11 @@ attr_dict = get_schema("channel_response", SCHEMA_FN_PATHS)
 # =============================================================================
 
 
-class ChannelResponseFilter(Base):
+class ChannelResponse(Base):
     """
     This class holds a list of all the filters associated with a channel.
+    The list should be ordered to match the order in which the filters are applied to the signal.
+
     It has methods for combining the responses of all the filters into a total
     response that we will apply to a data segment.
     """
@@ -60,6 +63,7 @@ class ChannelResponseFilter(Base):
     def __repr__(self):
         return self.__str__()
 
+
     @property
     def filters_list(self):
         """filters list"""
@@ -106,7 +110,7 @@ class ChannelResponseFilter(Base):
 
     def _validate_filters_list(self, filters_list):
         """
-        make sure the filters list is valid
+        make sure the filters list is valid.
 
         :param filters_list: DESCRIPTION
         :type filters_list: TYPE
@@ -114,7 +118,7 @@ class ChannelResponseFilter(Base):
         :rtype: TYPE
 
         """
-        ACCEPTABLE_FILTERS = [
+        supported_filters = [
             PoleZeroFilter,
             CoefficientFilter,
             TimeDelayFilter,
@@ -122,8 +126,8 @@ class ChannelResponseFilter(Base):
             FIRFilter,
         ]
 
-        def is_acceptable_filter(item):
-            if isinstance(item, tuple(ACCEPTABLE_FILTERS)):
+        def is_supported_filter(item):
+            if isinstance(item, tuple(supported_filters)):
                 return True
             else:
                 return False
@@ -139,11 +143,11 @@ class ChannelResponseFilter(Base):
         fails = []
         return_list = []
         for item in filters_list:
-            if is_acceptable_filter(item):
+            if is_supported_filter(item):
                 return_list.append(item)
             else:
                 fails.append(
-                    f"Item is not an acceptable filter type, {type(item)}"
+                    f"Item is not a supported filter type, {type(item)}"
                 )
 
         if fails:
@@ -222,15 +226,46 @@ class ChannelResponseFilter(Base):
             total_delay += delay_filter.delay
         return total_delay
 
+    def get_indices_of_filters_to_remove(self, include_decimation=False, include_delay=False):
+        indices = list(np.arange(len(self.filters_list)))
+
+        if not include_delay:
+            indices = [i for i in indices if self.filters_list[i].type != "time delay"]
+
+        if not include_decimation:
+            indices = [i for i in indices if not self.filters_list[i].decimation_active]
+
+        return indices
+
+    def get_list_of_filters_to_remove(self, include_decimation=False, include_delay=False):
+        """
+
+        :param include_decimation: bool
+        :param include_delay: bool
+        :return:
+
+        # Experimental snippet if we want to allow filters with the opposite convention
+        # into channel response -- I don't think we do.
+        # if self.correction_operation == "multiply":
+        #     inverse_filters = [x.inverse() for x in self.filters_list]
+        #     self.filters_list = inverse_filters
+        """
+        indices = self.get_indices_of_filters_to_remove(include_decimation=include_decimation,
+                                                        include_delay=include_delay)
+        return [self.filters_list[i] for i in indices]
+
     def complex_response(
         self,
         frequencies=None,
+        filters_list=None,
+        include_decimation=False,
         include_delay=False,
         normalize=False,
-        include_decimation=True,
         **kwargs,
     ):
         """
+        Computes the complex response of self.
+        Allows the user to optionally supply a subset of filters
 
         :param frequencies: frequencies to compute complex response,
          defaults to None
@@ -238,35 +273,31 @@ class ChannelResponseFilter(Base):
         :param include_delay: include delay in complex response,
          defaults to False
         :type include_delay: bool, optional
-        :param normalize: normalize the response to 1, defaults to False
-        :type normalize: bool, optional
         :param include_decimation: Include decimation in response,
          defaults to True
         :type include_decimation: bool, optional
+        :param normalize: normalize the response to 1, defaults to False
+        :type normalize: bool, optional
         :return: complex response along give frequency array
         :rtype: np.ndarray
 
         """
-
         if frequencies is not None:
             self.frequencies = frequencies
 
-        if include_delay:
-            filters_list = deepcopy(self.filters_list)
-        else:
-            filters_list = deepcopy(self.non_delay_filters)
-
-        if not include_decimation:
-            filters_list = deepcopy(
-                [x for x in filters_list if not x.decimation_active]
-            )
+        # make filters list if not supplied
+        if filters_list is None:
+            self.logger.warning("Filters list not provided, building list assuming all are applied")
+            filters_list = self.get_list_of_filters_to_remove(
+                include_decimation=include_decimation,
+            include_delay=include_delay)
 
         if len(filters_list) == 0:
-            # warn that there are no filters associated with channel?
+            self.logger.warning(f"No filters associated with {self.__class__}, returning 1")
             return np.ones(len(self.frequencies), dtype=complex)
 
+        # define the product of all filters as the total response function
         result = filters_list[0].complex_response(self.frequencies)
-
         for ff in filters_list[1:]:
             result *= ff.complex_response(self.frequencies)
 
@@ -274,6 +305,7 @@ class ChannelResponseFilter(Base):
             result /= np.max(np.abs(result))
         return result
 
+
     def compute_instrument_sensitivity(
         self, normalization_frequency=None, sig_figs=6
     ):
@@ -310,8 +342,8 @@ class ChannelResponseFilter(Base):
         """
         if self.filters_list is [] or len(self.filters_list) == 0:
             return None
-
-        return self.filters_list[0].units_in
+        else:
+            return self.filters_list[0].units_in
 
     @property
     def units_out(self):
@@ -320,8 +352,9 @@ class ChannelResponseFilter(Base):
         """
         if self.filters_list is [] or len(self.filters_list) == 0:
             return None
+        else:
+            return self.filters_list[-1].units_out
 
-        return self.filters_list[-1].units_out
 
     def _check_consistency_of_units(self):
         """
@@ -409,7 +442,7 @@ class ChannelResponseFilter(Base):
         pb_tol=1e-1,
         interpolation_method="slinear",
         include_delay=False,
-        include_decimation=True,
+        include_decimation=False,
     ):
         """
         Plot the response

mt_metadata/timeseries/filters/coefficient_filter.py

@@ -4,11 +4,10 @@ from obspy.core import inventory
 
 from mt_metadata.base import get_schema
 from mt_metadata.timeseries.filters.filter_base import FilterBase
-from mt_metadata.timeseries.filters.filter_base import OBSPY_MAPPING
+from mt_metadata.timeseries.filters.filter_base import get_base_obspy_mapping
 from mt_metadata.timeseries.filters.standards import SCHEMA_FN_PATHS
 from mt_metadata.base.helpers import write_lines
 
-obspy_mapping = copy.deepcopy(OBSPY_MAPPING)
 
 # =============================================================================
 attr_dict = get_schema("filter_base", SCHEMA_FN_PATHS)
@@ -24,7 +23,6 @@ class CoefficientFilter(FilterBase):
 
         super(FilterBase, self).__init__(attr_dict=attr_dict, **kwargs)
         self.type = "coefficient"
-        self.obspy_mapping = obspy_mapping
 
         if self.gain == 0.0:
             self.gain = 1.0

mt_metadata/timeseries/filters/filter_base.py

@@ -2,36 +2,41 @@
 """
 Created on Wed Dec 23 21:30:36 2020
 
-:copyright: 
+:copyright:
     Jared Peacock (jpeacock@usgs.gov)
     Karl Kappler
 
 :license: MIT
 
-This is a base class for filters.  We will extend this class for each specific 
-type of filter we need to implement.  Typical filters we will want to be able
-to support are:
-    
+This is a base class for filters associated with calibration and instrument
+and acquistion system responses. We will extend this class for each specific
+type of filter we need to implement. Typical filters we will want to support:
+
  - PoleZero (or 'zpk') responses like those provided by IRIS
  - Frequency-Amplitude-Phase (FAP) tables: look up tables from laboratory
    calibrations via frequency sweep on a spectrum analyser.
- - Time Delay Filters: can come about in decimation, or from general 
+ - Time Delay Filters: can come about in decimation, or from general
    timing errors that have been characterized
  - Coefficient multipliers, i.e. frequency independent gains
  - FIR filters
  - IIR filters
 
-Note that many filters can be represented in more than one of these forms. 
-For example a Coefficient Multiplier can be seen as an FIR with a single 
-coefficient.  Similarly, an FIR can be represented as a 'zpk' filter with 
-no poles.  An IIR filter can also be associated with a zpk representation. 
-However, solving for the 'zpk' representation can be tedious and approximate
-and if we have for example, the known FIR coefficients, or FAP lookup table,
-then there is little to be gained by changing the representation.
+Many filters can be represented in more than one of these forms. For example
+a Coefficient Multiplier can be seen as an FIR with a single coefficient.
+Similarly, an FIR can be represented as a 'zpk' filter with no poles.  An
+IIR filter can also be associated with a zpk representation.  However, solving
+for the 'zpk' representation can be tedious and approximate and if we have for
+example, the known FIR coefficients, or FAP lookup table, then there is little
+to be gained by changing the representation.
 
 The 'stages' that are described in the IRIS StationXML documentation appear
 to cover all possible linear time invariant filter types we are likely to
 encounter.
+
+A FilterBase object has a direction, defined by has units_in and units_out attrs.
+These are the units before and after multiplication by the complex_response
+of the filter in frequency domain.  It is very similar to an "obspy filter stage"
+
 """
 # =============================================================================
 # Imports
@@ -53,16 +58,35 @@ from mt_metadata.utils.mttime import MTime
 attr_dict = get_schema("filter_base", SCHEMA_FN_PATHS)
 # =============================================================================
 
-# Form is OBSPY_MAPPING['obspy_label'] = 'mth5_label'
-OBSPY_MAPPING = {}
-OBSPY_MAPPING["input_units"] = "units_in"
-OBSPY_MAPPING["name"] = "name"
-OBSPY_MAPPING["output_units"] = "units_out"
-OBSPY_MAPPING["stage_gain"] = "gain"
-OBSPY_MAPPING["description"] = "comments"
+def get_base_obspy_mapping():
+    """
+    Different filters have different mappings, but the attributes mapped here are common to all of them.
+    Hence the name "base obspy mapping"
+    Note: If we wanted to support inverse forms of these filters, and argument specifying filter direction could be added.
+
+    :return: mapping to an obspy filter, mapping['obspy_label'] = 'mt_metadata_label'
+    :rtype: dict
+    """
+    mapping = {}
+    mapping["description"] = "comments"
+    mapping["name"] = "name"
+    mapping["stage_gain"] = "gain"
+    mapping["input_units"] = "units_in"
+    mapping["output_units"] = "units_out"
+    return mapping
 
 
 class FilterBase(Base):
+    """
+    bstract base class is used to represent various forms of linear, time invariant (LTI) filters.
+    By convention, forward application of the filter is equivalent to multiplication in frequency domain by the
+    filter's complex response.  Removing the filter (applying the inverse) can be achieved by divding by the
+    filter's complex response.
+
+    This class is intended to support the calibration of data from archived units to physical units, although
+    it may find more application in future.
+
+    """
     __doc__ = write_lines(attr_dict)
 
     def __init__(self, **kwargs):
@@ -72,7 +96,7 @@ class FilterBase(Base):
 
         self._calibration_dt = MTime()
         self.comments = None
-        self.obspy_mapping = copy.deepcopy(OBSPY_MAPPING)
+        self._obspy_mapping = None
         self.gain = 1.0
 
         super().__init__(attr_dict=attr_dict, **kwargs)
@@ -80,6 +104,10 @@ class FilterBase(Base):
         if self.gain == 0.0:
             self.gain = 1.0
 
+    def make_obspy_mapping(self):
+        mapping = get_base_obspy_mapping()
+        return mapping
+
     @property
     def obspy_mapping(self):
         """
@@ -88,8 +116,23 @@ class FilterBase(Base):
         :rtype: dict
 
         """
+        if self._obspy_mapping is None:
+            self._obspy_mapping = self.make_obspy_mapping()
         return self._obspy_mapping
 
+    @obspy_mapping.setter
+    def obspy_mapping(self, obspy_dict):
+        """
+        set the obspy mapping: this is a dictionary relating attribute labels from obspy stage objects to
+        mt_metadata filter objects.
+        """
+        if not isinstance(obspy_dict, dict):
+            msg = f"Input must be a dictionary not {type(obspy_dict)}"
+            self.logger.error(msg)
+            raise TypeError(msg)
+
+        self._obspy_mapping = obspy_dict
+
     @property
     def name(self):
         """
@@ -114,18 +157,6 @@ class FilterBase(Base):
         else:
             self._name = None
 
-    @obspy_mapping.setter
-    def obspy_mapping(self, obspy_dict):
-        """
-        set the obspy mapping: this is a dictionary relating attribute labels from obspy stage objects to
-        mt_metadata filter objects.
-        """
-        if not isinstance(obspy_dict, dict):
-            msg = f"Input must be a dictionary not {type(obspy_dict)}"
-            self.logger.error(msg)
-            raise TypeError(msg)
-
-        self._obspy_mapping = obspy_dict
 
     @property
     def calibration_date(self):
@@ -214,6 +245,7 @@ class FilterBase(Base):
     @classmethod
     def from_obspy_stage(cls, stage, mapping=None):
         """
+        Expected to return a multiply operation function
 
         :param cls: a filter object
         :type cls: filter object
@@ -231,11 +263,11 @@ class FilterBase(Base):
 
         if not isinstance(stage, obspy.core.inventory.response.ResponseStage):
             msg = f"Expected a Stage and got a {type(stage)}"
-            cls.logger.error(msg)
+            cls().logger.error(msg)
             raise TypeError(msg)
 
         if mapping is None:
-            mapping = cls().obspy_mapping
+            mapping = cls().make_obspy_mapping()
         kwargs = {}
         for obspy_label, mth5_label in mapping.items():
             try:
@@ -243,11 +275,11 @@ class FilterBase(Base):
             except KeyError:
                 print(f"Key {obspy_label} not found in stage object")
                 raise Exception
-
         return cls(**kwargs)
 
     def complex_response(self, frqs):
-        print("Filter Base class does not have a complex response defined")
+        msg = f"complex_response not defined for {self._class_name} class"
+        self.logger.info(msg)
         return None
 
     def pass_band(self, frequencies, window_len=5, tol=0.5, **kwargs):
@@ -371,3 +403,4 @@ class FilterBase(Base):
             if self.decimation_factor != 1.0:
                 return True
         return False
+