Magnetometer Data from Seismological Networks (mth5)

This module converts the magnetometer data from the EarthScope USArray magnetotelluric (MT) program using the International Federation of Digital Seismographic Networks (FDSN) standards into high-level data products and provides access to the data via PySPEDAS. It utilizes the MTH5 and mt_metadata packages that were developed at the USGS (U.S. Geological Survey).

Installation requirements

The MTH5 package is not included as a default dependency in PySPEDAS. To use this module (pyspedas.mth5), please install MTH5:

pip install mth5

This module downloads cache h5 files using the EarthScope (formerly IRIS) Data Management Center, which provides FDSN-compliant access to a variety of information, including data and metadata. Note that in 2023, Incorporated Research Institutions for Seismology (IRIS) became part of the EarthScope Consortium, which explains the domain name of the data center. The cache files are stored in the mth5 folder, with the parent folder specified by the environment variable SPEDAS_DATA_DIR.

Load FDSN data

To load data, the user must specify FDSN network and station. Currently, the module supports only magnetotelluric data from MTArray. The stations can be explored using a browsable Gmap. Additional examples are available via Jupyter notebooks of PySPEDAS MTH5 examples and a comprehensive guide on Accessing Magnetic Field Data from EarthScope Using MTH5.

pyspedas.mth5.load_fdsn.load_fdsn(trange=None, network=None, station=None, nodownload=False, noexception=False, print_request=False, nowarnings=False, request_df=None)[source]

Load FDSN data using MTH5 interface.

Parameters:

  • trange (list of str) – Time range of interest.

  • network (str) – Network name.

  • station (str) – Station name.

  • nodownload (bool, default False) – If h5 file is already created do not load another one.

  • noexception (bool, default False) – If true, do not raise an exception produced by FDSN.

  • print_request (bool, default False) – Print request_df structure, which can be useful for debugging the request.

  • nowarnings (bool, default False) – If true, disable loguru warnings.

  • request_df (pandas.DataFrame, optional) – Custom request_df dataframe for the make_mth5_from_fdsn_client method of the FDSN class. This parameter is optional, and it is not advised to use it unless the user knows exactly what to do. request_df must contain the following:

    • One station, one network, and one location as a list.

    • A list of 3 strings for channels.

    • The start and end date fields must contain a list of one string.

    See pyspedas.mth5.load_fdsn._request_df_from_input implementation for reference.

Returns:

tplot_variable – Tplot variable name. Tplot variable is created if data is loaded successfully, None otherwise.

Return type:

str or None

Example

import pyspedas
from pyspedas.mth5.load_fdsn import load_fdsn
load_fdsn(network="4P", station="ALW48", trange=['2015-06-22', '2015-06-24'])
pyspedas.tplot('fdsn_4P_ALW48')
_images/mth5_4p_alw48.png

Datasets availability

pyspedas.mth5.utilities.datasets(trange=None, network=None, station=None, USAarea=False)[source]

Fetches datasets availablity based on time range, network, and station.

The function queries an FDSN (Federation of Digital Seismograph Networks) web service for station data within a specified time range and geographical bounds limited to the USA. It filters the resulting channels based on selection of 3 chanles of the same band and diffrent orienation, e.g., ‘LFE’, ‘LFN’, ‘LFZ’. If the dataset has less than 3 channels with the same band, it is excluded. The resulting dataset is organized by network, station, and time range, including only the channels that meet the specified criteria.

Parameters:

  • trange (list of str) – Time range of interest [starttime, endtime] with the format [‘YYYY-MM-DD’,’YYYY-MM-DD’]

  • network (str, optional) – The network code to filter the datasets. If None (default), no network filter is applied.

  • station (str, optional) – The station code to filter the datasets. If None (default), no station filter is applied.

  • USAarea (bool, optional) – If True, restricts the search to the geographical boundaries (box) of the USA:

    • Latitude: 24 to 49 degrees

    • Longitude: -127 to -59 degrees

Returns:

A dictionary organized by network and station, each containing a dictionary of time ranges (start_date, end_date) mapping to a list of channels that meet the filter criteria. The dictionary is empty if no channels meet the criteria or if the inputs do not match any available data.

Return type:

dict

Examples

>>> datasets(["2015-06-22", "2015-06-23"], network="4P", station="ALW48")
{'4P': {'ALW48': {('2015-06-18T15:00:36.0000', '2015-07-09T13:45:10.0000'): ['LFE', 'LFN', 'LFZ']}}}

Note

The function requires internet access to query the FDSN web service and parse the returned data. It uses the urllib library for the web request and the csv module to parse the response.

Example

from pyspedas.mth5.utilities import datasets
valid_dataset = datasets(trange=["2015-06-22", "2015-06-23"])
print(valid_dataset)

{'4P': {'ALW48': {('2015-06-18T15:00:36.0000', '2015-07-09T13:45:10.0000'): ['LFE', 'LFN', 'LFZ']}, ...
...
More entries
}