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 |
| 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:
Daily AQI value for the day prior to endTime
Last valid NowCast measurement
Last valid raw PM2.5 measurement
Mean of the last valid raw PM2.5 measurementwith the preceding two measurements
Previous valid NowCast measurement
Previous valid raw PM2.5 measurement
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:
NowCast level at the last valid time
NowCast level at the previous valid time
Monitor not reporting for more than 6 hours
New monitor reporting in the last 6 hours
NowCast level increased to Unhealthy for Sensitive Groups in the last 6 hours
NowCast level increased to Unhealthy in the last 6 hours
NowCast level increased to Very Unhealthy in the last 6 hours
NowCast level increased to Hazardous in the last 6 hours
NowCast level decreased to Moderate or Good in the last 6 hours
Monitor malfunctioning the last 6 hours (not currently implemented)
# \donttest{ # 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) # }