Nordic to QuakeML converter tool package

• What is Nor2QML?
• Applications within the package
• How to download and build the applications?
• How to run the applications?
  • Executable jars
  • War files
  • Docker
  • Configuration file
  • Edit HTML for web-service
  • Make custom profiles
  • Running docker
  • Monitoring
• Modules
• Mapping

What is Nor2QML?

Nor2QML is a conversion tool between the Nordic (used in SEISAN) and QuakeML (European Standard) formats for provision of earthquake parametric data. The SEISAN seismic analysis system contains a set of programs for analyzing earthquakes from analog and digital data (See official SEISAN documentation). The data is organized in catalogue structure using the file system. The smallest basic unit is a file (the S-file) containing original phase readings (arrival times, amplitude, period, azimuth, and apparent velocity) for one event. These s-files are expressed through the Nordic format, which since 1985 has been the common exchange format in the Nordic countries. The standard format for provision of earthquake parametric data within various European infrastructures is QuakeML (See official QuakeML documentation).

In addition, the Nor2QML package include a set of tools for easier exchange of earthquake parametric data between applications. The interaction is organized through a web-service , where A client can send a request over the internet for data through a web-service and receive the data in multiple formats (Nordic, Nordic2, QuakeML, Text) of their choice.

Applications

• Standalone converter (executable jar) - file conversion locally on the computer
• Ingestor (executable jar) - providing data to the web-service
• Web-service (war file) for data exchange (QuakeML, Nordic and text format)
• Web converter (war file) - web application for conversion in the browser - server and client

How to download and build the applications?

To download, build and run the various modules (see list below) within this package, you first need to have installed Git on you computer. See the official documentation for Git on: https://git-scm.com/

Clone the project from this GitHub repository into your desired folder by entering the command:\ git clone https://github.com/cronnevik/nor2qml.git

