evalresp

EVALRESP Manual (V3.3.0)

Index

NAME
SYNOPSIS
DESCRIPTION
COMMAND-LINE PARAMETERS
WHAT IS NEW
SUPPORT OF PRESSURE DATA
FIR FILTERS
IIR FILTERS
GENERIC RESPONSE BLOCKETTES
FILTER SEQUENCE
UNEXPECTED CASES:
HOW THE PROGRAM SEARCHES FOR RESPONSES
NOTES ABOUT USAGE
LIST BLOCKETTE INTERPOLATION
EXAMPLE
SEE ALSO

NAME

evalresp - evaluate response information and output to ASCII files using rdseed V4.16 and above RESP files.

SYNOPSIS

evalresp STA_LIST CHA_LIST YYYY DAY MIN_FREQ MAX_FREQ NFREQS [-f file] [-u units] [-t time-of-day] [-s type-of-spacing] [-r resp-type] [-n network-id] [-l location-id] [-stage start [stop]] [-stdio] [-use-delay] [-il] [-ii] [-it tension] [-v]

DESCRIPTION

evalresp can be used to calculate either the complex spectral response or the frequency-amplitude-phase response for a specified station or set of stations, channel or channels, and network, for a specified date, time and frequency, using the SEED ASCII response ("RESP") files produced by the program `rdseed' as input.

The major change in this release is modified handling of delay values for FIR filter stages (details below), the new default handling is designed to allow proper response calculation for most input without prior knowledge from the user. This release will also compile in 64-bit mode if the appropriate compiler options are set in the CFLAGS environment variable, but comprehensive testing of proper operation in 64-bit mode has not been completed.

COMMAND-LINE PARAMETERS

    '-f file':    directory-name|filename
    '-u units':    'dis'|'vel'|'acc'|'def'
    '-t time-of-day':    HH:MM:SS
    '-s type-of-spacing':    log|lin
    '-r resp_type':    'ap'=amp/pha | 'cs'=complex spectra
    '-n netid':    'II'|'IU'|'G'|'*'...
    '-l locid':    '01'|'AA,AB,AC'|'A?'|'*'...
    '-stage start [stop]':    start and stop are integer stage numbers
    '-stdio':    take input from stdin, output to stdout
    '-use-delay':    use estimated delay in computation of response
    '-il':    interpolate List blockette output
    '-ii':    interpolate List blockette input
    '-it tension':    tension for List blockette interpolation
    '-v':    verbose; list parameters on stdout

WHAT IS NEW

Version 3.3.0

*MODIFIED: processing of delays in FIR stages.
Now the following rules are applied for adding delays to the FIR stages:
1) Calculation of the response for a symmetrical FIR filter ignores the delay value in the RESP;
2) Calculation of the response for an asymmetrical FIR filter uses the "correction applied" field of the RESP by default and "estimated delay" field on user request (a user should use an option -use-estimated-delay to switch this option on).
* ADDED: use CFLAGS environment variable as compiler options

Version 3.2.40

* FIXED: bug in computation time limits

* REMOVED: 2 return statements in eversp which break LIB_MODE logic

Version 3.2.39

*REMOVED: -g -Wall hardcoded flags from configure.in. Made then configurable options;

Version 3.2.38

*ADDED: new configure option --enable-log-label
When evalresp is configured with this option, most of log messages
are being prepended by a label. A label consists of [Net.Sta.Loc.Chan].

* ADDED: Return (#ifdef LIB_MODE) if input file is not found

* FIXED: Bug pointed by <alessia@sismo.u-strasbg.fr> : use
else if(!strcmp(argv[i], "-u")) instead of just if in evalresp.c:141

* Libtoolized evresp library: using libtool instead of ranlib.
Now a builder can create dynamic library, not only static

Version 3.2.35: Modified to support channel-IDs with location codes equal to an empty string.

Version 3.2.34: Added 'free()' calls to "evresp.c" to fix memory leaks when program functions used in external applications.

Version 3.2.33: Added include_HEADERS target "evr_spline.h" to "Makefile.am"; upgraded "missing" script.

Version 3.2.32: Moved 'use_delay()' function from 'evalresp.c' to 'evresp.c'; modified to close input file when a single response file is specified.

Version 3.2.31: Renamed 'regexp' functions to prevent name clashes with other libraries; restored 'depcomp' script in distribution.

Version 3.2.30: Modified to unwrap phase values before interpolation and re-wrap after (if needed); modified to detect when all requested interpolated frequencies are out of range.

Version 3.2.29: Implemented interpolation of amplitude/phase values from responses containing List blockettes (55); modified message shown when List blockette encountered; modified so as not to require characters after file contains "B052F03 Location:" and nothing after it on line; added warnings for unrecognized parameters; fixed issue where program would crash under Linux/UNIX ("segmentation fault") if input response file contained Windows-style "CR/LF" line ends.

Version 3.2.28: Modified to allow command-line parameters for frequency values to be missing.

Version 3.2.27: Added command line option -use-delay (Use estimated delay in phase computation)

Version 3.2.26: Now evalresp runs on Mac OS X.

Version 3.2.25: Processing of B55 with GAIN stage fixed. Starting with this version, added ChangeLog file.

Version 3.2.24: Added two confuration options (--enable-delay Use estimated delay in phase computation) and (--enable-phase-unwrap Unwrap phase).

Version 3.2.23: Added support for SHAPE compatible RESP files. When parsing lines that are valid RESP format, but unexpected, evalresp now skips to the next line. Added support for blank lines within and at the end of a RESP file.

Version 3.2.21: Does not terminate execution if a "Generic Response Blockette" is found in the RESP file, but prints a warning and ignores the blockette.

Version 3.2.20: Allows a user to compile and run evalresp on WIN32 platform. See the details in README file. As many other contemporary programs evalresp now supports "make install" command. A default installation directory is /usr/local, however, it can be changed during configuration phase: "./configure --prefix=/user/directory". A bug in pole-zero representations for digital stages has been fixed.

Version 3.2.19: Service release; see README in the evalresp distribution for a list of bugs fixed.

SUPPORT OF PRESSURE DATA

evalresp is able to process responses of the pressure instruments (in Passcals). Note, that the default units are assumed to be Passcals, therefore a use of "-u" option does not make an effect.

FIR FILTERS

All FIR filters are considered as having a zero phase-shift, even if they are not symmetrical and the delay correction is null. If there are 2 FIR filters in the same stage, the program assumes that both filters have the same input sample interval (in other words, the first filter has a decimation factor of 1). Typically if two FIR filters appear in the same stage, the second FIR filter is a continuation of the first. This often results when the FIR filter in question has more than 415 coefficients (which causes the length of the blockette containing the response information to exceed the "%4.4d" format of the blockette length specifier (defined by SEED). When this occurs, a second (continuation) blockette is written that contains the coefficients that would not fit in the first blockette. evalresp will handle such continuation filters by joining all FIR filters in the same stage into one large FIR filter in the order that they were scanned.

IIR FILTERS

Versions 3.2.17 and above support IIR digital filters in coefficients format with a non-zero phase shift. IIR coefficients for a single stage must fit in a single blockette.

GENERIC RESPONSE BLOCKETTES

Versions 3.2.17 and above support generic response blockette (SEED blockettes 55). Generic response blockette is a list of phases and amplitudes computed for the preselected set of frequencies. This filter type is supported only if the response input file contains blockette(s) 55 as a stage 1 and possibly channel sensitivity blockette as a stage 0. If a generic response blockette is recognized in the input, evalresp ignores the user-defined frequency sampling from the command line. The ouput, therefore, contains responses for only those frequencies which have been defined in the generic response blockette.

FILTER SEQUENCE

The program assumes that the response information consists of a series of filter stages arranged in a cascade. It is assumed that the first filter in a given stage is one of the following: (1) A Laplace-Transform or Analog pole- zero filter, (2) an IIR pole-zero filter, (3) a FIR filter (either symmetric or asymmetric), or (4) a stand-alone gain blockette that indicates the overall sensitivity of the filter sequence (a stage zero filter). Versions of evalresp 3.2.17 and higher also support (5) IIR digital coefficients filters and (6) provide limited support for Generic Response Blockette. It is further assumed that the filters will be followed by a gain blockette (except Generic Response Blockettes). If the stage is a decimation stage, then a decimation blockette will be included. This decimation blockette typically precedes the gain blockette for the stage in a SEED response file, although the order of the blockettes within a stage does not matter. If the blockettes within a stage are not in the order that evalresp expects to find them in, evalresp will rearrange them so that they appear in the "correct" order. If the response is a single stage response, evalresp will allow the user to specify an overall (stage 0) gain, rather than requiring the user to specify a stage 1 and stage 0 gain blockette (since, in this case, the stage 0 and stage 1 gains are identical).

The stage sequence number is checked by evalresp during parsing and any break in the sequence is considered to be an error. The result is that filter sequences with out of order stages are rejected as invalid responses. In addition, the output units of a stage and the input units of the next stage are compared by evalresp. If the output units of a stage do not match the input units of the next stage, the filter sequence is considered to be invalid and the response is rejected as an invalid response. The only exception to this rule are so called "gain-only" stages. Since these stages have no units associated with them, the evalresp program will skip them in determining the input units of the next stage. If a gain-only filter is found in the sequence, evalresp will scan to the next non-gain-only stage and compare the output units of the current stage with the input units of that stage. Again, a difference in the units will be considered to be an error in the filter sequence and cause that response to be rejected as invalid.

UNEXPECTED CASES:

- stand alone FIR filters (i.e. those with no sample rate and gain specified) are discarded. (Only that stage is discarded, the rest of the filter sequence is kept and used to calculate a response).
  - FIR filters which are not normalized to 1 at frequency 0 are normalized.
  - IIR coefficients filter with a stage containing more than a single blockette 54.
  - Mixing generic response stage with the other responses in a single file.

HOW THE PROGRAM SEARCHES FOR RESPONSES

If the `-f' option is specified, a determination is made as to whether the filename that follows the `-f' flag is a directory.

