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.