pod Manual

pod (v4.x)

• pod USAGE
  • Command line parameters
  • pod Request File
  • Waveform Directories
  • Header File Directories
  • Header Files
  • Environmental Variables
• EXAMPLE USAGE
• PROGRAM FLOW
• SOURCE CODE ORGANIZATION
• Appendix A: Example Header Directory
  • Example Blockettes
• Updates and Bug Fixes

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.

pod 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 is the program name

out_volume is the file name of the output seed volume.

requests is the file name of the h. request file.

log_rec_size is the SEED logical record size (usually 4096).

phys_rec_size is the physical record size of data written.

vol_span is 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 is 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	[# 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 is 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

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.

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:

Here is the new version:

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\tNet\tCHN\tLoc\tFile start time\tFile end time\tfile name\t
stn/chn directory\trequest start\t request end\n

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