Manuals: POD

Jump to

Important Note: POD has been deprecated at the DMC and is unsupported and considered legacy code.

It has been moved to the Seiscode community repository.

NAME

pod – Program to Output Data

DESCRIPTION

pod is a program that was originally called output and was written by Mark Wiederspahn. Its function is to produce a SEED (Standard for the Exchange of Earthquake Data) volume from a set of waveform files, their associated station/channel descriptions and response information.

USAGE

pod requires five input data sources:

  1. Command line parameters.
  2. A request file.
  3. A wave form data directory.
  4. A SEED header directory.
  5. Environmental Variables

There are a number of conventions used; only one must be followed: pod assumes the structure of the Header blockette directories as described in the Header File Directories section of this manual.

Command Line Parameters

The invocation format is:

pod out_volume requests log_rec_size phys_rec_size vol_span time_span

where:

pod – the program name
out_volume – the file name of the output seed volume.
requests – the file name of the h. request file.
log_rec_size – the SEED logical record size (usually 4096).
phys_rec_size – the physical record size of data written.
vol_span – the length of the interval for this volume (yy,ddd,hh,mm,ss).

NOTE: trailing zero values need not be written (00,20 would be a span of 20 days.)

time_span – the time span that data will be broken into within the volume. The format is the same as vol_span. It is used to specify at what intervals blockette 70’s will be generated .

Error messages are written to stdout and are generally redirected to a file such as pod.out. The default used at the IRIS DMC is:

pod seed h.req 4096 32768 0, #of days 0, # of days.

POD Request File

The request file is a list of seismograms that are to be included in the SEED volume. Each record contains information that specifies a time interval and other information necessary to build the header, response and data records for the SEED volume. This request file has records as shown below. Each record is called a request record.

The following is an example of a simple request file.

KIV II BHE XX C 001 1992,050 1992,051 0000000100 0000000100 01836 II E KIV.II.BHE.92.0050 HAR000 BW 1992,050,11:34:30 1992,050,11:36:30
KIV II BHN XX C 001 1992,050 1992,051 0000000100 0000000100  01840 II E KIV.II.BHN.92.0050 HAR000 BW 1992,050,11:34:30 1992,050,11:36:30
KIV II BHZ XX C 001 1992,050 1992,051 0000000100 0000000100  01836 II E KIV.II.BHZ.92.0050 HAR000 BW 1992,050,11:34:30 1992,050,11:36:30
KIV II BHE XX C 001 1992,059 1992,059,12:00:50.7000 0000000100 000000010000920 II E KIV.II.BHE.92.059 HAR000 BW 1992,059,01:16:45 1992,059,01:18:45
KIV II BHN XX C 001 1992,059 1992,059,12:01:24 0000000100 0000000100 00920 II E KIV.II.BHN.92.059 HAR000 BW 1992,059,01:16:45 1992,059,01:18:45
KIV II BHZ XX C 001 1992,059 1992,059,12:01:37.1000 0000000100 0000000100 00920 II E KIV.II.BHE.92.059 HAR000 BW 1992,059,01:16:45 992,059,01:18:45
KIV II BHE XX C 002 1992,107 1992,108 0000000100 0000000100 01796 II E KIV.II.BHE.92.107 HAR000 BW 1992,107,14:18:50 1992,107,14:20:50
KIV II BHN XX C 002 1992,107 1992,108 0000000100 0000000100 01800 II E KIV.II.BHN.92.107 HAR000 BW 1992,107,14:18:50 1992,107,14:20:50
KIV II BHZ XX C 002 1992,107 1992,108 0000000100 000000010001796 II E KIV.II.BHZ.92.107 HAR000 BW 1992,107,14:18:50 1992,107,14:20:50

A request record has the following ascii fields, each separated from the next by an ascii tab (octal 011) character.

