NSF SAGE Facility IRISWS timeseriesplot Web Service Documentation

Description

The timeseriesplot service returns a graphical representation of time series data at the channel level for a specific time range.

Output format options:

  • PNG
  • JPEG

The service request offers several options:

  • single-series or “helicorder” style plots
  • a current-day indicator making it easy to obtain daily results
  • scaling of the plot to adjust the overall look
  • plot in raw instrument output or convert to earth units
  • monochrome or color mode

Below is a full list of service parameters and their usage.

Query Usage

/query? (channel-options) (date-range-options) [plot-options] [output-options]

where:

channel-options      ::  (net=<network> & sta=<station> & loc=<location> & cha=<channel>)
date-range-options   ::  (starttime=<time>|duration) & (endtime=<time>|duration)
plot-options         ::  [showtitle=<TRUE|false>] [showscale=<TRUE|false>] [monochrome=<true|FALSE>]
plot-options         ::  [helicordermode=<true|FALSE>] [segmentsperhour=<1-6>]
plot-options         ::  [earthunits=<TRUE|false>] [unitscale=<n>=0>] [demean=<true|FALSE>]
plot-options         ::  [width=<400-2000>] [height=<200-2000>]
filter-options       ::  [lp=FREQ] [hp=FREQ] [bp=LOFREQ-HIFREQ]
output-option        ::  [format=<png|jpeg>]

(..) required
[..] optional
default values in all caps, e.g., TRUE

Query parameters are joined by ampersands &, without blank space (see the sample queries).

Sample Queries

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
Channel Options (required)
The four SNCL parameters (Station – Network – Channel – Location) are used to determine the channel of interest, and are all required. Wildcards are not accepted.
net[work] IU Seismic network name N/A string
sta[tion] ANMO Station name N/A string
loc[ation] 00 Location code. Use loc=-- for empty location codes N/A string
cha[nnel] BHZ Channel Code N/A string
Date-Range Options (required, can be expressed as calendar dates, duration (seconds), or the key word: ‘currentutcday’)
Time ranges can be defined by specifying a start time and an end time.
Example
...starttime=2005-02-23T12:00:00&endtime=2005-02-23T12:05:00...
start[time] 2001-12-09T12:00:00 Start time N/A day/time
end[time] 2001-12-09T12:20:00 End time N/A day/time
Alternatively, time ranges can be defined by a combination of a calendar date and a duration in units of seconds. The following example specifies a calendar date as the starttime plus a 24-hour duration specified in the endtime parameter:
Example
...starttime=2005-02-23T12:00:00&endtime=86400...
start[time] 2001-12-09T12:00:00 Start time expressed as a calendar date N/A day/time
end[time] 86400 End time expressed as a duration (seconds) N/A integer
In addition, time ranges can be defined by a combination of the key word ‘currentutcday’ and a duration in units of seconds. The key word ‘currentutcday’ means exactly midnight of today’s date (UTC time). The following example specifies today’s midnight (UTC) as the starttime plus a 24-hour duration specified in the endtime parameter:
Example
...starttime=currentutcday&endtime=86400...

NOTE: the key word ‘currentutcday’ can also be used for the end[time] parameter indicating exactly midnight of today’s date. In this case the duration specified in the start[time] parameter specifies the duration prior to midnight (i.e., the previous day).
start[time] currentutcday today’s midnight (UTC) N/A string
end[time] 86400 End time expressed as a duration (seconds) N/A integer
Plot Options
showtitle true If true, the created image will include a title across the top showing the Channel and Date-Range information true boolean
showscale true If true, a scale will be shown on the right-side axis. This is independent of the earthunits option true boolean
monochrome false If false, the created image will be drawn in color. True creates a grayscale image. false boolean
helicordermode true If true the result is in “helicorder” style in which the timeseries data is shown in stacked time segments. See the segmentsperhour option. If false the plot is said to be in “single-series” mode. false boolean
segmentsperhour 3 Integer ranging from 1 to 6. Indicates the number of segments for each hour of timeseries data when in helicorder mode. 1 integer
earthunits true If true, the values are scaled to the units of the instrument. Should metadata for the channel be unavailable, the data will be plotted in raw units. true boolean
unitscale 0.001 Number greater than or equal to zero. Provides absolute scale factor for consistency in day-to-day plotting. Scales plot to X/100pixels. Value of zero (default) indicates no absolute scaling. 0 numeric
demean true If true, subtract the sample mean from each value. false boolean
width 500 Width of the output plot (pixels). The range is 400 to 2000. Note that the default is 1200 if in single-series mode and 900 in helicorder mode. 1200 or 900 integer
height 400 Height of the output plot (pixels). The range is 200 to 2000. Note that the default is 400 if in single-series mode and 1000 in helicorder mode. 400 or 1000 integer
lp 1.0 Apply a low-pass filter cutoff (Hz) using a Butterworth 4th order filter. N/A float
hp 0.1 Apply a high-pass filter cutoff (Hz) using a Butterworth 4th order filter. N/A float
bp 0.1,1.0 Apply a band-pass filter range (Hz) using a Butterworth 4th order filter. Define the frequency band with lower and upper values separated by a comma, semi-colon, dash, or forward-slash. N/A float
Output Option
format jpeg The desired image type of the plot. png string

Date and Time Formats

Year, Month, Day in Month — Time:

YYYY-MM-DDThh:mm:ss[.ssssss] ex. 1997-01-31T12:04:32.123

YYYY-MM-DD ex. 1997-01-31 a time of 00:00:00 is assumed

Where:

YYYY	:: four-digit year
MM	:: two-digit month (01=January, etc.)
DD	:: two-digit day of month (01 through 31)
T	:: date-time separator
hh	:: two digits of hour (00 through 23) (AM/PM NOT allowed)
mm	:: two digits of minute (00 through 59)
ss	:: two digits of second (00 through 59)
ssssss	:: one to six digits representing decimal fractions of a second, down to microseconds

Restricted Data Access

For access to restricted data, requests should be sent to: service/irisws/timeseriesplot/1/queryauth

Requests sent to this URL are authenticated via digest access authentication in order to establish the caller's credentials. For anonymous access, the user nobody@iris.edu and password anonymous may be used. This credential has identical data access permission as the regular submit path's: service/irisws/timeseriesplot/1/query


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.

IRISWS timeseriesplot web service