18.3 WAVETOOL, extract and convert waveform data

The program was called extract in SEISAN 7.2 and earlier. The program extracts all or selected time sections of waveform data, optionally applies some signal processing and then creates the output file(s). The input formats supported are SEISAN, SEED, MINISEED, GSE, HELMBERGER (only made by MULPLT), GURALP (one channel files) and SAC (all platforms)and output formats are SEISAN, MINISEED, GSE and SAC (all platforms)and SEED on Linux. The program can be used as a conversion program between these formats, instead of using e.g. SACSEI. It would also be possible to convert for example SAC and GSE files to SEISAN in one go. When creating GSE, MINISEED or SAC files, the respective format code is added to the filenames. The program can also extract data from a SEISAN continuous data base or a large SEED file.

File name convention for output files:

In interactive mode, the output file name is SEISAN by default since

there is no question about file name.

No output file name given: wavetool.out for SEISAN output file

wavetool.out_SEED for SEED output file

wavetool.out_MSEED for MSEED output file

wavetool.out_GSE for GSE output file

Output file name given as SEISAN: SEISAN name for SEISAN output file SEISAN_name_SEED for SEED output file SEISAN_name_MSEED for MSEED output file SEISAN_name_GSE for GSE output file

No output file name given and output format is SAC:

SEISAN_name_component_SAC

Output name given: That name is used exactly as specified. There

is no check if file exists and there is no

ending indicating format

Ouput of one channel files with SEISAN names: The channel code is added

to avoid overwrite of different channels

from the same station

Output format is SEISAN and ouput file exists: _SEI is added to file name

Note that for MINISEED writing, only Steim1 compression is used. Integer format is also possible, but requires a parameter change in WAVETOOL and recompilation.

There are two input options: (1) a single S-file or a list of S-files created with DIRF (is also an index file), which points to the waveform data or a filenr.lis type of file that gives the waveform file names; (2) a waveform file or a list of waveform files. The program can be started either interactively, without arguments, or non-interactive by specifying the commands as arguments.

Filtering: WAVETOOL only supports band pass filters hardwired to 4 poles and one pass (forwards). So if WAVETOOL is started from MULPLT to extract data as seen on the screen, the filter constants will ONLY be passed to WAVETOOL if 4 poles and band pass.

The arguments are: -sfile $<$sfile-name $>$ : The S-file name of the event you want to extract waveform data from.