Description Number of characters
1. station 5
2. network 2
3. channel 3
4. location 10 although location is 2 chars, reserve 10
5. mode 1 C continuous or T triggered (Not Used)
6. number of segments 3 1 if continuous (no longer used; assumed 0)
7. start time of data file 22 SEED time format: yyyy,ddd,hh:mm:ss.tttt
8. end time of data file 22
9. start time in Unix format 10 set to 0000000100 (Not Used)
10. end time in Unix format 10 0000000100 (Not Used)
11. length of file in kbytes (k = 1024) 5 Pod prints warning if mismatched with file size
12. originating Data Collection Center (DCC) 2 (Not Used)
13. original incoming medium 1 (Not Used)
14. Channel (data records) file name 30 file name where data records can be found
15. Header directory 30 directory containing header and response information
16. initials of operator loading tape 2 (Not Used)
17. request start time that user wants 22
18. request end time that user wants 22

All fields must be there, or blank. Field widths must be exact.

Waveform Directories

Each station-channel-continuous time chunk is kept in a file that contains other time chunks from the same day. These files are grouped into directories that are named for the station.The data in the file is stored as SEED data records. The names are conventionally chosen to be able to determine which input volume and which DCC the data file came from.

pod working directory

	data_files   h.req.file(holdings file)    HAR000(header dir)
	----------   -------------------------    ------------------
	    |
------------------------
| 	| 	| 	|
KIV 	ANMO 	COL 	PFO
-------
| | | |
| | | KIV.II.BHE.1997.190
| | KIV.II.BHN.1997.190
| KIV.II.BHZ.1997.190
KIV.II.MHZ.1997.190

And similiarily for stations ANMO, COL and PFO

Header File Directories

In pod 3.0 and above, the directory structure and naming conventions look like this:

pod working directory

data_files   H.A   h.req.file(holding file)   HAR000(Header dir) 
----------   ----  ------------------------   --------------------
						KIV.II 	   BAR.II    PFO.II
						| 		     |
						----------------    -----------------
						B050  BHE  BHN 	    B050  B051  BHE ...
						| 		    |
						---------- 	    ----
						B052 B059 optional) B052

For older versions of pod (< 3.0) use this head file directory structure:

pod working directory

data_files   H.A   h.req.file(holding file)   HAR000(Header dir) 
----------   ----  ------------------------   --------------------
						SKIV## 	SBAR## 	SPFO##
						| 		|
					------------------ 	----------------------
					B050   CBHE   CBHN 	B050   B051   CBHE ...
					| 			|
					---------- 		----
					B052 B059(optional)     B052

HARxxx/ Header directory, where SEED control headers are:

xxx conventionally 000 – 999
H.A abbreviation header blockettes
B050 station blockettes 050
B051 station comments
B052 channel blockettes 052-058, 060, 061
B059 channel comments

See Appendix A for examples of file contents.

Header Files

Each file which contains SEED header blockettes is an ascii file with a UNIX line terminator, lf, at the end of each blockette. They may not, in general, be edited as some blockettes may be up to 9999 bytes in size. The B052 files are usually the only ones which have records too long for the common UNIX text editors.

Within each Header file the blockettes should be sorted by increasing effective start/end time field. This allows the effective end=NULL blockettes to be the last ones output. pod will include any blockette where the effective time crosses the request time window in the order in which such blockettes are encountered in the blockette file. Any end=NULL blockette which starts before the request window is also included. Blockettes 053-058, 060 and 061 share the acceptance of the preceding 052 blockette. Any other blockette without an effective time is always accepted (eg, abbreviation definition blockettes). See Appendix A for example blockettes.

Environmental Variables

HEADER_PATH the path name of the directory which contains the header information
DATA_PATH a list of directories separated by “:” that contain data files
CREATOR a string which supplies the organization field in blockette10 for SEED version 2.2 or greater
SEED_VERSION version number i.e. 2.0 or 2.1 or 2.2
SEEDTOLERANCE precision pod uses when computing continuity of data. Default is 20% of sample interval, otherwise what is entered (in .0001 of a second)
SEEDOUTPUTNODATA when set to anything will cause pod to output a volume with no data records, i.e. a Dataless SEED volume

EXAMPLE USAGE

Let’s say, in your pod working directory, you have a directory called data_files which holds directories of waveforms. You also have a holding file called h.req, a header directory with the H.A and directories with station/channel response information. See the Header file directories section for appropriate directory structure.

In the data_files directory we have directories of waveforms for ANMO, PFO, BAR, CCM and COL. If we run pod from the working directory we would set the environment variables to look like this:

setenv DATA_PATH data_files/ANMO:data_files/PFO:data_files/BAR:data_files/CCM:data_files/COL

