mt_metadata.features ==================== .. py:module:: mt_metadata.features .. autoapi-nested-parse:: ====================== Features Metadata ====================== The Features module provides metadata containers for defining and calculating features from magnetotelluric data in both time domain and frequency domain. Features are computed quantities that characterize data quality, signal properties, or specific aspects of the electromagnetic response. This module supports various feature types including coherence metrics, spectral characteristics, and custom user-defined features. MetadataBase Objects -------------------- * Feature - Base class for all feature metadata, defining feature type, parameters, and computation methods * FeatureTSRun - Time series run features for time domain calculations (e.g., signal statistics, anomaly detection) * FeatureFCRun - Fourier coefficient run features for frequency domain calculations (e.g., spectral quality metrics, transfer function properties) * FeatureDecimationChannel - Channel-specific features at different decimation levels for multi-resolution analysis * StridingWindowCoherence - Coherence calculated over striding windows to assess signal consistency and quality over time * SUPPORTED_FEATURE_DICT - Registry of all available feature types and their configurations Usage ----- Features metadata objects define: - Feature type and calculation method - Input parameters and thresholds - Output specifications - Applicable frequency bands or time windows - Quality control criteria These metadata containers ensure reproducible feature calculations and facilitate sharing of feature extraction pipelines across different processing workflows. Submodules ---------- .. toctree:: :maxdepth: 1 /source/api/mt_metadata/features/coherence/index /source/api/mt_metadata/features/cross_powers/index /source/api/mt_metadata/features/fc_coherence/index /source/api/mt_metadata/features/feature/index /source/api/mt_metadata/features/feature_decimation_channel/index /source/api/mt_metadata/features/feature_fc/index /source/api/mt_metadata/features/feature_fc_run/index /source/api/mt_metadata/features/feature_ts/index /source/api/mt_metadata/features/feature_ts_run/index /source/api/mt_metadata/features/feature_weighting_window/index /source/api/mt_metadata/features/registry/index /source/api/mt_metadata/features/striding_window_coherence/index /source/api/mt_metadata/features/weight_kernel/index /source/api/mt_metadata/features/weights/index Attributes ---------- .. autoapisummary:: mt_metadata.features.SUPPORTED_FEATURE_DICT Classes ------- .. autoapisummary:: mt_metadata.features.FeatureTSRun mt_metadata.features.FeatureFCRun mt_metadata.features.FeatureDecimationChannel mt_metadata.features.Feature mt_metadata.features.StridingWindowCoherence Package Contents ---------------- .. py:class:: FeatureTSRun(**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:: id :type: Annotated[str, Field(default='', description='Suggested Run ID should be sample rate followed by a number or character. Characters should only be used if the run number is small, if the run number is high consider using digits with zeros. For example if you have 100 runs the run ID could be 001 or sr{sample_rate}_001. Should be the same as the time series run ID.', alias=None, pattern='^[a-zA-Z0-9_]*$', json_schema_extra={'units': None, 'required': True, 'examples': ['001']})] .. py:attribute:: sample_rate :type: Annotated[float, Field(default=0.0, description='Digital sample rate for the run', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': ['100']})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='Any comments about the feature', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['estimated using hilburt transform.']})] .. py:attribute:: time_period :type: Annotated[mt_metadata.common.TimePeriod, Field(default_factory=lambda: TimePeriod(), description='Time period for the feature', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['2020-01-01/2020-01-31']})] .. py:method:: validate_comments(value, info) :classmethod: .. py:class:: FeatureFCRun(**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:: id :type: Annotated[str, Field(default='', description='Suggested Run ID should be sample rate followed by a number or character. Characters should only be used if the run number is small, if the run number is high consider using digits with zeros. For example if you have 100 runs the run ID could be 001 or sr{sample_rate}_001. Should be the same as the time series run ID.', alias=None, pattern='^[a-zA-Z0-9_]*$', json_schema_extra={'units': None, 'required': True, 'examples': ['001']})] .. py:attribute:: sample_rate :type: Annotated[float, Field(default=0.0, description='Digital sample rate for the run', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': ['100']})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='Any comments about the feature', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['estimated using hilburt transform.']})] .. py:attribute:: time_period :type: Annotated[mt_metadata.common.TimePeriod, Field(default_factory=lambda: TimePeriod(), description='The time period over which the feature was calculated.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['2020-01-01T00:00:00']})] .. py:method:: validate_comments(value, info) :classmethod: .. py:class:: FeatureDecimationChannel(**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:: name :type: Annotated[str, Field(default='', description='Name of channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['ex']})] .. py:attribute:: frequency_max :type: Annotated[float, Field(default=0.0, description='Highest frequency present in the sprectrogam data.', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': [77.0]})] .. py:attribute:: frequency_min :type: Annotated[float, Field(default=0.0, description='Lowest frequency present in the sprectrogam data.', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': [99.0]})] .. py:attribute:: sample_rate_decimation_level :type: Annotated[float, Field(default=1.0, description='Sample rate of the time series that was Fourier transformed to generate the FC decimation level.', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': [60]})] .. py:attribute:: sample_rate_window_step :type: Annotated[float, Field(default=1.0, description='Sample rate of the windows.', alias=None, json_schema_extra={'units': 'samples per second', 'required': True, 'examples': [4]})] .. py:attribute:: units :type: Annotated[str, Field(default='count', description='Units of the channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['milliVolts']})] .. py:attribute:: time_period :type: Annotated[mt_metadata.common.TimePeriod, Field(default_factory=TimePeriod, description='Time period of the channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': [{'start': '2020-01-01', 'end': '2020-01-02'}]})] .. py:method:: validate_units(value) :classmethod: .. py:class:: Feature(**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:: name :type: Annotated[str, Field(default='', description='Name of the feature.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['simple coherence']})] .. py:attribute:: description :type: Annotated[str, Field(default='', description='A full description of what the feature estimates.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['Simple coherence measures the coherence between measured electric and magnetic fields.']})] .. py:attribute:: domain :type: Annotated[DomainEnum, Field(default=DomainEnum.frequency, description="Temporal domain the feature is estimated in [ 'frequency' | 'time' ]", alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['frequency']})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='Any comments about the feature', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['estimated using hilburt transform.']})] .. py:attribute:: data :type: Annotated[xarray.DataArray | xarray.Dataset | numpy.ndarray | None, Field(default=None, description='The data associated with the feature.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['path/to/datafile.nc']})] .. py:method:: validate_comments(value, info) :classmethod: .. py:method:: validate_data(value, info) :classmethod: .. py:method:: from_feature_id(meta_dict) :classmethod: Factory: instantiate the correct feature class based on 'feature_id'. not sure this is needed anymore. .. py:class:: StridingWindowCoherence(**data) Bases: :py:obj:`mt_metadata.features.coherence.Coherence` Computes coherence for each sub-window (FFT window) across the time series. Returns a 2D array: (window index, frequency). .. py:attribute:: subwindow :type: Annotated[mt_metadata.processing.window.Window, Field(default_factory=Window, description='The window used for the subwindow coherence calculation.', json_schema_extra={'units': None, 'required': False, 'examples': ['hann', 'hamming', 'blackman']})] .. py:method:: set_defaults(data) :classmethod: .. py:method:: set_subwindow_from_window(fraction=0.2) Set the subwindow as a fraction of the main window. .. py:method:: compute(ts_1, ts_2, parallel = False) For each main window (length self.window.num_samples, stride self.window.num_samples_advance), compute coherence using the subwindow parameters (self.subwindow) within that main window. :returns: 1D array of frequencies coherences: 2D array (n_main_windows, n_frequencies) :rtype: frequencies .. py:data:: SUPPORTED_FEATURE_DICT