Scripting¶
You can write Python scripts that call the GMrecordsApp application to create high-level workflows.
In the example below we create a Python script to run several subcommands to download and process ground motions recorded close to the epicenter of a magnitude 4.5 earthquake, and then export the results to CSV files and generate a report summarizing the results.
The configuration and parameter files are in the docs/contents/tutorials directory.
In this tutorial, the commands are written to be executed in Jupyter Notebooks.
Within a Jupyter Notebook, commands can be redirected to the terminal with the ! symbol and we make ue of this functionality here.
Local gmprocess configuration¶
In this example we specify parameters in the project configuration to produce a small dataset.
We use only the FDSN fetcher and limit the station distance to 0.1 degrees.
The configuration files are in the conf/scripting directory.
First, we list the available projects in the current directory.
!gmrecords projects --list
INFO 2026-06-04 18:01:30 | gmrecords._initialize: Logging level includes INFO.
INFO 2026-06-04 18:01:30 | gmrecords._initialize: PROJECTS_PATH: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/.gmprocess
INFO 2026-06-04 18:01:30 | projects.main: Running subcommand 'projects'
Project: cli-tutorial **Current Project**
Conf Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/conf/cli
Data Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/data/cli
Project: scripting-tutorial
Conf Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/conf/scripting
Data Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/data/scripting
The PROJECTS_PATH shows the location of the projects configuration file where the information for the projects is stored.
Second, we use the projects subcommand to select the project configuration scripting-tutorial.
!gmrecords projects --switch scripting-tutorial
INFO 2026-06-04 18:01:33 | gmrecords._initialize: Logging level includes INFO.
INFO 2026-06-04 18:01:33 | gmrecords._initialize: PROJECTS_PATH: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/.gmprocess
INFO 2026-06-04 18:01:33 | projects.main: Running subcommand 'projects'
Switched to project:
Project: scripting-tutorial **Current Project**
Conf Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/conf/scripting
Data Path: /builds/ghsc/esi/groundmotion-processing/docs/contents/tutorials/data/scripting
Third, we create the directory to hold the data.
Note
We include the directory with the processing parameters for the project in the source code.
At this point we have an empty data/scripting directory.
The conf/scripting directory has two files: fetchers/yml and user.yml.
These configuration files hold parameters that override default values provided with the source code.
See Configuration File for more information.
Download Data¶
In this example we will consider ground motions recorded for a magnitude 4.5 earthquake east of San Francisco, California.
We have cached a snippet of the results of running gmrecords download --eventid nc73291880 in the tests/data/tutorials directory.
Consequently, we simply copy the data from tests/data/tutorials/nc73291880 to data/scripting/nc73291880.
!mkdir -p data/scripting/.
!cp -r ../../../tests/data/tutorials/nc73291880 data/scripting/.
List Data¶
We now have earthquake rupture information and raw waveforms in the data/scripting directory.
!tree data/scripting
data/scripting
└── nc73291880
├── event.json
└── raw
├── BK.BRIB.01.HNE__20191015T053312Z__20191015T054042Z.mseed
├── BK.BRIB.01.HNN__20191015T053312Z__20191015T054042Z.mseed
├── BK.BRIB.01.HNZ__20191015T053312Z__20191015T054042Z.mseed
└── BK.BRIB.xml
3 directories, 5 files
Python Script¶
First we need to import the GMrecordsApp application and initial it
from gmprocess.apps.gmrecords import GMrecordsApp
app = GMrecordsApp()
app.load_subcommands()
Now, we need to create a dictionary with the arguments common to all subcommands. We must include arguments that normally are given default values by the command line argument parser.
args = {
'debug': False,
'quiet': False,
'event_id': "nc73291880",
'textfile': None,
'overwrite': False,
'num_processes': 0,
'label': None,
'datadir': None,
'confdir': None,
'resume': None,
}
And let’s make a convenience function to make calling the individual subcommands (i.e., “steps”) easier
def call_gmprocess_subcommand(subcommand):
step_args = {
'subcommand': subcommand,
'func': app.classes[subcommand]['class'],
'log': None,
}
args.update(step_args)
app.main(**args)
Now we can easily call each subcommand
call_gmprocess_subcommand("assemble")
call_gmprocess_subcommand("process_waveforms")
call_gmprocess_subcommand("compute_station_metrics")
call_gmprocess_subcommand("compute_waveform_metrics")
call_gmprocess_subcommand("export_metric_tables")
call_gmprocess_subcommand("generate_station_maps")
This will produce CSV files with the waveform metrics in the data/scripting directory.
!ls -1 data/scripting/*.csv
The station map will be in the data/scripting/nc73291880 directory.
!ls -1 data/scripting/nc73291880/*.html