Changes between Initial Version and Version 1 of Location_Code_Message_Changes


Ignore:
Timestamp:
01/19/12 18:22:12 (10 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Location_Code_Message_Changes

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