(1) If it is a directory, then that directory, and only that directory, is searched for files with names

like RESP.NET.STA.LOC.CHA (or RESP.NET.STA.CHA), where the NET, STA, and CHA match the user supplied
(or default) network-code, station names (from the STA_LIST), location-code, and channel names (from
the CHA_LIST).

(2) If it is not a directory, then a file with that name is used as input to the program. That file, and

only that file, will be searched for response information that matches the user's request.

(3) If the -f option is not specified, then both the current working directory and the directory pointed

to by the SEEDRESP environment variable (if it exists) are searched for response information that matches the user's request. As in the directory search (above), the filenames are constructed automatically. The files are searched starting with the local directory, so if a match is found in both the local and SEEDRESP directories, the information from the local file will be used.

(4) Because it is possible to use wildcards to specify the network-code, stations and channels that

are of interest, when the -f flag is used to pass the name of a directory to search or when the -f option is not given and the local and SEEDRESP directories are searched for matching files, all files whose names match the user's requested station, channel, and network code are searched for responses that have an effective time that includes the requested date (and time, if specified). This is necessary because there may be multiple, unique station-channel-network's that match a single input station-channel-network tuple from the user if wildcards are used. A list of all of the files that match is constructed and each is searched in turn. However, only the first matching response in each file is calculated.

