monitor_getCurrentStatus {AirMonitor}

Get current status of monitors

Description

This function augments monitor$meta with summary information derived from monitor$data reflecting recent measurements.

Usage

monitor_getCurrentStatus(
  monitor,
  enddate = NULL,
  minHours = 18,
  dayBoundary = c("clock", "LST")
)

Arguments

monitor

mts_monitor object.

enddate

Time relative to which current status is calculated. By default, it is the latest time in monitor$data$datetime. This time can be given as a POSIXct time, or a string/numeric value in ymd format (e.g. 20190301). This time converted to UTC.

minHours

Minimum number of valid hourly records required to calculate yesterday_PM2.5_avg. Days with fewer valid records will be assigned NA.

dayBoundary

Treatment of daylight savings time: "clock" uses daylight savings time as defined in the local timezone, "LST" uses "local standard time" all year round. (See monitor_dailyStatistic() for more details.)

Value

The monitor$meta table augmented with current status information for each time series.

"Last" and "Previous"

The goal of this function is to provide useful information about what happened recently with each time series in the provided mts_monitor object. Devices don't always consistently report data, however, and it is not alwlays useful to have NA's reported when there is recent valid data at earlier times. To address this, monitor_getCurrentStatus() uses last and previous valid times. These are the time when a monitor most recently reported data, and the most recent time of valid data before that, respectively. By reporting on these times, this function ensures that valid data is returned and provides information on how outdated this information is. This information can be used in maps to show AQI colored dots when data is only a few hours old but gray dots when data is older than some threshold.

Calculating latency

According to https://docs.airnowapi.org/docs/HourlyDataFactSheet.pdf a datum assigned to 2pm represents the average of data between 2pm and 3pm. So, if we check at 3:15pm and see that we have a value for 2pm but not 3pm then the data are completely up-to-date with zero latency.

monitor_getCurrentStatus() defines latency as the difference between a time index and the next most recent time index associated with a valid value. If there is no more recent time index, then the difference is measured to the given enddate parameter. Because mts_monitor objects are defined on an hourly axis, these differences have units of hours.

For example, if the recorded values for a monitor are [16.2, 15.8, 16.4, NA, 14.0, 12.5, NA, NA, 13.3, NA], then the last valid value is 13.3 with an index is 9, and the previous valid value is 12.4 with an index of 6. The last latency is then 1 (hour before the end), and the previous latency is 3 (hours before the last valid value).

Summary data

The table created by monitor_getCurrentStatus() includes per-time series summary information calculated from monitor$data. The additional data fields added to monitor$meta are listed below:

currentStatus_processingTime

Time at which this function was run

currentStatus_enddate

Time relative to which "currency" is calculated

last_validIndex

Row index of the last valid mesurement in monitor$data

previous_validIndex

Row index of the previous valid measurement in monitor$data

last_validTime

UTC time associated with last_validIndex

previous_validTime

UTC time associated with previous_validIndex

last_latency

Hours between last_validTime and endtime

previous_latency

Hours between previous_validTime andlast_validTime

last_validLocalTimestamp

Local time representation of last_validTime

previous_validLocalTimestamp

Local time representation of previous_validTime

last_PM2.5

Last valid PM2.5 measurement

previous_PM2.5

Previous valid PM2.5 measurement

last_nowcast

Last valid PM2.5 NowCast value

previous_nowcast

Previous valid PM2.5 NowCast value

yesterday_PM2.5_avg

Daily average PM2.5 for the day prior to enddate

Examples

# Fail gracefully if any resources are not available
try({

library(AirMonitor)

monitor <- airnow_loadLatest()
# TODO:  Needed before rebuilding of v2 database with fullAQSID
monitor$meta$fullAQSID <- paste0("840", monitor$meta$AQSID)

currentStatus <-
  monitor %>%
  monitor_filter(stateCode == "WA") %>%
  monitor_getCurrentStatus()

}, silent = FALSE)