The nor2qml package is build upon Java (Spring boot) with Apache Maven as the build tool. In order to build the individual modules, both java and maven (https://maven.apache.org/) needs to be installed.

To simplify the build of the applications and the modules they depend on, maven profiles have been applied. See the list of applications and modules.

To build an application, enter the command:\ mvn clean install -P <maven profile name>

The maven profile name is found in the modules list below. The maven build tool then produce a jar or a war file which is found in the target folder within the component/application folder.

How to run the applications?

For the executable jars and war files, please read first in the previous section on how to build the applications.

Executable jars

The jar files (located in the target folder of the application after building the application) is executable by the command:\ java -jar <name of file.jar>

Please be aware that the executable quakeml-web-service-ingestor application require a MySQL database running. Configurations for the MySQL connection can be altered by changing the values in the .env file located in the project root folder.

War files

The war files produces are applications ment for servers. For deployment these could be uploaded and made runnable by a Tomcat server.\ If you would like to run the server applications locally, an embedded tomcat server is applied and can be initiated by navigating into the application folder and execute the command:

mvn spring-boot:run -Dspring.profiles.active=prod

Please be aware that the quakeml-web-servicemapplication require a MySQL database running. Configurations for the MySQL connection can be altered by changing the values in .env file located in the project root folder.

Docker

A docker configuration has also been implemented to bypass the requirement of installing MySQL (ingestor, web-service) and a tomcat server for the web-service. Within docker, a virtual containers spins up to initiate the database, host the web-service application and populates the database with data from one or multiple catalog(s).

Configure Database, catalog path and Tomcat server

A configuration file (.env) exists in the main project folder for configuring credentials and ports for the MySQL database, tomcat server and monitoring data access. The application name can also be altered, whose name will be the end path of your hosting domain. The profile option is related to information presented within the query builder page. Please read the make custom profiles section for adding your own markup.

In addition, a path to REA folder (or alternative folder where catalogs are located) needs to be specified within the .env file. A catalogs option exists to select one or multiple catalogs to be accessible through the web-service. If left empty, no data will be loaded into the database. Each catalog should be represented in a JSON structure as demonstrated in the example below. Specify the name of the catalog (the folder name of the catalog within REA), the autorityID which represents you institution in the form of (top-level domain).(organisation/institution)[.(sub-unit of organisation)]. This information is used for ID generation for each QuakeML entity. The ID is prefixed with a schema name, which should be either smi (seismological meta-information) or quakeml and it is possible to choose the preferred option within the JSOn structure for each catalog.

The ingestor component has a scheduler for regular checks of the catalog folder(s) and updating the MySQL database respectively. If INGEST_SCHEDULER_ENABLED is set to false, the ingestor will only insert the data once as a fixed dataset. For regular updates, set the INGEST_SCHEDULER_INTERVAL option with the preferred interval between each check. The interval of the scheduler is defined by the ISO8601 Duration format.

DB_NAME=dbname
DB_USER=username
DB_PW=password
DB_ROOT_PW=password
DB_PORT=3306
TOMCAT_USER=username
TOMCAT_PASSWORD=password
TOMCAT_PORT=8090
MONITOR_USER=username
MONITOR_PASSWORD=password
WS_APP_NAME=eqcat
PROFILE=default
REA_FOLDER='C:/SEISAN/REA'
CATALOGS='[{"name":"NNSN_","authorityID":"no.uib.nnsn","prefix":"smi"}, {"name":"NNSN__","authorityID":"no.uib.nnsn","prefix":"smi"}]'
INGEST_SCHEDULER_ENABLED=true
INGEST_SCHEDULER_INTERVAL=PT02M

Important note: For running docker on Windows, the values for REA_FOLDER and CATALOGS needs to be in single quotes, as given within the example above. For Linux users, the single quotes have to be removed.

Configure html document for the web-service

The query builder page can be customised to your needs. The application has build in profiles for change of content in title, header and footer. To add your own custom content for these sections, please edit the default section (html comment is given where you can add your html code) within title.html, header.html and footer.html in the following folder:

quakeml-web-service -> src -> main -> resources -> pages -> fragments

After changes are made, if you have already built (applying the run command) the docker images, please make sure to remove the previous build images and rebuild (description given in section about running docker).

Make own custom profiles for html documents

If you want to make your own profile, or multiple profiles for various deployments, you can do so by adding another fragment within the same files as mentioned in the previous section. For example:

<header th:fragment="default-header"></header> 

Replace the default-header with you custom reference name. Then go into the index.html file within the pages folder (one level above the fragments folder) and add another statement below the following block:

<div th:replace="${profile == 'default'} ? ~{fragments/header :: default-header} : ~{}" />

Change default-header with you custom reference name, and change the default name in ${profile == 'default'} with a profile name of your choice. The last step is to apply this profile name within the .env file in the root folder of all the projects. Change the default in PROFILE=default with the name your selected for your new profile.

After changes are made, if you have already built (applying the run command) the docker images, please make sure to remove the previous build images and rebuild (description given in section about running docker).

Running the applications through docker

Make sure that you have docker installed on your computer and that it is running. Open a terminal, navigate to the main folder and enter

docker-compose up -d

To shutdown the docker instances, enter

docker-compose down

If you already did a run and want to change the database credentials, add the flag '-v' like so

docker-compose down -v

Please be aware that the '-v' flag will permanently delete the database volume, and you will lose all the data stored within the database created within the MySQL instance.

To remove the images created (useful for rebuild if changes are made to the html documents or other files within the applications), use the following command

docker-compose down --rmi=all

It is also possible to add both -v and --rmi=all in the same command for shutting down the application for rebuilding. To build the images again, enter the docker-compose up -d command again.

Running the monitoring system through docker

Make sure that the other applications are already running (see previous section). You can check that the applications are running by entering the following command:\

docker ps

A list of docker images (tomcat server and mysql database) should then appear with a status of Up and how long it has been running.

To run the monitoring applications through docker, enter:

docker-compose -f docker-compose-monitoring.yml up -d

And to stop these applications, enter:

docker-compose -f docker-compose-monitoring.yml down --rmi=all -v

Modules

Mapping

Mapping between QuakeML entities and Nordic lines. Check the excel file under documentation folder for more detailed information.

• Amplitude (From Nordic line type 1 and 4)
• Arrival (From Nordic line type 1 and 4)
• Event (From Nordic line type 1, 3, 6, I and S)
• FocalMechanism (From Nordic line type F)
• Magnitude (From Nordic line type 1)
• MomentTensor (From Nordic line type M)
• Origin (From Nordic line type 1 and E)
• OriginUncertainty (Currently no mapping)
• Pick (From Nordic line type 1 and 4)
• StationMagnitude (Currently no mapping)
• StationMagnitudeContribution (Currently no mapping)