Help: evalresp v.1

Description

The ws-evalresp webservice evaluates instrument channel response metadata held in the IRIS-DMC’s database. The service outputs amplitude–phase Bode plots as well as ASCII text files.

Output format options:

parameter option output data
output=fap Three column ASCII text file: frequency, amplitude, phase
output=cs Three column ASCII text file: frequency, real, imaginary (complex spectra)
output=plot Amplitude, phase Bode plot
output=plot-amp Amplitude only Bode plot
output=plot-phase Phase only Bode Plot

Detailed description of service

The data output by the ws-evalresp webservice is generated by an instance of the evalresp program.
Internally, the ws-evalresp service invokes the ws-resp webservice to obtain RESP formatted response information for the given network, station, location, channel and time. This information is in-turn passed to an instance of the evalresp program to obtain evaluated response information that is either directly returned (output=fap, output=cs), or used to generate a plot (output=plot, output=plot-amp, output=plot-phase).

Frequency Selection Options

minfreq, maxfreq

The output frequency range can be set with the minfreq and maxfreq parameter options.

If the minfreq parameter option is not given, the default value of 0.00001 Hz will be used.

If the maxfreq parameter option is not given, the channel’s sample rate will be used, unless the stage-zero frequency of sensitivity is greater than the sample rate, in which case that will be used. For most channels, the frequency of sensitivity is less than the channel sample rate.

nfreq

The nfreq parameter option is used to determine the number of frequency samples. If the nfreq parameter option is not given, the default value of 200 will be used.

spacing

The spacing option determines how frequencies are spaced. The samples will be equally spaced on logarithmic (spacing=log) or linear (spacing=lin) frequency scales. If the spacing option is not given, logarithmic spacing will be used.

Generic Response Blockette

As described in the evalresp manual , the minfreq, maxfreq and nfreq parameter options are ignored for responses containing generic list blockettes [55]. This is true of the output=fap and output=cs options. For the plotting output options (output=plot, output=plot-amp, output=plot-phase), the frequency range shown in the plot will correspond to the selected frequency range. For plots, if the minfreq parameter is not given, it will be set to half of the lowest frequency in the blockette list.

The following queries illustrate a channel (IM.IL01..SHZ) with a generic list blockette:

RESP from ws-resp:
/irisws/resp/1/query?net=IM&sta=IL01&loc=—&cha=SHZ&time=2010-001T00.00.00

Frequency, Amplitude, Phase from ws-evalresp:
/irisws/evalresp/1/query?net=IM&sta=IL01&loc=—&cha=SHZ&time=2010-001T00.00.00&output=fap

Amplitude-Phase plots from ws-evalresp:
/irisws/evalresp/1/query?net=IM&sta=IL01&loc=—&cha=SHZ&time=2010-001T00.00.00&output=plot

Units Option

The output units can be set with the units parameter option. There are four possible values:

parameter option output data units
units=def converts to the units indicated in the RESP response metadata
units=dis converts to units of displacement
units=vel converts to units of velocity
units=acc converts to units of acceleration

If the units parameter option is not given, the def option is assumed.

The data output from the output=fap and output=cs options do not indicate what the units of the data are.

However, the vertical axis labels of the plotted amplitude data do, as illustrated in these examples:

Plot Options

annotate

The annotate option allows for toggling the drawing of annotation lines on the output plots. If the annotate option is not given, it defaults to true.

The following queries illustrate plots with and without annotation lines:

With annotations
/irisws/evalresp/1/query?annotate=true&net=IU&sta=ANMO&loc=00&cha=BHZ&time=2011-06-07T00.00.00&output=plot

Without annotations
/irisws/evalresp/1/query?annotate=false&net=IU&sta=ANMO&loc=00&cha=BHZ&time=2011-06-07T00.00.00&output=plot

width, height

