mt_metadata.timeseries.channel ============================== .. py:module:: mt_metadata.timeseries.channel Classes ------- .. autoapisummary:: mt_metadata.timeseries.channel.ChannelBase mt_metadata.timeseries.channel.Channel Module Contents --------------- .. py:class:: ChannelBase(**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:: channel_number :type: Annotated[int, Field(default=0, description='Channel number on the data logger.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['1']})] .. py:attribute:: channel_id :type: 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']})] .. py:attribute:: comments :type: 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']})] .. py:attribute:: component :type: 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']})] .. py:attribute:: measurement_azimuth :type: 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]})] .. py:attribute:: measurement_tilt :type: 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]})] .. py:attribute:: sample_rate :type: 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]})] .. py:attribute:: translated_azimuth :type: 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]})] .. py:attribute:: translated_tilt :type: 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]})] .. py:attribute:: type :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']})] .. py:attribute:: units :type: 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']})] .. py:attribute:: data_quality :type: 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()']})] .. py:attribute:: filters :type: 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)"]})] .. py:attribute:: time_period :type: 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')"]})] .. py:attribute:: fdsn :type: 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()']})] .. py:method:: validate_component(value) :classmethod: make sure the value is all lower case .. py:method:: validate_comments(value, info) :classmethod: Validate that the value is a valid comment. .. py:method:: validate_units(value, info) :classmethod: validate units base on input string will return the long name :param value: unit string separated by either '/' for division or ' ' for multiplication. Or 'per' and ' ', respectively :type value: units string :param info: _description_ :type info: ValidationInfo :returns: return the long descriptive name of the unit. For example 'kilometers'. :rtype: str .. py:method:: validate_type(value, info) :classmethod: Validate that the type channel .. py:method:: parse_filters_string(value) :classmethod: Parse string representation of filters into list of AppliedFilter objects .. py:method:: validate_filters(value, info) :classmethod: sort the filters by stage number and check for duplicates .. py:method:: add_filter(applied_filter = None, name = None, applied = True, stage = None, comments = None) Add a filter to the filter list. :param name: Name of the filter. :type name: str :param applied: Whether the filter has been applied, by default True. :type applied: bool, optional :param stage: Stage of the filter in the processing chain, by default None. :type stage: int | None, optional .. py:property:: filter_names :type: list[str] List of filter names applied to the channel. :returns: List of filter names. :rtype: list[str] .. py:method:: remove_filter(name, reset_stages = True) Remove a filter from the filter list. :param name: Name of the filter to remove. :type name: str :param reset_stages: Whether to reset the stages of the remaining filters, by default True. :type reset_stages: bool, optional .. py:method:: get_filter(name) Get a filter from the filter list by name. :param name: Name of the filter to get. :type name: str :returns: The filter with the given name, or None if not found. :rtype: AppliedFilter | None .. py:method:: channel_response(filters_dict) full channel response from a dictionary of filter objects .. py:property:: unit_object :type: 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 :rtype: Unit .. py:method:: from_dict(meta_dict, skip_none = False) Fill attributes from a dictionary with backwards compatibility for legacy filter formats. :param meta_dict: Dictionary of attributes to set. :type meta_dict: dict :param skip_none: If True, skip attributes with None values, by default False. :type skip_none: bool, optional :raises MTSchemaError: If the input dictionary is not valid. .. rubric:: 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. .. py:class:: Channel(**data) Bases: :py:obj:`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. .. 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:: sensor :type: 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()'})] .. py:attribute:: location :type: 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)']})]