JEvalResp Manual
(for Version 1.77)
JEvalResp Manual
(for Version 1.77)
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.
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.
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.
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
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.
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.
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.
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.
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.
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
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.
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.
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.
