Core

Core data structures and utilities used throughout SeisMonitor.

Objects

class SeisMonitor.core.objects.Processing(order=None, decimate=None, detrend=None, filter=None, merge=None, normalize=None, resample=None, taper=None, select_networks=None, select_stations=None, filter_networks=None, filter_stations=None)

Bases: object

Defines processing steps to be applied to waveform data.

Parameters:

order:

list of str, optional Order of preprocessing steps (default includes ‘normalize’, ‘merge’, etc.).

decimate:

dict, optional Parameters for the decimate method.

detrend:

dict, optional Parameters for the detrend method.

filter:

dict, optional Parameters for the filter method.

merge:

dict, optional Parameters for the merge method.

normalize:

dict, optional Parameters for the normalize method.

resample:

dict, optional Parameters for the resample method.

taper:

dict, optional Parameters for the taper method.

select_networks:

list, optional List of networks to select (default is empty list).

select_stations:

list, optional List of stations to select (default is empty list).

filter_networks:

list, optional List of networks to filter out (default is empty list).

filter_stations:

list, optional List of stations to filter out (default is empty list).

run(st)

Applies the defined processing steps to a given waveform stream.

Parameters:

st:

obspy.Stream The waveform stream to process.

Returns:

: obspy.Stream

The processed waveform stream.

class SeisMonitor.core.objects.Provider(client, waveform_restrictions, processing=None, xml=None)

Bases: object

Handles the retrieval and storage of station metadata (inventory) from either an XML file or a client service.

Parameters:

• client (object) – An ObsPy-compatible client to fetch station metadata.

• waveform_restrictions (WaveformRestrictions) – Object containing selection criteria for waveform data.

• processing (Processing, optional) – Processing steps for waveform data (default is None).

• xml (str, optional) – Path to an XML file containing station metadata (default is None). This is used if the inventory is not fetched from the client.

copy()

Creates a deep copy of the Provider instance.

Returns:

: Provider

A new instance of Provider with copied attributes.

class SeisMonitor.core.objects.WaveformRestrictions(network, station, location, channel, starttime, endtime, location_preferences=None, channel_preferences=None, filter_networks=None, filter_stations=None, filter_domain=None)

Bases: object

Defines criteria for selecting waveform data, including network, station, location, and time range constraints.

Parameters:

• network (str) – Comma-separated list of network codes (wildcards allowed).

• station (str) – Comma-separated list of station codes (wildcards allowed).

• location (str) – Comma-separated list of location identifiers (wildcards allowed).

• channel (str) – Comma-separated list of channel codes (e.g., “BHZ,HHZ”).

• starttime (obspy.UTCDateTime) – Start time for waveform selection.

• endtime (obspy.UTCDateTime) – End time for waveform selection.

• location_preferences (list, optional) – Ordered list of preferred locations (default is an empty list).

• channel_preferences (list, optional) – Ordered list of preferred channels (default is an empty list).

• filter_networks (list, optional) – List of networks to filter out (default is an empty list).

• filter_stations (list, optional) – List of stations to filter out (default is an empty list).

• filter_domain (list, optional) – Geographic bounding box [lon_west, lon_east, lat_south, lat_north] (default is global coverage).

Clients

class SeisMonitor.core.client.LocalClient(*args: Any, **kwargs: Any)

Bases: Client

Local waveform archive client based on ObsPy’s SDS client.

This class extends obspy.clients.filesystem.sds.Client to support custom local archive directory structures using a user-defined filename format string.

The format string must use attributes available in an ObsPy Trace.stats object, such as year, month, day, network, station, location, channel, and Julian day.

Parameters:

• root (str) – Root directory of the local waveform archive.

• fmt (str) –

  File path template describing the archive structure.

  Example:

  "{year}-{month:02d}/{year}-{month:02d}-{day:02d}/"
  "{network}.{station}.{location}.{channel}.{year}.{julday:03d}"
  

• **kwargs – Additional keyword arguments passed to obspy.clients.filesystem.sds.Client.

Notes

LocalClient preserves all standard SDS client functionalities, including waveform retrieval with get_waveforms().

Example

Suppose the local archive is organized as:

{root_path}/seedfiles/{year}-{month:02d}/
{year}-{month:02d}-{day:02d}/
{network}.{station}.{location}.{channel}.{year}.{julday:03d}

Example usage:

from obspy import UTCDateTime

root_path = "/home/emmanuel/myarchive"

client = LocalClient(
    root=root_path,
    fmt=(
        "seedfiles/{year}-{month:02d}/"
        "{year}-{month:02d}-{day:02d}/"
        "{network}.{station}.{location}."
        "{channel}.{year}.{julday:03d}"
    )
)