If the -stdio option is given, the SEED response information is scanned from standard input and the resulting response is returned to standard output. In this case, the program will continue to search standard input for matching responses as long as it remains open (i.e. until an EOF is signaled). This allows the user to place evalresp into a pipeline of commands, or to use I/O redirection to read SEED responses from a file containing the response information.

NOTES ABOUT USAGE

(1) First, you must create an ASCII file containing the response information for the SEED volume.

For evalresp V3.0 (and later), rdseed V4.16 or later must be used to create these files. To create the files, the R option to rdseed can be specified (either on the command line or interactively). This places the response information in the SEED volume into ASCII files with names like RESP.NET.STA.CHA. Alternatively, the -d option can be specified and, by responding "yes" to the query of whether you want response files written, these same files will be extracted only for the station-channel-network tuples for which data is extracted from the SEED volume.

(2) If the file argument is a directory, that directory will be searched for RESP files of the form

RESP.NET.STA.LOC.CHA (or RESP.NET.STA.CHA).

(3) If the file argument is a file, that file is assumed to be a concatenated version of the output from

a call to rdseed with the -R option. If this is the case, then only this file will be searched for matching response information

(4) If the file argument is missing, the current directory will be searched for RESP files of the form

RESP.NET.STA.LOC.CHA or RESP.NET.STA.CHA (see "How the Program Searches for Responses", above).

