Help: evalresp v.1

Description

The ph5ws-evalresp webservice evaluates instrument channel response metadata held in the IRIS-DMC’s PH5 archive. 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 ph5ws-evalresp webservice is generated by an instance of the evalresp program.
Internally, the ph5ws-evalresp service invokes the ph5ws-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 ph5ws-resp:
/ph5ws/resp/1/query?net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50

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

Amplitude-Phase plots from ph5ws-evalresp:
/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&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
/ph5ws/evalresp/1/query?annotate=true&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot

Without annotations
/ph5ws/evalresp/1/query?annotate=false&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&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:
/ph5ws/evalresp/1/query?width=500&height=300&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot

2000 × 1500:
/ph5ws/evalresp/1/query?width=2000&height=1500&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot

HTTP response codes

200 OK

When the ph5ws-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 ph5ws-resp webservice to obtain the RESP information needed by the evalresp program.

If the ph5ws-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.

Example — Trying to obtain evaluated response for a fictitious channel (ABC):

—404 error—
Calling ph5ws-resp
/ph5ws/resp/1/query?net=5A&sta=1&loc=++&cha=BHZ&time=2018-03-12T18:05:50

Calling ph5ws-evalresp:
/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=BHZ&time=2018-03-12T18:05:50&output=fap

400 Bad Request

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

Example — Calling with a negative minfreq parameter option:
/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=BHZ&time=2018-03-12T18:05:50&output=fap&minfreq=-1.0

500 Internal Error

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

500 error:
/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=BHZ&time=2018-03-12T18:05:50&output=fap

URL Builder

The easiest way to gain an understanding of how to use ph5ws-evalresp is by experimenting with its URL builder web page located at /ph5ws/evalresp/docs/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 update options as you make selections.

Invoking from the UNIX command line

ph5ws-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/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&width=700&height=400&output=plot”
—2019-01-09 10:46:21— http://service.iris.edu/ph5ws/evalresp/1/query?net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&width=700&height=400&output=plot
Resolving service.iris.edu… 128.95.166.47
Connecting to service.iris.edu|128.95.166.47|:80… connected.
HTTP request sent, awaiting response… 200 OK
Length: 25603 (25K) [image/png]
Saving to: ‘BODE.5A.1..DPZ.2018.071T18.05.50.png’

BODE.5A.1..DPZ.2018.071T18.05.50.png 100%[================================================================>] 25.00K —.-KB/s in 0.001s

2019-01-09 10:46:40 (23.2 MB/s) – ‘BODE.5A.1..DPZ.2018.071T18.05.50.png’ saved [25603/25603]

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.5A.1..DPZ.2018.071T18.05.50.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


Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help@earthscope.org
We will address your issue as soon as possible.