Documentation of the Statistics REST interface

A web-service for the calculation of various statistics on TOAR data.

1 Base URL

The base URL of this service:

https://toar-data.fz-juelich.de/statistics/api/v1/

2 User Guide

https://toar-data.fz-juelich.de/statistics/api/v1/

Response: Description and documentation of service (this document)

3 Queries and options

There are options for names, sampling, seasons, crops, data_capture, timeseries_id, flags, format

Example query:

https://toar-data.fz-juelich.de/statistics/api/v1/?names=perc90,median&sampling=annual×eries_id=110

Response: The calculated statistics.

Options:

  • names: A list of statistics to calculate
  • sampling: The sampling frequency to use
  • seasons: Season names for seasonal statistics
  • crops: Crops for vegetation season statistics
  • data_capture: Percentage of available data to return a result
  • timeseries_id: Timeseries ID on which to calculate the statistics
  • flags: Filter data points by given flags
  • format: Format of the result (json or csv, default: json)

4 Response format

JSON and CSV responses are available.

5 List of statistics/metrics for toarstats service

More information on these statistics and metrics can be found in supplement 1 of Schultz et al. (2017).

References:

Schultz, M. G. et al. (2017a) Tropospheric Ozone Assessment Report:Database and Metrics Data of Global Surface Ozone Observations, https://doi.org/10.1525/elementa.244.

Schultz, M. G. et al. (2017b) Tropospheric Ozone Assessment Report:Global Surface Ozone Data Products, supplement to Schultz et al. (2017a), https://doi.org/10.1594/PANGAEA.876108.

Name

Description

data_capture

Fraction of valid (hourly) values available in the aggregation period.

average_values

Daily, monthly, … average value. No data capture criterion is applied, i.e. a daily average is valid if at least one hourly value of the day is present.

daytime_avg

Daytime average is defined as average of hourly values for the 12-h period from 08:00h to 19:59h solar time. All hourly values in the aggregation period are averaged, and the resulting value is valid if at least 75% of hourly values are present.

nighttime_avg

Same as daytime_average but accumulated over the daily interval from 20:00 h to 07:59 h solar time.

median

Median mixing ratio over the aggregation period. At least 10 valid values must be present to accept a median value as valid.

perc05

Fifth-percentile of hourly values in the aggregation period. At least 10 valid values must be present to accept a percentile value as valid.

perc10

As perc05, but for the 10th-percentile.

perc25

As perc05, but for the 25th-percentile.

perc75

As perc05, but for the 75th-percentile.

perc90

As perc05, but for the 90th-percentile.

perc95

As perc05, but for the 95th-percentile.

perc98

As perc05, but for the 98th-percentile. This percentile is only calculated for “summer” or “annual” aggregation periods.

dma8epa

Daily maximum 8-hour average statistics according to the US EPA definition. 8-hour averages are calculated for 24 bins starting at 0 h local time. The 8-h running mean for a particular hour is calculated on the concentration for that hour plus the following 7 hours. If less than 75% of data are present (i.e. less than 6 hours), the average is considered missing.

When the aggregation period is “seasonal”, “summer”, or “annual”, the 4th highest daily 8-hour maximum of the aggregation period will be computed.

Note that in contrast to the official EPA definition, a daily value is considered valid if at least 1 8-hour average is valid.

dma8epa_strict

As dma8epa, but additionally, a diurnal 8-hour maximum value is only saved if at least 18 out of the 24 8-hour averages are valid. This is the official dma8epa definition.

dma8epax

As dma8epa, but using the new US EPA definition of the daily 8-hour window from 7 h local time to 23 h local time.

dma8epax_strict

As dma8epax, but additionally, a diurnal 8-hour maximum value is only saved if at least 13 out of the 17 8-hour averages are valid. This is the official dma8epax definition.

dma8eu

As dma8epa, but using the EU definition of the daily 8-hour window starting from 17 h of the previous day.