(5) If the environment variable SEEDRESP exists and is the name of a directory, that directory will

also be searched for the requested files (if the -f option is not used, see "How the Program Searches for Responses", above).

i.e. if typed setenv SEEDRESP /foo/resp_dir and no file or directory is specified to search on the command line, then the current directory and the directory /foo/resp_dir will be searched for matching RESP files from which to calculate responses.

(6) The units argument is one of the following: DIS (displacement), VEL (velocity), ACC (acceleration), DEF (default units), and represents the units for which the output response

should be calculated (regardless of the units that are used to represent the response in the RESP file). If Default Units are chosen, the response is calculated in output units/input units, where these units are exactly the input units of the first stage of the response and the output units of the last stage of the response. This is a useful alternative if the units for a particular type of sensor (e.g. a pressure sensor) are not in units that can be converted to displacement, velocity, or acceleration. The default value for this argument is VEL.

(7) The time-of-day argument is in HH:MM:SS format. This is used only in the case where there is

more than one response in a given SEED volume for a given day. In that case, this argument can be used to choose one response over another according to the effective time of each. If this argument is not specified, then the first response that is found in the file that matches the requested year and day will be used. The default value for this argument is 00:00:00.0.

(8) The type-of-spacing argument is either logarithmic or linear ("log" or "lin" respectively). This

governs whether the frequencies chosen are spaced evenly between the minimum frequency and the maximum frequency in a linear or logarithmic sense. This argument defaults to a value of "log".

(9) The -v argument indicates that the user would like to receive the verbose ouput from the evalresp program. When this flag is included on the command line, diagnostic information will be

sent to standard output showing summary information of the calculated response for each station-channel-network tuple that matches the user's request. If this option is not specified, only error output will occur in the program.

(10) The -r argument indicates the response type the user desires. Available values are "cs" for

complex-spectra output and "ap" for amplitude-phase output. If the "cs" option is chosen, then the result is a set of files like SPECTRA.NET.STA..CHA (SPECTRA.NET.STA..CHA if location ID is present in the input file) that contain the frequency, real response and imaginary response (in that order). If the "ap" option is chosen, then a set of files like AMP.NET.STA..CHA (or AMP.NET.STA.LOC.CHA)
and PHASE.NET.STA..CHA (PHASE.NET.STA.LOC.CHA) are created, containing the amplitude and phase response, respectively. This argument defaults to a value of "ap".

(11) The use of wildcards is allowed in the specification of stations, channels, and networks to

search for. The first response of each station-channel-network that matches the wildcard pattern will be calculated and saved. For example, if the user requested response information from PFO 'BH?' with a network flag of -n '*', then the first response that matches the specified date for each of the broadband, high-gain channels will be returned for all of the networks that report a response for PFO. The wildcarding scheme used here is a "glob" style rather than "regular expression" style of pattern matching. The total length of the patterns used for the stations, channels, or networks is restricted to 64 characters by the program, although multiple examples can be combined in a comma separated list for the station and channel lists.

(12) The -stage argument can be used to specify a stage number or a range of stage numbers, if both

