Instrumental Software Technologies, Inc.

JEvalResp Manual
(for Version 1.78)




Introduction

     JEvalResp is a Java version of the 'evalresp' program and, like the original, it is designed to evaluate the response information from ASCII "RESP" files generated by rdseed (V4.16 and above).  JEvalResp is also capable of fetching and processing responses from web-services servers.  The program searches for one or more responses that match a user-specified station (or set of stations), channel (or set of channels), network and date/time value.  The output of the responses is then calculated for a user-specified set of frequencies, resulting in a list of amplitude/phase or complex-spectra values (written to output files).
     The parameter usage is very similar the original 'evalresp' program:

JEvalResp STA_LIST CHA_LIST YYYY DAY MIN_FREQ MAX_FREQ NFREQS [-f file] [-p server_properties] [-u units] [-t time_of_day] [-s type_of_spacing] [-r resp_type] [-n network_code] [-l location_id] [-stage start [stop]] [-m] [-ms] [-ey end_year] [-ed end_day] [-et end_time] [-h] [-v] [-stdio][-o output_directory] [-ver]

     This Java version of the program makes use of certain classes defined in the FISSURES framework, and in general provides greater portability and reusability of the code.



Installing JEvalResp

     The JEvalResp distribution is available in archived form as a "tar.gz" or ".zip" file, or as an executable installer that inactively guides the user through the installation.  The following files and directories should be installed:

