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:
- /ph5ws/evalresp/1/query?units=def&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot-amp
- /ph5ws/evalresp/1/query?units=dis&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot-amp
- /ph5ws/evalresp/1/query?units=vel&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot-amp
- /ph5ws/evalresp/1/query?units=acc&net=5A&sta=1&loc=++&cha=DPZ&time=2018-03-12T18:05:50&output=plot-amp
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:
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
- http://www.gnu.org/software/wget/manual/wget.html
- http://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Responses
- http://en.wikipedia.org/wiki/MIME#Content-Disposition
Problems with this service?
Please send an email report of which service you were using, your URL query, and any error feedback to:
[email protected]
We will address your issue as soon as possible.
