mth5.clients package

Submodules

mth5.clients.base module

Created on Fri Oct 11 11:36:26 2024

@author: jpeacock

class mth5.clients.base.ClientBase(data_path: str | Path, sample_rates: Sequence[float] = [1], save_path: str | Path | None = None, mth5_filename: str = 'from_client.h5', **kwargs: Any)

Bases: object

property data_path: Path

Path to data directory.

Returns:

Path to the data directory.

Return type:

Path

Examples

>>> client = ClientBase(data_path="./data")
>>> client.data_path
PosixPath('data')

get_run_dict() → Any

Get run information from the collection.

Returns:

Run information as returned by the collection’s get_runs method.

Return type:

Any

Examples

>>> client = ClientBase(data_path="./data")
>>> client.collection = ...  # assign a collection with get_runs method
>>> client.get_run_dict()
...

property h5_kwargs: dict[str, Any]

Dictionary of HDF5 keyword arguments for file creation.

Returns:

Dictionary of HDF5 file creation parameters.

Return type:

dict

Examples

>>> client = ClientBase(data_path="./data")
>>> client.h5_kwargs["compression"]
'gzip'

property sample_rates: list[float]

List of sample rates to look for.

Returns:

Sample rates.

Return type:

list of float

Examples

>>> client = ClientBase(data_path="./data", sample_rates=[1, 8, 256])
>>> client.sample_rates
[1.0, 8.0, 256.0]

property save_path: Path

Path to save the mth5 file.

Returns:

Full path to the mth5 file.

Return type:

Path

Examples

>>> client = ClientBase(data_path="./data", save_path="./output", mth5_filename="test.h5")
>>> client.save_path
PosixPath('output/test.h5')

mth5.clients.fdsn module

FDSN

Module for working with FDSN clients using Obspy

Created on Fri Feb 4 15:53:21 2022

@author: jpeacock

class mth5.clients.fdsn.FDSN(client: str = 'IRIS', **kwargs)

Bases: ClientBase

build_network_dict(df: DataFrame, client: Client) → dict

Build a dictionary of networks keyed by network_id and start_time.

Parameters:

• df (pandas.DataFrame) – Request DataFrame.

• client (obspy.clients.fdsn.Client) – FDSN client instance.

Returns:

networks – Dictionary of networks.

Return type:

dict

Examples

>>> networks = client.build_network_dict(df, client)

build_station_dict(df: DataFrame, client: Client, networks_dict: dict) → dict

Build a dictionary of stations keyed by network_id and start_time.

Parameters:

• df (pandas.DataFrame) – Request DataFrame.

• client (obspy.clients.fdsn.Client) – FDSN client instance.

• networks_dict (dict) – Dictionary of networks.

Returns:

stations – Dictionary of stations.

Return type:

dict

Examples

>>> stations = client.build_station_dict(df, client, networks_dict)

get_df_from_inventory(inventory: Inventory) → DataFrame

Create a DataFrame from an ObsPy Inventory object.

Parameters:

inventory (obspy.Inventory) – ObsPy Inventory object.

Returns:

df – DataFrame in request format.

Return type:

pandas.DataFrame

Examples

>>> df = client.get_df_from_inventory(inventory)

get_fdsn_channel_map() → dict[str, str]

Get mapping of FDSN channel codes to internal codes.

Returns:

FDSN_CHANNEL_MAP – Dictionary mapping FDSN channel codes.

Return type:

dict

Examples

>>> channel_map = client.get_fdsn_channel_map()

get_inventory_from_df(df: DataFrame | str | Path, client: str | None = None, data: bool = True, max_tries: int = 10) → tuple[Inventory, Stream]

Get an ObsPy Inventory and Stream from a DataFrame request.

Parameters:

• df (pandas.DataFrame or str or Path) –

  DataFrame or path to CSV with columns:

  • ’network’ : FDSN Network code

  • ’station’ : FDSN Station code

  • ’location’ : FDSN Location code

  • ’channel’ : FDSN Channel code

  • ’start’ : Start time YYYY-MM-DDThh:mm:ss

  • ’end’ : End time YYYY-MM-DDThh:mm:ss

• client (str, optional) – FDSN client name (default: self.client).

• data (bool, optional) – If True, retrieves waveform data (default: True).

• max_tries (int, optional) – Maximum number of retry attempts (default: 10).

Returns:

• inventory (obspy.Inventory) – Inventory of metadata requested.

• streams (obspy.Stream) – Stream of waveform data.

Examples

>>> from mth5.clients.fdsn import FDSN
>>> import pandas as pd
>>> df = pd.DataFrame({
...     'network': ['XX'],
...     'station': ['1234'],
...     'location': [''],
...     'channel': ['LHZ'],
...     'start': ['2022-01-01T00:00:00'],
...     'end': ['2022-01-02T00:00:00']
... })
>>> client = FDSN()
>>> inv, streams = client.get_inventory_from_df(df)

get_run_group(mth5_obj_or_survey, station_id: str, run_id: str)

This method is key to merging wrangle_runs_into_containers_v1 and wrangle_runs_into_containers_v2. Because a v1 mth5 object can get a survey group with the same method as can a v2 survey_group

Thus we can replace run_group = m.stations_group.get_station(station_id).add_run(run_id) & run_group = survey_group.stations_group.get_station(station_id).add_run(run_id) with run_group = mth5_obj_or_survey.stations_group.get_station(station_id).add_run(run_id) :param mth5_obj_or_survey: :type mth5_obj_or_survey: mth5.mth5.MTH5 or mth5.groups.survey.SurveyGroup

get_run_list_from_station_id(m: MTH5, station_id: str, survey_id: str | None = None) → list[str]

ignored_groups created to address issue #153. This might be better placed closer to the core of mth5.

Parameters:

• m

• station_id

Returns:

run_list

Return type:

list of strings

get_station_streams(station_id: str) → Stream

Get streams for a certain station

get_unique_networks_and_stations(df: DataFrame) → list[dict]

Get unique networks and stations from a request DataFrame.

Parameters:

df (pandas.DataFrame) – Request DataFrame.

Returns:

unique_list – List of network dictionaries with stations.

Return type:

list of dict

Examples

>>> unique_list = client.get_unique_networks_and_stations(df)

get_waveforms_from_request_row(client: Client, row) → Stream

Retrieve waveform data for a request row.

Parameters:

• client (obspy.clients.fdsn.Client) – FDSN client instance.

• row (pandas.Series) – Row of request DataFrame.

Returns:

streams – ObsPy Stream object with waveform data.

Return type:

obspy.Stream

Examples

>>> streams = client.get_waveforms_from_request_row(client, row)

make_filename(df: DataFrame) → str

Make a filename from a request DataFrame of networks and stations.

Parameters:

df (pandas.DataFrame) – Request DataFrame.

Returns:

filename – Filename in the format network_01+stations_network_02+stations.h5

Return type:

str

Examples

>>> filename = client.make_filename(df)

make_mth5_from_fdsn_client(df: DataFrame | str | Path, path: str | Path | None = None, client: str | None = None, interact: bool = False) → Path

Create an MTH5 file from an FDSN data center request.

Parameters:

• df (pandas.DataFrame or str or Path) –

  DataFrame or path to CSV with columns:

  • ’network’ : FDSN Network code

  • ’station’ : FDSN Station code

  • ’location’ : FDSN Location code

  • ’channel’ : FDSN Channel code

  • ’start’ : Start time YYYY-MM-DDThh:mm:ss

  • ’end’ : End time YYYY-MM-DDThh:mm:ss

• path (str or Path, optional) – Path to save MTH5 file (default: current directory).

• client (str, optional) – FDSN client name (default: “IRIS”).

• interact (bool, optional) – Deprecated. If True, logs a warning (default: False).

Returns:

file_name – Path to the created MTH5 file.

Return type:

Path

Raises:

• AttributeError – If the input DataFrame is not properly formatted.

• ValueError – If the values of the DataFrame are not correct.

Examples

>>> from mth5.clients.fdsn import FDSN
>>> import pandas as pd
>>> df = pd.DataFrame({
...     'network': ['XX'],
...     'station': ['1234'],
...     'location': [''],
...     'channel': ['LHZ'],
...     'start': ['2022-01-01T00:00:00'],
...     'end': ['2022-01-02T00:00:00']
... })
>>> client = FDSN()
>>> file_path = client.make_mth5_from_fdsn_client(df)

make_mth5_from_inventory_and_streams(inventory: Inventory | str | Path, streams: Stream | list[str | Path], save_path: str | Path | None = None) → Path

Create an MTH5 file from an ObsPy Inventory and waveform streams.

Parameters:

• inventory (obspy.Inventory or str or Path) – ObsPy Inventory object or path to StationXML file.

• streams (obspy.Stream or list of str or Path) – ObsPy Stream object or list of file paths to waveform data.

• save_path (str or Path, optional) – Path to save MTH5 file (default: current directory).

Returns:

file_name – Path to the created MTH5 file.

Return type:

Path

Examples

>>> from mth5.clients.fdsn import FDSN
>>> inv = ... # ObsPy Inventory
>>> streams = ... # ObsPy Stream
>>> client = FDSN()
>>> file_path = client.make_mth5_from_inventory_and_streams(inv, streams)

pack_stream_into_run_group(run_group, run_stream: Stream)

property run_list_ne_stream_intervals_message: str

note about not equal stream intervals

run_timings_match_stream_timing(run_group, stream_start: UTCDateTime, stream_end: UTCDateTime) → bool

Checks start and end times in the run. Compares start and end times of runs to start and end times of traces. If True, will packs runs based on time spans.

Parameters:

• run_group (mth5.groups.run.RunGroup)

• stream_start (obspy.UTCDateTime)

• stream_end (obspy.UTCDateTime)

Return type:

bool

stream_boundaries(streams: Stream) → tuple[list[UTCDateTime], list[UTCDateTime]]

Identify start and end times of streams

Parameters:

streams (obspy.core.stream.Stream)

property streams

obspy.Stream object

wrangle_runs_into_containers(m: MTH5, station_id: str, survey_group=None) → None

Note 1: There used to be two separate functions for this, but now there is one run_group_source is defined as either m or survey_group depending on v0.1.0 or 0.2.0

Note 2: If/elif/elif/else Logic: The strategy is to add the group first. This will get the already filled in metadata to update the run_ts_obj. Then get streams an add existing metadata.

Parameters:

• m

• streams

• station_id

• survey_group

mth5.clients.geomag module

Created on Mon Nov 14 13:58:44 2022

@author: jpeacock

class mth5.clients.geomag.GeomagClient(**kwargs)

