NEWS.md
Updated various examples that referenced example_pas with the newer example_pas_pm25.
pat_create() that generated:Elements `last_modified`, `privacy`, `model`, `hardware`, `firmware_version`, etc. don't exist.Updated all Clarity functions to default to format = "USFS2" which returns two extra fields: calibrationId, calibrationCategory.
Updated the of data that can be requested in a single call in pat_create() to match updates to the PurpleAir API:
| Average Period | Previous Limit | New Limit |
|---|---|---|
| Real-Time | 2 Days | 30 Days |
| 10 Minutes | 3 Days | 60 Days |
| 30 Minutes | 7 Days | 90 Days |
| 1 Hour | 14 Days | 180 Days |
| 6 Hours | 90 Days | 1 Year |
| 1 Day | 1 Year | 2 Years |
pat_createNew() now checks for and removes duplicate timesteps and guarantees that the returned object has class name ‘sts’ for “SingleTimeSeries” so that it can work with functions from MazamaTimeSeries.pat_toMonitor() that always complained about missing fields.sensor_index field returned from PurpleAir was sometimes interpreted as an integer instead of a character. (Identifiers should always be of character type as in “007” for James Bond.)pat_downloadParseRawData() where timestamps representing number of seconds sometimes used exponential notation which the PurpleAir API does not understand. Example of the bug:> MazamaCoreUtils::parseDatetime("2023-05-02 03:59:59", timezone = "UTC") %>% as.numeric()
[1] 1.683e+09Version 0.5 introduces changes in the default parameters that are requested when making data requests from the PurpleAir API. In the past, when data was free, functions download as many potentially relevant parameters as possible. Now that a payment system is in place, AirSensor2 will be focused on downloading as few parameters as required to accomplish a task. Many of the low level PurpleAir data access functions will thus behave differently.
Package dependency updates:
MazamaCoreUtils (>= 0.5.2)
MazamaLocationUtils (>= 0.4.3),
MazamaSpatialUtils (>= 0.8.6),
MazamaTimeSeries (>= 0.3.0),
AirMonitor (>= 0.4.0),pas_downloadParseRawData() defaults to only query for non-measurement fields defined in PurplAir_SENSOR_METADATA_FIELDS.pas_filterDate() to help find historical sensor data.pas_filterNearMonitor() to associate sensors with the closest available monitor in a mts_monitor object from the AirMonitor package.pas_get() to pas_pull().pas_createNew() and pas_leaflet() to default to working with non-measurement fields defined in PurplAir_SENSOR_METADATA_FIELDS.pas_lifespanPlot() to show when PurpleAir sensors were producing data.PurpleAir_PAS_MINIMAL_FIELDSPurpleAir_PAS_METADATA_FIELDSPurpleAir_PAS_AVG_PM25_FIELDSPurpleAir_PAList_PM25_FIELDSPurpleAir_PAT_QC_FIELDSPurpleAir_PAT_EPA_HOURLY_FIELDSsleep parameter to pat_create() to avoid “rate limiting” errors from the PurpleAir API.PurpleAir_createNewMonitor().pat_toMonitor().pat_createNew() to pat_create().pat_createRaw().Updated to handle changes in upstream packages:
The breaking change that precipitated this was the change from 'zip' to 'postalCode' in the core metadata used by MazamaLocationUtils. For backwards compatibility, all functions that work with metadata will guarantee that both 'zip' and 'postalCode' exist. These include:
Clarity_createAllOpenMonitors() to create a monitor object using the most recent 3 hours of data. (This is useful in the next function.)Clarity_updateAllOpenMonitors() to append the most recent 3 hours of data to an existing monitor object.parallel = TRUE. (not available on Windows)
pas~() functions.PurpleAir_createMonitor() to PurpleAir_createNewMonitor(). This leaves room for a modified PurpleAir_createMonitor() that will accept a previously saved “hourly pat” object.pm2.5_cf_1, pm2.5_cf_1_a, pm2.5_ f_1_b to PurpleAir_PAT_EPA_HOURLY_FIELDS so that the original EPA correction factor can be used with pm2.5_cf_1.pat_applyCorrection() to apply a correction equation to “hourly pat” data. Default correction uses the correction as described in the documentation.parameter argument for correction_FUN in `PurpleAir_createMonitor().pat_createHourly() as a convenience function for the common case of obtaining hourly aggergated for the following parameters: datetime, temperature, humidity, pm2.5_atm, pm2.5_atm_a, pm2.5_atm_b. Using this function greatly reduces data download volumes and allows for the most common forms of QC and correction.PurpleAir_createMonitor() to directly create monitor objects suitable for use with the AirMonitor package. This is a preliminary version of this function that includes neither QC nor correction.nowcast_QCFlag in the returned data.This version introduces data ingest functions for Clarity “Open” sensor data. In preparation for additional data providers, many of the PurpleAir functions using "pa" as shorthand have been renamed with a more explicit "PurpleAir":
pa_~() functions to PurpleAir_~().PURPLE_AIR_API_~ API keys to PurpleAir_API_~.purple_air_synoptic class to PurpleAir_synoptic.Clarity “Open” datasets are available to those with an API key allowing access to this data. The following functions provide access to Clarity “Open” data:
Clarity_getAllOpenHourly()Clarity_getAllOpenIndividual()Clarity_getOpenHourly()Clarity_getOpenIndividual()Clarity_createOpenSynoptic()Clarity_enhanceRawSynopticData()Clarity_createOpenMonitor()Generic synoptic data from non-PurpleAir providers (similar to PurpleAir ‘pas’ objects) is supported with:
PurpleAir_API_READY_KEY instead of MY_API_READ_KEY.show_only is used, spatial bounding information is ignored in: PurpleAir_getSensorsData(), pas_downloadParseRawData() and pas_createNew().pat_filter()pat_filterDate()pat_filiterDatetime()pat_trimDate()Added full support for the PurpleAir API described at https://api.purpleair.com.
Improvements include wrapper functions for PurpleAir API endpoints:
PurpleAir_PurpleAir_checkApiKey()PurpleAir_getSensorData(), PurpleAir_getSensorHistoryCSV(), PurpleAir_getSensorHistory(), PurpleAir_getSensorsData()
PurpleAir_createGroup(), PurpleAir_createMember(), PurpleAir_delteGroup(), PurpleAir_deleteMember(), PurpleAir_getGroupDetail(), PurpleAir_getGroupsList(), PurpleAir_getMemberData(), PurpleAir_getMemberHistory(), PurpleAir_getMembemrsData()
Additional updates include:
fields strings for PurpleAir_DATA_PM25_FIELDS and PurpleAir_PAT_QC_FIELDS
fields argument to pas_downloadParseRawData().locationID. (See geohashTools for reasons to use a geohash as a unique location identifier.)pas_downloadParseRawData() to use the new wrapper functions.pas_enhanceRawData() and pas_createNew() to harmonize argument names.pat_downloadParseRawData() using the new wrapper functions.pat_create() and example_pat dataset.pat_check(), pat_isValid(), pat_isEmpty(), pat_distinct(), pat_getData(), pat_getMeta().Documentation improvements to include links to PurpleAir Terms of service and Data license.
The AirSensor2 package is a refactoring of the core, data access and manipulation functionality found in the AirSensor package. The goal in AirSensor2 is to create a lean and generic package focused on data ingest and basic data manipulation.
Initial functions to download and work with PurpleAir synoptic data.