The width and height options allow pixel size of the plots to be adjusted. If the width parameter is not given, it defaults to 800. If the height parameter is not given, it defaults to 600. The product of width times height may not exceed 6,000,000.

The following illustrate plots with different sizes:

500 × 300:
/irisws/evalresp/1/query?width=500&height=300&net=IU&sta=ANMO&loc=00&cha=BHZ&time=2011-06-07T00.00.00&output=plot

2000 × 1500:
/irisws/evalresp/1/query?width=2000&height=1500&net=IU&sta=ANMO&loc=00&cha=BHZ&time=2011-06-07T00.00.00&output=plot

HTTP response codes

200 OK

When the ws-evalresp webservice is successfully invoked it will return with a 200 HTTP response code.

404 Not Found

As mentioned above, the ws-evalresp service invokes the ws-resp webservice to obtain the RESP information needed by the evalresp program.

If the ws-resp service is unable to find response information for the given network, station, location and channel at the given time it will return a 404 HTTP response code to the ws-evalresp webservice. This response code will in turn be returned to the caller of ws-evalresp.

Example — Trying to obtain evaluated response for a fictitious, none-existent, channel (ABC):

—404 error—
Calling ws-resp
/irisws/resp/1/query?net=IU&loc=00&cha=ABC&sta=ANMO&time=2011-001T00:00:00

Calling ws-evalresp:
/irisws/evalresp/1/query?net=IU&loc=00&cha=ABC&sta=ANMO&output=fap&time=2011-001T00:00:00

400 Bad Request

If ws-evalresp is called with invalid parameters, it will return with a 400 HTTP response code.

Example — Calling with a negative minfreq parameter option:

—400 error—
/irisws/evalresp/1/query?minfreq=-1.0&net=IU&loc=00&cha=ABC&sta=ANMO&output=fap

500 Internal Error

If the evalresp program is unable to interpret the RESP output from the ws-resp webservice, the ws-evalresp webservice will fail with a 500 HTTP response code.

This will commonly happen with channels that use Polynomial Coefficients (search for “Blockette 62” in the SEED Manual) to represent response rather than, for example, Poles and Zeros.

An example of this is the LDO channel for the IU network’s station ANMO. The RESP for this channel can be viewed with the following query:

Example of a channel with polynomial coefficients in its response:
/irisws/resp/1/query?net=IU&loc=30&cha=LDO&sta=ANMO&output=fap&time=2010-001T00:00:00

Invoking ws-evalresp for this channel will result in an error:

500 error:
/irisws/evalresp/1/query?net=IU&loc=30&cha=LDO&sta=ANMO&output=fap&time=2010-001T00:00:00&output=fap

URL Builder

The easiest way to gain an understanding of how to use ws-evalresp is by experimenting with its URL builder web page located at /irisws/evalresp/1/builder. This web page makes it relatively easy to understand what combinations of query parameters are legal for this web service. The web page will dynamically activate and deactivate different options as you make selections.

Invoking from the UNIX command line

ws-evalresp can be easily invoked using the UNIX wget or curl commands. The following demonstrates using wget to download a plot of filtered data.

$ wget --content-disposition "http://service.iris.edu/irisws/evalresp/1/query?net=IU&sta=ANMO&loc=00&cha=BHZ&time=2010-02-27T06.30.00&width=700&height=400&output=plot"
`BODE.IU.ANMO.00.BHZ.2010.058T06.30.00.png'' saved [26593/26593]
Evalresp figure

Because of the ampersand (&) characters in the URL, the URL must be surrounded by quote characters ('') or the UNIX shell will interpret them as background control characters. The --content-disposition flag tells wget to save the file to the name indicated in the HTTP response header. This file name is automatically generated by the web service.

In the previous example the auto-generated name was:

BODE.IU.ANMO.00.BHZ.2010.058T06.30.00.png

The --content-disposition flag is only available in more recent versions of wget. To save to a file of your own choosing, use the -O option.

See also