This function augments monitor$meta with summary information derived
from monitor$data reflecting recent measurements.
monitor_getCurrentStatus(
monitor,
enddate = NULL,
minHours = 18,
dayBoundary = c("clock", "LST")
)mts_monitor object.
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.
Minimum number of valid hourly records required to calculate
yesterday_PM2.5_avg. Days with fewer valid records will be assigned NA.
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.)
The monitor$meta table augmented with current status
information for each time series.
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.
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).
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:
Time at which this function was run
Time relative to which "currency" is calculated
Row index of the last valid mesurement in monitor$data
Row index of the previous valid measurement in monitor$data
UTC time associated with last_validIndex
UTC time associated with previous_validIndex
Hours between last_validTime and endtime
Hours between previous_validTime andlast_validTime
Local time representation of last_validTime
Local time representation of previous_validTime
Last valid PM2.5 measurement
Previous valid PM2.5 measurement
Last valid PM2.5 NowCast value
Previous valid PM2.5 NowCast value
Daily average PM2.5 for the day prior to enddate
# \donttest{
# 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)
# }