Metadata-Version: 2.4
Name: authcat
Version: 0.1.7
Summary: A Python toolkit for exploring and analysing earthquake bulletins from the Aristotle University of Thessaloniki Seismological Station
Author: Pavlos Bonatis, Vasilis Anagnostou
License-Expression: GPL-3.0-or-later
Project-URL: Repository, https://github.com/vanagno/AUTH-CAT
Keywords: seismology,earthquake catalogue,bulletin,magnitude of completeness,Omori
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Requires-Dist: matplotlib>=3.6
Requires-Dist: scipy>=1.9
Requires-Dist: cartopy>=0.21
Requires-Dist: shapely
Requires-Dist: emcee>=3.0
Requires-Dist: corner>=2.2
Requires-Dist: reportlab>=3.6
Requires-Dist: tqdm
Requires-Dist: certifi
Dynamic: license-file

# 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.

| Command | Script | Description |
|---|---|---|
| `bul` | `bulletin.py` | Download the earthquake bulletin from AUTH-SS |
| `cat` | `catalog.py` | Create the earthquake catalogue from the bulletin; transform into 6-column & XML |
| `map` | `seismicity_map.py` | Plot the epicenters in the catalogue |
| `hist` | `histograms.py` | Plot histograms of focal depths, magnitudes, RMS and azimuthal gaps |
| `mt` | `M_time.py` | Plot the magnitudes over time |
| `nt` | `N_time.py` | Plot the cumulative number of earthquakes over time |
| `mct` | `Mc_time.py` | Plot the Mc variations over time |
| `mc` | `Mc_analysis.py` | Determine the Mc of the earthquake dataset |
| `mags` | `magnitudes.py` | Plot the median residual of magnitudes for each station |
| `rmag` | `repmags.py` | Replace the initial magnitude estimations |
| `sta` | `stations.py` | Visualize the seismic stations with the number of picked phases |
| `stup` | `update_stations.py` | Update the station list regd.sta from the FDSN station services |
| `pha` | `phases.py` | Extract seismic phases from the bulletin |
| `pse` | `sel_phases.py` | Select only the phases from certain seismic stations |
| `vpvs` | `wadati.py` | Vp/Vs estimation through the Wadati method |
| `ou` | `omori_utsu.py` | Estimation of the Omori-Utsu law parameters |
| `rep` | `report.py` | Generate the project report |
| `batch` | `batch.py` | Run several steps on a project in one go, without questions |
| `project` | `project.py` | List the projects, or start one from a bulletin you already have |

`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.
