Downloader

Download waveform data from providers.

seismonitor

Concurrent seismic waveform downloader.

This module provides the MseedDownloader class, which manages parallel waveform downloads from multiple seismic data providers.

The downloader supports:

• Inventory and metadata generation

• Concurrent waveform downloads

• Chunked time-window requests

• Optional waveform processing pipelines

The implementation is compatible with ObsPy-based FDSN clients.

Example

>>> from obspy.clients.fdsn import Client
>>> client = Client("IRIS")
>>> downloader = MseedDownloader([client])
>>> isinstance(downloader.providers, list)
True

class SeisMonitor.monitor.downloader.seismonitor.MseedDownloader(providers)

Bases: object

Concurrent mass downloader for seismic waveform data.

This class manages metadata retrieval and waveform downloads from multiple providers using concurrent execution.

Parameters:

providers (list) – List of provider objects or ObsPy-compatible clients.

providers

Sanitized provider list.

Type:

list

providers_are_processed

Indicates whether providers have been processed.

Type:

bool

_stations_outside_domains

Stations that fall outside requested domains.

Type:

set or None

Notes

Providers must implement the required waveform and station interfaces.

download(mseed_storage, chunklength_in_sec=None, threshold=60, overlap_in_sec=0, picker_args={}, groupby='{network}.{station}.{channel}', n_processor=None)

Download waveform data from all configured providers.

Parameters:

• mseed_storage (str) – Storage path template for MiniSEED files.

• chunklength_in_sec (int, optional) – Length of each download chunk in seconds.

• threshold (int, default=60) – Minimum waveform length threshold in seconds.

• overlap_in_sec (int, default=0) – Overlap between adjacent chunks in seconds.

• picker_args (dict, optional) – Picker configuration dictionary.

• groupby (str, default="{network}.{station}.{channel}") – Trace grouping pattern.

• n_processor (int, optional) – Number of concurrent workers.

Notes

Supported path template variables include:

• {network}

• {station}

• {location}

• {channel}

• {year}

• {month}

• {day}

• {julday}

• {starttime}

• {endtime}

make_inv_and_json(out_folder=None)

Create merged inventory and station metadata JSON files.

Parameters:

out_folder (str, optional) – Output directory where files will be written.

Returns:

Tuple containing:

• Inventory object

• Station metadata dictionary

Return type:

tuple

Notes

If out_folder is provided, the following files are created:

• stations.json

• inv.xml

utils

Utility functions for seismic waveform downloading and inventory handling.

This module provides helper classes and functions used for:

• Waveform downloading

• MiniSEED file management

• Inventory filtering

• Station metadata extraction

• Stream preference selection

• Chunked time-window generation

The implementation is designed for ObsPy-based workflows.

class SeisMonitor.monitor.downloader.utils.DownloadRestrictions(mseed_storage, chunklength_in_sec=None, threshold=60, overlap_in_sec=0, picker_args={}, groupby='{network}.{station}.{channel}', n_processor=None)

Bases: object

Container class defining waveform download restrictions.

Parameters:

• mseed_storage (str) – MiniSEED output path template.

• chunklength_in_sec (int, optional) – Length of each download chunk in seconds.

• threshold (int, default=60) – Minimum waveform duration threshold in seconds.

• overlap_in_sec (int, default=0) – Chunk overlap in seconds.

• picker_args (dict, optional) – Picker configuration dictionary.

• groupby (str, default="{network}.{station}.{channel}") – Grouping rule for traces.

• n_processor (int, optional) – Number of parallel workers.

mseed_storage

MiniSEED output path template.

Type:

str

chunklength_in_sec

Chunk duration in seconds.

Type:

int or None

threshold

Minimum waveform duration threshold.

Type:

int

overlap_in_sec

Overlap between chunks.

Type:

int

picker_args

Picker configuration.

Type:

dict

groupby

Trace grouping rule.

Type:

str

n_processor

Number of parallel workers.

Type:

int or None

SeisMonitor.monitor.downloader.utils.get_all_sdswaveforms(client, **kwargs)

Download waveforms for multiple parameter combinations.

Parameters:

• client (Client) – ObsPy-compatible client instance.

• **kwargs (dict) –

  Waveform request parameters. Expected keys include:

  • network

  • station

  • location

  • channel

  • starttime

  • endtime

  Comma-separated values are automatically expanded.

Returns:

Combined waveform stream.

Return type:

Stream

Notes

Each combination of network, station, location, and channel is requested independently.

SeisMonitor.monitor.downloader.utils.get_chunktimes(starttime, endtime, chunklength_in_sec, overlap_in_sec=0)

Generate chunked time intervals.

Parameters:

• starttime (UTCDateTime) – Start time.

• endtime (UTCDateTime) – End time.

• chunklength_in_sec (int, optional) – Chunk duration in seconds.

• overlap_in_sec (int, optional) – Chunk overlap in seconds.

Returns:

List of (starttime, endtime) tuples.

Return type:

list

Raises:

ValueError – If chunklength_in_sec equals zero.

SeisMonitor.monitor.downloader.utils.get_client_waveforms(client, bulk, waveform_restrictions, processing)

Retrieve and optionally process waveform data.

Parameters:

• client (Client) – ObsPy-compatible waveform client.

• bulk (tuple) –

  Waveform request tuple containing:

  • Network

  • Station

  • Location

  • Channel

  • Starttime

  • Endtime

• waveform_restrictions (object) – Waveform restriction configuration.

