mt_metadata.features

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

• mt_metadata.features.coherence
• mt_metadata.features.cross_powers
• mt_metadata.features.fc_coherence
• mt_metadata.features.feature
• mt_metadata.features.feature_decimation_channel
• mt_metadata.features.feature_fc
• mt_metadata.features.feature_fc_run
• mt_metadata.features.feature_ts
• mt_metadata.features.feature_ts_run
• mt_metadata.features.feature_weighting_window
• mt_metadata.features.registry
• mt_metadata.features.striding_window_coherence
• mt_metadata.features.weight_kernel
• mt_metadata.features.weights

Attributes

SUPPORTED_FEATURE_DICT

Classes

FeatureTSRun	Base class for all metadata objects with Pydantic validation.
FeatureFCRun	Base class for all metadata objects with Pydantic validation.
FeatureDecimationChannel	Base class for all metadata objects with Pydantic validation.
Feature	Base class for all metadata objects with Pydantic validation.
StridingWindowCoherence	Computes coherence for each sub-window (FFT window) across the time series.

Package Contents

class mt_metadata.features.FeatureTSRun(**data)

Bases: 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.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

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

id: 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']})]

sample_rate: 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']})]

comments: 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.']})]

time_period: 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']})]

classmethod validate_comments(value, info)

class mt_metadata.features.FeatureFCRun(**data)

Bases: 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.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

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

id: 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']})]

sample_rate: 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']})]

comments: 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.']})]

time_period: 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']})]

classmethod validate_comments(value, info)

class mt_metadata.features.FeatureDecimationChannel(**data)

Bases: 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.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

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

name: Annotated[str, Field(default='', description='Name of channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['ex']})]

frequency_max: 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]})]

frequency_min: 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]})]

sample_rate_decimation_level: 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]})]

sample_rate_window_step: 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]})]

units: Annotated[str, Field(default='count', description='Units of the channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['milliVolts']})]

time_period: 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'}]})]

classmethod validate_units(value)

class mt_metadata.features.Feature(**data)

Bases: 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.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:

list[str]

_fields

Private attribute caching field information

Type:

dict[str, Any]

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

name: Annotated[str, Field(default='', description='Name of the feature.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['simple coherence']})]

description: 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.']})]

domain: 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']})]

comments: 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.']})]

data: 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']})]

classmethod validate_comments(value, info)

classmethod validate_data(value, info)

classmethod from_feature_id(meta_dict)

Factory: instantiate the correct feature class based on ‘feature_id’.

not sure this is needed anymore.

class mt_metadata.features.StridingWindowCoherence(**data)

Bases: mt_metadata.features.coherence.Coherence

Computes coherence for each sub-window (FFT window) across the time series. Returns a 2D array: (window index, frequency).

subwindow: 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']})]

classmethod set_defaults(data)

set_subwindow_from_window(fraction=0.2)

Set the subwindow as a fraction of the main window.

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)

Return type:

frequencies

mt_metadata.features.SUPPORTED_FEATURE_DICT