Bases: object

Get geomagnetic data from observatories.

key words

• observatory: Geogmangetic observatory ID

• type: type of data to get ‘adjusted’

• start: start date time to request UTC

• end: end date time to request UTC

• elements: components to get

• sampling_period: samples between measurements in seconds

• format: JSON or IAGA2002

See also

https://www.usgs.gov/tools/web-service-geomagnetism-data

property elements

property end

get_chunks()

Get the number of chunks of allowable sized to request, includes the elements

So the max length is the maximum time period that can be requested but includes the number of elements in the request. So if the max length is 172800 seconds and the sampling period is 1 second, then the maximum number of elements that can be requested is 172800 / (1 * len(elements)).

Returns:

DESCRIPTION

Return type:

TYPE

get_data(run_id='001', request_max=5)

Get data from geomag client at USGS based on the request. This might have to be done in chunks depending on the request size. The returned output is a json object, which we should turn into a ChannelTS object

For now read into a pandas dataframe and then into a ChannelTS

In the future, if the request is large, think about writing directly to an MTH5 for better efficiency.

Returns:

DESCRIPTION

Return type:

TYPE

property observatory

property sampling_period

property start

property user_agent

User agent for the URL request

Returns:

DESCRIPTION

Return type:

TYPE

class mth5.clients.geomag.USGSGeomag(**kwargs)

Bases: object

add_run_id(request_df)

Add run id to request df

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

add a run number to unique time windows for each observatory at each unique sampling period.

Return type:

pandas.DataFrame

property h5_kwargs

make_mth5_from_geomag(request_df)

Download geomagnetic observatory data from USGS webservices into an MTH5 using a request dataframe or csv file.

Parameters:

request_df (pandas.DataFrame, str or Path if csv file) –

DataFrame with columns

• ’observatory’ –> Observatory code

• ’type’ –> data type [ ‘variation’ | ‘adjusted’ | ‘quasi-definitive’ | ‘definitive’ ]

• ’elements’ –> Elements to get [D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z]

• ’sampling_period’ –> sample period [ 1 | 60 | 3600 ]

• ’start’ –> Start time YYYY-MM-DDThh:mm:ss

• ’end’ –> End time YYYY-MM-DDThh:mm:ss

Returns:

if interact is True an MTH5 object is returned otherwise the path to the file is returned

Return type:

Path or mth5.mth5.MTH5

See also

https://www.usgs.gov/tools/web-service-geomagnetism-data

validate_request_df(request_df)

Make sure the input request dataframe has the appropriate columns

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

valid request dataframe

Return type:

pandas.DataFrame

mth5.clients.lemi424 module

Created on Fri Oct 11 10:57:54 2024

@author: jpeacock

class mth5.clients.lemi424.LEMI424Client(data_path: str | Path, save_path: str | Path | None = None, mth5_filename: str = 'from_lemi424.h5', **kwargs: Any)

Bases: ClientBase

make_mth5_from_lemi424(survey_id: str, station_id: str, **kwargs: Any) → Path

Create an MTH5 file from LEMI 424 long period data.

Parameters:

• survey_id (str) – Survey identifier.

• station_id (str) – Station identifier.

• **kwargs (Any) – Additional keyword arguments to set as attributes.

Returns:

Path to the created mth5 file.

Return type:

Path

Examples

>>> client = LEMI424Client(data_path="./data")
>>> client.make_mth5_from_lemi424("SURVEY1", "ST01")
PosixPath('data/from_lemi424.h5')

mth5.clients.make_mth5 module

Make MTH5

This module provides helper functions to make MTH5 file from various clients

Supported Clients include:

• FDSN (through Obspy)

• Science Base (TODO)

• NCI - Australia (TODO)

• Phoenix MTU-5C

• Zen

• Phoenix legacy MTU (TODO)

• Metronix Geophysics

• USGS Geomagnetism

• LEMI (424 and 423)

• Metronix

• UoA (PR6-24 and Orange Box)

Updated on Wed Aug 25 19:57:00 2021

@author: jpeacock + tronan

class mth5.clients.make_mth5.MakeMTH5(mth5_version: str = '0.2.0', interact: bool = False, save_path: str | Path | None = None, **kwargs)

Bases: object

Factory class for creating MTH5 files from various data sources.

This class provides class methods to create MTH5 files from different magnetotelluric data acquisition systems and data repositories.

Parameters:

• mth5_version (str, default "0.2.0") – MTH5 file format version

• interact (bool, default False) – If True, keep file open for interactive use. If False, close file after creation.

• save_path (str or Path, optional) – Directory path to save MTH5 file. If None, uses current working directory.

• **kwargs (dict) – Additional keyword arguments for HDF5 file parameters. Any parameter starting with ‘h5’ will be used for HDF5 configuration.

h5_compression

HDF5 compression algorithm

Type:

str, default “gzip”

h5_compression_opts

Compression level (0-9 for gzip)

Type:

int, default 4

h5_shuffle

Enable byte shuffle filter for better compression

Type:

bool, default True

h5_fletcher32

Enable Fletcher32 checksum for data integrity

Type:

bool, default True

h5_data_level

Data processing level indicator

Type:

int, default 1

Examples

Create a basic MakeMTH5 instance:

>>> from mth5.clients import MakeMTH5
>>> maker = MakeMTH5(save_path="/path/to/save")
>>> print(maker)
MakeMTH5 Attibutes:
    mth5_version: 0.2.0
    h5_compression: gzip
    ...

Create with custom compression:

>>> maker = MakeMTH5(
...     save_path="/data/mt",
...     h5_compression="lzf",
...     h5_shuffle=False
... )

See also

mth5.mth5.MTH5

Main MTH5 file interface

classmethod from_fdsn_client(request_df: DataFrame, client: str = 'IRIS', **kwargs)

Create MTH5 file from FDSN data service.

Pull data from an FDSN archive like IRIS using ObsPy clients. The request DataFrame specifies which data to download.

Parameters:

• request_df (pd.DataFrame) –

  DataFrame with columns:

  • ’network’str

    FDSN Network code (e.g., ‘IU’, ‘TA’)

  • ’station’str

    FDSN Station code (e.g., ‘ANMO’, ‘CAS04’)

  • ’location’str

    FDSN Location code (e.g., ‘00’, ‘’)

  • ’channel’str

    FDSN Channel code (e.g., ‘LFE’, ‘BHZ’)

  • ’start’str

    Start time in format ‘YYYY-MM-DDThh:mm:ss’

  • ’end’str

    End time in format ‘YYYY-MM-DDThh:mm:ss’

• client (str, default "IRIS") – FDSN client name (e.g., ‘IRIS’, ‘USGS’, ‘NCEDC’)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=4).

Returns:

MTH5 object if interact=True, otherwise Path to created file

Return type:

mth5.mth5.MTH5 or Path

Raises:

• AttributeError – If the input DataFrame is not properly formatted

• ValueError – If the DataFrame column values are invalid

Notes

If any column value is blank, any matching value will be searched. For example, leaving ‘station’ blank will return all stations within the specified time range.

Examples

Create a request DataFrame and download data:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> # Define request
>>> request_df = pd.DataFrame({
...     'network': ['IU'],
...     'station': ['ANMO'],
...     'location': ['00'],
...     'channel': ['LF*'],
...     'start': ['2020-01-01T00:00:00'],
...     'end': ['2020-01-02T00:00:00']
... })
>>>
>>> # Create MTH5 with custom compression
>>> mth5_obj = MakeMTH5.from_fdsn_client(
...     request_df,
...     client='IRIS',
...     h5_compression_opts=1
... )

See also

from_fdsn_miniseed_and_stationxml

Create from existing files

obspy.clients.fdsn

ObsPy FDSN client documentation

classmethod from_fdsn_miniseed_and_stationxml(station_xml_path: str | Path, miniseed_files: str | Path | list[str | Path], save_path: str | Path | None = None, **kwargs)

Create MTH5 from existing StationXML and miniSEED files.

Use this method when you already have StationXML and miniSEED files downloaded from an FDSN client or created locally.

Parameters:

• station_xml_path (str, Path, or obspy.Inventory) – Full path to StationXML file or an ObsPy Inventory object

• miniseed_files (str, Path, list, or obspy.Stream) – List of miniSEED file paths or ObsPy Stream objects. Can also be a single file path or Stream object.

• save_path (str or Path, optional) – Directory to save new MTH5 file. If None, saves to current working directory.

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’).

Returns:

Path to created MTH5 file. Filename format is {network}_{station}.h5 based on unique network and station codes.

Return type:

Path

Raises:

TypeError – If inputs are not of correct type

Examples

Create MTH5 from existing files:

>>> from mth5.clients import MakeMTH5
>>> from pathlib import Path
>>>
>>> # Define file paths
>>> station_xml = Path("data/station.xml")
>>> miniseed = [
...     Path("data/IU.ANMO.00.LFE.mseed"),
...     Path("data/IU.ANMO.00.LFN.mseed")
... ]
>>>
>>> # Create MTH5
>>> mth5_path = MakeMTH5.from_fdsn_miniseed_and_stationxml(
...     station_xml,
...     miniseed,
...     save_path="output",
...     h5_compression="lzf"
... )
>>> print(mth5_path)
output/IU_ANMO.h5

Using ObsPy objects directly:

>>> from obspy import read, read_inventory
>>>
>>> inventory = read_inventory("station.xml")
>>> stream = read("data/*.mseed")
>>>
>>> mth5_path = MakeMTH5.from_fdsn_miniseed_and_stationxml(
...     inventory,
...     stream,
...     save_path="output"
... )

See also

from_fdsn_client

Download and create in one step

classmethod from_intermag(request_df: DataFrame | str | Path, **kwargs)

Create MTH5 from INTERMAGNET observatory data.

Downloads geomagnetic observatory data from INTERMAG webservices into an MTH5 file using a request DataFrame or CSV file.

Parameters:

• request_df (pd.DataFrame, str, or Path) –

  Request definition as DataFrame or path to CSV file. Required columns:

  • observatory : str - Observatory code (e.g., ‘BOU’, ‘FRN’)

  • type : str - Data type: ‘variation’, ‘adjusted’, ‘quasi-definitive’, or ‘definitive’

  • elements : str - Geomagnetic elements to retrieve: D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z

  • sampling_period : int - Sample period in seconds: 1, 60, or 3600

  • start : str - Start time in YYYY-MM-DDThh:mm:ss format (UTC)

  • end : str - End time in YYYY-MM-DDThh:mm:ss format (UTC)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1).

Returns:

