seisan2sc

seisan2sc: A tool to import SEISAN S-files into the SeisComP3 database.

Description

Working flow diagram

Schematic seisan2sc and sc2seisan.

seisan2sc and sc2seisan flow diagram.

seisan2sc can be executes in two modes:

  1. Real-time Mode for importing SEISAN S-files into the SeisComP3 database; and
  2. Batch-import Mode for importing legacy SEISAN S-Files into the database.

In batch import mode, there is also the option to import WAV files as mapped to by the individual S-files. In both modes, S-files are read into memory, translated into SC3XML and loaded into the SeisComP database.

seisan2sc will either add a new origin to the database or if that same origin is already in the database, then seisan2sc will update it. You can, therefore, import an S-file more than once without worrying about corrupting or adding clutter to the SeisComP database.

Mode 1: Real-time Mode

To run as a real-time process:

  1. Configure seisan2sc at scconfig (Modules >> OSOP >> seisan2sc), save and exit (you do not need to run "Update configuration" from the GUI nor "seiscomp update-config" from the command line when you make changes to the configuration). Please don't forget to set the path to the SEISAN.DEF file of your working SEISAN installation (Modules >> OSOP >> seisan2sc >> Input >> stations field).

  2. Configure scevent and make sure that seisan is listed in eventAssociation.agencies and Seisan magnitudes such as MW and ML are listed at eventAssociation.magTypes.

  3. Enable and start seisan2sc scevent:

    $ seiscomp enable scevent seisan2sc
    $ seiscomp start scevent seisan2sc
    
  4. Check they are alive and well:

    $ seiscomp status scevent seisan2sc
    

Mode 2: Batch-import mode

To run in batch import mode:

  1. Configure seisan2sc at scconfig (Modules >> OSOP >> seisan2sc), save and exit (you do not need to run "Update configuration" from the GUI nor "seiscomp update-config" from the command line when you make changes to the configuration). Please don't forget to set the path to the SEISAN.DEF file of your working SEISAN installation (Modules >> OSOP >> seisan2sc >> Input >> stations field).

  2. Configure scevent and make sure that seisan is listed in eventAssociation.agencies and Seisan magnitudes such as MW and ML are listed at eventAssociation.magTypes.

  3. Enable and start scevent

    $ seiscomp enable scevent
    $ seiscomp start scevent
    
  4. Check scevent is alive and well:

    $ seiscomp status scevent
    
  1. Execute seisan2sc from the command line:

    $ seisan2sc --import [path to the directory containing S-files]

  2. Importing also waveforms with s-files from command line (optional in case the waveform is not already at the archive or want to update it):

    $ seisan2sc --import [path to the directory containing S-files] --data

This will scan a directory, import all the S-file found in it, and exit.

Implementation

Network and location codes: SEISAN.DEF

In SEISAN S-files, the network and location codes are not used at all. Only station codes are used. So there cannot be stations, for instance, with the same station code even if they are from different networks (Or there can be, but it would give an error when it seeks for the STATION0.HYP coordinates). While in Seiscomp3 data structures, we have to specify a complete NSLC every now and then, for example, in picks and arrivals. Still, we know only the station part of NSLC from Type 4 lines of an S-file.

Solution:

In a live SEISAN installation, there is a file called SEISAN.DEF which contains a list of ARC_CHAN records. These records define all the NSLCs known to SEISAN. These can be used to create a lookup table which, given just the station part of a NSLC, gives us the remainder of NSLC: network, location, and channel. To know more about SEISAN.DEF, please refer to the SEISAN documentation.

Note

SEISAN.DEF file provided with the seisan2sc package (installed by default as /opt/seiscomp3/share/seisan2sc/SEISAN.DEF) is just the starting point useful for development and testing purposes. On a live SEISAN/Seiscomp3 system, you should run scconfig, check Modules section, pick seisan2sc module, and edit "stations" field in the "Input" section. There, please fill in the path to the actual SEISAN.DEF file of your SEISAN installation.

Note

If a station found in an S-file has no correspondence in SEISAN.DEF file, seisan2sc will log an ERROR message.

Note

Each arc station line on SEISAN.DEF has two dates (optionals) if they exists, seisan2sc can distinguish between two different stations with the same codes. These dates refers to the station working time period.

How to trace from what is imported into the SeisComP database back to the original S-file (useful for troubleshooting)

Also: How to distinguish between different locations in the same S-file

