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)
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
andvalue
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, ...
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 |
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 |