If interact=False (default), returns Path to created MTH5 file. If interact=True, returns MTH5 object with file open.

Return type:

Path or MTH5

Examples

Create MTH5 from USGS Boulder observatory using DataFrame:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> request = pd.DataFrame([{
...     'observatory': 'BOU',
...     'type': 'variation',
...     'elements': 'XYZF',
...     'sampling_period': 1,
...     'start': '2020-01-01T00:00:00',
...     'end': '2020-01-02T00:00:00'
... }])
>>>
>>> mth5_path = MakeMTH5.from_usgs_geomag(
...     request,
...     h5_compression='gzip',
...     h5_compression_opts=1
... )

Using CSV file:

>>> mth5_path = MakeMTH5.from_usgs_geomag('requests.csv')

Multiple observatories and periods:

>>> request = pd.DataFrame([
...     {'observatory': 'BOU', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 1,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'},
...     {'observatory': 'FRN', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 60,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'}
... ])
>>> mth5_path = MakeMTH5.from_usgs_geomag(request)

See also

mt_io.usgs_geomag.USGSGeomag

USGS geomagnetic data client

classmethod from_lemi(data_path, survey_id, station_id, sample_rates=None, mth5_filename=None, save_path=None, **kwargs)

Build a MTH5 file from LEMI instrument data.

Supports both LEMI-424 (long period, .txt) and LEMI-423 (broadband, .B423). Works mainly on a station by station basis because there is limited metadata in LEMI files.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

Example:

>>> # LEMI-424 data
>>> MakeMTH5.from_lemi(
...     '/data/lemi424', 'Survey01', 'MT001',
...     sample_rates=[1],
...     **{'h5_compression_opts': 1}
... )
>>>
>>> # LEMI-423 data at 1000 Hz
>>> MakeMTH5.from_lemi(
...     '/data/lemi423', 'Survey01', 'MT002',
...     sample_rates=[1000]
... )
>>>
>>> # LEMI-423 data, unknown rate (include all possible rates)
>>> MakeMTH5.from_lemi(
...     '/data/lemi423', 'Survey01', 'MT003',
...     sample_rates=[4000, 2000, 1000, 500, 250]
... )

Parameters:

• data_path (str or Path) – Directory where LEMI data files are, could be a single station or a full directory of stations.

• survey_id (str) – Survey ID for all stations

• station_id (str) – Station ID for station

• sample_rates (list or None, optional) – Sample rates to include. If None, will auto-detect and include all sample rates found in files. If specified, only processes files matching those rates. Valid rates: - LEMI-424: [1] Hz (long period only) - LEMI-423: [4000], [2000], [1000], [500], [250] Hz (broadband, auto-detected) Examples: - None (default): Process all files regardless of sample rate - [1]: Only LEMI-424 files - [1000]: Only LEMI-423 files recorded at 1000 Hz - [4000, 2000, 1000, 500, 250]: All possible LEMI-423 rates

• mth5_filename (str, optional) – Filename for the H5, defaults to ‘from_lemi.h5’

• save_path (str or Path, optional) – Path to save H5 file to, defaults to None which will place the file in data_path

Returns:

Path to MTH5 file

Return type:

Path

Note

• LEMI-424 files are .txt format at 1 Hz sample rate

• LEMI-423 files are .B423 format with variable sample rates

• Station and survey IDs must be provided (not in file metadata)

classmethod from_lemi417(data_path: str | Path, survey_id: str, station_id: str, mth5_filename: str = 'from_lemi417.h5', save_path: str | Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/mth5/checkouts/latest/docs'), **kwargs)

Create MTH5 from LEMI-417 long period data.

Builds an MTH5 file from LEMI-417 instrument data on a station-by-station basis. LEMI data has limited metadata, so survey and station IDs must be provided.

Parameters:

• data_path (str or Path) – Directory where LEMI-417 data files are stored. Can be single station or full directory.

• survey_id (str) – Survey ID to apply to all stations

• station_id (str) – Station ID for this station’s data

• mth5_filename (str, default 'from_lemi417.h5') – Filename for the MTH5 output file

• save_path (str or Path, default current directory) – Directory to save MTH5 file

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’).

Returns:

Path to created MTH5 file

Return type:

Path

Notes

LEMI-417 is a long-period magnetotelluric instrument. Data files have limited embedded metadata, requiring manual specification of survey and station information.

Process each station individually due to minimal automatic metadata extraction capabilities.

classmethod from_lemi424(data_path, survey_id, station_id, sample_rates=None, mth5_filename=None, save_path=None, **kwargs)

Backward-compatible constructor that uses LEMI424Client.

classmethod from_metronix(data_path, sample_rates=[128], mth5_filename=None, save_path=None, run_name_zeros=0, **kwargs)

Build a MTH5 file from Metronix Geophysics ATSS + JSON files saved in their new folder structure.

Parameters:

• data_path (str or pathlib.Path) – Highest level of where you want to archive data from, usuall the survey level. If you want just a single station, then use the station folder path.

• sample_rates (list of floats, optional) – sample rates to archive in samples/sercond, defaults to [128]

• mth5_filename (str, optional) – filename for the H5, defaults to ‘from_lemi424.h5’

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• run_name_zeros (int, defaults to 0) – number of zeros to include in new run names, will be named as ‘sr{sample_rate}_{run_id:0{run_name_zeros}}’. If set to 0 then will use the original run name, usually ‘run_0001’.

Returns:

Path to MTH5 file

Return type:

Path

classmethod from_nims(data_path, sample_rates=[4096, 1024, 256], save_path=None, calibration_path=None, survey_id=None, combine=True, **kwargs)

Create an MTH5 from nims data.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

>>> MakeMTH5.from_nims(
    data_path, **{'h5_compression_opts': 1}
    )

Parameters:

• data_path (Path, str) – directory to where data are stored

• sample_rates (list, optional) – sample rates to include, defaults to [4096, 1024, 256]

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• calibration_path (str or Path, optional) – path to calibration file amtant.cal, defaults to None

• survey_id (string) – survey ID to apply to all station found under data_path, defaults to None

• combine (bool) – if True combine the runs into a single run sampled at 1s, defaults to True

Returns:

MTH5 file name

Return type:

Path

classmethod from_phoenix(data_path, mth5_filename=None, save_path=None, sample_rates=[150, 24000], receiver_calibration_dict=None, sensor_calibration_dict=None, **kwargs)

Build an H5 file from Phoenix MTU-5C files. The key step when working with Phoenix data is to export the scal and rxcal files into JSON using EMPower. Place these files in a folder that you can easily find, and you can use this folder as inputs for the receiver_calibration_dict and sensor_calibration_dict which will search the folder and read in all the rxcal and scal files into appropriate dictionaries such that the filters will be linked with the data for appropriate calibration.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

>>> MakeMTH5.from_phoenix(
    data_path, **{'h5_compression_opts': 1}
    )

Parameters:

• data_path (str or Path) – Directory where data files are, could be a single station or a full directory of stations.

• mth5_filename (str, optional) – filename for the H5, defaults to ‘from_phoenix.h5’

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• sample_rates (list, optional) – sample rates to include in file, defaults to [150, 24000]

• receiver_calibration_dict (str, Path or dict, optional) – This can either be a directory path to where the rxcal.json files are or a dictionary where keys are the receiver IDs and the values are the filename of the rxcal.json file, defaults to None

• sensor_calibration_dict (str, Path, dict, optional) – This can either be a directory path to where the scal.json files are or a dictionary where keys are the sensor IDs and the values are the PhoenixCalibration objects that have read in the scal.json file for that sensor, defaults to None

Returns:

Path to MTH5 file

Return type:

Path

classmethod from_uoa(data_path, survey_id, station_id, instrument_type, run_id='001', mth5_filename=None, save_path=None, **kwargs)

Build a MTH5 file from University of Adelaide instrument data.

Supports PR6-24 (Earth Data Logger) and Orange Box instruments.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

Example:

>>> # PR6-24 long-period data
>>> MakeMTH5.from_uoa(
...     '/data/pr624', 'Survey01', 'MT001',
...     instrument_type='pr624',
...     sample_rate=10.0,
...     sensor_type='bartington',
...     dipole_length_ex=50.0,
...     dipole_length_ey=50.0,
...     **{'h5_compression_opts': 1}
... )
>>>
>>> # Orange Box data
>>> MakeMTH5.from_uoa(
...     '/data/orange', 'Survey01', 'ST61',
...     instrument_type='orange',
...     dipole_length_ex=100.0,
...     dipole_length_ey=100.0
... )

Parameters:

• data_path (str or Path) – Directory or file path to UoA data

• survey_id (str) – Survey ID

• station_id (str) – Station ID

• instrument_type (str) – ‘pr624’ or ‘orange’

• run_id (str, optional) – Run ID, defaults to “001”

• mth5_filename (str, optional) – Filename for the H5, defaults to ‘from_uoa.h5’

• save_path (str or Path, optional) – Path to save H5 file to, defaults to None which will place the file in data_path

• kwargs –

  Additional arguments for reader:

  PR6-24 arguments:

  • sample_rate (float): REQUIRED - sample rate in Hz

  • sensor_type (str): ‘bartington’ or ‘lemi120’

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • calibration_fn_bx (str): LEMI-120 .rsp file for Bx

  • calibration_fn_by (str): LEMI-120 .rsp file for By

  • calibration_fn_bz (str): LEMI-120 .rsp file for Bz

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

  Orange Box arguments:

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

Returns:

Path to MTH5 file

Return type:

Path

Note

• PR6-24 requires sample_rate parameter (not in file metadata)

• Orange Box auto-detects sample rate from file header

classmethod from_usgs_geomag(request_df: DataFrame | str | Path, **kwargs)

Create MTH5 from USGS geomagnetic observatory data.

Downloads geomagnetic observatory data from USGS webservices into an MTH5 file using a request DataFrame or CSV file.

Parameters:

• request_df (pd.DataFrame, str, or Path) –

  Request definition as DataFrame or path to CSV file. Required columns:

  • observatory : str - Observatory code (e.g., ‘BOU’, ‘FRN’)

  • type : str - Data type: ‘variation’, ‘adjusted’, ‘quasi-definitive’, or ‘definitive’

  • elements : str - Geomagnetic elements to retrieve: D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z

  • sampling_period : int - Sample period in seconds: 1, 60, or 3600

  • start : str - Start time in YYYY-MM-DDThh:mm:ss format (UTC)

  • end : str - End time in YYYY-MM-DDThh:mm:ss format (UTC)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1).

Returns:

If interact=False (default), returns Path to created MTH5 file. If interact=True, returns MTH5 object with file open.

Return type:

Path or MTH5

Notes

See USGS Geomagnetism Data web service for more information: https://www.usgs.gov/tools/web-service-geomagnetism-data

Examples

Create MTH5 from USGS Boulder observatory using DataFrame:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> request = pd.DataFrame([{
...     'observatory': 'BOU',
...     'type': 'variation',
...     'elements': 'XYZF',
...     'sampling_period': 1,
...     'start': '2020-01-01T00:00:00',
...     'end': '2020-01-02T00:00:00'
... }])
>>>
>>> mth5_path = MakeMTH5.from_usgs_geomag(
...     request,
...     h5_compression='gzip',
...     h5_compression_opts=1
... )

Using CSV file:

>>> mth5_path = MakeMTH5.from_usgs_geomag('requests.csv')

Multiple observatories and periods:

>>> request = pd.DataFrame([
...     {'observatory': 'BOU', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 1,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'},
...     {'observatory': 'FRN', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 60,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'}
... ])
>>> mth5_path = MakeMTH5.from_usgs_geomag(request)

See also

mt_io.usgs_geomag.USGSGeomag

USGS geomagnetic data client

classmethod from_zen(data_path: str | Path, sample_rates: list[int] = [4096, 1024, 256], calibration_path: str | Path | None = None, survey_id: str | None = None, combine: bool = True, **kwargs)

Create MTH5 from Zonge ZEN data files.

Processes ZEN data files from a directory structure and creates an MTH5 file with organized time series data.

Parameters:

• data_path (str or Path) – Directory where ZEN data files are stored

• sample_rates (list of int, default [4096, 1024, 256]) – Sample rates to include in Hz

• calibration_path (str or Path, optional) – Path to calibration file (amtant.cal). If None, looks for calibration file in data_path.

• survey_id (str, optional) – Survey ID to apply to all stations found under data_path. If None, attempts to extract from directory structure.

• combine (bool, default True) – If True, combine multiple runs into single run sampled at 1s

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1). Use save_path to specify output directory.

Returns:

Path to created MTH5 file

Return type:

Path

Notes

ZEN data is typically organized with multiple .Z3D files per station. The reader processes these files and organizes them into runs based on sampling rate and timing.

When combine=True, all runs are merged into a single continuous run sampled at 1 second intervals, which is useful for long-term datasets.

Examples

Create MTH5 from ZEN data directory:

>>> from mth5.clients import MakeMTH5
>>> from pathlib import Path
>>>
>>> data_dir = Path("data/zen_survey")
>>> mth5_path = MakeMTH5.from_zen(
...     data_dir,
...     sample_rates=[4096, 256],
...     survey_id="MT001",
...     save_path="output"
... )

With calibration file and HDF5 compression:

>>> mth5_path = MakeMTH5.from_zen(
...     "data/zen_survey",
...     calibration_path="data/amtant.cal",
...     survey_id="MT001",
...     combine=False,
...     h5_compression="gzip",
...     h5_compression_opts=4
... )

Process all sample rates without combining:

>>> mth5_path = MakeMTH5.from_zen(
...     "data/zen_survey",
...     sample_rates=[4096, 1024, 256, 64, 4],
...     combine=False
... )

See also

mt_io.zen.ZenCollection

ZEN data reader

get_h5_kwargs() → dict

Extract HDF5-related keyword arguments from instance attributes.

Returns:

Dictionary of HDF5 configuration parameters including version, compression settings, shuffle, fletcher32, and data level.

Return type:

dict

Examples

>>> maker = MakeMTH5(h5_compression="lzf", h5_data_level=2)
>>> kwargs = maker.get_h5_kwargs()
>>> print(kwargs["h5_compression"])
lzf

property save_path: Path

Get the save path as a Path object.

mth5.clients.metronix module

Created on Wed Nov 27 11:23:50 2024

@author: jpeacock

class mth5.clients.metronix.MetronixClient(data_path, sample_rates=[128], save_path=None, calibration_path=None, mth5_filename='from_metronix.h5', **kwargs)

Bases: ClientBase

get_run_dict(run_name_zeros=0)

get run information

Returns:

DESCRIPTION

Return type:

TYPE

get_survey_id(station_dict)

get survey name from a dictionary of a single station of runs :param station_dict: DESCRIPTION :type station_dict: TYPE :return: DESCRIPTION :rtype: TYPE

make_mth5_from_metronix(run_name_zeros=0, **kwargs)

Create an MTH5 from new ATSS + JSON style Metronix data.

Parameters:

**kwargs –

DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

set_station_metadata(station_dict, station_group)

set station group metadata from information in the station dict

Parameters:

• station_dict (TYPE) – DESCRIPTION

• station_group (TYPE) – DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

mth5.clients.phoenix module

class mth5.clients.phoenix.PhoenixClient(data_path: str | Path, sample_rates: list[int] = [150, 24000], save_path: str | Path | None = None, receiver_calibration_dict: dict | str | Path = {}, sensor_calibration_dict: dict | str | Path = {}, mth5_filename: str = 'from_phoenix.h5', **kwargs: dict)

Bases: ClientBase

make_mth5_from_phoenix(**kwargs: dict) → str | Path | None

Make an MTH5 from Phoenix files.

Split into runs, account for filters. Updates the MTH5 file with Phoenix data.

Parameters:

**kwargs (dict) – Optional keyword arguments to override instance attributes.

Returns:

Path to the saved MTH5 file.

Return type:

str, Path, or None

Examples

>>> client = PhoenixClient('data/path', save_path='output.h5')
>>> client.make_mth5_from_phoenix()
'output.h5'

property receiver_calibration_dict: dict

Receiver calibrations.

Returns:

Dictionary mapping receiver IDs to calibration file paths.

Return type:

dict

Examples

>>> client = PhoenixClient('data/path')
>>> client.receiver_calibration_dict = {'RX001': Path('RX001_rxcal.json')}
>>> client.receiver_calibration_dict
{'RX001': Path('RX001_rxcal.json')}

property sensor_calibration_dict: dict

Sensor calibration dictionary.

Returns:

Dictionary mapping sensor IDs to PhoenixCalibration objects.

Return type:

dict

Examples

>>> client = PhoenixClient('data/path')
>>> client.sensor_calibration_dict = {'H001': PhoenixCalibration('H001_scal.json')}
>>> client.sensor_calibration_dict['H001']
<PhoenixCalibration object>

mth5.clients.zen module

class mth5.clients.zen.ZenClient(data_path, sample_rates=[4096, 1024, 256], save_path=None, calibration_path=None, mth5_filename='from_zen.h5', **kwargs)

Bases: ClientBase

property calibration_path

Path to calibration data

get_run_dict()

Get Run information

Returns:

DESCRIPTION

Return type:

TYPE

get_survey(station_dict)

get survey name from a dictionary of a single station of runs :param station_dict: DESCRIPTION :type station_dict: TYPE :return: DESCRIPTION :rtype: TYPE

make_mth5_from_zen(survey_id=None, combine=True, **kwargs)

Make an MTH5 from Phoenix files. Split into runs, account for filters

Parameters:

• data_path (TYPE, optional) – DESCRIPTION, defaults to None

• sample_rates (TYPE, optional) – DESCRIPTION, defaults to None

• save_path (TYPE, optional) – DESCRIPTION, defaults to None

Returns:

DESCRIPTION

Return type:

TYPE

Module contents

Client package exports.

Use lazy imports so optional dependencies do not fail package import at module import time. Symbols are loaded on first access.

class mth5.clients.FDSN(client: str = 'IRIS', **kwargs)

Bases: ClientBase

build_network_dict(df: DataFrame, client: Client) → dict

Build a dictionary of networks keyed by network_id and start_time.

Parameters:

• df (pandas.DataFrame) – Request DataFrame.

• client (obspy.clients.fdsn.Client) – FDSN client instance.

Returns:

networks – Dictionary of networks.

Return type:

dict

Examples

>>> networks = client.build_network_dict(df, client)

build_station_dict(df: DataFrame, client: Client, networks_dict: dict) → dict

Build a dictionary of stations keyed by network_id and start_time.

Parameters:

• df (pandas.DataFrame) – Request DataFrame.

• client (obspy.clients.fdsn.Client) – FDSN client instance.

• networks_dict (dict) – Dictionary of networks.

Returns:

stations – Dictionary of stations.

Return type:

dict

Examples

>>> stations = client.build_station_dict(df, client, networks_dict)

get_df_from_inventory(inventory: Inventory) → DataFrame

Create a DataFrame from an ObsPy Inventory object.

Parameters:

inventory (obspy.Inventory) – ObsPy Inventory object.

Returns:

df – DataFrame in request format.

Return type:

pandas.DataFrame

Examples

>>> df = client.get_df_from_inventory(inventory)

get_fdsn_channel_map() → dict[str, str]

Get mapping of FDSN channel codes to internal codes.

Returns:

FDSN_CHANNEL_MAP – Dictionary mapping FDSN channel codes.

Return type:

dict

Examples

>>> channel_map = client.get_fdsn_channel_map()

get_inventory_from_df(df: DataFrame | str | Path, client: str | None = None, data: bool = True, max_tries: int = 10) → tuple[Inventory, Stream]

Get an ObsPy Inventory and Stream from a DataFrame request.

Parameters:

• df (pandas.DataFrame or str or Path) –

  DataFrame or path to CSV with columns:

  • ’network’ : FDSN Network code

  • ’station’ : FDSN Station code

  • ’location’ : FDSN Location code

  • ’channel’ : FDSN Channel code

  • ’start’ : Start time YYYY-MM-DDThh:mm:ss

  • ’end’ : End time YYYY-MM-DDThh:mm:ss

• client (str, optional) – FDSN client name (default: self.client).

• data (bool, optional) – If True, retrieves waveform data (default: True).

• max_tries (int, optional) – Maximum number of retry attempts (default: 10).

Returns:

• inventory (obspy.Inventory) – Inventory of metadata requested.

• streams (obspy.Stream) – Stream of waveform data.

Examples

>>> from mth5.clients.fdsn import FDSN
>>> import pandas as pd
>>> df = pd.DataFrame({
...     'network': ['XX'],
...     'station': ['1234'],
...     'location': [''],
...     'channel': ['LHZ'],
...     'start': ['2022-01-01T00:00:00'],
...     'end': ['2022-01-02T00:00:00']
... })
>>> client = FDSN()
>>> inv, streams = client.get_inventory_from_df(df)

get_run_group(mth5_obj_or_survey, station_id: str, run_id: str)

This method is key to merging wrangle_runs_into_containers_v1 and wrangle_runs_into_containers_v2. Because a v1 mth5 object can get a survey group with the same method as can a v2 survey_group

Thus we can replace run_group = m.stations_group.get_station(station_id).add_run(run_id) & run_group = survey_group.stations_group.get_station(station_id).add_run(run_id) with run_group = mth5_obj_or_survey.stations_group.get_station(station_id).add_run(run_id) :param mth5_obj_or_survey: :type mth5_obj_or_survey: mth5.mth5.MTH5 or mth5.groups.survey.SurveyGroup

get_run_list_from_station_id(m: MTH5, station_id: str, survey_id: str | None = None) → list[str]

ignored_groups created to address issue #153. This might be better placed closer to the core of mth5.

Parameters:

• m

• station_id

Returns:

run_list

Return type:

list of strings

get_station_streams(station_id: str) → Stream

Get streams for a certain station

get_unique_networks_and_stations(df: DataFrame) → list[dict]

Get unique networks and stations from a request DataFrame.

Parameters:

df (pandas.DataFrame) – Request DataFrame.

Returns:

unique_list – List of network dictionaries with stations.

Return type:

list of dict

Examples

>>> unique_list = client.get_unique_networks_and_stations(df)

get_waveforms_from_request_row(client: Client, row) → Stream

Retrieve waveform data for a request row.

Parameters:

• client (obspy.clients.fdsn.Client) – FDSN client instance.

• row (pandas.Series) – Row of request DataFrame.

Returns:

streams – ObsPy Stream object with waveform data.

Return type:

obspy.Stream

Examples

>>> streams = client.get_waveforms_from_request_row(client, row)

make_filename(df: DataFrame) → str

Make a filename from a request DataFrame of networks and stations.

Parameters:

df (pandas.DataFrame) – Request DataFrame.

Returns:

filename – Filename in the format network_01+stations_network_02+stations.h5

Return type:

str

Examples

>>> filename = client.make_filename(df)

make_mth5_from_fdsn_client(df: DataFrame | str | Path, path: str | Path | None = None, client: str | None = None, interact: bool = False) → Path

Create an MTH5 file from an FDSN data center request.

Parameters:

• df (pandas.DataFrame or str or Path) –

  DataFrame or path to CSV with columns:

  • ’network’ : FDSN Network code

  • ’station’ : FDSN Station code

  • ’location’ : FDSN Location code

  • ’channel’ : FDSN Channel code

  • ’start’ : Start time YYYY-MM-DDThh:mm:ss

  • ’end’ : End time YYYY-MM-DDThh:mm:ss

• path (str or Path, optional) – Path to save MTH5 file (default: current directory).

• client (str, optional) – FDSN client name (default: “IRIS”).

• interact (bool, optional) – Deprecated. If True, logs a warning (default: False).

Returns:

file_name – Path to the created MTH5 file.

Return type:

Path

Raises:

• AttributeError – If the input DataFrame is not properly formatted.

• ValueError – If the values of the DataFrame are not correct.

Examples

>>> from mth5.clients.fdsn import FDSN
>>> import pandas as pd
>>> df = pd.DataFrame({
...     'network': ['XX'],
...     'station': ['1234'],
...     'location': [''],
...     'channel': ['LHZ'],
...     'start': ['2022-01-01T00:00:00'],
...     'end': ['2022-01-02T00:00:00']
... })
>>> client = FDSN()
>>> file_path = client.make_mth5_from_fdsn_client(df)

make_mth5_from_inventory_and_streams(inventory: Inventory | str | Path, streams: Stream | list[str | Path], save_path: str | Path | None = None) → Path

Create an MTH5 file from an ObsPy Inventory and waveform streams.

Parameters:

• inventory (obspy.Inventory or str or Path) – ObsPy Inventory object or path to StationXML file.

• streams (obspy.Stream or list of str or Path) – ObsPy Stream object or list of file paths to waveform data.

• save_path (str or Path, optional) – Path to save MTH5 file (default: current directory).

Returns:

file_name – Path to the created MTH5 file.

Return type:

Path

Examples

>>> from mth5.clients.fdsn import FDSN
>>> inv = ... # ObsPy Inventory
>>> streams = ... # ObsPy Stream
>>> client = FDSN()
>>> file_path = client.make_mth5_from_inventory_and_streams(inv, streams)

pack_stream_into_run_group(run_group, run_stream: Stream)

property run_list_ne_stream_intervals_message: str

note about not equal stream intervals

run_timings_match_stream_timing(run_group, stream_start: UTCDateTime, stream_end: UTCDateTime) → bool

Checks start and end times in the run. Compares start and end times of runs to start and end times of traces. If True, will packs runs based on time spans.

Parameters:

• run_group (mth5.groups.run.RunGroup)

• stream_start (obspy.UTCDateTime)

• stream_end (obspy.UTCDateTime)

Return type:

bool

stream_boundaries(streams: Stream) → tuple[list[UTCDateTime], list[UTCDateTime]]

Identify start and end times of streams

Parameters:

streams (obspy.core.stream.Stream)

property streams

obspy.Stream object

wrangle_runs_into_containers(m: MTH5, station_id: str, survey_group=None) → None

Note 1: There used to be two separate functions for this, but now there is one run_group_source is defined as either m or survey_group depending on v0.1.0 or 0.2.0

Note 2: If/elif/elif/else Logic: The strategy is to add the group first. This will get the already filled in metadata to update the run_ts_obj. Then get streams an add existing metadata.

Parameters:

• m

• streams

• station_id

• survey_group

class mth5.clients.Intermag(**kwargs)

Bases: object

add_run_id(request_df)

Add run id to request df

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

add a run number to unique time windows for each observatory at each unique sampling period.

Return type:

pandas.DataFrame

property h5_kwargs

make_mth5_from_intermag(request_df)

Download geomagnetic observatory data from USGS webservices into an MTH5 using a request dataframe or csv file.

Parameters:

request_df (pandas.DataFrame, str or Path if csv file) –

DataFrame with columns

• ’observatory’ –> Observatory code

• ’type’ –> data type [ ‘variation’ | ‘adjusted’ | ‘quasi-definitive’ | ‘definitive’ ]

• ’elements’ –> Elements to get [D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z]

• ’sampling_period’ –> sample period [ 1 | 60 | 3600 ]

• ’start’ –> Start time YYYY-MM-DDThh:mm:ss

• ’end’ –> End time YYYY-MM-DDThh:mm:ss

Returns:

if interact is True an MTH5 object is returned otherwise the path to the file is returned

Return type:

Path or mth5.mth5.MTH5

See also

https://www.usgs.gov/tools/web-service-geomagnetism-data

validate_request_df(request_df)

Make sure the input request dataframe has the appropriate columns

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

valid request dataframe

Return type:

pandas.DataFrame

class mth5.clients.LEMI417Client(data_path: str | Path, save_path: str | Path | None = None, mth5_filename: str = 'from_lemi417.h5', **kwargs: Any)

Bases: ClientBase

make_mth5_from_lemi417(survey_id: str, station_id: str, **kwargs: Any) → Path

Create an MTH5 file from LEMI 417 long period data.

Parameters:

• survey_id (str) – Survey identifier.

• station_id (str) – Station identifier.

• **kwargs (Any) – Additional attribute parameters.

Returns:

Path to the generated MTH5 file.

Return type:

Path

class mth5.clients.LEMI424Client(data_path: str | Path, save_path: str | Path | None = None, mth5_filename: str = 'from_lemi424.h5', **kwargs: Any)

Bases: ClientBase

make_mth5_from_lemi424(survey_id: str, station_id: str, **kwargs: Any) → Path

Create an MTH5 file from LEMI 424 long period data.

Parameters:

• survey_id (str) – Survey identifier.

• station_id (str) – Station identifier.

• **kwargs (Any) – Additional keyword arguments to set as attributes.

Returns:

Path to the created mth5 file.

Return type:

Path

Examples

>>> client = LEMI424Client(data_path="./data")
>>> client.make_mth5_from_lemi424("SURVEY1", "ST01")
PosixPath('data/from_lemi424.h5')

class mth5.clients.LEMIClient(data_path, save_path=None, sample_rates=[1], mth5_filename='from_lemi.h5', **kwargs)

Bases: ClientBase

Client for creating MTH5 files from LEMI instrument data.

Supports both LEMI-424 and LEMI-423 instruments: - LEMI-424: Long period data (.txt files, 1 Hz) - LEMI-423: Broadband data (.B423 files, 4000/2000/1000/500/250 Hz)

Parameters:

• data_path (str or pathlib.Path) – Path to directory containing LEMI files

• save_path (str or pathlib.Path, optional) – Path to save MTH5 file, defaults to data_path

• sample_rates (list, optional) – Sample rates to include, defaults to [1] Valid rates: - LEMI-424: [1] (long period only) - LEMI-423: [4000, 2000, 1000, 500, 250] (broadband, auto-detected from tick counter) To include all LEMI-423 rates: [4000, 2000, 1000, 500, 250]

• mth5_filename (str, optional) – Name of output MTH5 file, defaults to “from_lemi.h5”

Example:

>>> from mth5.clients import LEMIClient
>>> # LEMI-424 data
>>> lc = LEMIClient("/path/to/lemi424/data", sample_rates=[1])
>>> mth5_path = lc.make_mth5_from_lemi("Survey01", "MT001")
>>>
>>> # LEMI-423 data at 1000 Hz
>>> lc = LEMIClient("/path/to/lemi423/data", sample_rates=[1000])
>>> mth5_path = lc.make_mth5_from_lemi("Survey01", "MT002")
>>>
>>> # LEMI-423 data, unknown sample rate (include all possible)
>>> lc = LEMIClient("/path/to/lemi423/data",
...                 sample_rates=[4000, 2000, 1000, 500, 250])
>>> mth5_path = lc.make_mth5_from_lemi("Survey01", "MT003")

make_mth5_from_lemi(survey_id, station_id, **kwargs)

Create an MTH5 file from LEMI instrument data.

Works with both LEMI-424 (.txt) and LEMI-423 (.B423) files.

Parameters:

• survey_id (str) – Survey identifier

• station_id (str) – Station identifier

• kwargs (dict) – Additional keyword arguments passed to collection

Returns:

Path to created MTH5 file

Return type:

pathlib.Path

Example:

>>> from mth5.clients import LEMIClient
>>> lc = LEMIClient("/data/lemi423", sample_rates=[1000])
>>> mth5_file = lc.make_mth5_from_lemi("MySurvey", "MT001")
>>> print(f"Created: {mth5_file}")

make_mth5_from_lemi424(survey_id, station_id, **kwargs)

Backward compatibility alias for make_mth5_from_lemi().

Deprecated since version 0.4.0: Use make_mth5_from_lemi() instead. This method will be removed in version 1.0.0.

class mth5.clients.MakeMTH5(mth5_version: str = '0.2.0', interact: bool = False, save_path: str | Path | None = None, **kwargs)

Bases: object

Factory class for creating MTH5 files from various data sources.

This class provides class methods to create MTH5 files from different magnetotelluric data acquisition systems and data repositories.

Parameters:

• mth5_version (str, default "0.2.0") – MTH5 file format version

• interact (bool, default False) – If True, keep file open for interactive use. If False, close file after creation.

• save_path (str or Path, optional) – Directory path to save MTH5 file. If None, uses current working directory.

• **kwargs (dict) – Additional keyword arguments for HDF5 file parameters. Any parameter starting with ‘h5’ will be used for HDF5 configuration.

h5_compression

HDF5 compression algorithm

Type:

str, default “gzip”

h5_compression_opts

Compression level (0-9 for gzip)

Type:

int, default 4

h5_shuffle

Enable byte shuffle filter for better compression

Type:

bool, default True

h5_fletcher32

Enable Fletcher32 checksum for data integrity

Type:

bool, default True

h5_data_level

Data processing level indicator

Type:

int, default 1

Examples

Create a basic MakeMTH5 instance:

>>> from mth5.clients import MakeMTH5
>>> maker = MakeMTH5(save_path="/path/to/save")
>>> print(maker)
MakeMTH5 Attibutes:
    mth5_version: 0.2.0
    h5_compression: gzip
    ...

Create with custom compression:

>>> maker = MakeMTH5(
...     save_path="/data/mt",
...     h5_compression="lzf",
...     h5_shuffle=False
... )

See also

mth5.mth5.MTH5

Main MTH5 file interface

classmethod from_fdsn_client(request_df: DataFrame, client: str = 'IRIS', **kwargs)

Create MTH5 file from FDSN data service.

Pull data from an FDSN archive like IRIS using ObsPy clients. The request DataFrame specifies which data to download.

Parameters:

• request_df (pd.DataFrame) –

  DataFrame with columns:

  • ’network’str

    FDSN Network code (e.g., ‘IU’, ‘TA’)

  • ’station’str

    FDSN Station code (e.g., ‘ANMO’, ‘CAS04’)

  • ’location’str

    FDSN Location code (e.g., ‘00’, ‘’)

  • ’channel’str

    FDSN Channel code (e.g., ‘LFE’, ‘BHZ’)

  • ’start’str

    Start time in format ‘YYYY-MM-DDThh:mm:ss’

  • ’end’str

    End time in format ‘YYYY-MM-DDThh:mm:ss’

• client (str, default "IRIS") – FDSN client name (e.g., ‘IRIS’, ‘USGS’, ‘NCEDC’)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=4).

Returns:

MTH5 object if interact=True, otherwise Path to created file

Return type:

mth5.mth5.MTH5 or Path

Raises:

• AttributeError – If the input DataFrame is not properly formatted

• ValueError – If the DataFrame column values are invalid

Notes

If any column value is blank, any matching value will be searched. For example, leaving ‘station’ blank will return all stations within the specified time range.

Examples

Create a request DataFrame and download data:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> # Define request
>>> request_df = pd.DataFrame({
...     'network': ['IU'],
...     'station': ['ANMO'],
...     'location': ['00'],
...     'channel': ['LF*'],
...     'start': ['2020-01-01T00:00:00'],
...     'end': ['2020-01-02T00:00:00']
... })
>>>
>>> # Create MTH5 with custom compression
>>> mth5_obj = MakeMTH5.from_fdsn_client(
...     request_df,
...     client='IRIS',
...     h5_compression_opts=1
... )

See also

from_fdsn_miniseed_and_stationxml

Create from existing files

obspy.clients.fdsn

ObsPy FDSN client documentation

classmethod from_fdsn_miniseed_and_stationxml(station_xml_path: str | Path, miniseed_files: str | Path | list[str | Path], save_path: str | Path | None = None, **kwargs)

Create MTH5 from existing StationXML and miniSEED files.

Use this method when you already have StationXML and miniSEED files downloaded from an FDSN client or created locally.

Parameters:

• station_xml_path (str, Path, or obspy.Inventory) – Full path to StationXML file or an ObsPy Inventory object

• miniseed_files (str, Path, list, or obspy.Stream) – List of miniSEED file paths or ObsPy Stream objects. Can also be a single file path or Stream object.

• save_path (str or Path, optional) – Directory to save new MTH5 file. If None, saves to current working directory.

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’).

