source: trunk/EW_msgs_addLoc.txt @ 1762

Revision 1762, 16.9 KB checked in by dietz, 16 years ago (diff)

* empty log message *

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1Adding Location Code to Earthworm Messages
22004/03/05:LDD, updated 2005/03/18:LDD
3________________________________________________________________________________
4
5SUMMARY
6
7Earthworm msg types used by NCSN that will require new versions
8to implement Location code in SCNL:
9
10Current Msg Type     New Msg Type            Generated by
11----------------     -------------           ------------
12TYPE_TRACEBUF        TYPE_TRACEBUF2          all data sources
13
14TYPE_TRACE_COMP_UA   TYPE_TRACE2_COMP_UA     compress_UA
15
16TYPE_PICK2K          TYPE_PICK_SCNL          pick_ew
17
18TYPE_CODA2K          TYPE_CODA_SCNL          pick_ew
19
20TYPE_EVENT2K         TYPE_EVENT_SCNL         eqproc,eqprelim
21
22TYPE_CARLSTATRIG     TYPE_CARLSTATRIG_SCNL   carlstatrig
23
24TYPE_TRIGLIST2K      TYPE_TRIGLIST_SCNL      carlsubtrig,arc2trignc,
25                                             evansassoc
26
27TYPE_LPTRIG          TYPE_LPTRIG_SCNL        evanstrig
28
29Format already contains fields for L, but code must be changed
30to implement it:
31TYPE_HYP2000ARC      TYPE_HYP2000ARC         eqcoda,hyp2000_mgr
32
33________________________________________________________________________________
34
35
36Adding Location code to Trace Data Messages
37-------------------------------------------
38
39TYPE_TRACEBUF2 & TYPE_TRACE2_COMP_UA
40
41The new trace data message header will be of the same length as
42the current message header. The location and version fields will
43be carved out of the currently over-sized chan field.  All other
44fields will remain the same length and in the same position in
45the header. This means that the station and network fields will
46still remain over-sized with respect to the SEED field length
47requirements.
48
49Here's the original and the new trace header, from trace_buf.h:
50
51/*---------------------------------------------------------------------------*
52 * Definition of original TYPE_TRACEBUF header with CSS3.0-length SNC fields *
53 *                                                                           *
54 * NOTE: The principal time fields in the TRACE_HEADER are:                  *
55 *         starttime, nsamp, and samprate.                                   *
56 *       The endtime field is included as a redundant convenience.           *
57 *---------------------------------------------------------------------------*/
58
59#define NETWORK_NULL_STRING "-"
60
61#define TRACE_STA_LEN   7
62#define TRACE_CHAN_LEN  9
63#define TRACE_NET_LEN   9
64#define TRACE_LOC_LEN   3
65
66typedef struct {
67        int     pinno;                 /* Pin number */
68        int     nsamp;                 /* Number of samples in packet */
69        double  starttime;             /* time of first sample in epoch seconds
70                                          (seconds since midnight 1/1/1970) */
71        double  endtime;               /* Time of last sample in epoch seconds */
72        double  samprate;              /* Sample rate; nominal */
73        char    sta[TRACE_STA_LEN];    /* Site name */
74        char    net[TRACE_NET_LEN];    /* Network name */
75        char    chan[TRACE_CHAN_LEN];  /* Component/channel code */
76        char    datatype[3];           /* Data format code */
77        char    quality[2];            /* Data-quality field */
78        char    pad[2];                /* padding */
79} TRACE_HEADER;
80
81/*---------------------------------------------------------------------------*
82 * Definition of TYPE_TRACEBUF2 header with SEED SNCL fields.                *
83 *                                                                           *
84 * The new TRACE2_HEADER is the same length as the original TRACE_HEADER.    *
85 *  + sta and net fields remain unchanged (longer than required by SEED).    *
86 *  + chan field is shortened to appropriate SEED length.                    *
87 *  + loc and version fields were added in the extra chan field bytes.       *     
88 *  + all other fields remain unchanged (same length, same position).        *
89 *                                                                           *
90 * NOTE: The principal time fields in the TRACE_HEADER are:                  *
91 *         starttime, nsamp, and samprate.                                   *
92 *       The endtime field is included as a redundant convenience.           *
93 *---------------------------------------------------------------------------*/
94
95#define TRACE2_STA_LEN    7    /* SEED: 5 chars plus terminating NULL */
96#define TRACE2_NET_LEN    9    /* SEED: 2 chars plus terminating NULL */
97#define TRACE2_CHAN_LEN   4    /* SEED: 3 chars plus terminating NULL */
98#define TRACE2_LOC_LEN    3    /* SEED: 2 chars plus terminating NULL */
99
100#define TRACE2_VERSION0  '2'   /* version[0] for TYPE_TRACEBUF2       */
101#define TRACE2_VERSION1  '0'   /* version[1] for TYPE_TRACEBUF2       */
102
103#define LOC_NULL_STRING  "--"  /* NULL string for location code field */
104
105typedef struct {
106        int     pinno;                 /* Pin number */
107        int     nsamp;                 /* Number of samples in packet */
108        double  starttime;             /* time of first sample in epoch seconds
109                                          (seconds since midnight 1/1/1970) */
110        double  endtime;               /* Time of last sample in epoch seconds */
111        double  samprate;              /* Sample rate; nominal */
112        char    sta[TRACE2_STA_LEN];   /* Site name (NULL-terminated) */
113        char    net[TRACE2_NET_LEN];   /* Network name (NULL-terminated) */
114        char    chan[TRACE2_CHAN_LEN]; /* Component/channel code (NULL-terminated)*/
115        char    loc[TRACE2_LOC_LEN];   /* Location code (NULL-terminated) */
116        char    version[2];            /* version field */
117        char    datatype[3];           /* Data format code (NULL-terminated) */
118        char    quality[2];            /* Data-quality field */
119        char    pad[2];                /* padding */
120} TRACE2_HEADER;
121
122The version field is included to differentiate the TYPE_TRACEBUF2
123message from the TYPE_TRACEBUF when data are stored without the
124context of an Earthworm message logo. This is important for NCSN
125because our continuous archive consists of files of raw trace messages.
126We have to be able to read a trace header and decide whether it
127contains the loc field or not.  The Earthworm tankplayer module has
128the same requirement; it reads a file containing raw trace messages
129and will have to know whether to write them to the ring as
130TYPE_TRACEBUF or TYPE_TRACEBUF2 messages.
131
132The version field will be filled with 2 ASCII characters (no NULLs):
133  TRACE2_VERSION0 = version[0] = main version number
134  TRACE2_VERSION1 = version[1] = subversion number
135
136________________________________________________________________________________
137
138
139Adding location code to pick and coda messages. 2004/5/25:LDD
140--------------------------------------------------------------
141
142+ New messages are white-space delimited, and thus are variable length.
143
144+ Pick sequence number range was increased to 0-999999.
145
146+ Pick time is reported to thousandths of a second to support sample rates
147  greater than 100sps.  Hypoinverse still has the hundredths of a second
148  limitation, but if we ever change locators, we'll be ready for increased
149  precision.
150
151+ Pick first motion (1-character) values:
152   'U' for Up (compression),
153   'D' for Down (dilatation),
154   '?' for unknown (previous column-oriented format used ' ' for unknown).
155
156+ Channel identifier is dot-delimited for better human readability.
157
158+ A "blank" location code will be written as "--" (without quotes).
159
160+ C library functions for converting the ascii pick/coda messages into
161  structures is available in rdpickcoda.c,h.
162
163--------------------------------------------------------------
164
165TYPE_PICK_SCNL
166
167Sample TYPE_PICK_SCNL message (new field-oriented format):
168
1698 4 3 2133 CMN.VHZ.NC.01 U1 19950831183134.900 953 1113 968\n
170
171Field  Description
172   1   MsgType (TYPE_PICK_SCNL=8, defined in earthworm_global.d)
173   2   ModuleId
174   3   InstId
175   4   Pick sequence number (0-999999)
176   5   channel identifier: Sta.Comp.Net.Loc
177   6   two-character pick descriptor: char1=first motion (U,D,?)
178                                      char2=pick quality (0-4, 0=best)
179   7   pick time: yyyymmddhhmmss.ttt
180       (seconds to the thousandths to support sample rates > 100sps)
181   8   amplitude of first  peak (digital counts)
182   9   amplitude of second peak (digital counts)
183  10   amplitude of third  peak (digital counts)
184  \n   newline
185
186For reference, sample TYPE_PICK2K message (column-oriented, 72 chars long):
187 10  4  3 2133 CMN  NCVHZ U1  19950831183134.90     953    1113     968\n
1880123456789 123456789 123456789 123456789 123456789 123456789 123456789 12
189
190--------------------------------------------------------------
191
192TYPE_CODA_SCNL
193
194Sample TYPE_CODA_SCNL message (new field-oriented format):
195
1969 4 3 2133 CMN.VHZ.NC.01 48 106 211 182 148 133 15\n
197
198Field  Description
199   1   MsgType (TYPE_CODA_SCNL=9, defined in earthworm_global.d)
200   2   ModuleId
201   3   InstId
202   4   Pick sequence number (0-999999)
203   5   channel identifier: Sta.Comp.Net.Loc
2046-11   six coda 2-sec average absolute amplitudes (digital counts),
205       listed in reverse chronological order (same as previous coda msg). 
206  12   coda duration (seconds)
207       Negative duration means that "noisy-trace" coda termination
208       method was used by the picker. 
209  \n   newline
210
211For reference, sample TYPE_CODA2K message (column-oriented, 79 characters long):
212 11  4  3 2133 CMN  NCVHZ      48     106     211     182     148     133  15 \n
2130123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
214
215
216________________________________________________________________________________
217
218
219Adding location code to TYPE_EVENT* messages. 2005/3/17:LDD
220------------------------------------------------------------
221
222TYPE_EVENT_SCNL
223
224This message type is used internally between eqproc/eqprelim and eqcoda in
225the Earthworm "mega module" and is never output to an Earthworm ring. The
226previous TYPE_EVENT2K message was column-oriented and the new TYPE_EVENT_SCNL
227message is field-oriented.  The TYPE_EVENT_SCNL message contains an event
228hypocenter line containing information from binder's TYPE_QUAKE messages,
229followed by one line for each associated phase. Each phase line is a
230compilation of information from TYPE_PICK_SCNL, TYPE_CODA_SCNL, and TYPE_LINK
231messages, plus a data source supplied by the producing module.
232
233Sample TYPE_EVENT_SCNL message:
234
23520050317235045.380 36.558600 -121.114800 13.44 12 140 6.9 0.09 51157910 1
236BVL VHZ NC -- U0 P 20050317235048.210 1515 1880 1992 30 59 64 171 124 174 15 W
237BPI VHZ NC -- D0 P 20050317235048.450 674 1036 818 40 66 130 263 267 0 9 W
238BBG VHZ NC -- D2 P 20050317235048.520 98 210 228 38 85 159 368 167 0 9 W
239BEM VHZ NC -- D0 P 20050317235048.720 1334 1853 1112 38 60 137 199 253 0 9 W
240BAV VHZ NC -- D0 P 20050317235048.790 228 205 101 29 51 52 0 0 0 5 W
241BEH VHZ NC -- D0 P 20050317235049.090 144 238 137 34 80 111 197 166 0 9 W
242BJO VHZ NC -- U0 P 20050317235049.680 569 638 535 35 59 84 148 142 0 9 W
243BJC VHZ NC -- U0 P 20050317235050.610 211 495 319 27 50 49 89 129 125 11 W
244BVY VHZ NC -- U1 P 20050317235052.220 185 541 294 32 83 0 0 0 0 3 W
245JBZ VHZ NC -- D2 P 20050317235056.890 157 128 114 36 57 51 76 0 0 7 W
246
247Hypocenter Line
248Field  Description
249   1   Origin time (yyyymmddhhmmss.ttt)
250   2   Latitude (decimal degrees)
251   3   Longitude (decimal degrees)
252   4   Depth (km)
253   5   Number of phases associated by binder
254   6   Azimuthal Gap
255   7   Distance to closes station (km)
256   8   RMS (sec)
257   9   Eventid from binder
258  10   Version for event, supplied by module producing this message.
259       If the module produces multiple TYPE_EVENT_SCNL msgs for each Eventid,
260       then the version should be incremented.
261
262Phase Line
263Field  Description
264   1   Station code
265   2   Component code
266   3   Network code
267   4   Location code
268   5   two-character pick descriptor: char1=first motion (U,D,?)
269                                      char2=pick quality (0-4, 0=best)
270   6   Phase descriptor from binder (P,Pg,Pn,S,Sg,Sn)
271   7   pick time: yyyymmddhhmmss.ttt
272       (seconds to the thousandths to support sample rates > 100sps)
273   8   amplitude of first  peak (digital counts)
274   9   amplitude of second peak (digital counts)
275  10   amplitude of third  peak (digital counts)
27611-16  six coda 2-sec average absolute amplitudes (digital counts),
277       listed in reverse chronological order.
278  17   coda duration (seconds)
279       Negative duration means that "noisy-trace" coda termination
280       method was used by the picker.
281  18   Data source - a single character describing the source of the
282       pick and coda information.  Examples: 'W' for local earthworm,
283       'I' for imported from another institution. 
284
285________________________________________________________________________________
286
287
288Adding location code to station trigger messages. 2005/3/17:LDD
289---------------------------------------------------------------
290
291TYPE_CARLSTATRIG_SCNL
292
293This is a field-oriented message produced by carlstatrig. The only change
294from the previous station trigger message is the addition of the location code
295field after the network code. Every time a station triggers, carlstatrig should
296write two TYPE_CARLSTATRIG_SCNL messages, one when the station trigger turns
297on, and another when the station trigger turns off.  Both messages have the
298same format.
299
300Sample TYPE_CARLSTATRIG_SCNL message:
301
302JSP EHZ NC 01 1111165293.0000 1111165294.0000 14617 13.87
303
304Field  Description
305   1   Station code
306   2   Component code
307   3   Network code
308   4   Location code
309   5   Trigger ON time (sec since 1970)
310   6   Trigger OFF time (sec since 1970, 0.0 while trigger is still ON)
311   7   serial number for this station trigger (so ON and OFF messages
312       can be matched up)
313   8   ETA when the station trigger went ON.
314       ETA is the triggering parameter computed from STA, LTA and other things.
315       A station trigger is ON when ETA > 0.0, OFF when ETA <= 0.0.
316
317
318________________________________________________________________________________
319
320
321Adding location code to triglist messages. 2005/3/17:LDD
322--------------------------------------------------------
323
324TYPE_TRIGLIST_SCNL
325
326Triglist messages are produced by a number of different Earthworm modules
327and the details of how certain fields are filled vary from module to module. 
328I'm not going to try to cover all the variations here.
329
330Here's a sample TYPE_TRIGLIST_SCNL message:
331
332v2.0 EVENT DETECTED     20050308 20:47:02.71 UTC EVENT ID: 69000541 AUTHOR: 014024003:033052003
333
334Sta/Cmp/Net/Loc   Date   Time                       start save       duration in sec.
335---------------   ------ ---------------    ------------------------------------------
336 GGP * NC -- P 20050308 20:47:03.45 UTC    save: 20050308 20:46:48.45       35
337 GDX * NC * P 20050308 20:47:04.40 UTC    save: 20050308 20:46:48.45       35
338 GPM * NC * P 20050308 20:47:05.01 UTC    save: 20050308 20:46:48.45       35
339 GAX * NC * P 20050308 20:47:04.86 UTC    save: 20050308 20:46:48.45       35
340 GAC * NC * P 20050308 20:47:05.18 UTC    save: 20050308 20:46:48.45       35
341 GSS VHZ NC 01 P 20050308 20:47:05.47 UTC    save: 20050308 20:46:48.45       35
342 NMC * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35
343 NFV * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35
344 NEA * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35
345
346Here are the differences between the previous triglist message and
347the new TYPE_TRIGLIST_SCNL:
3481. added version field to the beginning of the EVENT line
349   Version is set to "v2.0" for the TYPE_TRIGLIST_SCNL message.
3502. added location code field (just after the network code field) on the
351   station line. This field can contain the actual channel location code,
352   or "*" for wildcard.
353
354Library functions for parsing the TYPE_TRIGLIST_SCNL message are contained in
355parse_trig.c,h. These functions have been modified to recognize only
356TYPE_TRIGLIST_SCNL messages!
357
358
359________________________________________________________________________________
360
361
362Adding location code to station LP trigger messages. 2005/3/18:LDD
363------------------------------------------------------------------
364
365These messages are produced by evanstrig and consumed by evansassoc.
366I don't know of any other modules that use them.
367
368Sample TYPE_LPTRIG_SCNL message:
369
37031 32 3 16 MGP VHZ NC 01 1111103996.770 B
371
372Field  Description
373   1   MsgType (TYPE_LPTRIG_SCNL=31, defined in earthworm_global.d)
374   2   ModuleId
375   3   InstId
376   4   Channel pin number (legacy field)
377   5   Station code
378   6   Component code
379   7   Network code
380   8   Location code
381   9   Trigger time (sec since 1970)
382  10   Type of trigger (single character: N=normal, B=big)
383
384
385________________________________________________________________________________
386
387
388Adding location code to hypoinverse archive messages. 2005/3/18:LDD
389-------------------------------------------------------------------
390
391The hypoinverse archive format already includes a field for location code.
392See details of the "station archive format" in Fred Klein's documentation:
393
394ftp://ehzftp.wr.usgs.gov/klein/docs/shadow2000.pdf
395ftp://ehzftp.wr.usgs.gov/klein/hyp2000/docs/hyp2000-1.0.pdf
396
397Modules which produce and consume TYPE_HYP2000ARC messages have been modified
398to fill and read the location code field.
Note: See TracBrowser for help on using the repository browser.