NSF SAGE Facility MUSTANG noise-pdf-browser Web Service Documentation

Description

The noise-pdf-browser web service returns browsable views of PDF noise plots.

There are three service query methods:

/gallery

Produces a grid of PDF images where the columns are selected calendar intervals (for example months) while the rows are selected targets.

/breakout

For specified target, produces a plot of a calendar interval (for example a year) along with plots of the sub-intervals (for example months) that comprise it.

/spectrogram

Produces a column of spectrogram images for selected targets and time range.

/summary

Produces a list of targets with the date-ranges of available PDF information.

/availability

Produces a list of targets with date-ranges of available PDF information. Useful for automating the retrieval PSDs, PDFs and spectrograms.

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

Query Usage

/gallery

/gallery? (channel-options) [date-range-options] [image-size-options] [format-options] [no-data-options]

Where:

channel-options    :: (net[work]=<network>&sta[tion]=<station>&loc[ation]=<location>&cha[annel]=<channel>) | 
                      (target=<nslcq>[,<nslcq>...])
date-range-options :: [starttime=<time>][endtime=<time>][maxintervals=<number-of-date-intervals>]
                      [interval=<all|year|month|week>]
image-size-options :: [imgwidth=<image-width-pixels>] [imgheight=<image-height-pixels>]

/breakout

/breakout? (channel-options) [date-range-options]  [image-size-options] [format-options] [no-data-options]

Where:

channel-options    :: (net[work]=<network>&sta[tion]=<station>&loc[ation]=<location>&cha[annel]=<channel>) | 
                      (target=<nslcq>)
date-range-options :: [time=<time>](interval=<all|year|month|week>)
image-size-options :: [imgwidth=<image-width-pixels>] [imgheight=<image-height-pixels>]
                      [subimgwidth=<image-width-pixels>] [subimgheight=<image-height-pixels>]

/spectrogram

/spectrogram? (channel-options) [date-range-options]  [image-size-options] [color-options] [power-output-options] [no-data-options]

Where:

channel-options      :: (net[work]=<network>&sta[tion]=<station>&loc[ation]=<location>&cha[annel]=<channel>) | 
                        (target=<nslcq>)
date-range-options   :: [start[time]=<date>][end[time]=<date>]
image-size-options   :: [imgwidth=<image-width-pixels>] [imgheight=<image-height-pixels>]
color-options        :: [color.palette=<rainbow|RdYlBu|RdBu|BrBG|YlGnBu|viridis|OrRd>]
                        [color.invert=<true|false>]
power-output-options :: [powerrange=<power1,power2>] | [autorange=<value: 0 to 1>]
                        [output=<power|powerdhnm|powerdlnm|powerdnm|powerdmedian>] 
                        [noisemodel.byperiod=<pipe-separated-list>]
                        [noisemodel.byfrequency=<pipe-separated-list>]

/summary

/summary? (channel-options) [format-options] [no-data-options]

Where:

channel-options    :: (net[work]=<network>&sta[tion]=<station>&loc[ation]=<location>&cha[annel]=<channel>) | 
                      (target=<nslcq>[,<nslcq>...])

/availability

/availability? (channel-options) [format-options] [no-data-options]

Where:

channel-options    :: (net[work]=<network>&sta[tion]=<station>&loc[ation]=<location>&cha[annel]=<channel>) | 
                      (target=<nslcq>[,<nslcq>...])
date-range-options :: [starttime=<time>][endtime=<time>][interval=<all|year|month|week|day>]
format-options     :: (format=<text>)

format-options  :: (format=<text|json|html>)
no-data-options :: (nodata=<200|204|404>)
(..) required
[..] optional

Sample Queries

Gallery View
…/gallery?target=IU.ANMO.00.*.M
…/gallery?target=IU.ANMO.*.*.M&starttime=2011-03-01&interval=month&maxintervals=5
…/gallery?target=IU.*.*.BH1.M&endtime=2012-01-01&interval=year&maxintervals=3
…/gallery?target=IU.ANMO.00.BH?.M&starttime=2011-03-01&endtime=2011-06-02&interval=month
…/gallery?target=IU.ANMO.*.*.M&format=text
…/gallery?network=IU&station=ANMO&channel=BH1,BH2,BHZ&interval=all&starttime=2011-03-01&endtime=2011-06-02

Breakout View
…/breakout?target=IU.ANMO.00.BH2.M
…/breakout?target=IU.ADK.00.BH1.M&time=2010-01-01&interval=year

Spectrogram View
…/spectrogram?target=IU.ANMO.00.*.M
…/spectrogram?target=IU.ANMO.*.*.M&starttime=2010-03-01&endtime=2015-03-01
…/spectrogram?network=TA&channel=BHZ,BHE,BHN&station=A19K,B18K,C16K
…/spectrogram?target=IU.ANMO.00.*.M&powerrange=-180,-100
…/spectrogram?target=IU.ANMO.00.*.M&output=powerdmedian
…/spectrogram?target=IU.ANMO.00.*.M&color.palette=viridis
…/spectrogram?target=IU.ANMO.00.*.M&color.palette=RdBu&color.invert=true

