mt_metadata.common ================== .. py:module:: mt_metadata.common .. autoapi-nested-parse:: ====================== common metadata ====================== There are multiple containers for each type of metadata, named appropriately. These are common metadata containers. They all inherit from MetadataBase. MetadataBase Objects -------------------- * MTime - Time representation with validation * Comment - Structured comment metadata * ListDict - Dictionary of lists for multi-valued attributes * MinMaxRange - Numeric range with min/max values * StartEndRange - Time or value range with start/end * Declination - Magnetic declination information * GeographicLocation - Geographic coordinates and location data * Orientation - Sensor orientation parameters * Instrument - Instrument specifications and metadata * Fdsn - FDSN (International Federation of Digital Seismograph Networks) metadata * Rating - Data quality rating information * DataQuality - Comprehensive data quality metrics * Citation - Publication and citation information * Copyright - Copyright and licensing details * Person - Person contact information * AuthorPerson - Author-specific metadata * FundingSource - Funding agency and grant information * Software - Software and processing tool metadata * TimePeriod - Time period with start/end times * TimePeriodDate - Time period using dates * Provenance - Data provenance and processing history * BasicLocation - Basic location without datum * BasicLocationNoDatum - Minimal location information * Location - Full location with datum and projection * StationLocation - Station-specific location metadata * Band - Frequency band definition Created on Sun Apr 24 20:50:41 2020 :copyright: Jared Peacock (jpeacock@usgs.gov) :license: MIT Submodules ---------- .. toctree:: :maxdepth: 1 /source/api/mt_metadata/common/band/index /source/api/mt_metadata/common/citation/index /source/api/mt_metadata/common/comment/index /source/api/mt_metadata/common/copyright/index /source/api/mt_metadata/common/data_quality/index /source/api/mt_metadata/common/declination/index /source/api/mt_metadata/common/enumerations/index /source/api/mt_metadata/common/fdsn/index /source/api/mt_metadata/common/funding_source/index /source/api/mt_metadata/common/geographic_location/index /source/api/mt_metadata/common/instrument/index /source/api/mt_metadata/common/list_dict/index /source/api/mt_metadata/common/location/index /source/api/mt_metadata/common/mttime/index /source/api/mt_metadata/common/orientation/index /source/api/mt_metadata/common/person/index /source/api/mt_metadata/common/provenance/index /source/api/mt_metadata/common/range/index /source/api/mt_metadata/common/rating/index /source/api/mt_metadata/common/software/index /source/api/mt_metadata/common/time_period/index /source/api/mt_metadata/common/units/index Classes ------- .. autoapisummary:: mt_metadata.common.ChannelLayoutEnum mt_metadata.common.ChannelOrientationEnum mt_metadata.common.DataTypeEnum mt_metadata.common.ArrayDTypeEnum mt_metadata.common.FilterTypeEnum mt_metadata.common.GeographicReferenceFrameEnum mt_metadata.common.GeomagneticModelEnum mt_metadata.common.StdEDIversionsEnum mt_metadata.common.LicenseEnum mt_metadata.common.OrientationMethodEnum mt_metadata.common.SignConventionEnum mt_metadata.common.SymmetryEnum mt_metadata.common.MTime mt_metadata.common.Comment mt_metadata.common.ListDict mt_metadata.common.MinMaxRange mt_metadata.common.StartEndRange mt_metadata.common.Declination mt_metadata.common.GeographicLocation mt_metadata.common.Orientation mt_metadata.common.Instrument mt_metadata.common.Fdsn mt_metadata.common.Rating mt_metadata.common.DataQuality mt_metadata.common.Citation mt_metadata.common.Copyright mt_metadata.common.AuthorPerson mt_metadata.common.Person mt_metadata.common.FundingSource mt_metadata.common.Software mt_metadata.common.TimePeriod mt_metadata.common.TimePeriodDate mt_metadata.common.Provenance mt_metadata.common.BasicLocation mt_metadata.common.BasicLocationNoDatum mt_metadata.common.Location mt_metadata.common.StationLocation mt_metadata.common.Band mt_metadata.common.CenterAveragingTypeEnum mt_metadata.common.ClosedEnum Package Contents ---------------- .. py:class:: ChannelLayoutEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: L :value: 'L' .. py:attribute:: X :value: 'X' .. py:attribute:: plus :value: '+' .. py:class:: ChannelOrientationEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: orthogonal :value: 'orthogonal' .. py:attribute:: station :value: 'station' .. py:attribute:: site_layout :value: 'sitelayout' .. py:class:: DataTypeEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: RMT :value: 'RMT' .. py:attribute:: AMT :value: 'AMT' .. py:attribute:: BBMT :value: 'BBMT' .. py:attribute:: LPMT :value: 'LPMT' .. py:attribute:: ULPMT :value: 'ULPMT' .. py:attribute:: MT :value: 'MT' .. py:attribute:: LP :value: 'LP' .. py:attribute:: BB :value: 'BB' .. py:attribute:: WB :value: 'WB' .. py:attribute:: MT_TF :value: 'MT_TF' .. py:attribute:: BBMT_TF :value: 'BBMT_TF' .. py:attribute:: WBMT_TF :value: 'WBMT_TF' .. py:attribute:: LPMT_TF :value: 'LPMT_TF' .. py:attribute:: CSAMT :value: 'CSAMT' .. py:attribute:: NSAMT :value: 'NSAMT' .. py:class:: ArrayDTypeEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: real_type :value: 'real' .. py:attribute:: complex_type :value: 'complex' .. py:attribute:: float_type :value: 'float' .. py:attribute:: int_type :value: 'int' .. py:attribute:: complex_128_type :value: 'complex128' .. py:attribute:: complex_64_type :value: 'complex64' .. py:attribute:: float_64_type :value: 'float64' .. py:attribute:: float_32_type :value: 'float32' .. py:attribute:: float_16_type :value: 'float16' .. py:attribute:: int_64_type :value: 'int64' .. py:attribute:: int_32_type :value: 'int32' .. py:attribute:: int_16_type :value: 'int16' .. py:attribute:: int_8_type :value: 'int8' .. py:class:: FilterTypeEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: fap_table :value: 'fap' .. py:attribute:: zpk :value: 'zpk' .. py:attribute:: time_delay :value: 'time_delay' .. py:attribute:: coefficient :value: 'coefficient' .. py:attribute:: fir :value: 'fir' .. py:class:: GeographicReferenceFrameEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: geographic :value: 'geographic' .. py:attribute:: geomagnetic :value: 'geomagnetic' .. py:attribute:: station :value: 'station' .. py:attribute:: site_layout :value: 'sitelayout' .. py:class:: GeomagneticModelEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` split by - if needed .. py:attribute:: EMAG2 :value: 'EMAG2' .. py:attribute:: EMM :value: 'EMM' .. py:attribute:: HDGM :value: 'HDGM' .. py:attribute:: IGRF :value: 'IGRF' .. py:attribute:: WMM :value: 'WMM' .. py:attribute:: unknown :value: 'unknown' .. py:class:: StdEDIversionsEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: SEG_1 :value: 'SEG 1.0' .. py:attribute:: one :value: '1.0' .. py:attribute:: SEG_10 :value: 'SEG_1.0' .. py:attribute:: SEG_101 :value: 'SEG 1.01' .. py:attribute:: SEG_1011 :value: 'SEG_1.01' .. py:class:: LicenseEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` Enumeration of software licenses. Dynamically loaded from JSON data. .. py:class:: OrientationMethodEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: compass :value: 'compass' .. py:attribute:: GPS :value: 'GPS' .. py:attribute:: theodolite :value: 'theodolite' .. py:class:: SignConventionEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: plus :value: '+' .. py:attribute:: minus :value: '-' .. py:attribute:: exp_plus :value: 'exp(+iwt)' .. py:attribute:: exp_minus :value: 'exp(-iwt)' .. py:attribute:: exp_plus_iwt :value: 'exp(+ i\\omega t)' .. py:attribute:: exp_minus_iwt :value: 'exp(- i\\omega t)' .. py:class:: SymmetryEnum Bases: :py:obj:`StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: NONE :value: 'NONE' .. py:attribute:: ODD :value: 'ODD' .. py:attribute:: EVEN :value: 'EVEN' .. py:class:: MTime(/, **data) Bases: :py:obj:`pydantic.BaseModel` Date and time container based on pandas.Timestamp with UTC enforcement. A flexible datetime container that accepts various input formats and converts them to a UTC-localized pandas.Timestamp object. Provides convenient access to date/time components and handles nanosecond precision. :param time_stamp: Input timestamp in various formats: - float/int: epoch seconds - np.number: numpy numeric types (converted to Python types) - np.datetime64: numpy datetime - pd.Timestamp: pandas timestamp (will be UTC-localized) - str: ISO format or parseable date string - None: defaults to 1980-01-01T00:00:00+00:00 Default is None. :type time_stamp: float, int, np.number, np.datetime64, pd.Timestamp, str, or None, optional :param gps_time: If True, interprets time_stamp as GPS time and converts to UTC. Default is False. :type gps_time: bool, optional .. attribute:: time_stamp The stored timestamp, always UTC-localized. :type: pd.Timestamp .. attribute:: gps_time Whether GPS time conversion was applied. :type: bool .. rubric:: Notes The pandas.Timestamp backend allows nanosecond precision timing. Input values outside pandas timestamp bounds are automatically clamped: - Values > 2200: set to pandas.Timestamp.max (2262-04-11 23:47:16.854775807) - Values < 1900: set to pandas.Timestamp.min (1677-09-21 00:12:43.145224193) All timestamps are forced to UTC timezone regardless of input timezone. .. rubric:: Examples Create from various input types: >>> t = MTime() # Default time >>> t.isoformat() '1980-01-01T00:00:00+00:00' >>> t = MTime(time_stamp="2020-01-15T12:30:45") >>> t.year 2020 >>> t = MTime(time_stamp=1579095045.0) # Epoch seconds >>> t.isoformat() '2020-01-15T12:30:45+00:00' Access and modify components: >>> t.year = 2025 >>> t.month = 12 >>> t.day = 31 >>> t.epoch_seconds 1767225045.0 .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: gps_time :type: Annotated[bool, Field(description='Defines if the time give in GPS time [True] or UTC [False]', default=False, json_schema_extra={'units': None, 'required': False, 'examples': [True, False]})] :value: False .. py:attribute:: time_stamp :type: Annotated[float | int | numpy.number | numpy.datetime64 | pandas.Timestamp | str | None, Field(default_factory=lambda: pd.Timestamp(MTime._default_time.default), description='Time in UTC format', examples=['1980-01-01T00:00:00+00:00'])] .. py:method:: validate_time_stamp(field_value, validation_info) :classmethod: Validate and convert input timestamp to pandas Timestamp. Pydantic field validator that processes various timestamp input formats and converts them to a standardized UTC pandas Timestamp object. :param field_value: Input timestamp value in any supported format. :type field_value: float, int, np.datetime64, pd.Timestamp, str, or UTCDateTime :param validation_info: Pydantic validation context containing model data including gps_time setting. :type validation_info: ValidationInfo :returns: UTC-localized timestamp object, clamped to pandas bounds if necessary. :rtype: pd.Timestamp .. rubric:: Notes This method is automatically called during model instantiation. GPS time conversion is applied if gps_time=True in the model data. Out-of-bounds timestamps are automatically clamped to valid ranges. .. py:method:: is_default() Test if the time_stamp value is the default value .. py:method:: to_dict(nested=False, single=False, required=True) Convert the time stamp to a dictionary with the ISO format string. :returns: The ISO format string. :rtype: str .. py:method:: from_dict(value, skip_none=False) This will have to accept just a single value, not a dict. This is to keep original functionality. :param value: time stamp value :type value: str | int | float | np.datetime64 | pd.Timestamp .. py:property:: iso_str :type: str returns: ISO formatted string of the time stamp. :rtype: str .. py:property:: iso_no_tz :type: str ISO formatted string of the time stamp without the timezone. This is useful for storing the time stamp in a database or other format where the timezone is not needed. :returns: ISO formatted string of the time stamp without the timezone. :rtype: str .. py:property:: epoch_seconds :type: float Epoch seconds of the time stamp. This is the number of seconds since the epoch (1970-01-01 00:00:00 UTC). :returns: epoch seconds of the time stamp. :rtype: float .. py:property:: date :type: str Date in ISO format. This is the date part of the time stamp without the time part. This is useful for storing the date in a database or other format where the time is not needed. The date is in the format YYYY-MM-DD. :returns: ISO formatted date string of the time stamp. :rtype: str .. py:property:: year :type: int Year of the time stamp :returns: year of the time stamp :rtype: int .. py:property:: month :type: int Month of the time stamp. This is the month part of the time stamp without the time part. This is useful for storing the month in a database or other format where the time is not needed. :returns: month of time stamp :rtype: int .. py:property:: day :type: int Day of the time stamp. This is the day part of the time stamp without the time part. :returns: Day of the time stamp :rtype: int .. py:property:: hour :type: int Hour of the time stamp. :returns: hour of the time stamp :rtype: int .. py:property:: minutes :type: int .. py:property:: seconds :type: int .. py:property:: microseconds :type: int .. py:property:: nanoseconds :type: int .. py:method:: now() The current time in UTC format. :returns: The current time as an MTime object. :rtype: MTime .. py:method:: copy() make a copy of the time .. py:method:: isoformat() ISO formatted string of the time stamp. This is the ISO format string of the time stamp. formatted as: YYYY-MM-DDThh:mm:ss.ssssss+00:00 :returns: ISO formatted date time string :rtype: str .. py:method:: isodate() ISO formatted date string of the time stamp. This is the ISO format string of the date part of the time stamp. formatted as: YYYY-MM-DD :returns: _description_ :rtype: str .. py:method:: isocalendar() ISO formatted calendar string of the time stamp. This is the ISO format string of the calendar part of the time stamp. Formatted as: YYYY-WW-D where YYYY is the year, WW is the week number, and D is the day of the week. :returns: ISO formatted calendar string of the time stamp. :rtype: str .. py:class:: Comment(**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:: author :type: Annotated[str | None, Field(default=None, description='person who authored the comment', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['J. Pedantic']})] .. py:attribute:: time_stamp :type: Annotated[float | int | numpy.datetime64 | pandas.Timestamp | str | mt_metadata.common.mttime.MTime | None, Field(default_factory=lambda: MTime(time_stamp='1980-01-01T00:00:00+00:00'), description='Date and time of in UTC of when comment was made.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['2020-02-01T09:23:45.453670+00:00']})] .. py:attribute:: value :type: Annotated[str | list | None, Field(default=None, description='comment string', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['failure at midnight.']})] :value: None .. py:method:: validate_time(value, info) :classmethod: Validate that the value is a valid time. .. py:method:: validate_value(value, info) :classmethod: Validate that the value is a valid string or list. .. py:method:: set_variables() Validate that the value is a valid string. .. py:method:: as_string() Returns the comment as "{time_stamp} | {author} | {comment}" :returns: formatted comment :rtype: str .. py:method:: from_dict(value, skip_none=False) Parse input comment assuming "{time_stamp} | {author} | {comment}" :param value: _description_ :type value: str :param skip_none: _description_, by default False :type skip_none: bool, optional .. py:method:: read_dict(input_dict) can probably use from_dict method instead, but to keep consistency in EMTF XML metadata, this method is used to read the comment from a dictionary. :param input_dict: input dictionary containing comment data :type input_dict: dict :return: None :rtype: None .. py:method:: to_xml(string = False, required = True) Convert the Comment instance to XML format. :param string: If True, return the XML as a string. If False, return an ElementTree Element. :type string: bool, optional :param required: If True, include all required fields. :type required: bool, optional :return: XML representation of the Comment. :rtype: str | et.Element .. py:class:: ListDict(values={}) Hack together an object that acts like a dictionary and list such that a user can get an item by index or key. This is the first attempt, seems to work, might think about inheriting an OrderedDict and overloading. .. py:method:: copy() Copy object .. py:method:: keys() .. py:method:: values() .. py:method:: items() .. py:method:: append(obj) Append an object :param obj: DESCRIPTION :type obj: TYPE :return: DESCRIPTION :rtype: TYPE .. py:method:: remove(key) remove an item based on key or index :param key: DESCRIPTION :type key: TYPE :return: DESCRIPTION :rtype: TYPE .. py:method:: extend(other, skip_keys=[]) extend the dictionary from another ListDict object :param other: DESCRIPTION :type other: TYPE :return: DESCRIPTION :rtype: TYPE .. py:method:: sort(inplace=True) sort the dictionary keys into alphabetical order .. py:method:: update(other) Update from another ListDict .. py:method:: pop(key) pop item off of dictionary. The key must be verbatim :param key: key of item to be popped off of dictionary :type key: string :return: item popped .. py:method:: update_keys() Update all keys in the ListDict based on the current state of the objects. This is useful when object IDs have been changed after being added to the ListDict. The method will re-key all objects using their current ID values. :returns: A dictionary mapping old keys to new keys for objects that were re-keyed. :rtype: dict .. py:method:: to_dict(single=False, nested=False, required=False) need to implement this method .. py:method:: clear() Clear all items from the ListDict. .. py:class:: MinMaxRange(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Range of values. .. attribute:: minimum Minimum value of the range. :type: float .. attribute:: maximum Maximum value of the range. :type: float .. py:attribute:: minimum :type: Annotated[float, Field(default=0.0, description='Minimum value of the range.', validation_alias=AliasChoices('minimum', 'min'), json_schema_extra={'examples': '1.0', 'type': 'number', 'units': None, 'required': True})] .. py:attribute:: maximum :type: Annotated[float, Field(default=0.0, description='Maximum value of the range.', validation_alias=AliasChoices('maximum', 'max'), json_schema_extra={'examples': '1.0', 'type': 'number', 'units': None, 'required': True})] .. py:class:: StartEndRange(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Range of values. .. attribute:: start starting value of the range. :type: float .. attribute:: end Ending value of the range. :type: float .. py:attribute:: start :type: Annotated[float, Field(default=0.0, description='Starting value.', validation_alias=AliasChoices('start', 'beginning'), json_schema_extra={'examples': '1.0', 'type': 'number', 'units': None, 'required': True})] .. py:attribute:: end :type: Annotated[float, Field(default=0.0, description='Ending value of the range.', validation_alias=AliasChoices('end', 'finish'), json_schema_extra={'examples': '1.0', 'type': 'number', 'units': None, 'required': True})] .. py:class:: Declination(**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:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='any comments on declination', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['estimated from WMM 2016']})] .. py:attribute:: model :type: Annotated[mt_metadata.common.GeomagneticModelEnum, Field(default='IGRF', description='geomagnetic reference model used to calculate declination', json_schema_extra={'units': None, 'required': True, 'examples': ['WMM']})] .. py:attribute:: epoch :type: Annotated[str | None, Field(default=None, description='Epoch for which declination was approximated in.', json_schema_extra={'units': None, 'required': False, 'examples': ['2020']})] .. py:attribute:: value :type: Annotated[float, Field(default=0.0, description='declination angle relative to geographic north positive clockwise', json_schema_extra={'units': 'degrees', 'required': True, 'examples': ['12.5']})] .. py:method:: validate_comments(value, info) :classmethod: Validate that the value is a valid comment. .. py:class:: GeographicLocation(**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:: country :type: Annotated[str | list[str] | None, Field(default=None, description='Country of the geographic location, should be spelled out in full. Can be a list of countries.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'United States of America'})] .. py:attribute:: state :type: Annotated[str | list[str] | None, Field(default=None, description='State or province of the geographic location, should be spelled out in full. Can be a list of states or provinces.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '[Colorado, Utah]'})] .. py:attribute:: county :type: Annotated[str | list[str] | None, Field(default=None, description='County of the geographic location, should be spelled out in full. Can be a list of counties.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '[Douglass, Fayet]'})] .. py:attribute:: township :type: Annotated[str | list[str] | None, Field(default=None, description='Township or city name or code.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '090'})] .. py:attribute:: section :type: Annotated[str | list[str] | None, Field(default=None, description='Section name or code.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '012'})] .. py:attribute:: quarter :type: Annotated[str | list[str] | None, Field(default=None, description='Quarter section code.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '400'})] .. py:attribute:: parcel :type: Annotated[str | list[str] | None, Field(default=None, description='Land parcel ID.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '46b29a'})] .. py:class:: Orientation(**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:: method :type: Annotated[mt_metadata.common.enumerations.OrientationMethodEnum, Field(default='compass', description='method for orienting station layout', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': 'compass', 'type': 'string'})] .. py:attribute:: reference_frame :type: Annotated[mt_metadata.common.enumerations.GeographicReferenceFrameEnum, Field(default=GeographicReferenceFrameEnum.geographic, description='Reference frame for station layout. There are only 2 options geographic and geomagnetic. Both assume a right-handed coordinate system with North=0 E=90 and vertical positive downward', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': 'geomagnetic', 'type': 'string'})] .. py:attribute:: angle_to_geographic_north :type: Annotated[float | None, Field(default=None, description='Angle to rotate the data to align with geographic north. If this number is 0 then it is assumed the data are aligned with geographic north in a right handed coordinate system.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': 'geomagnetic', 'type': 'number'})] .. py:attribute:: value :type: Annotated[mt_metadata.common.enumerations.ChannelOrientationEnum | None, Field(default=ChannelOrientationEnum.orthogonal, description='Channel orientation relative to each other', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'orthogonal', 'type': 'string'})] .. py:class:: Instrument(**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 | None, Field(default='', description='Instrument ID number can be serial number or a designated ID.', validation_alias=AliasChoices('id', 'serial'), json_schema_extra={'units': None, 'required': False, 'examples': ['mt01']})] .. py:attribute:: manufacturer :type: Annotated[str | None, Field(default='', description='Who manufactured the instrument.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['mt gurus']})] .. py:attribute:: type :type: Annotated[str | None, Field(default='', description='Description of the instrument type.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['broadband 32-bit']})] .. py:attribute:: model :type: Annotated[str | None, Field(default=None, description='Model version of the instrument.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['falcon5']})] .. py:attribute:: name :type: Annotated[str | None, Field(default=None, description='Standard marketing name of the instrument.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['falcon5']})] .. py:class:: Fdsn(**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 | None, Field(default=None, description='Given FDSN archive ID name.', alias=None, pattern='^[a-zA-Z0-9._-]*$', json_schema_extra={'units': None, 'required': False, 'examples': ['MT001']})] .. py:attribute:: network :type: Annotated[str | None, Field(default=None, description='Given two character FDSN archive network code. Needs to be 2 alpha numeric characters.', alias=None, pattern='^[a-zA-Z0-9]{2}$', json_schema_extra={'units': None, 'required': False, 'examples': ['EM']})] .. py:attribute:: channel_code :type: Annotated[str | None, Field(default=None, description='Three character FDSN channel code. http://docs.fdsn.org/projects/source-identifiers/en/v1.0/channel-codes.html', alias=None, pattern='^[a-zA-Z0-9]{3}*$', json_schema_extra={'units': None, 'required': False, 'examples': ['LQN']})] .. py:attribute:: new_epoch :type: Annotated[bool | None, Field(default=None, description='Boolean telling if a new epoch needs to be created or not.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['False']})] .. py:attribute:: alternate_code :type: Annotated[str | None, Field(default=None, description='Alternate Code', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['_INT-NON_FDSN', '.UNRESTRICTED', '_US-ALL', '_US-MT', '_US-MT-TA']})] .. py:attribute:: alternate_network_code :type: Annotated[str | None, Field(default=None, description='Alternate Network Code', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['_INT-NON_FDSN', '.UNRESTRICTED', '_US-ALL', '_US-MT', '_US-MT-TA']})] .. py:class:: Rating(**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:: author :type: Annotated[str | None, Field(default=None, description='Author of who rated the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'gradstudent ace'})] .. py:attribute:: method :type: Annotated[str | None, Field(default=None, description='The method used to rate the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'standard deviation'})] .. py:attribute:: value :type: Annotated[int | None | str, Field(default=None, description='A rating from 1-5 where 1 is bad and 5 is good and 0 if unrated.', ge=0, le=5, alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '4'})] .. py:method:: validate_value(value, info) :classmethod: .. py:class:: DataQuality(**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:: warnings :type: Annotated[str | None, Field(default=None, description='any warnings about the data that should be noted', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['periodic pipeline noise']})] .. py:attribute:: good_from_period :type: Annotated[float | None, Field(default=None, description='Data are good for periods larger than this number', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['0.01']})] .. py:attribute:: good_to_period :type: Annotated[float | None, Field(default=None, description='Data are good for periods smaller than this number', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['1000']})] .. py:attribute:: flag :type: Annotated[int | None, Field(default=None, description='Flag for data quality', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['0']})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=Comment, description='any comments about the data quality', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['0']})] .. py:attribute:: rating :type: Annotated[mt_metadata.common.Rating, Field(default_factory=Rating, description='rating of the data quality', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['0']})] .. py:method:: validate_comments(value, info) :classmethod: Validate that the value is a valid string. .. py:class:: Citation(**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:: doi :type: Annotated[pydantic.HttpUrl | str | None, Field(default=None, description='full url of the doi number', validation_alias=AliasChoices('doi', 'survey_doi'), json_schema_extra={'units': None, 'required': False, 'examples': ['http://doi.###']})] .. py:attribute:: authors :type: Annotated[str | None, Field(default=None, description='author names', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['M.Tee A. Roura']})] .. py:attribute:: title :type: Annotated[str | None, Field(default=None, description='Full title of the citation', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Paper Title']})] .. py:attribute:: year :type: Annotated[str | None, Field(default=None, description='Year of citation', alias=None, pattern='^\\d{4}(-\\d{4})?$', json_schema_extra={'units': None, 'required': False, 'examples': ['2020']})] .. py:attribute:: volume :type: Annotated[str | None, Field(default=None, description='Journal volume of the citation', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['12']})] .. py:attribute:: pages :type: Annotated[str | None, Field(default=None, description='Page numbers of the citation', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['10-15']})] .. py:attribute:: journal :type: Annotated[str | None, Field(default=None, description='Journal title of citation', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Journal of Geophysical Research']})] .. py:attribute:: url :type: Annotated[pydantic.HttpUrl | str | None, Field(default=None, description='URL of the citation', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['https://example.com/citation']})] .. py:method:: validate_doi(value) :classmethod: Validate the DOI. :param value: The DOI value to validate. :type value: str | None :param info: Additional validation information. :type info: ValidationInfo :returns: The validated DOI or None if not provided. :rtype: str | None .. py:class:: Copyright(**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:: release_license :type: Annotated[mt_metadata.common.LicenseEnum, Field(default='CC BY 4.0', description='How the data can be used. The options are based on https://github.com/spdx/license-list-data', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': 'CC BY', 'type': 'string'})] .. py:method:: validate_license(value, info) :classmethod: Validate that the value is a valid license. .. py:class:: AuthorPerson(**data) Bases: :py:obj:`GenericPerson` 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:: author :type: Annotated[str | None, Field(default='', description='Persons name, should be full first and last name.', validation_alias=AliasChoices('author', 'name'), json_schema_extra={'units': None, 'required': True, 'examples': ['person name']})] .. py:class:: Person(**data) Bases: :py:obj:`GenericPerson` 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 | None, Field(default='', description='Persons name, should be full first and last name.', validation_alias=AliasChoices('name', 'author'), json_schema_extra={'units': None, 'required': True, 'examples': ['person name']})] .. py:class:: FundingSource(**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[list[str] | str | None, Field(default=None, description='Persons name, should be full first and last name.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'person name', 'items': {'type': 'string'}})] .. py:attribute:: organization :type: Annotated[list[str] | str | None, Field(default=None, description='Organization full name', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'mt gurus', 'items': {'type': 'string'}})] .. py:attribute:: email :type: Annotated[list[pydantic.EmailStr] | pydantic.EmailStr | None, Field(default=None, description='Email of the contact person', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'mt.guru@em.org', 'items': {'type': 'string'}})] .. py:attribute:: url :type: Annotated[list[pydantic.AnyHttpUrl] | pydantic.AnyHttpUrl | None, Field(default=None, description='URL of the contact person', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'em.org', 'items': {'type': 'string'}})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='Any comments about the person', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'expert digger'})] .. py:attribute:: grant_id :type: Annotated[list[str] | str | None, Field(default=None, description='Grant ID number or name', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'MT-01-2020', 'items': {'type': 'string'}})] .. py:method:: validate_comments(value, info) :classmethod: .. py:method:: validate_input(value) :classmethod: make sure the inputs are lists :param value: _description_ :type value: _type_ :returns: _description_ :rtype: list .. py:class:: Software(**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:: author :type: Annotated[str | None, Field(default='', description='Author of the software', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['Neo']})] .. py:attribute:: version :type: Annotated[str, Field(default='', description='Software version', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['12.01a']})] .. py:attribute:: last_updated :type: Annotated[mt_metadata.common.mttime.MTime | str | float | int | numpy.datetime64 | pandas.Timestamp | None, Field(default_factory=lambda: MTime(time_stamp=None), description='Most recent date the software was updated. Prefer to use version, but this works for non-versioned software.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['2020-01-01']})] .. py:attribute:: name :type: Annotated[str, Field(default='', description='Software name', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['mtrules']})] .. py:method:: validate_last_updated(field_value) :classmethod: .. py:class:: TimePeriod(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Time span of a period of time. .. py:attribute:: end :type: Annotated[str | float | int | numpy.datetime64 | pandas.Timestamp | mt_metadata.common.mttime.MTime, Field(default_factory=lambda: MTime(time_stamp='1980-01-01T00:00:00+00:00'), description='End date and time of collection in UTC.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '2020-02-04T16:23:45.453670+00:00', 'type': 'string'})] .. py:attribute:: start :type: Annotated[str | float | int | numpy.datetime64 | pandas.Timestamp | mt_metadata.common.mttime.MTime, Field(default_factory=lambda: MTime(), description='Start date and time of collection in UTC.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '2020-02-01T09:23:45.453670+00:00', 'type': 'string'})] .. py:method:: validate_time(value, info) :classmethod: Validate that the value is a valid time. .. py:method:: start_is_default() Check if the start time is the default time. .. py:method:: end_is_default() Check if the end time is the default time. .. py:class:: TimePeriodDate(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Time span of a period of time. .. py:attribute:: end_date :type: Annotated[str | float | int | numpy.datetime64 | pandas.Timestamp | mt_metadata.common.mttime.MTime | mt_metadata.common.mttime.MDate, Field(default_factory=lambda: MDate(time_stamp='1980-01-01'), description='End date and time of collection in UTC.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '2020-02-04', 'type': 'string'})] .. py:attribute:: start_date :type: Annotated[str | float | int | numpy.datetime64 | pandas.Timestamp | mt_metadata.common.mttime.MTime | mt_metadata.common.mttime.MDate, Field(default_factory=lambda: MDate(time_stamp='1980-01-01'), description='Start date and time of collection in UTC.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '2020-02-01', 'type': 'string'})] .. py:method:: validate_time(value, info) :classmethod: Validate that the value is a valid time. .. py:method:: start_is_default() Check if the start time is the default time. .. py:method:: end_is_default() Check if the end time is the default time. .. py:class:: Provenance(**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:: creation_time :type: Annotated[mt_metadata.common.mttime.MTime | str | float | int | numpy.datetime64 | pandas.Timestamp, Field(default_factory=lambda: MTime(time_stamp=None), description='Date and time the file was created.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': '2020-02-08T12:23:40.324600+00:00', 'type': 'string'})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=Comment, description='Any comments on provenance of the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'all good', 'type': 'string'})] .. py:attribute:: log :type: Annotated[str | None, Field(default=None, description='A history of changes made to the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': '2020-02-10T14:24:45+00:00 updated metadata', 'type': 'string'})] .. py:attribute:: creator :type: Annotated[mt_metadata.common.AuthorPerson, Field(default_factory=AuthorPerson, description='Person who created the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'Person(name=J. Pedantic, email=jped@mt.com)'})] .. py:attribute:: submitter :type: Annotated[mt_metadata.common.AuthorPerson, Field(default_factory=AuthorPerson, description='Person who submitted the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'Person(name=submitter_name, email=submitter@email)'})] .. py:attribute:: archive :type: Annotated[mt_metadata.common.Person, Field(default_factory=Person, description='Archive from which the data was downloaded from.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'Person(name=archive_name, url=https://archive.url)'})] .. py:attribute:: software :type: Annotated[mt_metadata.common.Software, Field(default_factory=Software, description='Software used to create the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': 'Software(name=mt_metadata, version=0.1)'})] .. py:method:: validate_creation_time(field_value) :classmethod: .. py:method:: validate_comments(value, info) :classmethod: Validate that the value is a valid comment. .. py:class:: BasicLocation(**data) Bases: :py:obj:`BasicLocationNoDatum` A partial location class that only includes the latitude, longitude, and elevation. This is used to avoid circular imports. .. py:attribute:: datum :type: Annotated[str | int, Field(default='WGS 84', description='Datum of the location values. Usually a well known datum like WGS84.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['WGS 84']})] .. py:attribute:: x :type: Annotated[float, Field(default=0.0, description='relative distance to the center of the station', validation_alias=AliasChoices('x', 'easting', 'east'), json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:attribute:: y :type: Annotated[float, Field(default=0.0, description='relative distance to the center of the station', validation_alias=AliasChoices('y', 'north', 'northing'), json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:attribute:: z :type: Annotated[float, Field(default=0.0, description='relative elevation to the center of the station', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:method:: validate_datum(value) :classmethod: Validate the datum value and convert it to the appropriate enum type. .. py:class:: BasicLocationNoDatum(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` A partial location class that only includes the latitude, longitude, and elevation. This is used to avoid circular imports. .. py:attribute:: latitude :type: Annotated[float | None, Field(default=0.0, description='Latitude of the location.', validation_alias=AliasChoices('latitude', 'lat'), json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['12.324']})] .. py:attribute:: longitude :type: Annotated[float | None, Field(default=0.0, description='Longitude of the location.', validation_alias=AliasChoices('longitude', 'lon', 'long'), json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['12.324']})] .. py:attribute:: elevation :type: Annotated[float, Field(default=0.0, description='Elevation of the location.', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['1234.0']})] .. py:method:: validate_position(value, info) :classmethod: .. py:class:: Location(**data) Bases: :py:obj:`BasicLocation` Positional location of a geographic point .. py:attribute:: latitude_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in latitude estimation in degrees', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['0.01']})] .. py:attribute:: longitude_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in longitude estimation in degrees', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['0.01']})] .. py:attribute:: elevation_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in elevation estimation', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['0.01']})] .. py:attribute:: x2 :type: Annotated[float, Field(default=0.0, description='relative distance to the center of the station', validation_alias=AliasChoices('x2', 'east', 'easting'), json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:attribute:: y2 :type: Annotated[float, Field(default=0.0, description='relative distance to the center of the station', validation_alias=AliasChoices('y2', 'north', 'northing'), json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:attribute:: z2 :type: Annotated[float, Field(default=0.0, description='relative elevation to the center of the station', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['10.0']})] .. py:attribute:: x_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in longitude estimation in x-direction', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['0.01']})] .. py:attribute:: y_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in longitude estimation in y-direction', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['0.01']})] .. py:attribute:: z_uncertainty :type: Annotated[float, Field(default=0.0, description='uncertainty in longitude estimation in z-direction', alias=None, json_schema_extra={'units': 'meters', 'required': False, 'examples': ['0.01']})] .. py:class:: StationLocation(**data) Bases: :py:obj:`Location` A class that represents the location of a station. It includes latitude, longitude, elevation, and other related attributes. .. py:attribute:: declination :type: Annotated[mt_metadata.common.Declination, Field(default_factory=Declination, description='Declination of the location.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['Declination(10.0)']})] .. py:attribute:: geographic_location :type: Annotated[mt_metadata.common.GeographicLocation, Field(default_factory=GeographicLocation, description='Geographic location of the station.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['GeographicLocation(latitude=12.34, longitude=56.78)']})] .. py:class:: Band(**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:: decimation_level :type: Annotated[int, Field(default=None, description='Decimation level for the band', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['0']})] .. py:attribute:: index_max :type: Annotated[int, Field(default=None, description='maximum band index', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['10']})] .. py:attribute:: index_min :type: Annotated[int, Field(default=None, description='minimum band index', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['10']})] .. py:attribute:: frequency_max :type: Annotated[float, Field(default=0.0, description='maximum band frequency', alias=None, json_schema_extra={'units': 'Hertz', 'required': True, 'examples': ['0.04296875']})] .. py:attribute:: frequency_min :type: Annotated[float, Field(default=0.0, description='minimum band frequency', alias=None, json_schema_extra={'units': 'Hertz', 'required': True, 'examples': ['0.03515625']})] .. py:attribute:: center_averaging_type :type: Annotated[CenterAveragingTypeEnum, Field(default=CenterAveragingTypeEnum.geometric, description='type of average to apply when computing the band center', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['geometric']})] .. py:attribute:: closed :type: Annotated[ClosedEnum, Field(default=ClosedEnum.left, description='whether interval is open or closed', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['left']})] .. py:attribute:: name :type: Annotated[Optional[str], Field(default='', description='Name of the band', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['0.039062']})] .. py:method:: validate_name(value, info) :classmethod: .. py:method:: update_name_on_frequency_change(value, info) :classmethod: .. py:method:: check_name() .. py:property:: lower_bound :type: float .. py:property:: upper_bound :type: float .. py:property:: width :type: float returns the width of the band (the bandwidth). .. py:property:: lower_closed :type: bool .. py:property:: upper_closed :type: bool .. py:method:: set_indices_from_frequencies(frequencies) assumes min/max freqs are defined .. py:method:: to_interval() .. py:property:: harmonic_indices Assumes all harmoincs between min and max are present in the band :rtype: numpy array of integers corresponding to harminic indices .. py:method:: in_band_harmonics(frequencies) :param frequencies: :type frequencies: array-like, floating poirt :param Returns: the actual harmonics or frequencies in band, rather than the indices. :type Returns: numpy array :param -------: .. py:property:: center_frequency :type: float returns: **center_frequency** -- The frequency associated with the band center. :rtype: float .. py:property:: center_period :type: float Returns the inverse of center frequency. .. py:method:: overlaps(other) Check if this band overlaps with another .. py:method:: contains(other) Check if this band contains nother .. py:property:: fractional_bandwidth :type: float See - https://en.wikipedia.org/wiki/Bandwidth_(signal_processing)#Fractional_bandwidth - https://en.wikipedia.org/wiki/Q_factor .. py:property:: Q :type: float Quality factor (Q) of the band. :returns: Q factor. Returns infinity for zero-width bands. :rtype: float .. py:class:: CenterAveragingTypeEnum Bases: :py:obj:`mt_metadata.common.enumerations.StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: arithmetic :value: 'arithmetic' .. py:attribute:: geometric :value: 'geometric' .. py:class:: ClosedEnum Bases: :py:obj:`mt_metadata.common.enumerations.StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: left :value: 'left' .. py:attribute:: right :value: 'right' .. py:attribute:: both :value: 'both'