Help: measurements v.1

Description

Query Parameters

The Metrics and their Measurements

Selecting the Current list of all metrics button lists the names of the metrics retrievable using the measurements service and displays a brief description of each. By selecting Detailed Documentation for a metric, you can view each metric’s

• Summary
• Uses in data quality assurance
• Data analyzed per measurement (window length and channel description)
• SEED Channel types currently analyzed (BH, SH, etc.)
• Algorithm description
• Description of returned values
• Additional notes or caveats

Channel Options

There are two ways to define desired channels when requesting measurements:

• target – labeled as N.S.L.C.Q (SEED Network.Station.Location.Channel.Quality)
  &target=IU.ANMO.00.BHZ.M
• SNCLQ filter – where the SNCLQ (SEED Sta[tion], Net[work], Chan[nel], Loc[ation] and Qual[ity]) are listed as separate key/value parameters in any order:
  &net=IU&sta=ANMO&loc=00&chan=BHZ&qual=M

SNCLQ filter parameters are optional. Omitting a parameter (e.g. channel) is equivalent to wildcarding (&channel=*) and returns measurements that match any name.

Both channel options accept virtual networks, such as _GSN, but the station name is ignored and measurements for all stations are returned. An exception to this occurs when a station list is provided – the measurements service returns an error.

All data in the IRIS miniSEED archive is now stored as M quality (merged) data. All measurements except the latency measurements are calculated using archived data, and so have quality M. Latency metrics are run on near-real-time data before it is archived and have quality R.

All data in the IRIS PH5 archive have metrics with quality D.

Time Constraints

Most metrics that analyze one-day time windows return truncated start times of 00:00:00 and end times of 23:59:59, although measurement calculation does include all samples in the second preceding 00:00:00 the next day. Consequently, query end dates of YYYY-MM-DD[:T00:00:00] return measurements up to, but not including the end date.

Measurements with event-based time windows return start and end dates that describe that time window. Measurements based on PSD calculations reflect the start and end dates of the data used in the PSDs.

Value Constraints

Limiting measurements by range of one or more numeric values returned involves appending one of the following strings:

• _eq – equal to
• _ne – not equal to
• _lt – less than
• _le – less than or equal to
• _gt – greater than
• _ge – greater than or equal to

to that value. The expressions value_eq=0 and value=0 are equivalent.

Metrics characterized by a single measurement typically return these values:

• value – the measurement for that metric
• target – the trace analyzed, labeled as N.S.L.C.Q (Network.Station.Location.Channel.Quality)
• start – time of the first sample of time series data for that measurement in UTC
• end – time of the last sample of time series data for that measurement in UTC (truncated as 23:59:59 UTC)
• lddate – local date/time the measurement was made

For metrics that calculate and return multiple values, see their Detailed Documentation for names and descriptions of returned values. (Currently, these include asl_coherence, metric_error, orientation_check and station_completeness.)

Because the value constraints involve numerical comparisons, they may be applied to numbers and dates, but not strings such as target.

Output Format

The measurements service offers these output formats to facilitate readability for both people and web service software:

• XML (default)
  XML (Extensible Markup Language) is a human- and machine-readable markup language. In the case of MUSTANG metrics, each element contains a measurement and each attribute is return value.
  

  <measurements>
  <num_spikes value="0" net="IU" sta="ANMO" loc="00" cha="BHZ" qual="M" target="IU.ANMO.00.BHZ.M" start="2018-05-01T00:00:00" end="2018-05-01T23:59:59" lddate="2018-05-03T12:47:47"/>
  </measurements>
  

• text
  In text format, each line contains a measurement expressed as comma-separated values (CSVs) and displayed in the browser or window that originated the query. Each returned value is enclosed in quotes.
  

  "Num Spikes Metric"
  "value","target","start","end","lddate"
  "0","IU.ANMO.00.BHZ.M","2018/05/01 00:00:00","2018/05/01 23:59:59","2018/05/03 12:47:47"
  

• CSV
  This format option uses the same formatting as the text option, but saves it as a CSV disk file.
  

  "Num Spikes Metric"
  "value","target","start","end","lddate"
  "0","IU.ANMO.00.BHZ.M","2018/05/01 00:00:00","2018/05/01 23:59:59","2018/05/03 12:47:47"
  

• JSON
  JSON (JavaScript Object Notation) is a human readable data format frequently used in web service communication.
  

  {"measurements":{"num_spikes":[{"value":0,"net":"IU","sta":"ANMO","loc":"00","cha":"BHZ","qual":"M","target":"IU.ANMO.00.BHZ.M","start":"2018-05-01T00:00:00","end":"2018-05-01T23:59:59","lddate":"2018-05-03T12:47:47"}]}}
  