Returns:

Path to created MTH5 file. Filename format is {network}_{station}.h5 based on unique network and station codes.

Return type:

Path

Raises:

TypeError – If inputs are not of correct type

Examples

Create MTH5 from existing files:

>>> from mth5.clients import MakeMTH5
>>> from pathlib import Path
>>>
>>> # Define file paths
>>> station_xml = Path("data/station.xml")
>>> miniseed = [
...     Path("data/IU.ANMO.00.LFE.mseed"),
...     Path("data/IU.ANMO.00.LFN.mseed")
... ]
>>>
>>> # Create MTH5
>>> mth5_path = MakeMTH5.from_fdsn_miniseed_and_stationxml(
...     station_xml,
...     miniseed,
...     save_path="output",
...     h5_compression="lzf"
... )
>>> print(mth5_path)
output/IU_ANMO.h5

Using ObsPy objects directly:

>>> from obspy import read, read_inventory
>>>
>>> inventory = read_inventory("station.xml")
>>> stream = read("data/*.mseed")
>>>
>>> mth5_path = MakeMTH5.from_fdsn_miniseed_and_stationxml(
...     inventory,
...     stream,
...     save_path="output"
... )

See also

from_fdsn_client

Download and create in one step

classmethod from_intermag(request_df: DataFrame | str | Path, **kwargs)

