mt_metadata.timeseries.survey ============================= .. py:module:: mt_metadata.timeseries.survey Classes ------- .. autoapisummary:: mt_metadata.timeseries.survey.Survey Module Contents --------------- .. py:class:: Survey(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Base class for all metadata objects with Pydantic validation. MetadataBase extends DotNotationBaseModel (which inherits from Pydantic's BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange. .. attribute:: _skip_equals Private attribute listing fields to skip in equality comparisons :type: list[str] .. attribute:: _fields Private attribute caching field information :type: dict[str, Any] .. rubric:: Notes - All field assignments are validated automatically via Pydantic - None values are converted to appropriate defaults (empty string or 0.0) - Supports nested attribute access via dot notation - Thread-safe for read operations after initialization .. py:attribute:: id :type: Annotated[str, Field(default='', description='Alpha numeric ID that will be unique for archiving.', alias=None, pattern='^[a-zA-Z0-9_\\- ]*$', json_schema_extra={'units': None, 'required': True, 'examples': ['EMT20']})] .. py:attribute:: comments :type: Annotated[mt_metadata.common.Comment, Field(default_factory=lambda: Comment(), description='Any comments about the survey.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['long survey']})] .. py:attribute:: datum :type: Annotated[str | int, Field(default='WGS 84', description='Datum of latitude and longitude coordinates. Should be a well-known datum, such as WGS84, and will be the reference datum for all locations. This is important for the user, they need to make sure all coordinates in the survey and child items (i.e. stations, channels) are referenced to this datum.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['WGS 84']})] .. py:attribute:: geographic_name :type: Annotated[str, Field(default='', description='Closest geographic reference to survey, usually a city but could be a landmark or some other common geographic reference point.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['Yukon']})] .. py:attribute:: name :type: Annotated[str, Field(default='', description='Descriptive name of the survey.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['MT Characterization of Yukon Terrane']})] .. py:attribute:: project :type: Annotated[str, Field(default='', description='Alpha numeric name for the project e.g USGS-GEOMAG.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['YUTOO']})] .. py:attribute:: stations :type: Annotated[mt_metadata.common.list_dict.ListDict | list | dict | collections.OrderedDict | tuple, Field(default_factory=ListDict, description='List of stations recorded in the survey.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['ListDict[Station(id=id)]']})] .. py:attribute:: filters :type: Annotated[mt_metadata.common.list_dict.ListDict | list | dict | collections.OrderedDict | tuple, Field(default_factory=ListDict, description='List of filters for channel responses.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['ListDict[Filter()]']})] .. py:attribute:: summary :type: Annotated[str, Field(default='', description='Summary paragraph of survey including the purpose; difficulties; data quality; summary of outcomes if the data have been processed and modeled.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['long project of characterizing mineral resources in Yukon']})] .. py:attribute:: time_period :type: Annotated[mt_metadata.common.TimePeriodDate, Field(default_factory=TimePeriodDate, description='End date of the survey in UTC.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ["TimePeriodDate(start_date='2000-01-01', end_date='2000-01-31')"]})] .. py:attribute:: fdsn :type: Annotated[mt_metadata.common.Fdsn, Field(default_factory=Fdsn, description='FDSN web service information.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Fdsn()']})] .. py:attribute:: acquired_by :type: Annotated[mt_metadata.common.AuthorPerson, Field(default_factory=AuthorPerson, description='Person or group that acquired the data.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Person()']})] .. py:attribute:: funding_source :type: Annotated[mt_metadata.common.FundingSource, Field(default_factory=FundingSource, description='Funding source for the survey.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['FundingSource()']})] .. py:attribute:: citation_dataset :type: Annotated[mt_metadata.common.Citation, Field(default_factory=Citation, description='Citation for the dataset.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Citation()']})] .. py:attribute:: citation_journal :type: Annotated[mt_metadata.common.Citation, Field(default_factory=Citation, description='Citation for the journal.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Citation()']})] .. py:attribute:: northwest_corner :type: Annotated[mt_metadata.common.BasicLocationNoDatum, Field(default_factory=BasicLocationNoDatum, description='Northwest corner of the survey area.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['BasicLocationNoDatum()']})] .. py:attribute:: southeast_corner :type: Annotated[mt_metadata.common.BasicLocationNoDatum, Field(default_factory=BasicLocationNoDatum, description='Southeast corner of the survey area.', alias=None, json_schema_extra={'units': 'degrees', 'required': False, 'examples': ['BasicLocationNoDatum()']})] .. py:attribute:: country :type: Annotated[list[str] | str | None, Field(default=None, description='Country where the survey was conducted.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Canada']})] .. py:attribute:: state :type: Annotated[list[str] | str | None, Field(default=None, description='State or province where the survey was conducted.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Yukon']})] .. py:attribute:: project_lead :type: Annotated[mt_metadata.common.AuthorPerson, Field(default_factory=AuthorPerson, description='Person or group that led the project.', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Person()']})] .. py:attribute:: release_license :type: Annotated[str, Field(default='CC-BY-4.0', description='Release license for the data.', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['CC-BY-4.0']})] .. py:method:: validate_comments(value, info) :classmethod: .. py:method:: validate_datum(value) :classmethod: Validate the datum value and convert it to the appropriate enum type. .. py:method:: validate_release_license(value, info) :classmethod: Validate that the value is a valid license. .. py:method:: validate_areas(value) :classmethod: validate country and state to be a list .. py:method:: validate_stations(value, info) :classmethod: .. py:method:: validate_filters(value, info) :classmethod: :param value: _description_ :type value: _type_ :param info: _description_ :type info: ValidationInfo :returns: _description_ :rtype: ListDict .. py:property:: survey_extent :type: dict Return the survey extent as a dictionary with keys 'northwest' and 'southeast'. .. py:method:: merge(other, inplace=False) Merge surveys together using the original metadata but adding other's stations. :param other: Survey object :type other: Survey :param inplace: merge in place, by default False :type inplace: bool, optional :returns: merged surveys :rtype: Survey :raises TypeError: If items cannot be merged. .. py:property:: n_stations :type: int Return the number of stations in the station. :return: number of runs in the station :rtype: int .. py:property:: station_names Return names of station in survey .. py:property:: filter_names return a list of filter names .. py:method:: has_station(station_id) Has station id :param station_id: station id verbatim :type station_id: string :return: True if exists or False if not :rtype: boolean .. py:method:: station_index(station_id) Get station index :param station_id: station id verbatim :type station_id: string :return: index value if station is found :rtype: integer .. py:method:: add_station(station_obj, update=True) Add a station, if has the same name update that object. :param station_obj: station object to add :type station_obj: `:class:`mt_metadata.timeseries.Station` .. py:method:: get_station(station_id) Get a station from the station id :param station_id: station id verbatim :type station_id: string :return: station object :rtype: :class:`mt_metadata.timeseries.Station` .. py:method:: remove_station(station_id, update=True) remove a station from the survey :param station_id: station id verbatim :type station_id: string .. py:method:: update_station_keys() Update the keys in the stations ListDict to match current station IDs. This is useful when station IDs have been modified after stations were added to the survey, ensuring that stations can be accessed by their current ID values. :returns: mapping of old keys to new keys :rtype: dict .. rubric:: Example >>> survey = Survey() >>> station = Station() >>> station.id = "" # empty ID initially >>> survey.add_station(station) >>> station.id = "MT001" # update the ID >>> key_mapping = survey.update_station_keys() >>> print(key_mapping) # {'': 'MT001'} >>> # Now station can be accessed as survey.stations['MT001'] .. py:method:: update_bounding_box() Update the bounding box of the survey from the station information .. py:method:: update_time_period() Update the start and end time of the survey based on the stations .. py:method:: update_all() Update time period and bounding box