The HEADER_PATH would simply be set to:

setenv HEADER_PATH HAR000 (using HAR000 as an example directory name)

Then run pod:

pod seed.example h.req 4096 32768 10,100 10,100

If you have many waveform files you could run out of environment space, as you are having to enter the directory name data_files for each file. As an alternative, which is how the DMC uses pod, run pod from the data_files directory itself:

cd data_files
setenv DATA_PATH ANMO:PFO:BAR:CCM:COL:....
setenv HEADER_PATH ../HAR000

Then to run pod enter:

pod seed.example ../h.req 4096 32768 10,100 10,100

In both examples SEED_VERSION must be set.

PROGRAM FLOW

The following psuedocode is intended to give the reader a generalized view of how the program flows. The program is generally well documented and the average programmer should be able to search out any specific questions he/she may have. 
begin
    read command line;
    read environment variables;
    initialize data structures;
    while (request lines available) begin
        if (start of new volume) begin
            output old volume ( ) begin
                make headers ( ) begin
                    make volume header;
                    make abbreviation headers;
                    make station/channel headers;
                    make channel response headers;
                    make time span headers;
                end;
                output headers;
                output time span headers;
                output data records;
            end;
            initialize volume data structure
        end;
        find requested data;
        if (start of new time span)
    end;
end;

SOURCE CODE ORGANIZATION

When you untar the pod tarfile you will get the source code organized in several directories.

Include Contains all the include files
Main Containsthe main program and some function files that are closely associated with the main processing loop
Scan_phase Contains functions used during the program phase where the data records are scanned to determine the count of data records. These counts are used to determine the time span indices
Header_phase Contains functions that build the SEED volume header records
Output_phase Contains functions that output the previously built SEED records to the SEED volume file
Utilities Contains general purpose utility functions

APPENDIX A: EXAMPLE HEADER DIRECTORY 

Example Header Directory
pod version 3.0 and greater
HAR000:
    H.A
    AFI.II
    CTAO.II
    LEM.II
    NWAO.II
    SNZO.II
    TAU.II
HAR000/AFI.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/AFI.II/LHE:
    B052
HAR000/AFI.II/LHN:
    B052
HAR000/AFI.II/LHZ:
    B052
HAR000/CTAO.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/CTAO.II/LHE:
    B052
HAR000/CTAO/LHN:
    B052
HAR000/CTAO/LHZ:
    B052
HAR000/LEM.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/LEM.II/LHE:
    B052
HAR000/LEM.II/LHN:
    B052
HAR000/LEM.II/LHZ:
    B052
    B059
HAR000/NWAO.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/NWAO.II/LHE:
    B052
HAR000/NWAO.II/LHN:
    B052
HAR000/NWAO.II/LHZ:
    B052
HAR000/SNZO.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/SNZO.II/LHE:
    B052
HAR000/SNZO.II/LHN:
    B052
HAR000/SNZO.II/LHZ:
    B052
HAR000/TAU.II:
    B050
    B051
    LHE
    LHN
    LHZ
HAR000/TAU.II/LHE:
    B052
HAR000/TAU.II/LHE:
    B052
HAR000/TAU.II/LHN:
    B052
HAR000/TAU.II/LHZ:
    B052

Example Blockettes

Following are some example blockettes. Each blockette is one line that is terminated with a newline character. The various blockettes are images of the ASCII volume control header blockette as defined in the SEED Reference Manual.

H.A
0300232Steim Integer Compression Format~000105006F1 P4 W4 D0-31 C2 R1 P8 W4 D0-31 C2~P0 
    W4 N15 S2,0,1~T0 X N0 W4 D0-31 C2~T1 N0 W1 D0-7 C2 N1 W1 D0-7 C2 N2 W1 D0-7 C2 N3 W1 
    D0-7 C2~T2 N0 W2 D0-15 C2 N1 W2 D0-15 C2~T3 N0 W4 D0-31 C2~
0300232Steim Integer Compression Format~000205006F1 P4 W4 D0-31 C2 R1 P8 W4 D0-31 C2~P0 
    W4 N15 S2,0,1~T0 X N0 W4 D0-31 C2~T1 N0 W1 D0-7 C2 N1 W1 D0-7 C2 N2 W1 D0-7 C2 N3 W1 
    D0-7 C2~T2 N0 W2 D0-15 C2 N1 W2 D0-15 C2~T3 N0 W4 D0-13 C2~