Create MTH5 from INTERMAGNET observatory data.

Downloads geomagnetic observatory data from INTERMAG webservices into an MTH5 file using a request DataFrame or CSV file.

Parameters:

• request_df (pd.DataFrame, str, or Path) –

  Request definition as DataFrame or path to CSV file. Required columns:

  • observatory : str - Observatory code (e.g., ‘BOU’, ‘FRN’)

  • type : str - Data type: ‘variation’, ‘adjusted’, ‘quasi-definitive’, or ‘definitive’

  • elements : str - Geomagnetic elements to retrieve: D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z

  • sampling_period : int - Sample period in seconds: 1, 60, or 3600

  • start : str - Start time in YYYY-MM-DDThh:mm:ss format (UTC)

  • end : str - End time in YYYY-MM-DDThh:mm:ss format (UTC)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1).

Returns:

If interact=False (default), returns Path to created MTH5 file. If interact=True, returns MTH5 object with file open.

Return type:

Path or MTH5

Examples

Create MTH5 from USGS Boulder observatory using DataFrame:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> request = pd.DataFrame([{
...     'observatory': 'BOU',
...     'type': 'variation',
...     'elements': 'XYZF',
...     'sampling_period': 1,
...     'start': '2020-01-01T00:00:00',
...     'end': '2020-01-02T00:00:00'
... }])
>>>
>>> mth5_path = MakeMTH5.from_usgs_geomag(
...     request,
...     h5_compression='gzip',
...     h5_compression_opts=1
... )

