JPlotResp Manual
(for version 1.57)

• Introduction
• Installing JPlotResp
• Running JPlotResp / Requirements
• Quick Start
• Entry Screen
• Plot Screens
• Network Access to FISSURES 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).  JPlotResp is also capable of fetching and processing responses from FISSURES 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.
dmc.prop - Properties file for the FISSURES server at the IRIS DMC.
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.4 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 FISSURES 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".

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 : The name of a properties file containing the information needed to locate a FISSURES network server.  When the "Server" radio-button is selected, a network connection will opened to the server and used to fetch responses (instead of using input files).  This field defaults to "dmc.prop", the name of the FISSURES server properties file provided with the distribution.  For more information, see the "Network Access to FISSURES Server" 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 Delay : When this check-box is selected, estimated delay is used in phase calculations.

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 FISSURES network server.

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" or "Amplitude/Phase2".  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.  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.

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.

Close : This button may be used to remove the tab holding the plot.

     When the "Server" radio-button is selected, the specified file will be used to locate the FISSURES server from which responses will be searched for and fetched.  The "dmc.prop" file provided with this distribution will locate FISSURES server from the IRIS Data Management Center in Seattle, WA.  The properties file should contain the following items:

  ooc.orb.service.NameService = corbaloc:iiop:host.domain:port/NameService
  fissures.networkDCname = edu/iris/dmc/IRIS_NetworkDC

The "ooc.orb.service.NameService" item specifies the location of the CORBA "NameService" object used to resolve names on the server.  For the IRIS-DMC server, it is set to "corbaloc:iiop:dmc.iris.washington.edu:6371/NameService".  The "fissures.networkDCname" item is used to specify the name bound (in the NameService) to the FISSURES Network DataCenter object.  For the IRIS-DMC server, it is set to "edu/iris/dmc/IRIS_NetworkDC".

     The properties file may also contain these item settings:

  org.omg.CORBA.ORBClass = com.ooc.CORBA.ORB
  org.omg.CORBA.ORBSingletonClass = com.ooc.CORBA.ORBSingleton

These optional items, as shown above, configure the program to use the CORBA package from ORBacus.  If they are not specified, the program will default to using the settings shown above.  In some instances, these settings could be used to configure the program to use a CORBA package from a different vendor.

Notes on network access to responses:

     While the use of wildcards characters ('*' & '?') in the fields for station, channel, network and location names is supported, using them will necessitate the fetching of sets of channel-ID items from the server that may take some time to transfer.  Omitting any of these fields will act the same as the match-all wildcard character ('*').

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.