mt_metadata.timeseries.survey

Classes

Survey

Base class for all metadata objects with Pydantic validation.

Module Contents

class mt_metadata.timeseries.survey.Survey(**data)

Bases: mt_metadata.base.MetadataBase

Base class for all metadata objects with Pydantic validation.

MetadataBase extends DotNotationBaseModel (which inherits from Pydantic’s BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange.

_skip_equals

Private attribute listing fields to skip in equality comparisons

Type:: list[str]

_fields

Private attribute caching field information

Type:: dict[str, Any]

Notes

All field assignments are validated automatically via Pydantic
None values are converted to appropriate defaults (empty string or 0.0)
Supports nested attribute access via dot notation
Thread-safe for read operations after initialization

id: Annotated[str, Field(default='', description='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']})]

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

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

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

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

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

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

filters: 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()]']})]

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

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

fdsn: 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()']})]

acquired_by: 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()']})]

funding_source: 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()']})]

citation_dataset: 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()']})]

citation_journal: 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()']})]

northwest_corner: 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()']})]

southeast_corner: 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()']})]

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

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

project_lead: 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()']})]

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

classmethod validate_comments(value, info)

classmethod validate_datum(value)

Validate the datum value and convert it to the appropriate enum type.

classmethod validate_release_license(value, info)

Validate that the value is a valid license.

classmethod validate_areas(value)

validate country and state to be a list

classmethod validate_stations(value, info)

classmethod validate_filters(value, info)

Parameters:

value (_type_) – _description_
info (ValidationInfo) – _description_

Returns:

_description_

Return type:

ListDict

property survey_extent: dict

Return the survey extent as a dictionary with keys ‘northwest’ and ‘southeast’.

merge(other, inplace=False)

Merge surveys together using the original metadata but adding other’s stations.

Parameters:

other (Survey) – Survey object
inplace (bool, optional) – merge in place, by default False

Returns:

merged surveys

Return type:

Survey

Raises:

TypeError – If items cannot be merged.

property n_stations: int

Return the number of stations in the station.

Returns:: number of runs in the station
Return type:: int

property station_names: Return names of station in survey

property filter_names: return a list of filter names

has_station(station_id)

Has station id

Parameters:: station_id (string) – station id verbatim
Returns:: True if exists or False if not
Return type:: boolean

station_index(station_id)

Get station index

Parameters:: station_id (string) – station id verbatim
Returns:: index value if station is found
Return type:: integer

add_station(station_obj, update=True)

Add a station, if has the same name update that object.

Parameters:: station_obj (:class:`mt_metadata.timeseries.Station) – station object to add

get_station(station_id)

Get a station from the station id

Parameters:: station_id (string) – station id verbatim
Returns:: station object
Return type:: mt_metadata.timeseries.Station

remove_station(station_id, update=True)

remove a station from the survey

Parameters:: station_id (string) – station id verbatim

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
Return type:: dict

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']

update_bounding_box(): Update the bounding box of the survey from the station information

update_time_period(): Update the start and end time of the survey based on the stations

update_all(): Update time period and bounding box