JEvalResp.jar - Java archive file containing the classes for the program.
JEvalResp - Unix script for launching the program via the "JEvalResp" command.
JEvalResp0 - Alternate version of the Unix launching script (doesn't use "which").
JEvalResp.exe - Windows executable for launching via the "JEvalResp" command.
irisws.prop - Properties file for the web-services server at the IRIS DMC.
ncedcws.prop - Properties file for the web-services server at the NCEDC/Berkley.
irisncedcws.prop
- Properties file for the two specified web-services servers.
testnetws - Simple test of access to web-services server (Unix).
testnetws.bat - Simple test of access to web-services server (Windows).
JEvalRespf.jar - Files-only version of the program (no FISSURES net support).
JEvalRespClasses.jar - Classes minus those from FISSURES and ORBacus.
jc - Unix script for launching using "JEvalRespClasses.jar".
jc.bat - Windows batch file for launching using "JEvalRespClasses.jar".
src.jar - Java archive of source code files.
jars/ - Miscellaneous Java archives used by the source code.
javadocs/ - Source code documentation generated via 'javadoc'.
JEvalResp.html - A copy of this documentation.

     After installation, it can useful to configure the target system so that the program may be executed from any directory by simply entering the 'JEvalResp' command.  This may be accomplished as follows:

Under Unix:
     The 'JEvalResp' script uses the "which" command to determine its current directory, and thus the location of the 'JEvalResp.jar' file.  (For this to work, the files must be in the same directory.)  To enable the 'JEvalResp' command to work from any directory, the path to the 'JEvalResp' directory can be added to the system PATH environment variable, using a command like one of the following:
   PATH=path-to-JEvalResp-dir:$PATH
     or
   setenv PATH path-to-JEvalResp-dir:$PATH
To make the change permanent, the command should be added to the ".cshrc" or ".bashrc" file that is executed at login.  An "export PATH" command may also need to be added.  Alternately, a copy of the 'JEvalResp' script file could be created and edited with "path-to-JEvalResp-dir/JEvalResp.jar" replacing "`which JEvalResp`.jar", and then placed in a directory that is already in the system PATH.

Under Windows:
     The "JEvalResp.exe" executable file is able to determine its current directory, and thus the location of the 'JEvalResp.jar' file.  (For this to work, the files must be in the same directory.)  To enable the 'JEvalResp' command to work from any directory, the path to the 'JEvalResp' directory can be added to the PATH environment variable, using a command like the following:
   PATH=path-to-JEvalResp-dir;%PATH%
To make the change permanent, the command may added to the AUTOEXEC.BAT file (usually at "C:\"), or the PATH settings may altered in the operating system's configuration windows.



Running JEvalResp / Requirements

     Use of JEvalResp requires that a Java Version Machine (JVM) version 1.5 or higher be available on the host system.  An installable version of the Java Runtime Environment (JRE) containing the latest JVM may be downloaded from Sun.  A command like the following may be used to start the program:

java -jar JEvalResp.jar [parameters]

     The file "JEvalResp.jar" must be available in the local directory, or the pathname to the file must be provided.  Script and executable launcher files (e.g. "JEvalResp") that allow the program to be started with just the command "JEvalResp [parameters]" are provided with the distribution.

     The program supports searching the directory pointed to by the "SEEDRESP" environment variable, but in order for this support to work, the contents of the variable must be passed to the Java environment when the program is started, like this:

For Unix:
java -DSEEDRESP=$SEEDRESP -jar JEvalResp.jar [parameters]

For Windows:
java -DSEEDRESP="%SEEDRESP%" -jar JEvalResp.jar [parameters]

     The provided JEvalResp script and executable files are already setup to support passing the "SEEDRESP" environment variable.



Command-Line Parameters

     Running the program with no command-line parameters will display help information like the following:

JEvalResp, Version #.## parameters:
 stationList channelList year julianDay minFreq maxFreq numFreqs [options]
JEvalResp options:
 -f                    --fileName         File and directory names to use
 -p                    --propsFile        Properties file for network server
 -u                    --outUnitsConv     Output units conversion (def|dis|vel|acc)
 -t                    --timeOfDay        Requested time of day (HH:MM:SS)
 -s                    --typeOfSpacing    Type of freq. spacing (log|lin)
 -n                    --networkId        Requested network ID(s)
 -l                    --locationId       Requested location ID(s)
 -r                    --responseType     Type of response output (ap|cs|ap2|fap)
 -stage                --stageNumbers     Start & stop stage #'s (1 or 2 values)
 -stdio                --stdioFlag        Use 'stdio' for I/O
 -m                    --multiOutFlag     Enable outputs with same net.sta.loc.cha
 -ms                   --multiSvrFlag     Fetch from multiple web servers
 -ey                   --endYear          Year value for end of time range
 -ed                   --endDay           Julian day value for end of time range
 -et                   --endTime          Time-of-day value for end of time range
 -h                    --headerFlag       Enable header info in output file(s)
 -v                    --verboseFlag      Send verbose messages to 'stderr'
 -o                    --outputDirectory  Output directory for generated files
 -use-estimated-delay  --useDelay         Use estimated delay in FIR_ASYM calc
 -i                    --showInputFlag    Show RESP input text
 -il                   --interpListFlag   Interpolate List blockette output
 -ii                   --interpInputFlag  Interpolate List blockette input
 -it                   --interpTension    Tension for List blockette interpolation
 -unwrap               --unwrapPhaseFlag  Unwrap phase output values
 -ts                   --totalSensitFlag  Use stage 0 (total) sensitivity
 -b62_x                --b62XValue        Sample value for polynomial blockette
 -ver                  --version          Show program version information

     The switch parameters (with one or two leading dashes) may be given in any order, and each has two versions, either of which may be used.  The command-line parameters are described as follows:

stationList : A comma-separated list of station names to be matched when searching for responses.  The wildcard characters '*' and '?' (glob-style) may be used.

channelList : A comma-separated list of channel names to be matched when searching for responses.  The wildcard characters '*' and '?' (glob-style) may be used.

year : A numeric year value used to specify a date to be matched.  If an end-date/time is given (via the parameters "-ey", "-ed" and "-et") then the specified date is treated as the beginning of a date-range that must intersect the range of dates found in matching responses.  If no end-date/time is given then the specified date is treated as a single date that must be within the range of dates found in matching responses.  A single asterisk ('*') may be given to specify "all dates".

julianDay : A numeric Julian day-of-the-year value that is added to the year parameter to specify a date to be matched.  The first day of the year has a value of '1'.  A single asterisk ('*') may be given, which will specify "all dates" (if year='*') or the value '1' (if a year value is given).

minFreq : The minimum value for the range of frequency values used when calculating response output numbers.  Note that the type-of-spacing parameter ("-s") specifies how the values are generated.

maxFreq : The maximum value for the range of frequency values used when calculating response output numbers.  Note that the type-of-spacing parameter ("-s") specifies how the values are generated.

numFreqs : The number of frequency values to be included in the range of frequency values used when calculating response output numbers.  Note that the type-of-spacing parameter ("-s") specifies how the values are generated.

-f  : The names of one or more files to search for responses, the names of one or more directories to search for response files, or any combination of the two.  The file names may contain the wildcard characters '*' and '?' (glob-style).  When a given name contains a path, the path is also used for any proceeding file names that do not have a path.  If no paths are given then the local directory is used.  For Unix systems the colon character (':') is used to separate the names, for Windows systems the semicolon (';') is used.
     A URL to a remote input file may also be specified.  The URL should
start with "http://" or "ftp://".  When a URL is specified, wildcard characters are not allowed.
     If this parameter is not given then the local directory and the directory specified by the "SEEDRESP" environment variable are searched for matching response files.  This parameter may not be specified with the "-p" parameter.


-p  : This parameter may be used to specify the information needed to locate a network server.  If the name of a properties file is given then its contents are used.  The "irisws.prop" file provided with this distribution will locate the IRIS DMC web-services server.  Alternately, the URL of a web-services server may be specified directly (i.e., "-p http://service.iris.edu/irisws/resp/1").  When this parameter is specified, a network connection will be opened to the server and used to fetch responses (instead of using input files).  This parameter may not be specified with the "-f" parameter.  Multiple web-services servers may also be specified.  For more information, see the "Network Access to Servers" section.

-u  : The output units conversion parameter, which may be set to one of the following values:  dis (displacement), vel (velocity), acc (acceleration) or def (default); 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 ("def") 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 parameter is "vel".

-t  : A time-of-day value, in HH:MM:SS format, to be included when specifying a date to be matched.  (See the year parameter for a description of how the specified date is treated.)  This parameter can be useful when greater accuracy in the date specification is needed.  When a date is specified (via year and julianDay) with this parameter not given, a time-of-day value of 00:00:00 is used.

-s  : The type-of-frequency-spacing may be set to one of the following values:  log (logarithmic) or lin (linear); and represents the type of spacing used when generating the set of frequencies specified by the "minFreq", "maxFreq" and "numFreqs" parameters.  The default value for this parameter is "log".

-n  : The network name(s) to be matched when searching for responses.  The parameter may be set to a single name or a comma-separated list of names.

-l  : The location ID name(s) to be matched when searching for responses.  The parameter may be set to a single name or a comma-separated list of names, any of which may include the wildcard characters '*' and '?' (glob-style).  Omitting the location value will act the same as the match-all wildcard character ('*'), and specifying "--" will act as an empty location code.

-r  : Selects the type of response output values to be generated; set to one of the following values:  ap (Amplitude/Phase, 2 output files), cs (Complex-Spectra), ap2 (Amplitude/Phase2, single output file), or fap (fAmplitude/Phase, single output file).
     If Amplitude/Phase ("ap") is chosen then sets of files like AMP.NET.STA.LOC.CHA and PHASE.NET.STA.LOC.CHA are created, containing the calculated amplitude and phase response output values.  If Complex-Spectra ("cs") is chosen then files like SPECTRA.NET.STA.LOC.CHA are created, containing the calculated "real" and "imaginary" response output values.  If Amplitude/Phase2 ("ap2") is chosen then files like AP.NET.STA.LOC.CHA are created, containing both the calculated amplitude and phase response output values.  If fAmplitude/Phase ("fap") is chosen then files like FAP.NET.STA.LOC.CHA are created, containing both the calculated amplitude and phase response output values (and the generated phase values are "unwrapped"; see the '-unwrap' parameter).
     The default value for this parameter is "ap".  See the Output File Formats section for details on the contents of these files.


-stage :  One or two numeric values, used to select a stage or range of stages to be processed in the response.  A single value selects a single stage, while two values specify a range of stages to be processed.

-stdio : Specifies that input should be taken from standard input stream and output should be sent to standard output stream.  In the case where both "-stdio" and "-v" are specified, the response output can be separated from the "verbose" messages by splitting the standard output stream (which will contain the response output) from the standard error stream (which will contain the verbose messages). When this flag is defined, the standard input stream is parsed for input responses until an EOF is found, indicating the end of the input stream of response information.  Note that after the first matching response is received and processed, all other response data will be ignored.

-m : Specifying this parameter will enable the generation of more than one output from responses with the same network/station/channel/location ("net.sta.loc.cha") code, and all generated output files will have a date/time code appended to their filenames (e.g. "AMP.XX.RUB03.01.BHE.1996.151.13.06.22").  When this parameter is not specified, only one output will be generated for any given "net.sta.loc.cha" code.

-ms : When this parameter is specified and multiple web-services servers are available (via the '-p' parameter), the program will attempt to fetch and process matching responses from all the specified servers.  When this parameter is not specified, only the first matching response will be fetched and processed.  Anytime this parameter is specified the host address of the source web-services server will be appended to the filename of the generated output files (e.g.,
"AMP.XX.RUB03.01.BHE_www.iris.edu").

-ey : A numeric year value used to specify the end-date/time of a date-range that must intersect the range of dates found in matching responses.  The begin-date/time is specified via the year, julianDay and -t parameters.

-ed : A numeric Julian day-of-the-year value that is added to the -ey parameter value to specify the end-date/time of a date-range that must intersect the range of dates found in matching responses.  The first day of the year has a value of '1'.  The begin-date/time is specified via the year, julianDay and -t parameters.

-et  : A time-of-day value, in HH:MM:SS format, to be included when specifying the end-date/time of a date-range that must intersect the range of dates found in matching responses.  This parameter can be useful when greater accuracy in the end-date/time specification is needed.  The begin-date/time is specified via the year, julianDay and -t parameters.  When an end-date/time is specified (via -ey and -ed) with this parameter not given, a time-of-day value of 00:00:00 is used.

-h  : Enables the inclusion of header information in the generated output files.  The information includes items such as station identification, frequencies used and time created.  Each header line begins with a "pound" character ('#').

-v  : Specifies that verbose messages should sent (to the standard error stream) showing summary information about the matching responses, including units, sensitivity, delay, corrections and stage-type information.  If this parameter is not specified, only error output will be sent by the program.

-o  : The output directory into which generated files are saved.  If this parameter is not given then the current directory is used.

-use-estimated-delay  : Specifies that estimated delay is to be used with calculations on asymmetrical FIR filters; otherwise the correction-applied value will be used with calculations on asymmetrical FIR filters.

-i : Specifies that a RESP-text representation of the response input should be sent to the console (via 'stdout').  This can be useful when the source of the response data is a network server.

-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.
     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.

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

-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.

-unwrap : Specifies that generated phase values should be "unwrapped".  Phase values are "wrapped" by adding +/-360 to portions of the dataset to make all the values be between -180 and +180 (inclusive).  Phase values are "unwrapped" by detecting transitions where the dataset has been "wrapped" and adding +/-360 to restore the "original" values.  When phase values are unwrapped, if the first phase value is negative then 360 will be added to make it a positive value.

-ts : Specifies that the stage 0 (total) sensitivity should be used instead of the product of the stage gains.  This can be utilized in combination with the '-stage' parameter to provide a full scale response.  For instance, using just stage 1 (the sensor) with a correct system gain (i.e., SAC Poles and Zeros).

-b62_x : Sample value for polynomial blockette.  See the "
Polynomial Response (Non-Linear) Blockette 62" notes below.

-ver : Causes the program to display a line of version information and exit.

Notes on command-line parameters:
    When wildcard characters ('*' and '?') are included in a command-line parameter, the parameter may need to be surrounded by quote characters to prevent the operating system from expanding the wildcards into filenames.  (Under Windows, the "JEvalResp.exe" launcher file provided with the distribution will automatically surround all parameters with quotes.)
     If any of the "minFreq", "maxFreq" and "numFreqs" parameters are not provided, they will default to a value of '1'.  Thus, if none of them are provided, the resulting range will be the single frequency value '1.0'.
     If any of the "stationList",  "channelList",  "year", and "julianDay" parameters are not provided, they will default to a value of "*", translating to "match any".  Thus, if none of them are provided then any station name, channel name and date value in a response will result in a match.



How the Program Searches for Responses

     For each name specified via the filename parameter ("-f"), a determination is made as to whether the name references a file or a directory.
     If it is a directory, then that directory is searched for files with names like RESP.NET.STA.CHA and RESP.NET.STA.LOC.CHA, where NET, STA, LOC and CHA match the user supplied (or default) network-code, station names (from the STA_LIST), location ID and channel names (from the CHA_LIST).
     If it is not a directory, then a file with that name is used as the input to the program, to be searched for a single response that matches the user's request.

     If the filename parameter ("-f") is not specified, then both the local 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 described 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.

     Because it is possible to use wildcards to specify the network-code, stations and channels that are of interest, when 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 codes 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.  Unless the multi-output flag parameter ("-m") is specified, only the first matching response in each file is calculated (or, when retrieving responses from a network server, the matching response with the latest date).

     If the stdio-flag parameter ("-stdio") is given, the response information is scanned from the standard input stream and the resulting response output is sent to the standard output stream.  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 the program into a pipeline of commands, or to use I/O redirection to read responses from a file containing the response information.



Response Parsing Notes

Filter Sequence:
     The program expects the response information to consist of a series of filter stages arranged in a cascade, and that the first filter in a given stage is always 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),
(4) a stand-alone gain blockette that indicates the overall sensitivity of the filter sequence (a stage 0 filter),
(5) a stand-alone gain blockette (gain-only stage),
(6) an IIR digital coefficients filters or
(7) a Response List blockette (#55).
(8) a Generic Response blockette (#56).
     It is further expected that each filter will be followed by a gain blockette (except for a List Response blockette, or for a single stage response, in which case an overall (stage 0) gain may be the only one).
     The stage sequence numbers are checked during parsing and any break in the sequence is not allowed.  In addition, if the output units conversion parameter ("-u") is not set to default ("def") then the output units of a stage and the input units of the next stage are compared, and if they do not match then the filter sequence is considered to be invalid.

SEED Filter Coefficients and Stage Delay Correction:
     As of July 2007 the SEED standard was clarified to require that digital filter coefficients are to be listed in forward order.  For a mathematical description, see the SEED manual.  As a reference, minimum-phase filters (which are asymmetric) should be written with the largest values near the beginning of the coefficients list.  Additionally, the sign convention for the estimated delay and correction applied values specified in Blockette 57 for a given stage were clarified.  In almost all cases both the estimated delay and correction applied should be positive values and very nearly the same value (if not exactly the same value).
     Proper evaluation of responses requires that the above conventions be followed.  Evaluating SEED response descriptions that do not follow the conventions will likely result in improper results.  Furthermore, applying these results to time series data can result in either obvious, or more problematic, subtle data modifications.

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 two FIR filters in the same stage, the program expects that the second FIR filter is a continuation of the first.

IIR Filters:
     Support is provided for IIR digital filters in coefficients format with a non-zero phase shift.

Pressure, Magnetic Density Flux Data and Temperature:
     The program is able to process responses with pressure units (in pascals), magnetic density flux units (in teslas) and temperature (in C) for input. When these units are used, the output units conversion parameter ("-u") is ignored.

Response List Blockettes:
     The Response List blockette (#55) contains a list of phase and amplitude values computed for a preselected set of frequencies.  This filter type is supported only if the response contains a single Response List blockette and possibly a stage 0 channel sensitivity blockette.  When a Response List blockette is processed in the input, the user-defined frequency range from the command line is ignored, and the response ouput is calculated for the set of frequencies defined in the Response List blockette.

Decimation Blockette:
     By default JEvalResp uses correction_applied (field 9 of B57) minus calculated_delay to compute the delay introduced by an asymmetrical FIR filter (delay is set to 0 for all other cases).  There are some historical responses where the correction_applied value is set incorrectly.  In these cases specifying the command-line parameter '-use-estimate-delay' will have the delay computed as estimated_delay (field 7 of B57).

Polynomial Response (Non-Linear) Blockette 62:
     In general, Blockette 62 cannot be represented as a Fourier response because it is intrinsically non-linear.  See, for example, p28 of Bendat & Piersol, where they explicitly state that Fourier analysis is done on the assumption of a linear system (as defined p26).  But there are two exceptions.
     First, the polynomial may be linear (have only two terms, y = a x + b).  In that case, it is (by definition) linear and can be treated as an offset ("a", ignored by the Fourier response) and gain ("b", the slope, independent of frequency).  Note that the amplitude response is always positive (abs(b)); the phase will be zero if the slope of the curve is positive (b>0) and 180 degrees if negative (b<0).
     Second, the user may have a signal that uses some part of the (non-linear) response curve that is sufficiently small (for the accuracy they require) that it can be treated as linear in that region.  In this case we use a tangent (first order Taylor expansion) of the polynomial at the given point (and then treat that as the linear case above).
     For a polynomial f(x) = a0 + a1 x + a2 x^2 + ... an x^n the slope at x is f'(x) where f' = a1 + 2 a2 x + 3 a3 x^2 ... n an x^(n\-1).  So the recipe to calculate the gain (b) at a given x is:  sum(i=1 to n)  i * ai * x^(i\-1)
     The value for 'x' in the equation above may be specified using the command-line parameter '-b62_x'.  This value is assumed to be in digital counts if B62 is the only blockette of the response, or volts if B62 is the part of the cascade.  The results of the processing (response amplitude) depends on the value specified.

Generic Response Blockettes:
     Generic Response blockettes (#56) are accepted and parsed, but any "corner" data values that they contain are ignored.



Network Access to Servers

     When the "-p" (properties file) parameter is given, a network connection will be opened to a server and used to fetch responses (instead of using input files).  The following types of network servers may be accessed:

Web-Services Server:

     The following properties files are provided with this distribution:

irisws.prop - Properties file for the web-services server at the IRIS DMC.
ncedcws.prop - Properties file for the web-services server at the NCEDC/Berkley.
irisncedcws.prop - Properties file for the two specified web-services servers.

     The web-services properties file should contain one or more server URLs (i.e., http://service.iris.edu/irisws/resp/1).  If multiple URLs are specified, they should be placed on separate lines (see "irisncedcws.prop" for an example).

     Alternately, one or more web-services URLs may be specified directly with the "-p" parameter, with each URL separated by a comma, semicolon or space (e.g., "-p http://service.iris.edu/irisws/resp/1,http://service.ncedc.org/ncedcws/resp/1").

     See the description of the '-ms' parameter for information on how multiple web-services servers are used.

     For web-services queries, station and network names must both be provided and may not contain wildcard characters ('*' and '?').  The channel and location values may contain wildcard characters.  Omitting the location value will act the same as the match-all wildcard character ('*'), and specifying "--" will act as an empty location code.

     The provided script file "testnetws" (or "testnetws.bat") may be executed to perform a simple test-fetching and processing of a response from the IRIS-DMC web-services server.  If successful, a set of output messages for the station 'ANMO.BHZ.IU' will be shown and the files "AMP.IU.ANMO..BHZ" and "PHASE.IU.ANMO..BHZ" will be created.




Output File Formats

     All output data is written as ASCII text, with numeric values in "exponential" format and seven significant digits before the exponent (e.g. "1.000000E+00").

     If the stdio-flag parameter ("-stdio") is not given then the output of the program is sent to one or more files using the following formats:

Amplitude/Phase (response type ("-r") set to "ap"):
     For each matching response, two files are written; one for amplitude data (with its filename beginning with "AMP.") and one for phase data (with its filename beginning with "PHASE.").  For each value in the range of frequency values, a line is written containing the frequency value, a space character, and then the corresponding amplitude or phase output value.

Complex-Spectra (response type ("-r") set to "cs"):
     For each matching response, one file is written (with its filename beginning with "SPECTRA.").  For each value in the range of frequency values, a line is written containing the frequency value, a space character, the "real" part of the corresponding complex-spectra output value, a space character, and then the "imaginary" part of the corresponding complex-spectra output value.

Amplitude/Phase2 or fAmplitude/Phase (response type ("-r") set to "ap2" or "fap"):
     For each matching response, one file is written (with its filename beginning with "AP." if "ap2" or "FAP." if "fap").  For each value in the range of frequency values, a line is written containing the frequency value, a space character, the corresponding amplitude output value, a space character, and then the corresponding phase output value.

     If the stdio-flag parameter ("-stdio") is given then the output of the program is sent to the standard output stream using the following formats:

Amplitude/Phase (response type ("-r") set to "ap", "ap2" or "fap"):
     The output begins with a header like this one:
--------------------------------------------------
AMP/PHS.NET.STA.LOC.CHA
--------------------------------------------------
where the NET.STA.LOC.CHA values are the network, station, location and channel codes for the matching response.  Following that, for each value in the range of frequency values, a line is output containing the frequency value, a space character, the corresponding amplitude value, a space character, and then the corresponding phase value.

Complex-Spectra (response type ("-r") set to "cs"):
     The output begins with a header like this one:
--------------------------------------------------
SPECTRA.NET.STA.LOC.CHA
--------------------------------------------------
where the NET.STA.LOC.CHA values are the network, station, location and channel codes for the matching response.  Following that, for each value in the range of frequency values, a line is output containing the frequency value, a space character, the "real" part of the corresponding complex-spectra output value, a space character, and then the "imaginary" part of the corresponding complex-spectra output value.



Examples

     The following shows several example sets of parameters for the program:

For Unix:
JEvalResp HRV,ANMO 'BHN,BHE,LH?' 1992 231 0.001 10 100 -f /home/RESP/NEW -t 12:31:04 -v
JEvalResp ANMO,ANTO 'BH?' 1996 100 0.01 10 10 -n IU -v -p irisws.prop
JEvalResp ANMO BHZ 2011 100 0.01 10 10 -l 00 -n IU -v -p http://service.iris.edu/irisws/resp/1

For Windows:
JEvalResp HRV,ANMO "BHN,BHE,LH?" 1992 231 0.001 10 100 -f /home/RESP/NEW -t 12:31:04 -v
JEvalResp ANMO,ANTO "BH?" 1996 100 0.01 10 10 -n IU -v -p irisws.prop
JEvalResp ANMO BHZ 2011 100 0.01 10 10 -l 00 -n IU -v -p http://service.iris.edu/irisws/resp/1

The quotes in the commands are required to prevent the operating system from expanding the '?' character before passing it into the program.
     If the RESP files for HRV and ANMO are contained in the directory '/home/RESP/NEW' then the examples containing the "-f" parameter will output the following eight files for the HRV and ANMO BHE and BHN channels:  "AMP.IU.HRV.BHE", "PHASE.IU.HRV.BHE", "AMP.IU.HRV.BHN", "PHASE.IU.HRV.BHN", "AMP.IU.ANMO.BHE", "PHASE.IU.ANMO.BHE", "AMP.IU.ANMO.BHN", "PHASE.IU.ANMO.BHN"
     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.  These files contain the amplitude and phase information and can be used as the input for graphing or SAC.  For example, one could take the amplitude file and try this:  graph < AMP.HRV.BHE.IU | xtek



Source Code Notes

     The basic set of JEvalResp Java source code files resides in the "src" and "filesrc" subdirectories of "src.jar" archive included in the distribution.  The program also uses class files from the "jars/isti.util.jar" and "jars/gnu-regexp-1.1.3.jar" archives, as well as class files from the "FissuresIDL.jar" and "FissuresImpl.jar" archives (which may be downloaded from the FISSURES homepage), and the ORBacus v4.0.5 archives "OB.jar" and "OBNaming.jar".
     The source code documentation, generated by running "javadoc" on the source code files, is available in the "javadocs" directory of the distribution.
     For the program to run under Java 1.2 the class files from the "jars/RespCORBAStub.jar" archive are needed to substitute for some of the dependencies in the FISSURES files for classes in CORBA, which is not used by JEvalResp.  Under Java 1.3 this is not a problem.
     In the distibution, the "JEvalResp.jar" archive contains the complete set of class files needed to run the program.  The "JEvalRespClasses.jar" archive contains a similar set, minus the class files from FISSURES and ORBacus archives.  The "JEvalRespf.jar" archive contains a version of the program that only supports reading responses from input files (no FISSURES server support).
     The major classes in the program are:
RespFileParser - Parses ASCII response ("RESP") files into FISSURES response objects.
OutputGenerator - Processes and outputs data from FISSURES response objects.
Run / RespProcessor - The "front-end" to handle command-line parameters.
RespNetProc - Provides methods for accessing FISSURES network servers.
     The parts are made to be modular, to allow, for instance, the parser or output-generator to be used separately, or to have the methods used in a separate program.

     There is also extensive support for 'C'-code native-language interfacing to the Java classes used in the program.  The files involved in this are in the "c" directory of the "src.jar" archive, and they include:
startJVM.c - Functions for starting an instance of the Java Virtual Machine.
jevresp.c - Functions for processing responses via the JEvalResp Java classes.
jevresp.h - Header file for "jevresp.c".
evalresp/evresp.h - Header file from 'evalresp' (needed to define structures).
jevtest.c - Simple test program that uses "jevresp.c".
compile.sh - Unix script for compiling the "evalrespj" executable.
compile_jevtest.sh - Unix script for compiling the "jevresp" test program.
compile_fortran.sh - Unix script for compiling the "evalrespf" FORTRAN test program.
run.sh - Unix script for running the "evalrespj" executable.
run_jevtest.sh - Unix script for running the "jevresp" test program.
run_fortran.sh - Unix script for running the "evalrespf" FORTRAN test program.
evalrespj.exe - Windows executable of "evalrespj".
jevtest.exe - Windows executable of "jevtest".
setcp.bat - Sets up a 'jevresp' classpath to include the "JEvalResp.jar" archive.
setjvmpath.bat - Adds standard JVM library locations to system PATH.
jevresp.dll - Windows DLL library version of the "jevresp.c" and "startJVM.c" functions.
jevresp.lib - Borland C++ compatible "lib" file for "jevresp.dll".
jevresp.ide - Borland project file for compiling all the source.
msevj.bat - Windows batch file for compiling "evalrespj" with Microsoft C.
msjevtest.bat - Windows batch file for compiling "jevtest" with Microsoft C.
     To compile and run these files, there must be access to the Java Virtual Machine 'C'-language library files via the library search path mechanism of the operating system.  The sample Unix scripts are for a Linux PC under Java 1.3, with the "JAVA_HOME" environment variable set to the location of the Java installation.  Other configurations may require changes to the library paths.
     Under Windows, the sample "msevj.bat" and "msjevtest.bat" batch files are configured to work with Microsoft C.  The "setcp.bat" and "setjvmpath.bat" batch files attempt to setup the environment to allow the executable files to run.

     The interface into the Java code is the "RunBlks" class, which contains methods that deal with an array of response objects.  In "jevresp.c" are exact substitutes for the 'evresp()' and 'print_fncts()' functions that were in 'evalresp's "evresp.c".  This allows for the possibility of interfacing in the same way as one would to the original 'evalresp'.
     The "evalrespj" executable uses the "front-end" of source files from the original 'evalresp' to handle parameter processing, and then uses "jevresp.c" and the JEvalResp Java classes to do all the processing.  The 'evalresp' source files used are in the "c/evalresp" directory (none had to be modified).
     Support for the FORTRAN interface in the original 'evalresp' is preserved in the "evalresp/evresp_.c" file, which contains the "evresp_()" function extracted from the original 'evalresp' "evresp.c" file.  The sample "evalrespf.f" file is a test program that has the following parameters hard-coded:  "ANMO BHZ 1990 1 .001 100 100 -f ../../test/RESP.IU.ANMO..BHZ".  It may be used as a template for other programs.
     The "Launcher" subdirectory contains the 'C' code used to create the "JEvalResp.exe" Windows executable file that launches the program via the 'JEvalResp.jar' file.  The code can be compiled under other operating systems to create similar native executables.

Revision History Notes

  8/26/2014 -- Version 1.78:  Modified to properly handle location value of "--" (meaning location code empty).

  4/11/2014 -- Version 1.77:  Updated web-service URLs in '.prop' files.

  10/29/2013 -- Version 1.76:

  4/3/2012 -- Version 1.75:  Added support for specification of multiple web-services-server URLs; added support for '-ms' ('--multiSvrFlag') parameter.

  1/30/2012 -- Version 1.7:  Added support for network access to web-services servers; fixed bug where site/location parameters were not properly processed when finding local RESP input files.

  8/6/2010 -- Version 1.6:

  11/10/2009 -- Version 1.59:  Added 'RunDirect' class for support of input and output via method calls for processing a single response.

  5/31/2007 -- Version 1.57:  Modified to check if any FIR coefficients filter should be normalized to 1.0 at frequency zero and adjust the filter values if so.

  8/23/2006 -- Version 1.56:  Modified to support 'tesla' units; modified to make sure that if input units are 'pascal' or 'tesla' then output units conversion must be 'Velocity' or 'Default'.

  11/3/2005 -- Version 1.55:  Implemented interpolation of amplitude/phase values from responses containing List blockettes (55); modified to be able to successfully parse response files that contain no "B052F03 Location:" entry; fixed support for URLs as input file names under UNIX.

  10/13/2005 -- Version 1.54:  Modified to allow decimation and gain blockettes in stages containing list blockettes.

  7/11/2005 -- Version 1.53:  Modified to handle List Blockettes (55) that do not contain an "index" ("i") column in their data.

  6/29/2005 -- Version 1.52:  Fixed bug where response sensitivity frequency was not properly selected when no "stage 0 gain" blockette was provided.

  6/1/2005 -- Version 1.51:  Modified to allow negative values in gain stages.

  5/23/2005 -- Version 1.5:

Added support for optional "-use-delay" parameter for using estimated delay in phase calculations.

Added support for URLs as input file names.

Added support for optional "-i"/"--showInputFlag" parameter to show RESP input text (sent to 'stdout').

Miscellaneous minor changes and improvements:
  Modified to suppress "No matching response files found" error message when all matching response files contain errors.
  Modified launcher to only show "Unable to start command processor" message if return value from 'system()' call is less than zero.
  Modified to display infinite-number value as "*" in verbose output.
  Fixed 'propsFileProp' null pointer when running "(file)" version of program.
  Changed how 'calculatedDelay' is computed (by allowing FIR stages with no coefficients to affect the 'calculatedDelay' sum) to synchronize with 'evalresp'.
  Modified to interpret gain object with '-1' values as equivalent to "no gain object" (sometimes comes from network server).
  Modified to show "Illegal parameter" instead of "Too many parameters" when invalid parameter is given (and other parameters are supplied).

  3/4/2004 -- Version 1.201:  Fixed "JEvalResp.exe" launcher to work when the ".exe" and ".jar" files are not in the current working directory.

10/22/2003 -- Version 1.2:  Implemented fix to IIR PZ transformation (to synchronize with 'evalresp' version 3.2.22).

 9/15/2003 -- Version 1.1b:  Added additional files for Max OSX support in 'c' directory.

 9/13/2003 -- Version 1.1a:  Fixed "RunBlks.java" to work again with 'C' code; removed "malloc.h" includes from the 'C' modules that had them.



See Also

JPlotResp - Graphically-oriented Java program for processing and plotting responses.
evalresp - The manual for the original program.
rdseed - Reads an FDSN SEED format volume.
IRIS - The IRIS Consortium website.
FISSURES - The FISSURES Project homepage.
ORBacus - CORBA ORBs for C++ and Java.


8/26/2014 - Eric Thomas / Kevin Frechette, Instrumental Software Technologies, Inc. - www.isti.com


Click here to visit the ISTI home page