mth5.clients.fdsn

Module for working with FDSN clients using Obspy

Created on Fri Feb 4 15:53:21 2022

@author: jpeacock

Classes

FDSN

Module Contents

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

Bases: mth5.clients.base.ClientBase

logger

request_columns = ['network', 'station', 'location', 'channel', 'start', 'end']

client = 'IRIS'

property run_list_ne_stream_intervals_message: str

note about not equal stream intervals

get_run_list_from_station_id(m: mth5.mth5.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

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

Identify start and end times of streams

Parameters:

streams (obspy.core.stream.Stream)

get_station_streams(station_id: str) → obspy.Stream

Get streams for a certain station

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

pack_stream_into_run_group(run_group, run_stream: obspy.Stream)

run_timings_match_stream_timing(run_group, stream_start: obspy.UTCDateTime, stream_end: obspy.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

wrangle_runs_into_containers(m: mth5.mth5.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

make_mth5_from_fdsn_client(df: pandas.DataFrame | str | pathlib.Path, path: str | pathlib.Path | None = None, client: str | None = None, interact: bool = False) → pathlib.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)

property streams

obspy.Stream object

make_mth5_from_inventory_and_streams(inventory: obspy.Inventory | str | pathlib.Path, streams: obspy.Stream | list[str | pathlib.Path], save_path: str | pathlib.Path | None = None) → pathlib.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)

build_network_dict(df: pandas.DataFrame, client: obspy.clients.fdsn.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: pandas.DataFrame, client: obspy.clients.fdsn.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_waveforms_from_request_row(client: obspy.clients.fdsn.Client, row) → obspy.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)

get_inventory_from_df(df: pandas.DataFrame | str | pathlib.Path, client: str | None = None, data: bool = True, max_tries: int = 10) → tuple[obspy.Inventory, obspy.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_df_from_inventory(inventory: obspy.Inventory) → pandas.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_unique_networks_and_stations(df: pandas.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)

make_filename(df: pandas.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)

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()