When the aggregation period is “seasonal”, “summer”, or “annual”, the 26th highest daily 8-hour maximum of the aggregation period will be computed.

dma8eu_strict

As dma8eu, but additionally, a diurnal 8-hour maximum value is only saved if at least 18 out of the 24 8-hour averages are valid. This is the official dma8eu definition.

avgdma8epax

Average value of the daily dma8epax statistics during the aggregation period.

drmdmax1h

Maximum of the 3-months running mean of daily maximum 1-hour mixing ratios during the aggregation period.

This statistics also produces day_of_max_drmdmax1h, which is the Julian day in the year when the maximum value of the 3-months running mean of daily maximum 1-hour concentrations occurred.

somo10

Sum of excess of daily maximum 8-h means (EU Airbase standard with relaxed criterion: dma8eu) over the cut-off of 10 ppb, i.e. 20 μg/m3 calculated for all days in the aggregation period. SOMO10 will be set to missing if less than 75% of days are available. The quantity will be weighted by the number of theoretical days over the number of available days.

somo10_strict

As somo10, but using dma8eu_strict for data capture.

somo35

As somo10, but accumulating ozone values above 35 ppb.

somo35_strict

As somo10_strict, but accumulating ozone values above 35 ppb.

w90

Daily maximum W90 5-h Experimental Exposure Index:

EI = SUM(wiCi) with weight wi = 1/[1 +M exp(-ACi/1000)], where M = 1400, A = 90, and where Ci is the hourly average O3 mixing ratio in units of ppb (Lefohn et al., 2010). For each day, 24 W90 indices are computed as 5-hour sums, requiring that at least 4 of the 5 hours are valid data (75%). If a sample consists of only 4 data points, a fifth value shall be constructed from averaging the 4 valid mixing ratios.

For aggregation periods “month”, “season”, “summer”, or “annual”, the 4th highest W90 value is computed, but only if at least 75% of days in this period have valid W90 values.

aot40

Daily 12-h AOT40 values are accumulated using hourly values for the 12-h period from 08:00h until 19:59h solar time interval. AOT40 is defined as cumulative ozone above 40 ppb. If less than 75% of hourly values (i.e. less than 9 out of 12 hours) are present, the cumulative AOT40 is considered missing. When there exist 75% or greater data capture in the daily 12-h window, the scaling by fractional data capture (ntotal/nvalid) is utilized.

For monthly, seasonal, summer, or annual statistics, the daily AOT40 values are accumulated over the aggregation period and scaled by (ntotal/nvalid) days. If less than 75% of days are valid, the value is considered missing.

daylight_aot40

As aot40, but using solar elevation > 5 degrees to identify “daytime” hours.

w126

Daily W126 index is accumulated using hourly values for the 12-h period from 08:00h until 19:59h solar time interval. W126 = SUM(wiCi) with weight wi = 1/[1 +M exp(-ACi/1000)], where M = 4403, A = 126, and where Ci is the hourly average O3 mixing ratio in units of ppb. If there are less than 9 valid hourly values in the 12 hour window, the daily value is considered missing. When there exist 75% or greater data capture in the daily 12-h window, the scaling by fractional data capture (ntotal/nvalid) is utilized.

Seasonal, summer, or annual statistics are calculated as sum over the daily W126 values. Results are marked as missing if less than 75% of daily values are valid.

w126_24h

As w126, but using all 24 hours of a day.

nvgt050

Number of days with exceedance of the dma8epax value above 50 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt060

Number of days with exceedance of the dma8epax value above 60 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt070

Number of days with exceedance of the dma8epax value above 70 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt080

Number of days with exceedance of the dma8epax value above 80 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt090

Number of days with exceedance of the daily max1h_values above 90 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt100

Number of days with exceedance of the daily max1h_values above 100 ppb. The value is marked as missing if less than 75% of days contain valid data.

nvgt120

Number of days with exceedance of the daily max1h_values above 120 ppb. The value is marked as missing if less than 75% of days contain valid data.

6 Source Code

Gitlab Repository of toarstats