• processing (object, optional) – Processing pipeline object.

Returns:

Tuple containing:

• Stream

• Preprocessed flag

• Comment string

Return type:

tuple

SeisMonitor.monitor.downloader.utils.get_filenames(mseed, filter_net=[], filter_sta=[], filter_cha=[])

Retrieve MiniSEED filenames with optional filtering.

Parameters:

• mseed (str) – Directory containing MiniSEED files.

• filter_net (list of str, optional) – Network codes to exclude.

• filter_sta (list of str, optional) – Station codes to exclude.

• filter_cha (list of str, optional) – Channel codes to include.

Returns:

Filtered MiniSEED filenames.

Return type:

list of str

Raises:

TypeError – If any filter parameter is not a list.

Examples

>>> files = get_filenames("/data/mseed")
>>> isinstance(files, list)
True

SeisMonitor.monitor.downloader.utils.get_inv_and_json(inventory, filter_networks=[], filter_stations=[], filter_domain=[-180, 180, -90, 90])

Filter an inventory and generate station metadata.

Parameters:

• inventory (Inventory) – ObsPy inventory object.

• filter_networks (list of str, optional) – Networks to exclude.

• filter_stations (list of str, optional) – Stations to exclude.

• filter_domain (list of float, optional) –

  Geographic domain defined as:

  [minlon, maxlon, minlat, maxlat]

Returns:

Tuple containing:

• Filtered inventory

• Station metadata dictionary

• Stations outside domain

Return type:

tuple

SeisMonitor.monitor.downloader.utils.get_max_allowed_batch_size(data_length, segment_length, overlap)

Compute the maximum valid batch size.

Parameters:

• data_length (float) – Total waveform duration in seconds.

• segment_length (float) – Segment duration in seconds.

• overlap (float) – Fractional overlap between segments.

Returns:

Maximum allowed batch size.

Return type:

int

SeisMonitor.monitor.downloader.utils.get_merged_inv_and_json(providers)

Merge inventories and station metadata from providers.

Parameters:

providers (list) – List of provider objects.

Returns:

Tuple containing:

• Merged inventory

• Station metadata dictionary

• Updated providers

• Stations outside requested domains

Return type:

tuple

SeisMonitor.monitor.downloader.utils.get_mseed_filename(_str, tr, ppc=False)

Generate a MiniSEED filename from a template.

Parameters:

• template (str) – Output path template.

• trace (Trace) – ObsPy trace object.

• ppc (bool, default=False) – Append preprocessing suffix.

Returns:

Generated file path.

Return type:

str

Raises:

TypeError – If the generated path is invalid.

SeisMonitor.monitor.downloader.utils.get_st_according2preference(st, location_list, channel_list)

Suppose that your preference_type is “location” and your location_list is [“00”,”20”,”10”], then this function first filter the stream according to location and returns a new stream only with location “00”, if no exist “00” will continue with the next preference “20”, and otherwise, “10”. After that, it is going to take new stream and it will go to filter according to channel_list preference if the new stream has more than one channel type (“HH or BH).

Parameters:

• st (Stream) – ObsPy stream object.

• location_list (list) – Preferred locations ordered by priority.

• channel_list (list) – Preferred channel prefixes ordered by priority.

Returns:

Filtered stream.

Return type:

Stream

SeisMonitor.monitor.downloader.utils.inside_the_polygon(p, pol_points)

Determine whether a point lies inside a polygon.

Parameters:

• point (tuple) – Point coordinates (longitude, latitude).

• polygon_points (list of tuple) – Polygon vertices.

Returns:

True if the point is inside the polygon.

Return type:

bool

SeisMonitor.monitor.downloader.utils.sanitize_provider_times(providers)

Ensure all providers share the same time interval.

Parameters:

providers (list) – Provider list.

Returns:

Validated provider list.

Return type:

list

Raises:

ValueError – If providers use different time intervals.

SeisMonitor.monitor.downloader.utils.select_inventory(inv, network, station, location, channel, starttime, endtime)

Filter an inventory using waveform selection criteria.

Parameters:

• inventory (Inventory) – Input ObsPy inventory.

• network (str) – Comma-separated network codes.

• station (str) – Comma-separated station codes.

• location (str) – Comma-separated location codes.

• channel (str) – Comma-separated channel codes.

• starttime (UTCDateTime) – Selection start time.

• endtime (UTCDateTime) – Selection end time.

Returns:

Filtered inventory object.

Return type:

Inventory

SeisMonitor.monitor.downloader.utils.write_client_waveforms(client, bulk, waveform_restrictions, download_restrictions, processing)

Download and write waveform data to MiniSEED files.

Parameters:

• client (Client) – ObsPy-compatible client.

• bulk (tuple) – Waveform request tuple.

• waveform_restrictions (object) – Waveform restriction configuration.

• download_restrictions (DownloadRestrictions) – Download restriction configuration.

• processing (object, optional) – Processing pipeline.

SeisMonitor.monitor.downloader.utils.write_stream(st, mseed_storage, threshold=None, picker_args={}, ppc_and_comment=[False, ''])

Write a waveform stream to MiniSEED format.

Parameters:

• st (Stream) – ObsPy stream object.

• mseed_storage (str) – Output storage template.

• threshold (int, optional) – Minimum waveform duration threshold.

• picker_args (dict, optional) – Picker validation parameters.

• ppc_and_comment (sequence, optional) –

  Tuple/list containing:

  • Preprocessed flag

  • Log comment