st = client.get_waveforms(
    network="YY",
    station="XXXX",
    location="00",
    channel="HHZ",
    starttime=UTCDateTime("20220102T000100"),
    endtime=UTCDateTime("20220102T000200"),
)

Utils

SeisMonitor.core.utils.add_aditional_catalog_info(catalog, agency=None)

Adds additional metadata to a seismic catalog object.

Parameters:

catalogobspy.core.event.Catalog

The seismic catalog to update.

agencystr, optional

The agency responsible for the catalog.

Returns:

: catalog : obspy.core.event.Catalog

The updated catalog object.

SeisMonitor.core.utils.add_aditional_event_info(event, agency=None, event_type='earthquake', event_type_certainty='suspected')

Adds additional metadata to a seismic event object.

Parameters:

eventobspy.core.event.Event

The seismic event to update.

agencystr, optional

The agency responsible for the event.

event_typestr, optional

The type of seismic event (default is “earthquake”).

event_type_certaintystr, optional

Certainty level of event classification (default is “suspected”).

Returns:

: event : obspy.core.event.Event

The updated event object.

SeisMonitor.core.utils.add_aditional_origin_info(origin, agency=None, region=None, method_id=None, earth_model_id=None, evaluation_mode='automatic', evaluation_status='preliminary')

Adds additional metadata to a seismic origin object.

Parameters:

originobspy.core.event.Origin

The seismic origin to update.

agencystr, optional

The agency responsible for the origin.

regionstr, optional

The geographic region of the event.

method_idstr, optional

Identifier for the location method used.

earth_model_idstr, optional

Identifier for the Earth model used.

evaluation_modestr, optional

Mode of evaluation (default is “automatic”).

evaluation_statusstr, optional

Status of evaluation (default is “preliminary”).

Returns:

: origin : obspy.core.event.Origin

The updated origin object.

SeisMonitor.core.utils.get_csv_events(seiscomp_file, version='0.9', with_magnitude=True, export=None, from_format='SC3ML', inside_polygon=False)

Extracts event and pick data from a SeisComp file and returns it as Pandas DataFrames.

Parameters:

• seiscomp_file (str) – Path to the SC3ML SeisComp file that contains information about a single event.

• version (str, optional) – The version of the XML schema used in the SeisComp file. Default is “0.9”.

• with_magnitude (bool, optional) – If True, the magnitude and magnitude-related information will be included. Default is True.

• export (str, optional) – Path to the file where the CSV will be exported. If None, no file is created and only DataFrames are returned. Default is None.

• from_format (str, optional) – The format of the SeisComp file. Default is “SC3ML”.

• inside_polygon (bool, optional) – If True, only events inside the specified polygon will be considered. Default is False.

Returns:

• events_df (pandas.DataFrame) – DataFrame containing event information such as event ID, time, location, and magnitude.

• picks_df (pandas.DataFrame) – DataFrame containing pick information such as pick ID, phase, time, and associated station.

SeisMonitor.core.utils.preproc_stream(st, order=['normalize', 'merge', 'detrend', 'taper', 'filter'], decimate=None, detrend=None, filter=None, merge=None, normalize=None, resample=None, taper=None, select_networks=[], select_stations=[], filter_networks=[], filter_stations=[])

Preprocesses a seismic stream according to specified operations.

Parameters:

• st (obspy.Stream) – The seismic stream object to preprocess.

• order (list of str, optional) – A list of preprocessing steps to apply, in order. The options are: ‘normalize’, ‘merge’, ‘detrend’, ‘taper’, ‘filter’. The default is [‘normalize’, ‘merge’, ‘detrend’, ‘taper’, ‘filter’].

• decimate (dict, optional) – Parameters for decimating the stream, passed to st.decimate().

• detrend (dict, optional) – Parameters for detrending the stream, passed to st.detrend().

• filter (dict, optional) – Parameters for filtering the stream, passed to st.filter().

• merge (dict, optional) – Parameters for merging the stream, passed to st.merge().

• normalize (dict, optional) – Parameters for normalizing the stream, passed to st.normalize().

• resample (dict, optional) – Parameters for resampling the stream, passed to st.resample().

• taper (dict, optional) – Parameters for applying a taper to the stream, passed to st.taper().

• select_networks (list of str, optional) – A list of networks to include for preprocessing. If empty, all networks are included. Default is an empty list.

• select_stations (list of str, optional) – A list of stations to include for preprocessing. If empty, all stations are included. Default is an empty list.

• filter_networks (list of str, optional) – A list of networks to exclude from preprocessing. Default is an empty list.

• filter_stations (list of str, optional) – A list of stations to exclude from preprocessing. Default is an empty list.

Returns:

• st (obspy.Stream) – The preprocessed seismic stream object.

• processed (bool) – True if the stream was processed, False if not.

• comment (str) – A string containing the result of each preprocessing step, indicating success or failure.