qml2extendedtext |

The qml2extendedtext.py code is included into the present docker.

The docker is used to parse a full QuakeML (xml) file or QuakeML webservice response containing information on hypocenter and related arrival times picks, and write the following information about the hypocenter on one single line:

• event_id: agency event unique identifier
• event_type: type of event (eg: earthquake, quarry blast and other agency dependent definitions)
• origin_id: agency hypocenter unique identifier; this correspond to the asked version of hypocenter that can be "preferred" or specific a-priori known location versions (see the tag below)
• version: this is a specific tag describing the type of solution (eg for INGV: 0,1,2 are automatic solutions (1 is not always present), 100,200,1000 are revised solutions and 1000 is the Bulletin one)
• ot: specific solution origintime in standard format YYYY-mm-ddTHH:MM:SS.x
• lon: hypocenter geographic longitude expressed in decimal degrees positive east from Greenwich
• lat: hypocenter geographic latitude expressed in decimal degrees positive northward
• depth: hypocenter depth expressed in km positive downward from the sea level
• fixed_depth: 0 for not, 1 for yes
• origin_Q: hypocenter location quality; 2 characters (A,B,C,D) for INGV origin versions 0, 1, 2, 100, 1000 based on estimated errors (position 1) and goodness-of-fit (position 2)
• rms: Root Mean Square of the location residuals of the specific hypocenter expressed in seconds
• gap: azimuthal gap of the contributing stations distribution
• nph_tot: total number of P+S arrivals (picks associated to the specific hypocenter)
• nph_tot_used: total number of P+S arrivals contributing to the specific hypocenter
• nph_p_used: number of P arrivals contributing to the specific hypocenter
• nph_s_used: number of S arrivals contributing to the specific hypocenter
• min_dist_km: distance of the closest used station (km)
• max_dist_km: distance of the farest used stations (km)
• err_ot: uncertainty on ot expressed in seconds
• err_lon_km: uncertainty on lon expressed in +/- km
• err_lat_km: uncertainty on lat expressed in +/- km
• err_depth: uncertainty on depth expressed in km
• **err_h: horizontal error expressed in +/-km (not necessarily available)
• **err_z: vertical error (like err_depth)
• confidence level: errors ellipsoid confidence level
• magnitud_id: agency unique identifier of the "hypocenter magnitude" (see below the note for the definition) magnitude associated to the specific hypocenter (this might be different from the preferred and from magnitudes associated to other hypocenters of the same event)
• magnitude_type: type of "hypocenter magnitude"
• magnitude_value: value of the "hypocenter magnitude"
• magnitude_Q: magnitude quality. For INGV origin version 0, 1, 2 (Earthworm automatic versions) 1 character (A,B,C,D) based on number of available values; for INGV origin versions 100, 1000: 2 characters (A,B,C,D) based on number of available values and weighted standard deviation.
• magnitude_err: uncertainty of the "hypocenter magnitude"
• magnitude_nsta_used: number of stations contributing to the "hypocenter magnitude"
• pref_magnitud_id: agency unique identifier of the "event magnitude" which is the preferred type and value of magnitude for the event, not necessarily associated to the specific hypocenter (eg: if a Mw is available it is preferred to the hypocenter related ML)
• pref_magnitude_type: type of the preferred magnitude
• pref_magnitude_value: value of the preferred magnitude
• pref_magnitude_Q: magnitude quality. For INGV origin version 0, 1, 2 (Earthworm automatic versions) 1 character (A,B,C,D) based on number of available values; for INGV origin versions 100, 1000: 2 characters (A,B,C,D) based on number of available values and weighted standard deviation
• pref_magnitude_err: uncertainty associated to the preferred magnitude (not always present)
• pref_magnitude_nsta_used: number of stations contributing to the preferred magnitude (non always present)
• source: the source of the QuakeML information (it is either a file name or a web service query depending on the used option, see below)

Note: the "hypocenter magnitude" is the magnitude directly associated to the specific hypocenter; it is calculated consequently to the hypocenter, it is typically an ML and it might be not selected as the "preferred" if a hierarchically more reliable one is present (eg: Mw)

Anyway, only for information completeness here it is:

usage: qml2extendedtext.py [-h] [--qmlin QMLIN] [--qmldir QMLDIR] [--eventid EVENTID] [--version VERSION] [--conf CONF] [--nophases] [--noamps] [--nofocals] [--agency AGENCY]