Summary View
…/summary?target=IU.*.*.BH?.M
…/summary?target=IU.*.*.BH?.M&format=text
…/summary?target=IU.*.*.BH?.M&format=json

Availability View
…/availability?target=IU.*.*.BH?.M
…/availability?target=IU.*.*.BH?.M&&starttime=2010-03-01&endtime=2015-03-01
…/availability?target=IU.*.*.BH?.M&&starttime=2010-03-01&endtime=2015-03-01&interval=month

Detailed Descriptions of each Query Parameter

Common Parameters

All 5 methods (/gallery, /breakout, /spectrogram, /summary, /availability) take these parameters.

parameter examples discussion default type
net[work] IU Select Network code. (*) (**) string
sta[tion] ANMO Select station code. (*) (**) string
loc[ation] 00 Select location code. Use — for empty location (double dash). (*). (**) string
cha[nnel] BH? Select channel code. (*) (**) string
quality M Select quality code. “M” for data from our miniSEED archive. “D” for data from our PH5 archive. (*) (**) string
target IU.ANMO.00.BHZ.M Select mustang target name (Network.Station.Location.Channel.Quality) (*) string
format html one of html, json or text html string
nodata 200 Determines http response code when query results in no data. Must be one of 200, 204, 404 200 string

(*) For the /gallery, /summary and /availability methods glob wild cards of * and ? can be used as well as CSV (comma separated value) lists.

(**) For the /gallery, /summary and /availability methods, if any of the [network, station, location, channel, quality] parameters are set, any unspecified parameters from that set will be wild carded.

/gallery Parameters

Takes all common parameters (see above).

parameter example discussion default type
starttime 2010-12-01 start time of gallery (see help) not set day
endtime 2013-03-02 start time of gallery (see help) current time day
maxintervals 5 number of time intervals to display (see help) 4 number
interval month one of all, year, month, week, day (see help) year string
imgwidth 400 pixel width of generated images 250 positive number
imgheight 300 pixel height of generated images 200 positive number

Any combination of starttime, endtime and maxintervals is allowed except for all three together.

Multiple targets allowed: yes

/breakout Parameters

Takes all common parameters (see above).

parameter example discussion default type
time 2010-12-01 time of selected interval (see help) current time day
interval month one of all, year, month, week, day (see help) all string
imgwidth 500 pixel width of main image 500 positive number
imgheight 400 pixel height of main image 400 positive number
subimgwidth 250 pixel width of sub-interval images 250 positive number
subimgheight 200 pixel height of sub-interval images 200 positive number

If interval=all is selected, the time parameter is ignored and is not required. Otherwise, the time parameter is required.

Multiple targets allowed: no

/spectrogram Parameters

Takes all common parameters (see above).

parameter example discussion default type
starttime 2010-12-01 start time of spectrograms (see help) earliest date available for spectrogram measurements day
endtime 2013-03-02 start time of spectrograms (see help) latest date available for spectrogram measurements day
imgwidth 400 pixel width of generated images 1250 positive number
imgheight 300 pixel height of generated images 300 positive number
color.palette Color scheme to use for plot and power scale rainbow string
rainbow (default) cpt-city rainbow palette
RdYlBu ColorBrewer RdYlBu palette
RdBu Colorbrewer RdBu palette
BrBG Colorbrewer BrBG palette
YlGnBu ColorBrewer YlGnBu palette
viridis Matplotlib viridis palette
OrRd ColorBrewer OrRd palette
color.invert true Inverts the color palette false boolean
powerrange -180,-110 Range of power values to be mapped to color scale. Mutually exclusive with autorange two comma separated values
autorange 0.9 A number from 0 to 1. Determines range of data mapped to color scale based on percentile. Mutually exclusive with powerrange 0.95 number
output how to display power see help
power (default) show power
powerdmedian power relative to the median per frequency power level
powerdhnm power relative to the High Noise Model
powerdlnm power relative to the Low Noise Model
powerdnm power relative to both Noise Models. Positive values designate powers above both noise models, negative values designate powers below both noise models and zero values designate powers between both noise models
noisemodel.byperiod User specified noise model by period see help
noisemodel.byfrequency User specified noise model by frequency see help

Multiple targets allowed: yes

/summary Parameters

Takes all common parameters (see above).

Multiple targets allowed: yes

/availability Parameters

Takes all common parameters (see above).

parameter example discussion default type
starttime 2010-12-01 start time of PDFs (see help) earliest date available for PDF measurements day
endtime 2013-03-02 end time of PDFs (see help) latest date available for PDF measurements day
interval month calendar intervals to return. can be one of all, year, month, week, day all calendar interval

Multiple targets allowed: yes


Date Formats

Year, Month, Day in Month:

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)

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.

MUSTANG noise-pdf-browser web service