-wav_files $<$file-name $>$: Extract from a list of waveform files in filenr.lis format. Input from S-file will be ignored. This option merges all files from list (if within a 'reasonable time window') and program is then partly doing what SEISEI is doing. If file-name is given as `SEISAN', then the output file name follows SEISAN convention.

-wav_in_file: input waveform file.

-maxpoints : Skip points to get approximately maxpoints

-wav_out_file $<$file-name $>$: Name of waveform output file, not used if output format is SAC.

-start $<$time $>$: Start time can be used to set start time the same for all channels instead of using chansel file, time can be absolute or relative to beginning of the first trace. Options are Start time relative earliest channnel, Abs start time string yy...s.sss for all channels.If ABS time used, string MUST contain a '.'.Abs start time string yyyymmddhhmmss (integer), used to define cont start time.

-duration $<$time $>$: Select duration of time window in seconds if -start is used.

-interactive : enable interactive mode

-cbase: name of file with selected continuous databases,all bases is default

-command_file: give arguments to wavetool in a file rather than on the command line (used by Seisweb)

-cwav: Input is from the SEISAN continuous data base, useful for extracting intervals

-cseed: Input from large SEED file, similar to -cwav -wav_in_file $<$file-name $>$: Input of one waveform file

-arc: Input from BUD or SeisComp archive.

-sfile $<$file-name $>$: Input of S-file name

-format $<$output format $>$: The output formats supported are SEISAN, SAC, GSE (GSECM6) and GSEINT. In case of SEISAN or GSE, multi-trace files including all selected traces are created, while for SAC, single trace files are generated. SEED is also possible on Linux.

-chansel $<$file-name $>$: Input file to select channels and time windows. The first line contains number of channels. The following lines give station code, start time (both absolute and relative to earliest trace allowed) and duration. If start time and duration are set to 0, complete traces are selected.

-chan_out_file: file name of file with channel description if this option is given, program terminates after writing out the file.

-chandef $<$file-name $>$: change station and/or channel names following standard also used in the conversion programs, for example:

Header line text (29 chars) ... NetCd (5 Chars), comment in next line
                                  
 chan stati  comi stato  como, In and Out definitions
             p0          HH Z
             p1          HH N
             p2          HH E

-ground : compute displacement, velocity or acceleration (1,2,3)

-seed_location: seed location code NOT USED.

-rsam: comput 1 min rsam data.

Example

Select the first three complete traces
3
1 0 0.0
2 0 0.0
3 0 0.0

Use absolute start time, and duration of 180 seconds

3
1 19991001124500.000 180
2 19991001124500.000 180
3 19991001124500.000 180

Use relative start time of 60 seconds from beginning of earliest trace, and 300 seconds duration

3
1 60 300
2 60 300
3 60 300

The program assumes that a large number is absolute time.

-chan_out_file $<$file-name $>$ : Name of text file containing a list of available channels from a list of waveform files. If wav_out_file is not specified, program terminates after creating the list.

Example

 1 KBS   BV Z  1996  6  3 20  2 18.991  6000   20.000 2666.400  299.950  
 2 LOF   S  Z  1996  6  3 20  5  5.531  5800   50.000 2832.940  115.980  
 3 MOL   S  Z  1996  6  3 20  5 24.984 10000   50.000 2852.393  199.980  
 4 FOO   S  Z  1996  6  3 20  5 34.156  9650   50.000 2861.565  192.980  
 5 HYA   S  Z  1996  6  3 20  5 36.078  9900   50.000 2863.487  197.980

-filter $<$flow $>$ $<$fhigh $>$ : bandpass filter limits

If a filter is used, a 4 pole Butterworth filter is used one way. No other filters are possible. Filter in WAVETOOL

-ground $<$1,2,3 $>$ : compute displacement, velocity or acceleration (1,2,3)

-ichan $<$id $>$ : select one channel only

-interactive : Flag to specify non-interactive use, in which case the program does not ask any questions (for example given by SEISAN-autodrm interface), default is interactive.

-seisweb : Flag to indicate that the program is started by SEISWEB.

-maxpoints $<$number $>$ : Number specifies the total number of points desired for the total time window covering all selected traces. This option is meant to reduce the number of points to what is needed to visual correctly plot the traces. When plotting the trace using a number of pixels, which is smaller than the number of points on the trace, samples are plotted on top of each other for one time sample. This results in the maximum and minimum being plotted at the same place on the x-axis. The idea now is to reduce the trace to these maxima and minima only. Then using twice the number of samples than pixels will allow to visually correctly show the trace. Note that this is not a resample routine. Option mainly used with SEISWEB.

-stat_out : write out station location file, simple xy output file (station_list.out)

-rsam : convert data to RSAM (1-minute absolute average), which is commonly used in volcano seismology

-resp_out : write out list of all response files for channels given in waveform files (respfile_list.out)

Intercative input

The interactive input has less options as the mon interactive input, however the option are as above. The questions are:

Filename of s-file or waveform file, number or filenr.lis Maximum number of points in output trace, return for all same as -maxpoints Ground motion output (dis = 1, vel = 2, acc = 3, none = return) Filter low and high, return for no filter Select all data, y=return,n If answer is n, then the following 2 questions come: Number of channels to read Channel number, start time and window

Output formats (SEISAN, GSE (def=CM6), GSEINT, SAC, MSEED) Default is SEISAN=return

Another way of extracting waveform data is using MULPLT where many traces can be extracted as a binary SEISAN file (using WAVETOOL in the background) or a single trace as an ASCII file.

Accuracy of extracted data

If the data is filtered or corrected for instrument response, the number out can be less than one and an output file of zeros can be made. If the output format is SEISAN, the values will always be scaled to avoid this and the appropriate scaling factor is included in the waveform file. Subsequently reading of these files in SEISAN will produce the correct values. For this reason, it is advised to use SEISAN as output format when filtering or correcting for instrument response. SAC data can have values less than 1.0 so only if written in SAC or SEISAN will the values be correctly represented. If a more specific combination of filters and and response removal is required (like making a Wood Anderson trace with an addtional fileter) it can only be done for one event using the MULPLT OutW option which creates an ASCII Helmerger file which then can be converted with WAVETOOL to any other format. SAC input data is checked for max values. If smnaller then 10, output will be scaled in SEISAN format. Note: Parameter MERGE_WAVFORM in SEISAN.DEF sets the network extension of extracted files.