mt_metadata.timeseries.channel

Classes

ChannelBase	Base class for all metadata objects with Pydantic validation.
Channel	Base class for all metadata objects with Pydantic validation.

Module Contents

class mt_metadata.timeseries.channel.ChannelBase(**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

channel_number: Annotated[int, Field(default=0, description='Channel number on the data logger.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['1']})]

channel_id: Annotated[str | None, Field(default=None, description='channel id given by the user or data logger', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['1001.11']})]

comments: Annotated[mt_metadata.common.Comment, Field(default_factory=Comment, description='Any comments about the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['ambient air temperature was chilly, ice on cables']})]

component: Annotated[str, Field(default='auxiliary_default', description="Name of the component measured, can be uppercase and/or lowercase.  For now electric channels should start with an 'e' and magnetic channels start with an 'h', followed by the component. If there are multiples of the same channel the name could include an integer.  {type}{component}{number} --> Ex01.", alias=None, pattern='\\w+', json_schema_extra={'units': None, 'required': True, 'examples': ['ex']})]

measurement_azimuth: Annotated[float, Field(default=0.0, description='Horizontal azimuth of the channel in measurement coordinate system spcified in station.orientation.reference_frame.  Default reference frame is a geographic right-handed coordinate system with north=0, east=90, vertical=+ downward.', validation_alias=AliasChoices('measurement_azimuth', 'azimuth'), json_schema_extra={'units': 'degrees', 'required': True, 'examples': [0.0]})]

measurement_tilt: Annotated[float, Field(default=0.0, description='Vertical tilt of the channel in measurement coordinate system specified in station.orientation.reference_frame.  Default reference frame is a geographic right-handed coordinate system with north=0, east=90, vertical=+ downward.', validation_alias=AliasChoices('measurement_tilt', 'dip'), json_schema_extra={'units': 'degrees', 'required': True, 'examples': [0]})]

sample_rate: Annotated[float, Field(default=0.0, description='Digital sample rate', validation_alias=AliasChoices('sample_rate', 'sampling_rate'), json_schema_extra={'units': 'samples per second', 'required': True, 'examples': [8.0]})]

translated_azimuth: Annotated[float | None, Field(default=None, description='Horizontal azimuth of the channel in translated coordinate system, this should only be used for derived product.  For instance if you collected your data in geomagnetic coordinates and then translated them to geographic coordinates you would set measurement_azimuth=0, translated_azimuth=-12.5 for a declination angle of N12.5E.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': [0.0]})]

translated_tilt: Annotated[float | None, Field(default=None, description='Tilt of channel in translated coordinate system, this should only be used for derived product.  For instance if you collected your data using a tripod you would set measurement_tilt=45, translated_tilt=0 for a vertical component.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': [0.0]})]

type: Annotated[str, Field(default='base', description='Data type for the channel, should be a descriptive word that a user can understand.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['temperature']})]

units: Annotated[str, Field(default='', description="Units of the data, should be in SI units and represented as the full name of the unit all lowercase.  If a complex unit use 'per' and '-'.", alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['celsius']})]

data_quality: Annotated[mt_metadata.common.DataQuality, Field(default_factory=DataQuality, description='Data quality for the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['DataQuality()']})]

filters: Annotated[list[mt_metadata.timeseries.AppliedFilter], Field(default_factory=list, description='Filter data for the channel.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ["AppliedFilter(name='filter_name', applied=True, stage=1)"]})]

time_period: Annotated[mt_metadata.common.TimePeriod, Field(default_factory=TimePeriod, description='Time period for the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ["TimePeriod(start='2020-01-01', end='2020-12-31')"]})]

fdsn: Annotated[mt_metadata.common.Fdsn, Field(default_factory=Fdsn, description='FDSN information for the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Fdsn()']})]

classmethod validate_component(value)

make sure the value is all lower case

classmethod validate_comments(value, info)

Validate that the value is a valid comment.

classmethod validate_units(value, info)

validate units base on input string will return the long name

Parameters:

• value (units string) – unit string separated by either ‘/’ for division or ‘ ‘ for multiplication. Or ‘per’ and ‘ ‘, respectively

• info (ValidationInfo) – _description_

Returns:

return the long descriptive name of the unit. For example ‘kilometers’.

Return type:

str

classmethod validate_type(value, info)

Validate that the type channel

classmethod parse_filters_string(value)

Parse string representation of filters into list of AppliedFilter objects

classmethod validate_filters(value, info)

sort the filters by stage number and check for duplicates

add_filter(applied_filter=None, name=None, applied=True, stage=None, comments=None)

Add a filter to the filter list.

Parameters:

• name (str) – Name of the filter.

• applied (bool, optional) – Whether the filter has been applied, by default True.

• stage (int | None, optional) – Stage of the filter in the processing chain, by default None.

property filter_names: list[str]

List of filter names applied to the channel.

Returns:

List of filter names.

Return type:

list[str]

remove_filter(name, reset_stages=True)

Remove a filter from the filter list.

Parameters:

• name (str) – Name of the filter to remove.

• reset_stages (bool, optional) – Whether to reset the stages of the remaining filters, by default True.

get_filter(name)

Get a filter from the filter list by name.

Parameters:

name (str) – Name of the filter to get.

Returns:

The filter with the given name, or None if not found.

Return type:

AppliedFilter | None

channel_response(filters_dict)

full channel response from a dictionary of filter objects

property unit_object: mt_metadata.common.units.Unit

Some channels have a unit object that is used to convert between units. This is a property that returns the unit object for the channel. The unit object is created using the units attribute of the channel. The unit object is used to convert between units and to get the unit

Returns:

BaseModel object with unit attributes

Return type:

Unit

from_dict(meta_dict, skip_none=False)

Fill attributes from a dictionary with backwards compatibility for legacy filter formats.

Parameters:

• meta_dict (dict) – Dictionary of attributes to set.

• skip_none (bool, optional) – If True, skip attributes with None values, by default False.

Raises:

MTSchemaError – If the input dictionary is not valid.

Notes

Supports backwards compatibility for three filter formats:

1. Legacy format (oldest): - Keys: ‘filter.applied’, ‘filter.name’ - Values: Lists of booleans and strings

2. Old format (intermediate): - Keys: ‘filtered.applied’, ‘filtered.name’ - Values: Lists of booleans and strings

3. New format (current): - Key: ‘filters’ - Value: List of AppliedFilter objects or dictionaries

All legacy formats are automatically converted to the new format using AppliedFilter objects. A warning is issued when legacy formats are detected.

class mt_metadata.timeseries.channel.Channel(**data)

Bases: ChannelBase

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

sensor: Annotated[mt_metadata.common.Instrument, Field(default_factory=Instrument, description='Sensor for the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'Instrument()'})]

location: Annotated[mt_metadata.common.BasicLocation, Field(default_factory=BasicLocation, description='Location information for the channel.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['BasicLocation(latitude=0.0, longitude=0.0, elevation=0.0)']})]