Catalogs operations

This example demonstrates how to perform standard operations on a catalog. This example requires an internet connection to access ComCat.

Overview:

1. Load catalog from ComCat

2. Create filtering parameters in space, magnitude, and time

3. Filter catalog using desired filters

4. Write catalog to standard CSEP format

Load required libraries

Most of the core functionality can be imported from the top-level csep package. Utilities are available from the csep.utils subpackage.

import csep
from csep.core import regions
from csep.utils import time_utils, comcat
# sphinx_gallery_thumbnail_path = '_static/CSEP2_Logo_CMYK.png'

Load catalog

PyCSEP provides access to the ComCat web API using csep.query_comcat(). This function requires a datetime.datetime to specify the start and end dates.

start_time = csep.utils.time_utils.strptime_to_utc_datetime('2019-01-01 00:00:00.0')
end_time = csep.utils.time_utils.utc_now_datetime()
catalog = csep.query_comcat(start_time, end_time)
print(catalog)

Out:

Fetched ComCat catalog in 11.441219091415405 seconds.

Downloaded catalog from ComCat with following parameters
Start Date: 2019-01-01 12:01:46.950000+00:00
End Date: 2021-11-30 16:07:02.280000+00:00
Min Latitude: 31.5025 and Max Latitude: 42.8543333333333
Min Longitude: -125.3876667 and Max Longitude: -113.1001667
Min Magnitude: 2.5
Found 8056 events in the ComCat catalog.

        Name: None

        Start Date: 2019-01-01 12:01:46.950000+00:00
        End Date: 2021-11-30 16:07:02.280000+00:00

        Latitude: (31.5025, 42.8543333333333)
        Longitude: (-125.3876667, -113.1001667)

        Min Mw: 2.5
        Max Mw: 7.1

        Event Count: 8056

Filter to magnitude range

Use the csep.core.catalogs.AbstractBaseCatalog.filter() to filter the catalog. The filter function uses the field names stored in the numpy structured array. Standard fieldnames include ‘magnitude’, ‘origin_time’, ‘latitude’, ‘longitude’, and ‘depth’.

catalog = catalog.filter('magnitude >= 3.5')
print(catalog)

Out:

Name: None

Start Date: 2019-01-13 09:35:49.870000+00:00
End Date: 2021-11-20 02:39:07.540000+00:00

Latitude: (31.5158, 42.7775)
Longitude: (-125.3826667, -113.4886667)

Min Mw: 3.5
Max Mw: 7.1

Event Count: 1021

Filter to desired time interval

We need to define desired start and end times for the catalog using a time-string format. PyCSEP uses integer times for doing time manipulations. Time strings can be converted into integer times using csep.utils.time_utils.strptime_to_utc_epoch(). The csep.core.catalog.AbstractBaseCatalog.filter() also accepts a list of strings to apply multiple filters. Note: The number of events may differ if this script is ran at a later date than shown in this example.

# create epoch times from time-string formats
start_epoch = csep.utils.time_utils.strptime_to_utc_epoch('2019-07-06 03:19:54.040000')
end_epoch = csep.utils.time_utils.strptime_to_utc_epoch('2019-09-21 03:19:54.040000')

# filter catalog to magnitude ranges and times
filters = [f'origin_time >= {start_epoch}', f'origin_time < {end_epoch}']
catalog = catalog.filter(filters)
print(catalog)

Out:

Name: None

Start Date: 2019-07-06 03:20:36.080000+00:00
End Date: 2019-09-19 09:59:46.580000+00:00

Latitude: (32.2998352, 41.1244)
Longitude: (-125.0241667, -115.3243332)

Min Mw: 3.5
Max Mw: 5.5

Event Count: 356

Filter to desired spatial region

We use a circular spatial region with a radius of 3 average fault lengths as defined by the Wells and Coppersmith scaling relationship. PyCSEP provides csep.utils.spatial.generate_aftershock_region() to create an aftershock region based on the magnitude and epicenter of an event.

We use csep.utils.comcat.get_event_by_id() the ComCat API provided by the USGS to obtain the event information from the M7.1 Ridgecrest mainshock.

m71_event_id = 'ci38457511'
event = comcat.get_event_by_id(m71_event_id)
m71_epoch = time_utils.datetime_to_utc_epoch(event.time)

# build aftershock region
aftershock_region = regions.generate_aftershock_region(event.magnitude, event.longitude, event.latitude)

# apply new aftershock region and magnitude of completeness
catalog = catalog.filter_spatial(aftershock_region).apply_mct(event.magnitude, m71_epoch)
print(catalog)

Out:

Name: None

Start Date: 2019-07-06 03:22:35.630000+00:00
End Date: 2019-09-08 14:07:23.350000+00:00

Latitude: (35.448, 36.1823333)
Longitude: (-117.8875, -117.2796667)

Min Mw: 3.5
Max Mw: 5.5

Event Count: 234

Write catalog

Use csep.core.catalogs.AbstractBaseCatalog.write_ascii() to write the catalog into the comma separated value format.

catalog.write_ascii('2019-11-11-comcat.csv')