D - Catalog and Model Queries

The following example shows an experiment whose forecasts are retrieved from a repository (Zenodo - https://zenodo.org) and the testing catalog from an authoritative source web service (namely the gCMT catalog from the International Seismological Centre - http://www.isc.ac.uk).

TL; DR

In a terminal, navigate to floatcsep/tutorials/case_d and type:

$ floatcsep run config.yml

After the calculation is complete, the results will be summarized in results/report.md. The experiment region, catalog, forecasts and results can be viewed in the Experiment Dashboard with:

$ floatcsep view config.yml

Experiment Components

The source code can be found in the tutorials/case_d folder or in GitHub. The initial input structure of the experiment is:

case_d
    ├── config.yml
    ├── models.yml
    └── tests.yml

Once the catalog and models have been downloaded, the experiment structure will look like this:

case_d
    └──  models
        └──  team
            ├── TEAM=N10L11.csv
            ├── TEAM=N25L11.csv
            ...
        └──  wheel
            ├── WHEEL=N10L11.csv
            ├── WHEEL=N25L11.csv
            ...
    ├── config.yml
    ├── catalog.json
    ├── models.yml
    └── tests.yml

Note

In this experiment no region file is needed because the region is encoded in the forecasts themselves, which are based on the QuadTree description (See Working with quadtree-gridded forecasts, and the Zenodo repositories https://zenodo.org/record/6289795 and https://zenodo.org/record/6255575 ).

Configuration

Catalog

The catalog inset from config.yml now makes reference to a catalog query function, in this case query_gcmt().

tutorials/case_d/config.yml
catalog: query_gcmt

floatcsep will automatically filter the catalog to the experiment time, spatial and magnitude windows of the experiment.

Note

Query functions are located in pycsep (e.g. csep.query_comcat(), csep.query_bsi(), csep.query_gcmt(), csep.query_gns()). Only the name of the function is needed to retrieve the catalog. Refer to csep API reference.

Models

The model configuration is set in models.yml.

tutorials/case_d/models.yml
- TEAM:
    zenodo_id: 6289795
    path: models/team
    flavours:
      N10L11: TEAM=N10L11.csv
      N25L11: TEAM=N25L11.csv
      N50L11: TEAM=N50L11.csv
- WHEEL:
    zenodo_id: 6255575
    path: models/wheel
    flavours:
      N10L11: WHEEL=N10L11.csv
      N25L11: WHEEL=N25L11.csv
      N50L11: WHEEL=N50L11.csv

  • The option zenodo_id makes reference to the zenodo record id. The model team is found in https://zenodo.org/record/6289795, whereas the model wheel in https://zenodo.org/record/6255575.

  • The zenodo (or git) repositories could contain multiple files, each of which can be assigned to a flavour.

  • The option flavours allows multiple model sub-classes to be quickly instantiated.

  • When multiple flavours are passed, path refers to the folder where the models would be downloaded.

  • If a single file of the repository is needed (without specifying model flavours), path can reference to the file itself. For example, you can try replacing the whole WHEEL inset in models.yml to:

    - WHEEL:
    zenodo_id: 6255575
    path: models/WHEEL=N10L11.csv

Running the experiment

The experiment can be run by simply navigating to the tutorials/case_d folder in the terminal and typing.

$ floatcsep run config.yml

This will automatically set all the calculation paths (testing catalogs, evaluation results, figures) and will create a summarized report in results/report.md.

pyCSEP under the hood

This tutorial uses floatCSEP as the orchestrator, but relies on pyCSEP for functions and objects.

Classes and functions used in this tutorial

Where to learn pyCSEP further: