mth5.groups.survey

Classes

MasterSurveyGroup	Collection helper for surveys under Experiment/Surveys.
SurveyGroup	Wrapper for a single survey at Experiment/Surveys/<id>.

Module Contents

class mth5.groups.survey.MasterSurveyGroup(group: h5py.Group, **kwargs: Any)

Bases: mth5.groups.BaseGroup

Collection helper for surveys under Experiment/Surveys.

Provides helpers to add, fetch, or remove surveys and to summarize all channels in the experiment.

Examples

>>> from mth5 import mth5
>>> m5 = mth5.MTH5()
>>> _ = m5.open_mth5("/tmp/example.mth5", mode="a")
>>> surveys = m5.surveys_group
>>> _ = surveys.add_survey("survey_01")
>>> surveys.channel_summary.head()

property channel_summary: pandas.DataFrame

Return a DataFrame summarizing all channels across surveys.

Returns:

Columns include survey, station, run, location, component, start/end, sample info, orientation, units, and HDF5 reference.

Return type:

pandas.DataFrame

Examples

>>> summary = surveys.channel_summary
>>> set(summary.columns) >= {"survey", "station", "run", "component"}
True

add_survey(survey_name: str, survey_metadata: mt_metadata.timeseries.Survey | None = None) → SurveyGroup

Add or fetch a survey at /Experiment/Surveys/<name>.

Parameters:

• survey_name (str) – Survey identifier; validated with validate_name.

• survey_metadata (Survey, optional) – Metadata container used to seed the survey attributes.

Returns:

Wrapper for the created or existing survey.

Return type:

SurveyGroup

Raises:

• ValueError – If survey_name is empty.

• MTH5Error – If the provided metadata id conflicts with the group name.

Examples

>>> survey = surveys.add_survey("survey_01")
>>> survey.metadata.id
'survey_01'

get_survey(survey_name: str) → SurveyGroup

Return an existing survey by name.

Parameters:

survey_name (str) – Existing survey name.

Returns:

Wrapper for the requested survey.

Return type:

SurveyGroup

Raises:

MTH5Error – If the survey does not exist.

Examples

>>> existing = surveys.get_survey("survey_01")
>>> existing.metadata.id
'survey_01'

remove_survey(survey_name: str) → None

Delete a survey reference from the file.

Parameters:

survey_name (str) – Existing survey name.

Notes

HDF5 deletion removes the reference only; storage is not reclaimed.

Examples

>>> surveys.remove_survey("survey_01")

class mth5.groups.survey.SurveyGroup(group: h5py.Group, survey_metadata: mt_metadata.timeseries.Survey | None = None, **kwargs: Any)

Bases: mth5.groups.BaseGroup

Wrapper for a single survey at Experiment/Surveys/<id>.

Handles survey-level metadata, child groups (stations, reports, filters, standards), and synchronization utilities.

Examples

>>> survey = surveys.add_survey("survey_01")
>>> survey.metadata.id
'survey_01'

initialize_group(**kwargs: Any) → None

Create default subgroups and write survey metadata.

Parameters:

**kwargs – Additional attributes to set on the instance before initialization.

Examples

>>> survey.initialize_group()

metadata() → mt_metadata.timeseries.Survey

Survey metadata enriched with station and filter information.

write_metadata() → None

Write HDF5 attributes from the survey metadata object.

property stations_group: mth5.groups.MasterStationGroup

property filters_group: mth5.groups.FiltersGroup

Convenience accessor for /Survey/Filters group.

property reports_group: mth5.groups.ReportsGroup

Convenience accessor for /Survey/Reports group.

property standards_group: mth5.groups.StandardsGroup

Convenience accessor for /Survey/Standards group.

update_survey_metadata(survey_dict: dict[str, Any] | None = None) → None

Deprecated alias for update_metadata().

Raises:

DeprecationWarning – Always raised to direct callers to update_metadata.

Examples

>>> survey.update_survey_metadata()
Traceback (most recent call last):
...
DeprecationWarning: 'update_survey_metadata' has been deprecated use 'update_metadata()'

update_metadata(survey_dict: dict[str, Any] | None = None) → None

Synchronize survey metadata from station summaries.

Parameters:

survey_dict (dict, optional) – Additional metadata values to merge before synchronization.

Notes

Updates survey start/end dates and bounding box from station summaries, then writes metadata to HDF5.

Examples

>>> _ = survey.update_metadata()
>>> survey.metadata.time_period.start_date
'2020-01-01'