monitor_getCurrentStatus: Get current status of monitors
In PWFSLSmoke: Utilities for Working with Air Quality Monitoring Data

Description Usage Arguments Value "Last" and "Previous" Calculating latency Summary data Event flags Examples

View source: R/monitor_getCurrentStatus.R

This function augments the metadata from a ws_monitor object with summarized and aggregate data from the ws_monitor object.

monitor_getCurrentStatus(
  ws_monitor,
  endTime = NULL,
  monitorURLBase = "http://tools.airfire.org/monitoring/v4/#!/?monitors="
)

`ws_monitor`	ws_monitor object.
`endTime`	Time to which the status of the monitors will be current. By default, it is the most recent time in `ws_monitor`. This time can be given as a POSIXct time, or a string/numeric value in ymd format (eg. 20190301). This time converted to UTC.
`monitorURLBase`	A URL prefix pointing to where more information about a monitor can be found. By default, it points to the AirFire monitoring site.

A table containing the current status information for all the monitors in ws_monitor.

The goal of this function is to provide useful information about what happened recently with each monitor in the provided ws_monitor object. Monitors sometimes don't consistently report data, however, and it's not useful to have NA's reported when there is still valid data at other 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, the function ensures that valid data is returned and provides information on how outdated this information is.

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 in time between the given time index and the next most recent time index. If there is no more recent time index, then the difference is measured to the given endTime parameter. These differences are recorded in 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 time index is 9, and the previous valid time index is 6. The last latency is then 1 (hour), and the previous latency is 3 (hours).

The table created by monitor_getCurrentStatus() includes summary information for the data part of the given ws_monitor object. The summaries included are listed below with a description:

yesterday_pm25_24hr: Daily AQI value for the day prior to endTime
last_nowcast_1hr: Last valid NowCast measurement
last_PM2.5_1hr: Last valid raw PM2.5 measurement
last_PM2.5_3hr: Mean of the last valid raw PM2.5 measurementwith the preceding two measurements
previous_nowcast_1hr: Previous valid NowCast measurement
previous_PM2.5_1hr: Previous valid raw PM2.5 measurement
previous_PM2.5_3hr: Mean of the previous valid raw PM2.5 measurement with the preceding two measurements

It should be noted that all averages are "right-aligned", meaning that the three hour mean of data at time n will comprise of the data at times [n-2, n-1, n]. Data for n-2 and n-1 is not guaranteed to exist, so a three hour average may include 1 to 3 data points.

The table created by monitor_getCurrentStatus() also includes binary flags representing events that may have occurred for a monitor within the bounds of the specified end time and data in the ws_monitor object. Each flag is listed below with its corresponding meaning:

last_nowcastLevel: NowCast level at the last valid time
previous_nowcastLevel: NowCast level at the previous valid time
NR6: Monitor not reporting for more than 6 hours
NEW6: New monitor reporting in the last 6 hours
USG6: NowCast level increased to Unhealthy for Sensitive Groups in the last 6 hours
U6: NowCast level increased to Unhealthy in the last 6 hours
VU6: NowCast level increased to Very Unhealthy in the last 6 hours
HAZ6: NowCast level increased to Hazardous in the last 6 hours
MOD6: NowCast level decreased to Moderate or Good in the last 6 hours
MAL6: Monitor malfunctioning the last 6 hours (not currently implemented)

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

library(PWFSLSmoke)

ws_monitor <- monitor_loadLatest() %>% monitor_subset(stateCodes = "WA")
statusTbl <- monitor_getCurrentStatus(ws_monitor)

}, silent = FALSE)