JPlotResp Manual
(for version 1.77)
JPlotResp is a
graphically-oriented
Java program for processing and plotting the response information from
ASCII "RESP" files generated by rdseed (V4.16 and above).
JPlotResp
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 values that may be written to files or
plotted.
Lists of complex-spectra values may also be written to output files.
JPlotResp makes direct use of
functions within JEvalResp to fetch and process response data.
For
more details, see the JEvalResp Manual.
For generating plots,
JPlotResp
uses JFreeChart
as its graphing engine.
The JPlotResp 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:
JPlotResp.jar - Java archive file containing
the
classes for JPlotResp.
JEvalResp.jar - Java archive file containing the
classes for JEvalResp.
run - Unix script for launching the program from
the command line.
run.bat - Windows batch file for launching the
program from the command line.
CmdLnPlotter - Unix script for command-line
access
to JPlotResp plots.
CmdLnPlotter.bat - Windows batch file for
command-line
access to JPlotResp plots.
JEvalResp - Unix script for running JEvalResp.
JEvalResp.exe - Windows executable for running
JEvalResp.
irisws.prop - Properties file for the web-services server from 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.
src.jar - Java archive of source code files.
javadocs/ - Source
code documentation generated
via 'javadoc'.
JPlotResp.html - A copy of this documentation.
JEvalResp.html - A copy of the JEvalResp
documentation.
If the interactive installer was used to install JPlotResp then an executable file should be available for running the program.
Use of JPlotResp 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.
If the interactive installer
was used to install JPlotResp then a shortcut-icon should be available
for running the program. Alternately, a command like the
following
may be used to start the program:
java -jar JPlotResp.jar
The files "JPlotResp.jar" and "JEvalResp.jar" must be available in the local directory, or the pathname to the files must be provided. Script (and batch) launcher files that allow the program to be started with just the command "run" 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 JPlotResp.jar
For Windows:
java -DSEEDRESP="%SEEDRESP%" -jar JPlotResp.jar
The provided "run" script (and batch) files are already setup to support passing the "SEEDRESP" environment variable.
It is also possible to run the program in a "command line" mode, where all of the response parameters are specified on the command line and one or more plots are generated. The "CmdLnPlotter" script (and batch) file may be used for this purpose. The set of parameters is the same as those for the JEvalResp program.
To perform a quick test of the software, enter the items below into the "Entry Screen". (You'll need to have an Internet connection available to reach the network server.)
Network : IU
Station : ANMO
Channel : BH1
Min Freq : 0.0001
Max Freq : 100
Num Freqs : 100
After entering the items
above,
click on the "Server:" radio button (to select server
access),
and then click on the "Plot" Button. You should see series
of messages on the "Console" tab, and then a tab should appear
containing
the response plots for "IU.ANMO..BH1". Clicking on the "Run
JEvalResp"
button back on the "Entry" tab should produce a similar series of
messages
on the "Console" tab, followed by the creation of two files,
"AMP.IU.ANMO..BH1"
and "PHASE.IU.ANMO..BH1".
If you have response files
(such
as "RESP.IU.ANMO..BH1") available on your local system, you can process
them by hitting the "Browse" button near the "Filenames:"
field and selecting the file or files. (Make sure that the "Network:",
"Station:" and "Channel:" fields are either blank or
contain
names that match the channel-IDs for the desired responses.
The entry screen contains the text entry fields, combo-boxes and buttons used to operate JPlotResp. They are described as follows:
Network : The network name(s) to be matched when searching for responses. This field 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). If this field is left blank then all network names will be matched (same as '*').
Station : A comma-separated list of station names to be matched when searching for responses. The wildcard characters '*' and '?' (glob-style) may be used. If this field is left blank then all station names will be matched (same as '*').
Location : The location ID name(s) to be matched when searching for responses. This field 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). If this field is left blank then all location names will be matched (same as '*').
Channel : A comma-separated list of channel names to be matched when searching for responses. The wildcard characters '*' and '?' (glob-style) may be used. If this field is left blank then all channel names will be matched (same as '*').
Min Freq : The minimum value for the range of frequency values used when calculating response output numbers. Note that the "Frequency Spacing" selection specifies how the values are generated. If this field is left blank then a single frequency value of '1.0' will be used.
Max Freq : The maximum value for the range of frequency values used when calculating response output numbers. Note that the "Frequency Spacing" selection specifies how the values are generated.
Num Freqs : The number of frequency values to
be
included in the range of frequency values used when calculating
response
output numbers. Note that the "Frequency Spacing" selection
specifies
how the values are generated. If this field is left blank then a
single frequency value will be used.
Begin Time Settings:
Year : A numeric year value used to specify a date to be matched. If an end-date/time is entered (via the End Time settings) 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 entered then the specified date is treated as a single date that must be within the range of dates found in matching responses. This field may be left blank or set to a single asterisk ('*') to specify "all dates".End Time Settings:Julian Day : A numeric Julian day-of-the-year value that is added to the Year value to specify a date to be matched. The first day of the year has a value of '1'. This field may be left blank or set to a single asterisk ('*'), which will specify "all dates" (if Begin Time Year is blank or '*') or the value '1' (if a Begin Time Year value is entered).
Time : A time-of-day value, in HH:MM:SS format, to be included when specifying a date to be matched. This can be useful when greater accuracy in the date specification is needed. When a date is specified (via Begin Time Year and Julian Day) with this field left blank, a time-of-day value of 00:00:00 is used.
Year : 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. This field may be left blank or set to a single asterisk ('*') to specify "all dates".Enable multi-date outputs : This checkbox may be selected to 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"), as well as the generated plot titles. When this checkbox is not selected, only one output will be generated for any given "net.sta.loc.cha" code.Julian Day : A numeric Julian day-of-the-year value that is added to the the End Time Year 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'. This field may be left blank or set to a single asterisk ('*'), which will specify "all dates" (if End Time Year is blank or '*') or the value '1' (if an End Time Year value is entered).
Time : 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 can be useful when greater accuracy in the end-date/time specification is needed. When an end-date/time is specified (via End Time Year and Julian Day) with this field left blank, a time-of-day value of 00:00:00 is used.
Filenames : 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. If
this
field is left blank then the local directory and the directory
specified
by the "SEEDRESP" environment variable are searched. Selecting
the
"Filename" radio-button causes the program to fetch responses from
files,
rather than from a server (see below).
Clicking on the Browse
button next to this field will bring up a file-chooser window that may
be used to select one or more files or directories to be searched for
responses.
Within the file-chooser, the "Append" button may be used to add the
selected
name or names to those selected previously, whereas using the "OK"
button
will overwrite any previously selected names.
Server : This field 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., http://service.iris.edu/irisws/resp/1). When the "Server"
radio-button is selected, a network connection will be opened to the
server and used to fetch responses (instead of using input
files). Multiple web-services servers may also be specified. For more information, see the "Network Access to Servers" section.
Clicking on the Browse
button next to this field will bring up a file-chooser window that may
be used to select a properties file.
Start Stage : One of the two numeric fields used to select a stage or range of stages to be processed in the response. This field specifies the first stage to be processed. If the "Stop Stage" field is left blank then only the single stage specified by this field will be processed. If both fields are left blank then all stages will be processed. (Stage numbers begin with '1'.)
Stop Stage : One of the two numeric fields used to select a stage or range of stages to be processed in the response. This field specifies the last stage to be processed. If this field is left blank then only the single stage specified by the "Start Stage" field will be processed. If both fields are left blank then all stages will be processed.
Verbose : When this check-box is selected, verbose messages will be shown on the "Console" tab. The messages will contain summary information about the matching responses, including units, sensitivity, delay, corrections and stage-type information.
Headers : When this check-box is selected, the inclusion of header information in generated output files is enabled. (These files are generated when the "Run JEvalResp" button is pressed.) The header information includes items such as station identification, frequencies used and time created. Each header line begins with a "pound" character ('#').
Use Est Delay : When this check-box is selected, estimated delay is used with calculations on asymmetrical FIR filters; otherwise the correction-applied value is used with calculations on asymmetrical FIR filters.
Show Input : When this check-box is selected, a RESP-text representation of the response input is sent to the "Console" tab. This can be useful when the source of the response data is a network server.
b62_x : Sample value for polynomial blockette. See the "Polynomial Response (Non-Linear) Blockette 62" notes in the JEvalResp manual.
Multi-server plots
: When this check-box is
selected and multiple web-services servers are available (via the
'Server' field), the program will attempt to fetch and process matching
responses from all the specified servers. When this checkbox is
not selected, only the first matching response will be fetched and
processed. Anytime this checkbox is selected the host address of
the source web-services server will be appended to the filenames of the
generated output files (e.g., "AMP.XX.RUB03.01.BHE_www.iris.edu"), as
well as the generated plot titles.
Unwrap Phase : When this check-box is
selected, generated phase values are "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.
Use Total Sensit : When this check-box is
selected, the stage 0 (total) sensitivity will be used instead of the
product of the stage gains. This can be utilized in combination
with the Start/Stop-Stage fields 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).
Interpolate Output : When this check-box is
selected,
amplitude/phase values generated from responses
containing List blockettes (55) are 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 "Tension" field (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" tab. If a
response does not contain a List blockette or if a complex-spectra
response output file is being generated then this check-box will have
no effect. If this check-box and the "Interpolate Input"
check-box are not selected then the output for a response containing a
List blockette will be generated only for the frequencies defined in
the List blockette.
The "Interpolate Output" option differs from
the "Interpolate Input" option in that when "Interpolate Output" is
selected the interpolation happens after the response data values have
been processed by the program. When "Interpolate Input" is
selected 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.
Interpolate Input : When this check-box is
selected,
amplitude/phase values input from a response
containing a List blockette (55) are 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 "Tension"
field (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" tab.
If a response does not contain a List blockette then
this check-box will have no effect. This
option (rather than "Interpolate Output") can be useful when a
complex-spectra response output file is being generated. If this check-box and the "Interpolate Output"
check-box are not selected then the output for a response containing a
List blockette will be generated only for the frequencies defined in
the List blockette.
The "Interpolate Input" option differs from
the "Interpolate Output" option in that when "Interpolate Input" is
selected the List-blockette data values are interpolated before they
are processed by the program. When "Interpolate Output" is
selected 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.
Tension : Specifies the "tension" value used by the cubic-spline interpolation algorithm (see "Interpolate Output" and "Interpolate Input"). A relatively high "tension" value is desirable because it makes the interpolated values "track" closely to the original values. The "tension" is specified as a floating-point value, and its default value is 1000.0.
Output Units : This combo-box selects the output units conversion value, which may be set to "Displacement", "Velocity", "Acceleration" or "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" 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.)
Frequency Spacing : This combo-box selects the type of frequency spacing used. It may be set to "Logarithmic" or "Linear"; and represents the type of spacing used when generating the set of frequencies specified by the "Min Freq", "Max Freq" and "Num Freqs" fields.
Output-File Type : This combo-box selects the type of response output values to be produced when generating output files, which only happens when the "Run JEvalResp" button is pressed. (When the "Plot" button is pressed this setting is ignored.) This combo-box may be set to "Amplitude/Phase", "Complex-Spectra", "Amplitude/Phase2" or "fAmplitude/Phase". If "Amplitude/Phase" 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" is chosen then files like SPECTRA.NET.STA.LOC.CHA are created, containing the calculated "real" and "imaginary" response output values. If "Amplitude/Phase2" 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" 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"). For more information on the output files see the JEvalResp Manual section on output file formats.
Output Directory : This text entry field specifies the destination directory for generated output files. Clicking on the Browse button next to this field will bring up a file-chooser window that may be used to select the destination directory.
Plot Options:
Display : This combo-box selects which output values are displayed in the generated output plots. It may be set to "Amplitude", "Phase", "Amplitude/Phase", "Show Stages Amplitude", "Show Stages Phase" or "Show Stages Amp/Phase". When one of the "Show Stages..." options is selected, a separate graph line will be generated for each of the stages of the response.
Show Datapoints : This check-box may be selected to highlight the datapoints used to generate the plot.
Logarithmic Amplitude : This check-box may be selected to use a logarithmic axis when showing the amplitude graph.
Combine Amplitude/Phase : This check-box may be selected to show the "Amplitude/Phase" graphs displayed on a single plot.
Show Freq Line : This check-box may be selected to display a vertical-line marker on the amplitude plot indicating the sensitivity-frequency value (from stage 0 of the response).
Buttons:
Close All Plots : Closes all of the plots
that are currently displayed.
Update Options on All Plots : Sets the options for all plots
that are currently displayed to match those in the Plot Options.
Run JEvalResp : This button processes the responses found using the entered values and generates one or more output files. The files are saved to the location specified in the Output Directory field. For more information on the output files see the JEvalResp Manual section on output file formats. Messages generated while processing the response data are shown on the "Console" tab. If none is present then a "Console" tab is created; if one already exists then the messages are appended to it.
Plot : This button processes the responses found using the entered values and generates one or more output plots. Messages generated while processing the response data are shown on the "Console" tab. If none is present then a "Console" tab is created; if one already exists then the messages are appended to it.
Quit : Exits the program.
About : Displays information about the program revision and authorship.
Help : Displays a viewer containing this help information. From within the viewer, the "Launch Brower" button may be used view the information in a web browser (if the "JPlotResp.html" file is in the same directory as the program).
For each matching response
found
after pressing the "Plot" button, a new tab containing the plot is
created.
The name of the tab is based on the network, station, location and
channel
name for the response. When a plot is displayed and the mouse
cursor hovers over a data point on a graph line, a "tool-tip" window is
displayed showing information about the data point.
On the plots, the right-mouse button may be
used to display a menu of functions (print, save, etc.), and the plot
display may be zoomed using mouse-dragging actions (down and to the
right to zoom in; up and to the left to zoom out). The "Auto Range"
item on the menu may also be used to zoom out the axes so that all
data-points are visible.
Under the plot, several lines of detail notes on the response are displayed. Below these are the following controls:
Display : This combo-box may be used to change which output values are displayed in the plot. It may be set to "Amplitude", "Phase", "Amplitude/Phase", "Show Stages Amplitude", "Show Stages Phase" or "Show Stages Amp/Phase". When one of the "Show Stages..." options is selected, a separate graph line will be generated for each of the stages of the response.
Show Datapoints : This check-box may be selected to highlight the datapoints used to generate the plot.
Logarithmic Amplitude : This check-box may be selected to use a logarithmic axis when showing the amplitude graph.
Combine Amplitude/Phase : This check-box may
be
selected to show the "Amplitude/Phase" graphs displayed on a single
plot.
Show Freq Line : This check-box may be
selected to display a vertical-line marker on the amplitude plot
indicating the sensitivity-frequency value (from stage 0 of the
response).
Close : This button may be used to remove the tab holding the plot.
When the "Server" radio-button is selected, a network connection will 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 in the "Server" entry field, with each URL
separated by a comma, semicolon or space (e.g.,
"http://service.iris.edu/irisws/resp/1,http://service.iris.edu/irisws/resp/1").
See the description of the "Multi-server plots" checkbox 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.
JEvalResp
- RESP file processing program.
JFreeChart
- Graphing engine used by JPlotResp.
evalresp
- The manual for the original 'C' 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.