Using CSV file:

>>> mth5_path = MakeMTH5.from_usgs_geomag('requests.csv')

Multiple observatories and periods:

>>> request = pd.DataFrame([
...     {'observatory': 'BOU', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 1,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'},
...     {'observatory': 'FRN', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 60,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'}
... ])
>>> mth5_path = MakeMTH5.from_usgs_geomag(request)

See also

mt_io.usgs_geomag.USGSGeomag

USGS geomagnetic data client

classmethod from_lemi(data_path, survey_id, station_id, sample_rates=None, mth5_filename=None, save_path=None, **kwargs)

Build a MTH5 file from LEMI instrument data.

Supports both LEMI-424 (long period, .txt) and LEMI-423 (broadband, .B423). Works mainly on a station by station basis because there is limited metadata in LEMI files.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

Example:

>>> # LEMI-424 data
>>> MakeMTH5.from_lemi(
...     '/data/lemi424', 'Survey01', 'MT001',
...     sample_rates=[1],
...     **{'h5_compression_opts': 1}
... )
>>>
>>> # LEMI-423 data at 1000 Hz
>>> MakeMTH5.from_lemi(
...     '/data/lemi423', 'Survey01', 'MT002',
...     sample_rates=[1000]
... )
>>>
>>> # LEMI-423 data, unknown rate (include all possible rates)
>>> MakeMTH5.from_lemi(
...     '/data/lemi423', 'Survey01', 'MT003',
...     sample_rates=[4000, 2000, 1000, 500, 250]
... )

Parameters:

• data_path (str or Path) – Directory where LEMI data files are, could be a single station or a full directory of stations.

• survey_id (str) – Survey ID for all stations

• station_id (str) – Station ID for station

• sample_rates (list or None, optional) – Sample rates to include. If None, will auto-detect and include all sample rates found in files. If specified, only processes files matching those rates. Valid rates: - LEMI-424: [1] Hz (long period only) - LEMI-423: [4000], [2000], [1000], [500], [250] Hz (broadband, auto-detected) Examples: - None (default): Process all files regardless of sample rate - [1]: Only LEMI-424 files - [1000]: Only LEMI-423 files recorded at 1000 Hz - [4000, 2000, 1000, 500, 250]: All possible LEMI-423 rates

• mth5_filename (str, optional) – Filename for the H5, defaults to ‘from_lemi.h5’

• save_path (str or Path, optional) – Path to save H5 file to, defaults to None which will place the file in data_path

Returns:

Path to MTH5 file

Return type:

Path

Note

• LEMI-424 files are .txt format at 1 Hz sample rate

• LEMI-423 files are .B423 format with variable sample rates

• Station and survey IDs must be provided (not in file metadata)

classmethod from_lemi417(data_path: str | Path, survey_id: str, station_id: str, mth5_filename: str = 'from_lemi417.h5', save_path: str | Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/mth5/checkouts/latest/docs'), **kwargs)

Create MTH5 from LEMI-417 long period data.

Builds an MTH5 file from LEMI-417 instrument data on a station-by-station basis. LEMI data has limited metadata, so survey and station IDs must be provided.

Parameters:

• data_path (str or Path) – Directory where LEMI-417 data files are stored. Can be single station or full directory.

• survey_id (str) – Survey ID to apply to all stations

• station_id (str) – Station ID for this station’s data

• mth5_filename (str, default 'from_lemi417.h5') – Filename for the MTH5 output file

• save_path (str or Path, default current directory) – Directory to save MTH5 file

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’).

Returns:

Path to created MTH5 file

Return type:

Path

Notes

LEMI-417 is a long-period magnetotelluric instrument. Data files have limited embedded metadata, requiring manual specification of survey and station information.

Process each station individually due to minimal automatic metadata extraction capabilities.

classmethod from_lemi424(data_path, survey_id, station_id, sample_rates=None, mth5_filename=None, save_path=None, **kwargs)

Backward-compatible constructor that uses LEMI424Client.

classmethod from_metronix(data_path, sample_rates=[128], mth5_filename=None, save_path=None, run_name_zeros=0, **kwargs)

Build a MTH5 file from Metronix Geophysics ATSS + JSON files saved in their new folder structure.

Parameters:

• data_path (str or pathlib.Path) – Highest level of where you want to archive data from, usuall the survey level. If you want just a single station, then use the station folder path.

• sample_rates (list of floats, optional) – sample rates to archive in samples/sercond, defaults to [128]

• mth5_filename (str, optional) – filename for the H5, defaults to ‘from_lemi424.h5’

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• run_name_zeros (int, defaults to 0) – number of zeros to include in new run names, will be named as ‘sr{sample_rate}_{run_id:0{run_name_zeros}}’. If set to 0 then will use the original run name, usually ‘run_0001’.

Returns:

Path to MTH5 file

Return type:

Path

classmethod from_nims(data_path, sample_rates=[4096, 1024, 256], save_path=None, calibration_path=None, survey_id=None, combine=True, **kwargs)

Create an MTH5 from nims data.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

>>> MakeMTH5.from_nims(
    data_path, **{'h5_compression_opts': 1}
    )

Parameters:

• data_path (Path, str) – directory to where data are stored

• sample_rates (list, optional) – sample rates to include, defaults to [4096, 1024, 256]

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• calibration_path (str or Path, optional) – path to calibration file amtant.cal, defaults to None

• survey_id (string) – survey ID to apply to all station found under data_path, defaults to None

• combine (bool) – if True combine the runs into a single run sampled at 1s, defaults to True

Returns:

MTH5 file name

Return type:

Path

classmethod from_phoenix(data_path, mth5_filename=None, save_path=None, sample_rates=[150, 24000], receiver_calibration_dict=None, sensor_calibration_dict=None, **kwargs)

Build an H5 file from Phoenix MTU-5C files. The key step when working with Phoenix data is to export the scal and rxcal files into JSON using EMPower. Place these files in a folder that you can easily find, and you can use this folder as inputs for the receiver_calibration_dict and sensor_calibration_dict which will search the folder and read in all the rxcal and scal files into appropriate dictionaries such that the filters will be linked with the data for appropriate calibration.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

>>> MakeMTH5.from_phoenix(
    data_path, **{'h5_compression_opts': 1}
    )

Parameters:

• data_path (str or Path) – Directory where data files are, could be a single station or a full directory of stations.

• mth5_filename (str, optional) – filename for the H5, defaults to ‘from_phoenix.h5’

• save_path (str or Path, optional) – path to save H5 file to, defaults to None which will place the file in data_path

• sample_rates (list, optional) – sample rates to include in file, defaults to [150, 24000]

• receiver_calibration_dict (str, Path or dict, optional) – This can either be a directory path to where the rxcal.json files are or a dictionary where keys are the receiver IDs and the values are the filename of the rxcal.json file, defaults to None

• sensor_calibration_dict (str, Path, dict, optional) – This can either be a directory path to where the scal.json files are or a dictionary where keys are the sensor IDs and the values are the PhoenixCalibration objects that have read in the scal.json file for that sensor, defaults to None

Returns:

Path to MTH5 file

Return type:

Path

classmethod from_uoa(data_path, survey_id, station_id, instrument_type, run_id='001', mth5_filename=None, save_path=None, **kwargs)

Build a MTH5 file from University of Adelaide instrument data.

Supports PR6-24 (Earth Data Logger) and Orange Box instruments.

Any H5 file parameters like compression, shuffle, etc need to have a prefix of ‘h5’. For example h5_compression=’gzip’.

Example:

>>> # PR6-24 long-period data
>>> MakeMTH5.from_uoa(
...     '/data/pr624', 'Survey01', 'MT001',
...     instrument_type='pr624',
...     sample_rate=10.0,
...     sensor_type='bartington',
...     dipole_length_ex=50.0,
...     dipole_length_ey=50.0,
...     **{'h5_compression_opts': 1}
... )
>>>
>>> # Orange Box data
>>> MakeMTH5.from_uoa(
...     '/data/orange', 'Survey01', 'ST61',
...     instrument_type='orange',
...     dipole_length_ex=100.0,
...     dipole_length_ey=100.0
... )

Parameters:

• data_path (str or Path) – Directory or file path to UoA data

• survey_id (str) – Survey ID

• station_id (str) – Station ID

• instrument_type (str) – ‘pr624’ or ‘orange’

• run_id (str, optional) – Run ID, defaults to “001”

• mth5_filename (str, optional) – Filename for the H5, defaults to ‘from_uoa.h5’

• save_path (str or Path, optional) – Path to save H5 file to, defaults to None which will place the file in data_path

• kwargs –

  Additional arguments for reader:

  PR6-24 arguments:

  • sample_rate (float): REQUIRED - sample rate in Hz

  • sensor_type (str): ‘bartington’ or ‘lemi120’

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • calibration_fn_bx (str): LEMI-120 .rsp file for Bx

  • calibration_fn_by (str): LEMI-120 .rsp file for By

  • calibration_fn_bz (str): LEMI-120 .rsp file for Bz

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

  Orange Box arguments:

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

Returns:

Path to MTH5 file

Return type:

Path

Note

• PR6-24 requires sample_rate parameter (not in file metadata)

• Orange Box auto-detects sample rate from file header

classmethod from_usgs_geomag(request_df: DataFrame | str | Path, **kwargs)

Create MTH5 from USGS geomagnetic observatory data.

Downloads geomagnetic observatory data from USGS webservices into an MTH5 file using a request DataFrame or CSV file.

Parameters:

• request_df (pd.DataFrame, str, or Path) –

  Request definition as DataFrame or path to CSV file. Required columns:

  • observatory : str - Observatory code (e.g., ‘BOU’, ‘FRN’)

  • type : str - Data type: ‘variation’, ‘adjusted’, ‘quasi-definitive’, or ‘definitive’

  • elements : str - Geomagnetic elements to retrieve: D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z

  • sampling_period : int - Sample period in seconds: 1, 60, or 3600

  • start : str - Start time in YYYY-MM-DDThh:mm:ss format (UTC)

  • end : str - End time in YYYY-MM-DDThh:mm:ss format (UTC)

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1).

Returns:

If interact=False (default), returns Path to created MTH5 file. If interact=True, returns MTH5 object with file open.

Return type:

Path or MTH5

Notes

See USGS Geomagnetism Data web service for more information: https://www.usgs.gov/tools/web-service-geomagnetism-data

Examples

Create MTH5 from USGS Boulder observatory using DataFrame:

>>> import pandas as pd
>>> from mth5.clients import MakeMTH5
>>>
>>> request = pd.DataFrame([{
...     'observatory': 'BOU',
...     'type': 'variation',
...     'elements': 'XYZF',
...     'sampling_period': 1,
...     'start': '2020-01-01T00:00:00',
...     'end': '2020-01-02T00:00:00'
... }])
>>>
>>> mth5_path = MakeMTH5.from_usgs_geomag(
...     request,
...     h5_compression='gzip',
...     h5_compression_opts=1
... )

Using CSV file:

>>> mth5_path = MakeMTH5.from_usgs_geomag('requests.csv')

Multiple observatories and periods:

>>> request = pd.DataFrame([
...     {'observatory': 'BOU', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 1,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'},
...     {'observatory': 'FRN', 'type': 'variation',
...      'elements': 'XYZF', 'sampling_period': 60,
...      'start': '2020-01-01T00:00:00', 'end': '2020-01-02T00:00:00'}
... ])
>>> mth5_path = MakeMTH5.from_usgs_geomag(request)

See also

mt_io.usgs_geomag.USGSGeomag

USGS geomagnetic data client

classmethod from_zen(data_path: str | Path, sample_rates: list[int] = [4096, 1024, 256], calibration_path: str | Path | None = None, survey_id: str | None = None, combine: bool = True, **kwargs)

Create MTH5 from Zonge ZEN data files.

Processes ZEN data files from a directory structure and creates an MTH5 file with organized time series data.

Parameters:

• data_path (str or Path) – Directory where ZEN data files are stored

• sample_rates (list of int, default [4096, 1024, 256]) – Sample rates to include in Hz

• calibration_path (str or Path, optional) – Path to calibration file (amtant.cal). If None, looks for calibration file in data_path.

• survey_id (str, optional) – Survey ID to apply to all stations found under data_path. If None, attempts to extract from directory structure.

• combine (bool, default True) – If True, combine multiple runs into single run sampled at 1s

• **kwargs (dict) – Additional keyword arguments. HDF5 parameters should be prefixed with ‘h5_’ (e.g., h5_compression=’gzip’, h5_compression_opts=1). Use save_path to specify output directory.

Returns:

Path to created MTH5 file

Return type:

Path

Notes

ZEN data is typically organized with multiple .Z3D files per station. The reader processes these files and organizes them into runs based on sampling rate and timing.

When combine=True, all runs are merged into a single continuous run sampled at 1 second intervals, which is useful for long-term datasets.

Examples

Create MTH5 from ZEN data directory:

>>> from mth5.clients import MakeMTH5
>>> from pathlib import Path
>>>
>>> data_dir = Path("data/zen_survey")
>>> mth5_path = MakeMTH5.from_zen(
...     data_dir,
...     sample_rates=[4096, 256],
...     survey_id="MT001",
...     save_path="output"
... )

With calibration file and HDF5 compression:

>>> mth5_path = MakeMTH5.from_zen(
...     "data/zen_survey",
...     calibration_path="data/amtant.cal",
...     survey_id="MT001",
...     combine=False,
...     h5_compression="gzip",
...     h5_compression_opts=4
... )

Process all sample rates without combining:

>>> mth5_path = MakeMTH5.from_zen(
...     "data/zen_survey",
...     sample_rates=[4096, 1024, 256, 64, 4],
...     combine=False
... )

See also

mt_io.zen.ZenCollection

ZEN data reader

get_h5_kwargs() → dict

Extract HDF5-related keyword arguments from instance attributes.

Returns:

Dictionary of HDF5 configuration parameters including version, compression settings, shuffle, fletcher32, and data level.

Return type:

dict

Examples

>>> maker = MakeMTH5(h5_compression="lzf", h5_data_level=2)
>>> kwargs = maker.get_h5_kwargs()
>>> print(kwargs["h5_compression"])
lzf

property save_path: Path

Get the save path as a Path object.

class mth5.clients.MetronixClient(data_path, sample_rates=[128], save_path=None, calibration_path=None, mth5_filename='from_metronix.h5', **kwargs)

Bases: ClientBase

get_run_dict(run_name_zeros=0)

get run information

Returns:

DESCRIPTION

Return type:

TYPE

get_survey_id(station_dict)

get survey name from a dictionary of a single station of runs :param station_dict: DESCRIPTION :type station_dict: TYPE :return: DESCRIPTION :rtype: TYPE

make_mth5_from_metronix(run_name_zeros=0, **kwargs)

Create an MTH5 from new ATSS + JSON style Metronix data.

Parameters:

**kwargs –

DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

set_station_metadata(station_dict, station_group)

set station group metadata from information in the station dict

Parameters:

• station_dict (TYPE) – DESCRIPTION

• station_group (TYPE) – DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

class mth5.clients.NIMSClient(data_path: str | Path, sample_rates: list[int] = [1, 8], save_path: str | Path | None = None, calibration_path: str | Path | None = None, mth5_filename: str = 'from_nims.h5', **kwargs)

Bases: ClientBase

property calibration_path: Path | None

Path to calibration data.

Returns:

Path to calibration file, or None if not set.

Return type:

Path or None

Examples

>>> client = NIMSClient('data_dir')
>>> client.calibration_path = 'calib.dat'
>>> print(client.calibration_path)
PosixPath('calib.dat')

get_run_dict() → dict

Get run information from the NIMS collection.

Returns:

Dictionary of run information.

Return type:

dict

Examples

>>> client = NIMSClient('data_dir')
>>> runs = client.get_run_dict()
>>> print(list(runs.keys()))
['station1', 'station2']

get_survey(station_dict: dict) → str

Get survey name from a dictionary of a single station of runs.

Parameters:

station_dict (dict) – Dictionary of runs for a station.

Returns:

Survey name.

Return type:

str

Examples

>>> client = NIMSClient('data_dir')
>>> runs = client.get_run_dict()
>>> survey = client.get_survey(runs['station1'])
>>> print(survey)
'survey_name'

make_mth5_from_nims(survey_id: str = 'default_survey', combine: bool = True, **kwargs) → str | Path

Make an MTH5 file from Phoenix NIMS files. Splits into runs, accounts for filters.

Parameters:

• survey_id (str, optional) – Survey identifier. Default is “default_survey”.

• combine (bool, optional) – Whether to combine runs. Default is True.

• **kwargs – Additional keyword arguments to set as attributes.

Returns:

Path to the saved MTH5 file.

Return type:

str or Path

Examples

>>> client = NIMSClient('data_dir')
>>> mth5_path = client.make_mth5_from_nims(survey_id='survey1')
>>> print(mth5_path)
'output_dir/from_nims.h5'

class mth5.clients.PhoenixClient(data_path: str | Path, sample_rates: list[int] = [150, 24000], save_path: str | Path | None = None, receiver_calibration_dict: dict | str | Path = {}, sensor_calibration_dict: dict | str | Path = {}, mth5_filename: str = 'from_phoenix.h5', **kwargs: dict)

Bases: ClientBase

make_mth5_from_phoenix(**kwargs: dict) → str | Path | None

Make an MTH5 from Phoenix files.

Split into runs, account for filters. Updates the MTH5 file with Phoenix data.

Parameters:

**kwargs (dict) – Optional keyword arguments to override instance attributes.

Returns:

Path to the saved MTH5 file.

Return type:

str, Path, or None

Examples

>>> client = PhoenixClient('data/path', save_path='output.h5')
>>> client.make_mth5_from_phoenix()
'output.h5'

property receiver_calibration_dict: dict

Receiver calibrations.

Returns:

Dictionary mapping receiver IDs to calibration file paths.

Return type:

dict

Examples

>>> client = PhoenixClient('data/path')
>>> client.receiver_calibration_dict = {'RX001': Path('RX001_rxcal.json')}
>>> client.receiver_calibration_dict
{'RX001': Path('RX001_rxcal.json')}

property sensor_calibration_dict: dict

Sensor calibration dictionary.

Returns:

Dictionary mapping sensor IDs to PhoenixCalibration objects.

Return type:

dict

Examples

>>> client = PhoenixClient('data/path')
>>> client.sensor_calibration_dict = {'H001': PhoenixCalibration('H001_scal.json')}
>>> client.sensor_calibration_dict['H001']
<PhoenixCalibration object>

class mth5.clients.USGSGeomag(**kwargs)

Bases: object

add_run_id(request_df)

Add run id to request df

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

add a run number to unique time windows for each observatory at each unique sampling period.

Return type:

pandas.DataFrame

property h5_kwargs

make_mth5_from_geomag(request_df)

Download geomagnetic observatory data from USGS webservices into an MTH5 using a request dataframe or csv file.

Parameters:

request_df (pandas.DataFrame, str or Path if csv file) –

DataFrame with columns

• ’observatory’ –> Observatory code

• ’type’ –> data type [ ‘variation’ | ‘adjusted’ | ‘quasi-definitive’ | ‘definitive’ ]

• ’elements’ –> Elements to get [D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z]

• ’sampling_period’ –> sample period [ 1 | 60 | 3600 ]

• ’start’ –> Start time YYYY-MM-DDThh:mm:ss

• ’end’ –> End time YYYY-MM-DDThh:mm:ss

Returns:

if interact is True an MTH5 object is returned otherwise the path to the file is returned

Return type:

Path or mth5.mth5.MTH5

See also

https://www.usgs.gov/tools/web-service-geomagnetism-data

validate_request_df(request_df)

Make sure the input request dataframe has the appropriate columns

Parameters:

request_df (pandas.DataFrame) – request dataframe

Returns:

valid request dataframe

Return type:

pandas.DataFrame

class mth5.clients.UoAClient(data_path, save_path=None, instrument_type='pr624', mth5_filename='from_uoa.h5', **kwargs)

Bases: ClientBase

Client for creating MTH5 files from University of Adelaide instrument data.

Supports: - PR6-24 (Earth Data Logger): ASCII files (.BX, .BY, .BZ, .EX, .EY) - Orange Box: Binary files (.BIN)

Parameters:

• data_path (str or pathlib.Path) – Path to directory or file(s)

• save_path (str or pathlib.Path, optional) – Path to save MTH5 file, defaults to data_path

• instrument_type (str, optional) – ‘pr624’ or ‘orange’, defaults to ‘pr624’

• mth5_filename (str, optional) – Name of output MTH5 file, defaults to “from_uoa.h5”

Example:

>>> from mth5.clients import UoAClient
>>> # PR6-24 data
>>> uc = UoAClient("/path/to/pr624/data", instrument_type='pr624')
>>> mth5_path = uc.make_mth5_from_uoa(
...     survey_id="Survey01",
...     station_id="MT001",
...     sample_rate=10.0,
...     dipole_length_ex=50.0,
...     dipole_length_ey=50.0
... )
>>>
>>> # Orange Box data
>>> uc = UoAClient("/path/to/orange/data", instrument_type='orange')
>>> mth5_path = uc.make_mth5_from_uoa(
...     survey_id="Survey01",
...     station_id="ST61",
...     dipole_length_ex=100.0,
...     dipole_length_ey=100.0
... )

make_mth5_from_uoa(survey_id, station_id, run_id='001', **kwargs)

Create an MTH5 file from UoA instrument data.

Parameters:

• survey_id (str) – Survey identifier

• station_id (str) – Station identifier

• run_id (str, optional) – Run identifier, defaults to “001”

• kwargs (dict) –

  Additional keyword arguments for reader:

  PR6-24 arguments:

  • sample_rate (float): REQUIRED - sample rate in Hz

  • sensor_type (str): ‘bartington’ or ‘lemi120’

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • calibration_fn_bx (str): LEMI-120 .rsp file for Bx

  • calibration_fn_by (str): LEMI-120 .rsp file for By

  • calibration_fn_bz (str): LEMI-120 .rsp file for Bz

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

  Orange Box arguments:

  • dipole_length_ex (float): Ex dipole length in meters

  • dipole_length_ey (float): Ey dipole length in meters

  • latitude (float): Station latitude

  • longitude (float): Station longitude

  • elevation (float): Station elevation

Returns:

Path to created MTH5 file

Return type:

pathlib.Path

Example:

>>> from mth5.clients import UoAClient
>>> # PR6-24 long-period data
>>> uc = UoAClient("/data/pr624", instrument_type='pr624')
>>> mth5_file = uc.make_mth5_from_uoa(
...     survey_id="MySurvey",
...     station_id="MT001",
...     sample_rate=10.0,
...     sensor_type='bartington',
...     dipole_length_ex=50.0,
...     dipole_length_ey=50.0
... )
>>>
>>> # Orange Box data
>>> uc = UoAClient("/data/orange", instrument_type='orange')
>>> mth5_file = uc.make_mth5_from_uoa(
...     survey_id="MySurvey",
...     station_id="ST61",
...     dipole_length_ex=100.0,
...     dipole_length_ey=100.0
... )

class mth5.clients.ZenClient(data_path, sample_rates=[4096, 1024, 256], save_path=None, calibration_path=None, mth5_filename='from_zen.h5', **kwargs)

Bases: ClientBase

property calibration_path

Path to calibration data

get_run_dict()

Get Run information

Returns:

DESCRIPTION

Return type:

TYPE

get_survey(station_dict)

get survey name from a dictionary of a single station of runs :param station_dict: DESCRIPTION :type station_dict: TYPE :return: DESCRIPTION :rtype: TYPE

make_mth5_from_zen(survey_id=None, combine=True, **kwargs)

Make an MTH5 from Phoenix files. Split into runs, account for filters

Parameters:

• data_path (TYPE, optional) – DESCRIPTION, defaults to None

• sample_rates (TYPE, optional) – DESCRIPTION, defaults to None

• save_path (TYPE, optional) – DESCRIPTION, defaults to None

Returns:

DESCRIPTION

Return type:

TYPE