Last modified 20 months ago
Last modified on 01/19/12 18:22:12
Adding Location Code to Earthworm Messages
2004/03/05:LDD, updated 2005/03/18:LDD
________________________________________________________________________________
SUMMARY
Earthworm msg types used by NCSN that will require new versions
to implement Location code in SCNL:
Current Msg Type New Msg Type Generated by
---------------- ------------- ------------
TYPE_TRACEBUF TYPE_TRACEBUF2 all data sources
TYPE_TRACE_COMP_UA TYPE_TRACE2_COMP_UA compress_UA
TYPE_PICK2K TYPE_PICK_SCNL pick_ew
TYPE_CODA2K TYPE_CODA_SCNL pick_ew
TYPE_EVENT2K TYPE_EVENT_SCNL eqproc,eqprelim
TYPE_CARLSTATRIG TYPE_CARLSTATRIG_SCNL carlstatrig
TYPE_TRIGLIST2K TYPE_TRIGLIST_SCNL carlsubtrig,arc2trignc,
evansassoc
TYPE_LPTRIG TYPE_LPTRIG_SCNL evanstrig
Format already contains fields for L, but code must be changed
to implement it:
TYPE_HYP2000ARC TYPE_HYP2000ARC eqcoda,hyp2000_mgr
________________________________________________________________________________
Adding Location code to Trace Data Messages
-------------------------------------------
TYPE_TRACEBUF2 & TYPE_TRACE2_COMP_UA
The new trace data message header will be of the same length as
the current message header. The location and version fields will
be carved out of the currently over-sized chan field. All other
fields will remain the same length and in the same position in
the header. This means that the station and network fields will
still remain over-sized with respect to the SEED field length
requirements.
Here's the original and the new trace header, from trace_buf.h:
/*---------------------------------------------------------------------------*
* Definition of original TYPE_TRACEBUF header with CSS3.0-length SNC fields *
* *
* NOTE: The principal time fields in the TRACE_HEADER are: *
* starttime, nsamp, and samprate. *
* The endtime field is included as a redundant convenience. *
*---------------------------------------------------------------------------*/
#define NETWORK_NULL_STRING "-"
#define TRACE_STA_LEN 7
#define TRACE_CHAN_LEN 9
#define TRACE_NET_LEN 9
#define TRACE_LOC_LEN 3
typedef struct {
int pinno; /* Pin number */
int nsamp; /* Number of samples in packet */
double starttime; /* time of first sample in epoch seconds
(seconds since midnight 1/1/1970) */
double endtime; /* Time of last sample in epoch seconds */
double samprate; /* Sample rate; nominal */
char sta[TRACE_STA_LEN]; /* Site name */
char net[TRACE_NET_LEN]; /* Network name */
char chan[TRACE_CHAN_LEN]; /* Component/channel code */
char datatype[3]; /* Data format code */
char quality[2]; /* Data-quality field */
char pad[2]; /* padding */
} TRACE_HEADER;
/*---------------------------------------------------------------------------*
* Definition of TYPE_TRACEBUF2 header with SEED SNCL fields. *
* *
* The new TRACE2_HEADER is the same length as the original TRACE_HEADER. *
* + sta and net fields remain unchanged (longer than required by SEED). *
* + chan field is shortened to appropriate SEED length. *
* + loc and version fields were added in the extra chan field bytes. *
* + all other fields remain unchanged (same length, same position). *
* *
* NOTE: The principal time fields in the TRACE_HEADER are: *
* starttime, nsamp, and samprate. *
* The endtime field is included as a redundant convenience. *
*---------------------------------------------------------------------------*/
#define TRACE2_STA_LEN 7 /* SEED: 5 chars plus terminating NULL */
#define TRACE2_NET_LEN 9 /* SEED: 2 chars plus terminating NULL */
#define TRACE2_CHAN_LEN 4 /* SEED: 3 chars plus terminating NULL */
#define TRACE2_LOC_LEN 3 /* SEED: 2 chars plus terminating NULL */
#define TRACE2_VERSION0 '2' /* version[0] for TYPE_TRACEBUF2 */
#define TRACE2_VERSION1 '0' /* version[1] for TYPE_TRACEBUF2 */
#define LOC_NULL_STRING "--" /* NULL string for location code field */
typedef struct {
int pinno; /* Pin number */
int nsamp; /* Number of samples in packet */
double starttime; /* time of first sample in epoch seconds
(seconds since midnight 1/1/1970) */
double endtime; /* Time of last sample in epoch seconds */
double samprate; /* Sample rate; nominal */
char sta[TRACE2_STA_LEN]; /* Site name (NULL-terminated) */
char net[TRACE2_NET_LEN]; /* Network name (NULL-terminated) */
char chan[TRACE2_CHAN_LEN]; /* Component/channel code (NULL-terminated)*/
char loc[TRACE2_LOC_LEN]; /* Location code (NULL-terminated) */
char version[2]; /* version field */
char datatype[3]; /* Data format code (NULL-terminated) */
char quality[2]; /* Data-quality field */
char pad[2]; /* padding */
} TRACE2_HEADER;
The version field is included to differentiate the TYPE_TRACEBUF2
message from the TYPE_TRACEBUF when data are stored without the
context of an Earthworm message logo. This is important for NCSN
because our continuous archive consists of files of raw trace messages.
We have to be able to read a trace header and decide whether it
contains the loc field or not. The Earthworm tankplayer module has
the same requirement; it reads a file containing raw trace messages
and will have to know whether to write them to the ring as
TYPE_TRACEBUF or TYPE_TRACEBUF2 messages.
The version field will be filled with 2 ASCII characters (no NULLs):
TRACE2_VERSION0 = version[0] = main version number
TRACE2_VERSION1 = version[1] = subversion number
________________________________________________________________________________
Adding location code to pick and coda messages. 2004/5/25:LDD
--------------------------------------------------------------
+ New messages are white-space delimited, and thus are variable length.
+ Pick sequence number range was increased to 0-999999.
+ Pick time is reported to thousandths of a second to support sample rates
greater than 100sps. Hypoinverse still has the hundredths of a second
limitation, but if we ever change locators, we'll be ready for increased
precision.
+ Pick first motion (1-character) values:
'U' for Up (compression),
'D' for Down (dilatation),
'?' for unknown (previous column-oriented format used ' ' for unknown).
+ Channel identifier is dot-delimited for better human readability.
+ A "blank" location code will be written as "--" (without quotes).
+ C library functions for converting the ascii pick/coda messages into
structures is available in rdpickcoda.c,h.
--------------------------------------------------------------
TYPE_PICK_SCNL
Sample TYPE_PICK_SCNL message (new field-oriented format):
8 4 3 2133 CMN.VHZ.NC.01 U1 19950831183134.900 953 1113 968\n
Field Description
1 MsgType (TYPE_PICK_SCNL=8, defined in earthworm_global.d)
2 ModuleId
3 InstId
4 Pick sequence number (0-999999)
5 channel identifier: Sta.Comp.Net.Loc
6 two-character pick descriptor: char1=first motion (U,D,?)
char2=pick quality (0-4, 0=best)
7 pick time: yyyymmddhhmmss.ttt
(seconds to the thousandths to support sample rates > 100sps)
8 amplitude of first peak (digital counts)
9 amplitude of second peak (digital counts)
10 amplitude of third peak (digital counts)
\n newline
For reference, sample TYPE_PICK2K message (column-oriented, 72 chars long):
10 4 3 2133 CMN NCVHZ U1 19950831183134.90 953 1113 968\n
0123456789 123456789 123456789 123456789 123456789 123456789 123456789 12
--------------------------------------------------------------
TYPE_CODA_SCNL
Sample TYPE_CODA_SCNL message (new field-oriented format):
9 4 3 2133 CMN.VHZ.NC.01 48 106 211 182 148 133 15\n
Field Description
1 MsgType (TYPE_CODA_SCNL=9, defined in earthworm_global.d)
2 ModuleId
3 InstId
4 Pick sequence number (0-999999)
5 channel identifier: Sta.Comp.Net.Loc
6-11 six coda 2-sec average absolute amplitudes (digital counts),
listed in reverse chronological order (same as previous coda msg).
12 coda duration (seconds)
Negative duration means that "noisy-trace" coda termination
method was used by the picker.
\n newline
For reference, sample TYPE_CODA2K message (column-oriented, 79 characters long):
11 4 3 2133 CMN NCVHZ 48 106 211 182 148 133 15 \n
0123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
________________________________________________________________________________
Adding location code to TYPE_EVENT* messages. 2005/3/17:LDD
------------------------------------------------------------
TYPE_EVENT_SCNL
This message type is used internally between eqproc/eqprelim and eqcoda in
the Earthworm "mega module" and is never output to an Earthworm ring. The
previous TYPE_EVENT2K message was column-oriented and the new TYPE_EVENT_SCNL
message is field-oriented. The TYPE_EVENT_SCNL message contains an event
hypocenter line containing information from binder's TYPE_QUAKE messages,
followed by one line for each associated phase. Each phase line is a
compilation of information from TYPE_PICK_SCNL, TYPE_CODA_SCNL, and TYPE_LINK
messages, plus a data source supplied by the producing module.
Sample TYPE_EVENT_SCNL message:
20050317235045.380 36.558600 -121.114800 13.44 12 140 6.9 0.09 51157910 1
BVL VHZ NC -- U0 P 20050317235048.210 1515 1880 1992 30 59 64 171 124 174 15 W
BPI VHZ NC -- D0 P 20050317235048.450 674 1036 818 40 66 130 263 267 0 9 W
BBG VHZ NC -- D2 P 20050317235048.520 98 210 228 38 85 159 368 167 0 9 W
BEM VHZ NC -- D0 P 20050317235048.720 1334 1853 1112 38 60 137 199 253 0 9 W
BAV VHZ NC -- D0 P 20050317235048.790 228 205 101 29 51 52 0 0 0 5 W
BEH VHZ NC -- D0 P 20050317235049.090 144 238 137 34 80 111 197 166 0 9 W
BJO VHZ NC -- U0 P 20050317235049.680 569 638 535 35 59 84 148 142 0 9 W
BJC VHZ NC -- U0 P 20050317235050.610 211 495 319 27 50 49 89 129 125 11 W
BVY VHZ NC -- U1 P 20050317235052.220 185 541 294 32 83 0 0 0 0 3 W
JBZ VHZ NC -- D2 P 20050317235056.890 157 128 114 36 57 51 76 0 0 7 W
Hypocenter Line
Field Description
1 Origin time (yyyymmddhhmmss.ttt)
2 Latitude (decimal degrees)
3 Longitude (decimal degrees)
4 Depth (km)
5 Number of phases associated by binder
6 Azimuthal Gap
7 Distance to closes station (km)
8 RMS (sec)
9 Eventid from binder
10 Version for event, supplied by module producing this message.
If the module produces multiple TYPE_EVENT_SCNL msgs for each Eventid,
then the version should be incremented.
Phase Line
Field Description
1 Station code
2 Component code
3 Network code
4 Location code
5 two-character pick descriptor: char1=first motion (U,D,?)
char2=pick quality (0-4, 0=best)
6 Phase descriptor from binder (P,Pg,Pn,S,Sg,Sn)
7 pick time: yyyymmddhhmmss.ttt
(seconds to the thousandths to support sample rates > 100sps)
8 amplitude of first peak (digital counts)
9 amplitude of second peak (digital counts)
10 amplitude of third peak (digital counts)
11-16 six coda 2-sec average absolute amplitudes (digital counts),
listed in reverse chronological order.
17 coda duration (seconds)
Negative duration means that "noisy-trace" coda termination
method was used by the picker.
18 Data source - a single character describing the source of the
pick and coda information. Examples: 'W' for local earthworm,
'I' for imported from another institution.
________________________________________________________________________________
Adding location code to station trigger messages. 2005/3/17:LDD
---------------------------------------------------------------
TYPE_CARLSTATRIG_SCNL
This is a field-oriented message produced by carlstatrig. The only change
from the previous station trigger message is the addition of the location code
field after the network code. Every time a station triggers, carlstatrig should
write two TYPE_CARLSTATRIG_SCNL messages, one when the station trigger turns
on, and another when the station trigger turns off. Both messages have the
same format.
Sample TYPE_CARLSTATRIG_SCNL message:
JSP EHZ NC 01 1111165293.0000 1111165294.0000 14617 13.87
Field Description
1 Station code
2 Component code
3 Network code
4 Location code
5 Trigger ON time (sec since 1970)
6 Trigger OFF time (sec since 1970, 0.0 while trigger is still ON)
7 serial number for this station trigger (so ON and OFF messages
can be matched up)
8 ETA when the station trigger went ON.
ETA is the triggering parameter computed from STA, LTA and other things.
A station trigger is ON when ETA > 0.0, OFF when ETA <= 0.0.
________________________________________________________________________________
Adding location code to triglist messages. 2005/3/17:LDD
--------------------------------------------------------
TYPE_TRIGLIST_SCNL
Triglist messages are produced by a number of different Earthworm modules
and the details of how certain fields are filled vary from module to module.
I'm not going to try to cover all the variations here.
Here's a sample TYPE_TRIGLIST_SCNL message:
v2.0 EVENT DETECTED 20050308 20:47:02.71 UTC EVENT ID: 69000541 AUTHOR: 014024003:033052003
Sta/Cmp/Net/Loc Date Time start save duration in sec.
--------------- ------ --------------- ------------------------------------------
GGP * NC -- P 20050308 20:47:03.45 UTC save: 20050308 20:46:48.45 35
GDX * NC * P 20050308 20:47:04.40 UTC save: 20050308 20:46:48.45 35
GPM * NC * P 20050308 20:47:05.01 UTC save: 20050308 20:46:48.45 35
GAX * NC * P 20050308 20:47:04.86 UTC save: 20050308 20:46:48.45 35
GAC * NC * P 20050308 20:47:05.18 UTC save: 20050308 20:46:48.45 35
GSS VHZ NC 01 P 20050308 20:47:05.47 UTC save: 20050308 20:46:48.45 35
NMC * NC * P 16000101 00:00:00.00 UTC save: 20050308 20:46:48.45 35
NFV * NC * P 16000101 00:00:00.00 UTC save: 20050308 20:46:48.45 35
NEA * NC * P 16000101 00:00:00.00 UTC save: 20050308 20:46:48.45 35
Here are the differences between the previous triglist message and
the new TYPE_TRIGLIST_SCNL:
1. added version field to the beginning of the EVENT line
Version is set to "v2.0" for the TYPE_TRIGLIST_SCNL message.
2. added location code field (just after the network code field) on the
station line. This field can contain the actual channel location code,
or "*" for wildcard.
Library functions for parsing the TYPE_TRIGLIST_SCNL message are contained in
parse_trig.c,h. These functions have been modified to recognize only
TYPE_TRIGLIST_SCNL messages!
________________________________________________________________________________
Adding location code to station LP trigger messages. 2005/3/18:LDD
------------------------------------------------------------------
These messages are produced by evanstrig and consumed by evansassoc.
I don't know of any other modules that use them.
Sample TYPE_LPTRIG_SCNL message:
31 32 3 16 MGP VHZ NC 01 1111103996.770 B
Field Description
1 MsgType (TYPE_LPTRIG_SCNL=31, defined in earthworm_global.d)
2 ModuleId
3 InstId
4 Channel pin number (legacy field)
5 Station code
6 Component code
7 Network code
8 Location code
9 Trigger time (sec since 1970)
10 Type of trigger (single character: N=normal, B=big)
________________________________________________________________________________
Adding location code to hypoinverse archive messages. 2005/3/18:LDD
-------------------------------------------------------------------
The hypoinverse archive format already includes a field for location code.
See details of the "station archive format" in Fred Klein's documentation:
ftp://ehzftp.wr.usgs.gov/klein/docs/shadow2000.pdf
ftp://ehzftp.wr.usgs.gov/klein/hyp2000/docs/hyp2000-1.0.pdf
Modules which produce and consume TYPE_HYP2000ARC messages have been modified
to fill and read the location code field.