0300232Steim Integer Compression Format~000305006F1 P4 W4 D0-31 C2 R1 P8 W4 D0-31 C2~P0 
    W4 N15 S2,0,1~T0 X N0 W4 D0-31 C2~T1 N0 W1 D0-7 C2 N1 W1 D0-7 C2 N2 W1 D0-7 C2 N3 W1 
    D0-7 C2~T2 N0 W2 D0-15 C2 N1 W2 D0-15 C2~T3 N0 W4 D0-13 C2~
03100430740STime correction is unknown.~000
03100324010CChannel is down.~000
0330039001IRIS/IDA Network (UCSD/IGPP)~
0330027002IRIS-1 Prototype~
0330055003Caltech Southern, California Seismic Network~
0330055004Caltech Southern, California Seismic Network~
0330055005Caltech Southern, California Seismic Network~
0330055006Caltech Southern, California Seismic Network~
0330045007Streckeisen STS-1H/VBB Seismometer~
0330045008Streckeisen STS-1V/VBB Seismometer~
0330038009La Coste-Romberg Gravimeter~
0330045010Streckeisen STS-1V/VBB Seismometer~
0330045011Streckeisen STS-1H/VBB Seismometer~
0330045012Streckeisen STS-1V/VBB Seismometer~
0330045013Streckeisen STS-1H/VBB Seismometer~
0330045014Streckeisen STS-1H/VBB Seismometer~
0330045015Streckeisen STS-1V/VBB Seismometer~
0330045016Kinemetrics FBA-23 Low-Gain Sensor~
0330045017Kinemetrics FBA-23 Low-Gain Sensor~
0330040018Streckeisen STS-2 Seismometer~
0340044001M/S~Velocity in Meters Per Second~
0340018002V~Volts~
0340018003V~Volts~
0340032004COUNTS~Digital Counts~
0340032005COUNTS~Digital Counts~
0340062006M/S**2~Acceleration in Meters Per Second Per Second~
0340044007M/S~Velocity in Meters Per Second~
0340020008A~Amperes~
0340044009M/S~Velocity in Meters Per Second~
0340018010~Volts~
0340032011COUNTS~Digital Counts~
0340062012M/S**2~Acceleration in Meters Per Second Per Second~
0340062013M/S**2~Acceleration in Meters Per Second Per Second~
0340020014A~Amperes~

File HAR000/SGAC##/B050[13] more HAR000/SGAC##/B050
0500093GSC +35.302800-116.808300+0990.00000000Goldston, California, USA~0053210101990,201~~N

File HAR000/SGSC##/B051[14] more HAR000/SGSC##/B051
05100351991,151~1991,156~0740000000
05100351991,139~1991,158~0740000000
05100351991,118~1991,166~0740000000
05100351991,146~1991,168~0740000000
05100351991,098~1991,301~0740000000
05100351991,156~1991,173~0740000000
05100351991,156~1991,174~0740000000
05100351991,158~1991,162~0740000000

File HAR000/SGSC##/CBHE/B052 [17] more HAR000/SGSC##/CBHE/B052
0520113 BHE0000011~007008+35.302800-116.808300+0990.0000.0090.0+00.0000212 2.000E+01 
    2.000E-030000CG~1990,201~~N
0530334A01009000 3.95010E+03 2.00000E-02002 0.00000E+00 0.00000E+00 0.00000E+000.00000E+00 
    0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00004-1.23400E-02 1.23400E-02 0.00000E+00 
    0.00000E+00-1.23400E-02-1.23400E-02 0.00000E+00 0.00000E+00-3.91800E+01 4.91200E+01 
    0.00000E+00 0.00000E+00-3.91800E+01-4.91200E+01 0.00000E+00 0.00000E+00
