AUTH-CAT

A Python toolkit for exploring and analysing earthquake bulletins from the Seismological Station of the Aristotle University of Thessaloniki (AUTH-SS).

Installation

pip install authcat                                          # from PyPI
pip install git+https://github.com/vanagno/AUTH-CAT          # straight from GitHub

This installs the authcat command and everything it needs.

Commands

Each step of the workflow is a command: authcat <command>. authcat --help lists them, and authcat <command> -h shows a command's own options, where it has any.

python -m authcat <command> works the same way, and the script names work as commands too (e.g. authcat histograms).

Projects

Every analysis session is kept in its own project folder, so runs never overwrite each other. The project folders live in Projects/ inside the folder you run authcat from, so each working folder keeps its own projects; set the AUTHCAT_PROJECTS environment variable to keep them in one folder elsewhere. The example projects in this repository are found when authcat is run from its top folder.

Projects/<name>/
    <name>.json   project record: the results of every script, and a history of runs. Acts as a diary for the whole workflow
    Input/        where the bulletin is stored
    Results/      catalogues, phase lists, summaries all outputs from AUTH-CAT scripts
    Figures/      plots and maps
    Magnitudes/   station magnitude lists and their plots
    Reports/      the PDF report written by authcat rep

Reference files shared by every project, such as the station list regd.sta and the report logo LOGO.png, are installed with AUTH-CAT (authcat/Utilities/). authcat stup keeps the station list up to date from the FDSN station services (every EIDA data centre, and IRIS): the listed stations take their most recent positions, and every station of the area (Greece and its neighbours, or the one given with --region) missing from the list is added; no station is removed. It rewrites Utilities/regd.sta, keeping the previous one as Utilities/regd.sta.bak. authcat stup --dry-run shows what would change.

The maps draw the full-resolution coastlines of GSHHG (Wessel & Smith, 1996; GNU LGPL). Those of Greece and its neighbours (lat 33.5-43.5, lon 18-31) are installed with AUTH-CAT (Utilities/gshhg_f_*_greece.wkb.gz); for a map reaching beyond them, cartopy downloads GSHHG once (about 150 MB), and without internet the maps fall back to Natural Earth 1:10m. python -m authcat.coastlines rebuilds the bundled extract.

Figures are saved at 300 dpi. Figures and report use the Tw Cen MT font when it is installed (it comes with Microsoft Office; its licence does not allow shipping it with AUTH-CAT); without it they keep matplotlib's DejaVu Sans and Times. The AUTHCAT_FONT environment variable names another installed font to use instead, e.g. AUTHCAT_FONT="Liberation Sans". With an editable install (pip install -e .) this updates the repository's own copy, ready to commit; with a regular install, upgrading AUTH-CAT replaces it with the list of the new release.

Quickstart guide

1. Start a project by downloading the bulletin for your target period and study area:

   authcat bul                    # asks for the project name, date range and lat/lon boundaries. Direct input in the command line
   authcat bul -p Arkal --start 2021-06-01 --end 2022-12-31 --min-lat 35.0 --max-lat 35.3 --min-lon 25.1 --max-lon 25.4 # Without further command line interaction
   

   or from a bulletin you already have (currently supports only AUTOLOC3 format):

   authcat project Arkal --bulletin Arkal.bul
   

2. Run the desired commands. Each one first asks which project to work on (pressing Enter takes the last one used), reads its input from that project and writes its output there. When input is piped in by a batch script, the last project used is taken without asking. authcat cat and authcat pha also accept -p/--project. When a command asks for a bulletin, catalogue or phase list, pressing Enter takes the project's own file (e.g. Tyrnavos.bul, Tyrnavos_cat.txt).

3. Or run the routine steps in one go, without questions -- figures are saved rather than shown:

   authcat batch Arkal                      # cat map hist mt mc nt mct mags sta pha vpvs ou rep
   authcat batch Arkal -s cat map hist mc   # only some steps
   authcat batch Arkal --mc 2.5 --omori-start "2021-09-27 06:17:21"
   

   The Mc for nt defaults to the one found by mc (--mc-method), ou starts at the largest earthquake, and mags only plots the residuals: the steps that need judgement (recomputing magnitudes with mags and rmag, choosing the stations in pse) are best run one by one. authcat batch -h lists all options.

4. Build the PDF report of everything recorded so far:

   authcat rep                    # asks which project
   authcat rep -p Arkal           # or name the project
   

The project record follows the layout in project.py (TEMPLATE). A section reads "available": false until the script that fills it has run, paths are relative to the project folder, and history lists each run with its inputs and parameters, so the file can be used to build a report for the project.