a starting and stopping stage number are included, for which to evaluate responses. For example, if this argument is included on the command line as -stage 3, then only the response of stage 3 will be calculated (ignoring all other stages). If the user wishes to calculate a response for stages 1 through 3, then the appropriate usage would be -stage 1 3. Setting the starting stage to a number less than zero will cause the default behavior to occur; evaluation of responses for all stages in a RESP file. If the number specified for a "single stage" response is higher than the number of stages in the response, no output will occur and an error message will be printed indicating why no output occurred. If a range of responses is specified that is outside of the range that is given in the RESP file, then no output will occur. Otherwise, the stages with numbers within the interval from the starting to the stopping stage will be used to calculate the response.

(13) The -stdio argument can be used to specify that input should be taken from standard input and

output should be sent to standard output. In the case where both -stdio and -v are specified, the response can be separated from the "verbose" output by splitting the standard output (which will contain the response) from the standard error (which will contain the verbose output). When this flag is defined, standard input is parsed for input responses until an EOF is found, indicating the end of the input stream of response information.

LIST BLOCKETTE INTERPOLATION

The following command-line parameters are used to enable List-blockette interploation:

-il : Specifies that the amplitude/phase values generated from responses containing List blockettes (55) are to be interpolated to correspond to the set of frequencies requested by the user. A cubic-spline interpolation algorithm is used, with a "tension" value specified via the -it parameter (see below). If any of the user-requested frequency values fall outside of the range of frequencies defined in the List blockette then the out-of-range frequencies will be "clipped" (ignored), the output will be generated for the in-range frequencies, and a warning message will be sent to the console. If a response does not contain a List blockette or if the complex-spectra response output type is selected ("-r cs") then this parameter will have no effect. If this parameter and the -ii parameter are not specified then the output for a response containing a List blockette will be generated only for the frequencies defined in the List blockette.

-ii : Specifies that the amplitude/phase values input from a response containing a List blockette (55) are to be interpolated to correspond to the set of frequencies requested by the user. The interpolated values are then processed by the program. A cubic-spline interpolation algorithm is used, with a "tension" value specified via the -it parameter (see below). If any of the user-requested frequency values fall outside of the range of frequencies defined in the List blockette then the out-of-range frequencies will be "clipped" (ignored), the values will be generated for the in-range frequencies, and a warning message will be sent to the console. If a response does not contain a List blockette then this parameter will have no effect. This parameter (rather than -il) can be useful when the complex-spectra response output type is selected ("-r cs"). If this parameter and the -il parameter are not specified then the output for a response containing a List blockette will be generated only for the frequencies defined in the List blockette.

-it : The "tension" value used by the cubic-spline interpolation algorithm (see the -il and -ii parameters). A relatively high "tension" value is desirable because it makes the interpolated values "track" closely to the original values. This parameter may be specified as a floating-point value, and its default value is 1000.0.

Note: The -il ("interpolate List-blockette output") parameter differs from the -ii ("interpolate List-blockette input") parameter in that when -il ("output") is specified the interpolation happens after the response data values have been processed by the program. When -ii ("input") is specified the List-blockette data values are interpolated before they are processed by the program. The two types of interpolation should generate results that are basically identical.

EXAMPLE

: evalresp HRV,ANMO `BHN,BHE,LH?' 1992 231 0.001 10 100 -f /home/RESP/NEW -t 12:31:04 -v

The quotes in this command are required to prevent the shell from expanding the `?' character before passing it into evalresp. If the RESP files for HRV and ANMO are contained in the directory `/home/RESP/NEW', then this example will output eight files, called:

AMP.IU.HRV..BHE, PHASE.IU.HRV..BHE, AMP.IU.HRV..BHN, PHASE.IU.HRV..BHN
and
AMP.IU.ANMO..BHE, PHASE.IU.ANMO..BHE, AMP.IU.ANMO..BHN, PHASE.IU.ANMO..BHN

for the HRV and ANMO BHE and BHN channels. A corresponding set of files would be output for the ANMO broadband channels and for all the HRV and ANMO long-period high-gain channels in the directory `/home/RESP/NEW'. These files contain the amplitude and phase information, respectively.

These can be used as input for graph or SAC. For example, take the amplitude file and try this:

graph < HRV.BHE.IU.AMP | xtek