Skip to content

Metrics in measurements

Metric

A metric brings together several notions into a reportable quantity

  • What is sensed (e.g. PM2.5, NO2, Wind)
  • A measurable trait of above (e.g. Mass concentration, Speed, Compass direction)
  • The aggregation applied (e.g. No aggregation, 1-Hour mean, 24-hour mean)
  • The units or pollution index applied (e.g. μg/m³, ppb, US EPA AQI)
  • QC Assessment and QC Flags (e.g. device returned out-of-bounds value in PM sensor)

Attributes within a metric

Some metrics have ready-to-use values directly from the sensor. No further processing occurs. Examples are temperature, relative humidity and wind. Other metrics have raw data that can benefit from further processing in the cloud. We call these metrics cloud-calibrated. Examples are PM2.5 and NO2.

  • Direct from sensor: raw and value are the same
  • Cloud-calibrated: raw is from sensor, value is cloud-calibrated

This means you can consistently access the same attribute regardless of metric, with value being most appropriate for visualization and analysis. Keep an eye on the status field though (see Status table below). If the response is a JSON format, the attributes are in an object, like this (where the word metric is a name from the metrics dictionary)

   ...
   "metric": {
       "raw":
       "value":
       "status":
   }
   ...

If the response is tabular, like CSV or Parquet, the attributes are dot-notation column headers like this:

    ..., metric.raw, metric.value, metric.status...

You may optionally request qc information, these fields, when available, are added beside the raw/metric/value fields:

   ...
   "metric": {
       "raw":
       "value":
       "status":
       "qc":
       "qcFlags":
   }
   ...
or as separate columns in the column-oriented formats:
    ..., metric.qc, metric.qcFlags, metric.raw, metric.value, metric.status...

Attribute details

Clarity Node - metric is direct from sensor

attribute description
raw The sensed value direct from the device
value Same as raw
status sensor-ready

Clarity Node - metric can be cloud-calibratred

attribute description
raw The sensed value direct from the device
value The calibration result. null if calibration has not occurred
status see table below

status for cloud-calibrated metrics

status description
calibration-missing No calibrated value because a calibration was not assigned to the device durign the last processing
calibration-processing Calibration is in process
calibrated-reprocessing A calibrated value exists and a newer calibration is in process
calibration-error Calibration failed for the data coming from the device
calibrated-ready Calibration has completed
calibrated-mixed Only for aggregations:
The individual samples in the aggregation period do not all have the same calibration-status. To understand the mix of statuses, fetch the individual measurements

For reference sites

attribute description
raw null
value The value direct from the reference provider
status reference-ready

If you request QC Assessment and/or QC Flags be included in the response, they appear only on node measurements. They may be ommitted from reference sites in json formats or empty in the column-based formats.

attribute description
qcAssessment Either valid or invalid or empty
qcFlags A json array of strings. The strings detail the reasons for an invalid QC Assessment. See the Knowledge Base article on QC Flags.

JSON Arrays are encoded in CSV output

For example, to transmit this JSON array in the qcFlag field: ["QC.I.OOB.002","QC.I.OOB.001"]
The CSV file will use this encoding: "[""QC.I.OOB.002"",""QC.I.OOB.001""]"
We recommend using a CSV parsing library like those built into Python or Pandas to correctly process these encodings.

Output frequency

The fields a measurement contains depend on the output frequency of the measurement. Your request to retrieve measurements includes an outputFrequency. Tables below list all the possible metrics, by output frequency.

Output frequency type of measurement
minute An individual sample, received from a deployed device, containing everything that device sends.
hour An hourly aggregation.
day A daily aggregation, where a new day is defined in UTC time

Limit what gets returned

By default, each measurement will be reported with many metrics. Sometimes, you may want to control which metrics within each measurement are returned. You can do this with the metricsSelect parameter. Here are a few examples. See Metrics selection for more details.

Selector example of returns in the measurement
only :pm Colon : category matching metrics in the PM category
only no2*aqi Star * pattern matching metrics whose name starts with no2 and ends with aqi
all - :blackcarbon Removal - from set all metrics minus any in the black carbon category