mth5.groups.station

Attributes

meta_classes

Classes

MasterStationGroup	Collection helper for all stations in a survey.
StationGroup	Utility wrapper for a single station at /Survey/Stations/<id>.

Module Contents

mth5.groups.station.meta_classes

class mth5.groups.station.MasterStationGroup(group: h5py.Group, **kwargs: Any)

Bases: mth5.groups.BaseGroup

Collection helper for all stations in a survey.

The group lives at /Survey/Stations and offers convenience accessors to add, fetch, or remove stations along with a summary table.

Examples

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5()
>>> _ = mth5_obj.open_mth5("/tmp/example.mth5", mode="a")
>>> stations = mth5_obj.stations_group
>>> _ = stations.add_station("MT001")
>>> stations.station_summary.head()

property station_summary: pandas.DataFrame

Return a summary DataFrame of all stations in the file.

Returns:

Columns include station, start, end, latitude, and longitude. Empty if no stations are present.

Return type:

pandas.DataFrame

Notes

Timestamps are parsed to pandas datetime64[ns] when possible.

Examples

>>> summary = stations.station_summary
>>> list(summary.columns)
['station', 'start', 'end', 'latitude', 'longitude']

add_station(station_name: str, station_metadata: mt_metadata.timeseries.Station | None = None) → StationGroup

Add or fetch a station group at /Survey/Stations/<name>.

Parameters:

• station_name (str) – Station identifier, typically matches metadata.id.

• station_metadata (mt_metadata.timeseries.Station, optional) – Metadata container to seed the station attributes.

Returns:

Convenience wrapper for the created or existing station.

Return type:

StationGroup

Raises:

ValueError – If station_name is empty.

Examples

>>> station = stations.add_station("MT001")
>>> station.metadata.id
'MT001'

get_station(station_name: str) → StationGroup

Return an existing station by name.

Parameters:

station_name (str) – Name of the station to retrieve.

Returns:

Wrapper for the requested station.

Return type:

StationGroup

Raises:

MTH5Error – If the station does not exist.

Examples

>>> existing = stations.get_station("MT001")
>>> existing.name
'MT001'

remove_station(station_name: str) → None

Delete a station group reference from the file.

Parameters:

station_name (str) – Existing station name.

Notes

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

Examples

>>> stations.remove_station("MT001")

class mth5.groups.station.StationGroup(group: h5py.Group, station_metadata: mt_metadata.timeseries.Station | None = None, **kwargs: Any)

Bases: mth5.groups.BaseGroup

Utility wrapper for a single station at /Survey/Stations/<id>.

Station groups manage run collections, metadata propagation, and provide summary utilities for quick inspection.

Examples

>>> from mth5 import mth5
>>> m5 = mth5.MTH5()
>>> _ = m5.open_mth5("/tmp/example.mth5", mode="a")
>>> station = m5.stations_group.add_station("MT001")
>>> _ = station.add_run("MT001a")
>>> station.run_summary.shape[0] >= 1
True

initialize_group(**kwargs: Any) → None

Create default subgroups and write metadata.

Parameters:

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

Examples

>>> station.initialize_group()

property master_station_group: MasterStationGroup

Shortcut to the containing master station group.

property transfer_functions_group: mth5.groups.TransferFunctionsGroup

Convenience accessor for /Station/Transfer_Functions.

property fourier_coefficients_group: mth5.groups.MasterFCGroup

Convenience accessor for /Station/Fourier_Coefficients.

property features_group: mth5.groups.MasterFeaturesGroup

Convenience accessor for /Station/Features.

property survey_metadata: mt_metadata.timeseries.Survey

Return survey metadata with this station appended.

metadata() → mt_metadata.timeseries.Station

Station metadata enriched with run information.

property name: str

property run_summary: pandas.DataFrame

Return a summary of runs belonging to the station.

Returns:

Columns include id, start, end, components, measurement_type, sample_rate, and hdf5_reference.

Return type:

pandas.DataFrame

Notes

Channel lists stored as byte arrays or JSON strings are normalized before summarization.

Examples

>>> station.run_summary.head()

make_run_name(alphabet: bool = False) → str | None

Generate the next run name using an alphabetic or numeric suffix.

Parameters:

alphabet (bool, default False) – If True use letters (a, b, …); otherwise use numeric suffixes (001).

Returns:

Proposed run name or None if generation fails.

Return type:

str or None

Examples

>>> station.metadata.id = "MT001"
>>> station.make_run_name()
'MT001a'

locate_run(sample_rate: float, start: str | mt_metadata.common.mttime.MTime) → pandas.DataFrame | None

Locate runs matching a sample rate and start time.

Parameters:

• sample_rate (float) – Sample rate in samples per second.

• start (str or MTime) – Start time string or MTime instance.

Returns:

Matching rows from run_summary or None when no match exists.

Return type:

pandas.DataFrame or None

Examples

>>> station.locate_run(256.0, "2020-01-01T00:00:00")

add_run(run_name: str, run_metadata: mt_metadata.timeseries.Run | None = None) → mth5.groups.RunGroup

Add a run under this station.

Parameters:

• run_name (str) – Run identifier (for example id + suffix).

• run_metadata (mt_metadata.timeseries.Run, optional) – Metadata container to seed the run attributes.

Returns:

Wrapper for the created or existing run.

Return type:

RunGroup

Examples

>>> run = station.add_run("MT001a")
>>> run.metadata.id
'MT001a'

get_run(run_name: str) → mth5.groups.RunGroup

Return a run by name.

Parameters:

run_name (str) – Existing run name.

Returns:

Wrapper for the requested run.

Return type:

RunGroup

Raises:

MTH5Error – If the run does not exist.

Examples

>>> existing_run = station.get_run("MT001a")
>>> existing_run.name
'MT001a'

remove_run(run_name: str) → None

Remove a run from this station.

Parameters:

run_name (str) – Existing run name.

Notes

Deleting removes the reference only; storage is not reclaimed.

Examples

>>> station.remove_run("MT001a")

update_station_metadata() → None

Deprecated alias for update_metadata().

Raises:

DeprecationWarning – Always raised to direct callers to update_metadata.

Examples

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

update_metadata() → None

Synchronize station metadata from contained runs.

Notes

The station time_period is set to the min/max of all runs, and channels_recorded combines all recorded components.

Examples

>>> _ = station.update_metadata()
>>> station.metadata.time_period.start
'2020-01-01T00:00:00'