optional arguments:
  -h, --help         show this help message and exit
  --qmlin QMLIN      Full path to a single qml event file
  --qmldir QMLDIR    Full path to the directory containing more qml event files
  --eventid EVENTID  INGV event id
  --version VERSION  Agency coding origin version type (**default**: preferred) preferred,all, or an integer for known version numbers
  --conf CONF        needed with --eventid agency webservices routes list type (**default**: ./ws_agency_route.conf)
  --nophases         If on, no phase extraction and count is done
  --noamps           If on, no amp extraction and count is done
  --nofocals         If on, no focal mechanism extraction and count is done
  --agency AGENCY    needed with --eventid agency to query for (see routes list in .conf file) type (default: ingv)

Note: this script can be used either to parse QuakeML file(s) (--qmlin and --qmldir are alternative choices) or to get info from a webservice for a single event based on its unique identifier by the agency (--eventid)

An header,starting with a "#" is given in output in all cases at line one of the screen output. In the case of --qmldir this is a the top of a list of hypocenters.

Quickstart

Docker image

To obtain qml2extendedtext docker image, you have two options:

1) Get built image from DockerHub (preferred)

Get the last built image from DockerHub repository:

docker pull ingv/qml2extendedtext

2) Build by yourself

First, clone the git repository

git clone https://github.com/INGV/qml2extendedtext.git
cd qml2extendedtext
docker build --tag ingv/qml2extendedtext .

in case of errors, try:

docker build --no-cache --pull --tag ingv/qml2extendedtext .

Run docker

To run the container, use the command below; the -v option is used to "mount" working directory into container:

docker run --rm --user $(id -u):$(id -g) -v $(pwd)/example:/opt/input ingv/qml2extendedtext

example with webservice (INGV)

docker run --rm --user $(id -u):$(id -g) -v $(pwd):/opt/input ingv/qml2extendedtext --eventid 25883521 --agency ingv --conf /opt/input/ws_agency_route.conf --version preferred

output:

#event_id|event_type|origin_id|version|ot|lon|lat|depth|err_ot|err_lon|err_lat|err_depth|err_h|err_z|nph_tot|nph_tot_used|nph_p_used|nph_s_used|magnitud_id|magnitude_type|magnitude_value|magnitude_err|magnitude_nsta_used|pref_magnitud_id|pref_magnitude_type|pref_magnitude_value|pref_magnitude_err|pref_magnitude_nsta_used|rms|gap|source

25883521|earthquake|85930721|100|2021-01-01T01:09:10.220000Z|13.1877|42.8343|8.4|0.26|0.7991095982233789|0.8006034718408229|1.5|0.93|1.5|10|10|6|4|91710461|ML|1.3|0.2|4|91710461|ML|1.3|0.2|4|0.17|212.0|http://webservices.ingv.it/fdsnws/event/1/query?eventid=25883521&includeallmagnitudes=true&includeallorigins=true&includeallstationsmagnitudes=true&includearrivals=true

example with qml input file (same event)

docker run --rm --user $(id -u):$(id -g) -v $(pwd):/opt/input ingv/qml2extendedtext --qmlin /opt/input/example/20210101-010910__25883521__INGV-EVENT.qml --version preferred

output:

#event_id|event_type|origin_id|version|ot|lon|lat|depth|err_ot|err_lon|err_lat|err_depth|err_h|err_z|nph_tot|nph_tot_used|nph_p_used|nph_s_used|magnitud_id|magnitude_type|magnitude_value|magnitude_err|magnitude_nsta_used|pref_magnitud_id|pref_magnitude_type|pref_magnitude_value|pref_magnitude_err|pref_magnitude_nsta_used|rms|gap|source

25883521|earthquake|85930721|100|2021-01-01T01:09:10.220000Z|13.1877|42.8343|8.4|0.26|0.7991095982233789|0.8006034718408229|1.5|0.93|1.5|10|10|6|4|91710461|ML|1.3|0.2|4|91710461|ML|1.3|0.2|4|0.17|212.0|20210101-010910__25883521__INGV-EVENT.qml

Docker CLI

To override the ENTRYPOINT directive and enter into the Docker container, run:

docker run --rm -it --user $(id -u):$(id -g) --entrypoint=bash qml2extendedtext

Update Docker image from DockerHub

Get last Docker image from DockerHub repository:

docker pull ingv/qml2extendedtext

Contribute

Thanks to your contributions!

Here is a list of users who already contributed to this repository:

Author

(c) 2021 Raffaele Distefano raffaele.distefano[at]ingv.it

(c) 2021 Valentino Lauciani valentino.lauciani[at]ingv.it

Istituto Nazionale di Geofisica e Vulcanologia, Italia