0540408D020100000016 3.79981E+01 7.59961E-01-2.76078E+03-5.52156E+01 5.82071E+03 
    1.16414E+02-9.58113E+03-1.91623E+02 1.16618E+04 2.33236E+02-7.79824E+03
    -1.55965E+02-1.49200E+04-2.98400E+02 4.29849E+05 8.59699E+03 1.01658E+05 2.03315E+03
    -5.29201E+04-1.05840E+03 3.13166E+04 6.26333E+02-1.70699E+04-3.41398E+02 7.72151E+03 
    1.54430E+02-2.55273E+03-5.10546E+01-3.39736E+02-6.79472E+00 2.69027E+01 5.38054E-010000
058003500 1.01590E+09 2.00000E-0200

Note: All B052 files contain the corresponding B053, B054, B055 B056, B057 abd B058 blockettes. This is because the effective time for a blockette 52 is inherited by the blockettes 53 to 58 which follow. Therefore we associate the 53 through 58 blockettes with their parent blockette by putting them in the same file.

File HAR000/SGSC##/CBHZ/B059 [26] more HAR000/SGSC##/CBHZ/B059
05900471991,148,19:37~1991,158,18:30~4010000000
05900471991,148,19:37~1991,158,18:30~4010000000
05900411991,148,19:37~1991,158~4010000000
05900351991,151~1991,156~4010000000
05900471991,148,19:37~1991,158,18:30~4010000000
05900411991,156~1991,158,18:30~4010000000
05900411991,156~1991,158,18:30~4010000000
05900411991,158~1991,158,18:30~4010000000

UPDATES AND BUG FIXES

pod v 4.x

New directory structure for pod. Adding in support for location codes meant changing station/channel file/directory naming conventions. Here is the old version of the stn/chn directory:

                                      HAR000
    ----------------------------------------------------------------------------
    |        |        |        |         |          |         |        |        |
ANMO.II    BAR.G    PFO.II    CCM.IU    COL.IU    PFO.TS    DGR.IU    H.A    ISA.TS
    |                                               |
-------------------                     -------------------
B050  BHE  BHN  BHZ                     B050  BHE  BHN  BHZ

Here is the new version

                                      HAR000
    ----------------------------------------------------------------------------
    |        |        |        |         |          |         |        |        |
ANMO.II    BAR.G    PFO.II    CCM.IU    COL.IU    PFO.TS    DGR.IU    H.A    ISA.TS
    |                                               |
------------------                        --------------------------
B050  BHE.01  BHN.                        B050  BHE.  BHN.01  BHZ.02

Notice the new name for the channel directories. The location code is tagged onto the channel directory name. In the case of spaces for location codes, just the dot . is used. No trailing blanks. There is also a new request file structure. All of the fields which were no longer used are taken out. New request file example:

AAK   KN   BHE   1993,278,00:00:00    1993,278,23:51:59  AAK.KN.BHE.93.278  HAR000  1993,278,02:01:28  1993,278,02:11:44
AAK   KN   BHN   1993,278,00:00:00    1993,279,00:00:00  AAK.KN.BHN.93.278  HAR000  1993,278,02:01:28  1993,278,02:11:44
AAK   KN   BHZ   1993,278,00:00:00    1993,279,00:00:00  AAK.KN.BHZ.93.278  HAR000  1993,278,02:01:28  1993,278,02:11:44

The fields are variable tabbed delimited.

Fields Names 

Stn    Net    CHN    Loc    File start time    File end time    file name    stn/chn directory    request start    request end

New Functionality

You no longer have to specify pod waveform directories at the station detail. You can specify a umbrella data files directory which pod will scan recursively for the files it needs. This change was need to as more and more stations were added, pod was running out of environment space. Previously you invoked pod with the environment specifiying station waveform directories:

setenv DATA_PATH /data_files/SAA:/data_files/SBB/data_file/ETC

now:

setenv DATA_PATH /data_files

New environment variable:

PODJUSTDOIT

Set this to anything and pod will ignore the request file and make a seed volume out of any and all files located in its HEADER_PATH and DATA_PATH env variables.

You still need to specify a dummy request file in the pod command line for a place holder, ie.

setenv PODJUSTDOIT
pod seed.me xxxxx 4096 32768 10,100 10,100

Related Content

These other pages were tagged similarly:

  • No related content available

Categories

Tags

POD

Release date:     Modified date:

NSF SAGE Facility has been certified as a trustworthy data repository by the CoreTrustSeal Standards and Certification Board
03:53:06 v.9bc884e1