• JSONP
  JSONP (JSON with Padding) wraps a JSON data from a URL request with JavaScript code that can be specified including the callback=<function_name> parameter in the query.
  

  handleJsonpResponse({"measurements":{"num_spikes":[{"value":0,"net":"IU","sta":"ANMO","loc":"00","cha":"BHZ","qual":"M","target":"IU.ANMO.00.BHZ.M","start":"2018-05-01T00:00:00","end":"2018-05-01T23:59:59","lddate":"2018-05-03T12:47:47"}]}})
  

Server Response

It’s possible to choose which HTTP status code the service returns when the query is successful but there is no data to return. Although status code 204 is defined as describing this case, browsers receiving status code 204 do not refresh their previous contents, so it can be difficult to tell that the query completed successfully. Selecting status code 404 when there is no data to return causes the browsers to refresh and display a blank or nearly blank page. Note that the URL Builder appends &nodata=404 to each query that it builds.

More Ways to Query measurements

The Service Interface page describes how to construct MUSTANG queries that use the HTTP GET method. Another alternative is to use a command line utility like curl or wget to send an HTTP POST request. Dedicated web service clients are a third way to query metrics measurements.

Command line queries (HTTP POST)

Two command line utilities allow you to request MUSTANG measurements: curl and wget.

curl Usage Synopsis
curl [-L] [--data-urlencode snclqs@filename] query_URL

Where

curl                               ::  the curl utility (installed on your machine)
-L                                 ::  option to allow curl to follow HTTP redirections.
--data-urlencode <snclqs@filename> ::  load the channels listed in 'filename' into the parameter 'snclqs', 
                                     url-encoded it, and send it as a POST request.  Details are provided below.
query_URL                          ::  the URL described in the measurements service interface page.

Example
curl -L 'https://service.earthscope.org/mustang/measurements/1/query?metric=max_stalta&station=ANMO&start=2012-10-01&end=2013-01-01&format=text'

Creating a channel list file

To include multiple channels (i.e. targets) in a query, you can create a properly formatted list by using the targets service:

curl -L 'https://service.earthscope.org/mustang/targets/1/query?metric=transfer_function&net=IU&format=text > targets.txt'

head -5 targets.txt
net=IU sta=LSZ loc=10:00 cha=BH:BH1 qual=M
net=IU sta=LSZ loc=10:00 cha=BH:BH2 qual=M
net=IU sta=AFI loc=10:00 cha=BH:BH1 qual=M
net=IU sta=ANMO loc=10:00 cha=BH:BHZ qual=M
net=IU sta=ANTO loc=10:00 cha=BH:BH2 qual=M

After editing targets.txt file to remove any unwanted channels, it can be used as a channel list for queries:
curl -L --data-urlencode [email protected] 'https://service.earthscope.org/mustang/measurements/1/query?metric=sample_snr&start=2012-10-01&end=2013-01-01&format=text'

wget Usage Synopsis
wget [-qO-] query_URL

Where

wget                       ::  the wget utility (installed on your machine)
-qO-                       ::  print results to standard output in quiet mode
query_URL                  ::  the URL described in the measurements service interface page.

Example
wget -qO- 'https://service.earthscope.org/mustang/measurements/1/query?metric=max_stalta&station=ANMO&start=2012-10-01&end=2013-01-01&format=text'

The expressions value_eq=0 and value=0 are equivalent. These are numerical comparisons – they will work for numbers and dates, but not for strings

Clients for Viewing Measurements

In addition to viewing measurements in text form, the following web clients also provide graphic displays:

• MUSTANG Databrowser – box and time series plots of measurements, plus trace plotting and display of PSDs and PDFs.
• LASSO – displays measurements in sortable, color-coded tables and as time series.
• MUSTANGular – displays color-coded map views of station measurements.

By using utilities such as curl and wget described above, anyone can create a custom client. The clients listed here were developed by different members the seismological community and we encourage the sharing of new clients that become available.

Citations and DOIs

To cite the MUSTANG system or reference the use of MUSTANG metrics:

• Assuring the Quality of IRIS Data with MUSTANG
  Robert Casey, Mary E. Templeton, Gillian Sharer, Laura Keyson, Bruce R. Weertman, Tim Ahern
  Seismological Research Letters (2018) 89 (2A): 630-639.
  DOI: https://doi.org/10.1785/0220170191

Problems with this service?