JPlotResp Manual
(for version 1.80)

• Introduction
• Installing JPlotResp
• Running JPlotResp / Requirements
• Quick Start
• Entry Screen
• Plot Screens
• Network Access to Servers
• Revision History Notes
• See Also

     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) or station.xml formatted files.  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).  Entering "--" will specifiy an empty location code.  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".

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

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.
irisxml.prop - Properties file for the IRIS DMC FDSNWS Station Web Service (which returns data in station.xml format).

     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").
     URLs should not contain the /query? part, but may contain additional parameters, appended in the form &name=value. Additional parameters may also be given on separate lines in the file, with the format name=value, and will be added to all URLs.
     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.