S-file does not have unique identifiers. Worse, if an S-file has two locations, there is no unique identifier to tell them apart. To solve this problem and to ensure that we could always trace back from the SeisComP database to the origin S-file, we exploited the @ function in the author name and publicIDs:

The field continues "seisan@[original S-file name]", like

seisan@03-1842-37L.S201504

Pick, origin, mangitude, and focal mechanism fields have been adjusted with the line number in the data file from which they originate, like

<pick publicID="Pick#20160220162028.420396.45@line78">
<origin publicID="SEISORI#sfileID@line1">
<magnitude publicID="Magnitude#20160220162028.37607.3@line1">
<focalMechanism publicID="FocalMechanism#20160220162028.376402.4@line2">

Pick weights

SeiscomP and Seisan use different weighting schema. In seismology, there seem to be 2 dominate weight schema:

  1. 0 (best ever or 100% certain) to 4 (don't take into account or 100% uncertain). Examples: SEISAN, Hypo71
  2. 1 (activated) or 0 (deactivated). Examples: NonLinLoc, SeisComP.

In SeisComP, picks generated by the automatic picking module scautopick do not carry any pick uncertainty at all. In scolv (the manual re-picking GUI), you can only toggle between 0 and 1.

Solution:

If a pick in SEISAN has a weight of 0, 1, 2 or 3, map it to a weight of "1" (activated) in SeisComP. If a pick in SEISAN has a weight of 4, map it to a weight of "0" (deactivated) in SeisComP.

ML Magnitude

Unlike MW, ML is not explicitly shown in the SEISAN S-file. Instead, the amplitude and period are reported. So ML needs to be calculated before it can be included in SeisComP. The formula used for this purpose is:

ML = a*log10(amp) + b*log10(dist) + c*dist + d

where 'amp' is the amplitude and 'dist' is the hypocentral distance from the station to the earthquake in kilometers. 'amp' and 'dist' are taken from the S-file and combined with a, b, c and d to calculate the ML automatically when importing the new origin. These parameters can be configured in scconfig.

Since the DIST column in the S-fie is epicentral distance, this is combined with the depth of the earthquake (also taken from the S-file) in order to calculate hypocentral distance using the Pythagoream theorem.

Other special considerations

We dealt with cases where S-files use commas instead of periods as is common in Latin America

Logging

All logs are written to ~/.seiscomp3/log/seisan2sc.log

Technical Support

If you have any questions, feel free to email us at support@osop.com.pa.

Configuration

Note

seisan2sc is a standalone module and does not inherit global options.

etc/defaults/seisan2sc.cfg
etc/seisan2sc.cfg
~/.seiscomp3/seisan2sc.cfg
input.directory

Type: string

Directory in which incoming S-files appear.

input.stations

Type: string

Path to SEISAN.DEF file of your SEISAN installation

input.interval

Type: integer

Interval in seconds between the directory scans

origin.author

Type: string

Author of the event to be used in SC3ML file.

origin.agency

Type: string

Reporting agency to be used in SC3ML file.

origin.preferred

Type: boolean

if true, preferredOrigin is written; otherwise it is not.

origin.method

Type: string

Location method, default LOCSAT

origin.model

Type: string

Earth model ID, default iasp91

logging.level

Type: integer

Logging level (1=ERROR, 2=WARNING, 3=INFO, 4=DEBUG).

license.directory

Type: string

Directory which contains license.txt and license.key

waveform.WAVdir

Type: string

Directory where SEISAN stores waveform files

waveform.SDSdir

Type: string

Directory where Seiscomp3 maintains SDS directory structure

magnitude.a

Type: float

'a' parameter for Ml station magnitudes

magnitude.b

Type: float

'b' parameter for Ml station magnitudes

magnitude.c

Type: float

'c' parameter for Ml station magnitudes

magnitude.d

Type: float

'd' parameter for Ml station magnitudes

filter.minLat

Type: float

minimum latitude (deg)

filter.maxLat

Type: float

maximum latitude (deg)

filter.minLon

Type: float

minimum longitude (deg)

filter.maxLon

Type: float

maximum longitude (deg)

Note

nearest_city_fix.* Some S-files have the Epicentro: Type 3 line which contains the closest city to the epicenter. This option allows to extract the closest city and to write it to the database, so that it will be displayed in scolv (column Region of the Event tab).

nearest_city_fix.enable

Type: boolean

enable this option

nearest_city_fix.host

Type: string

database host

nearest_city_fix.user

Type: string

database user

nearest_city_fix.password

Type: string

database password

nearest_city_fix.database

Type: string

name of the database