Create a new PurpleAir hourly timeseries dataset.

Source: R/pat_createHourly.R

Create a pat object for a specific sensor_index. This function splits up the requested time range into 2-day intervals (the maximum allowed by the PurpleAir API) and makes repeated calls to pat_downloadParseRawData(). The sleep parameter waits a small amount of time between API requests.

The PurpleAir API will respond with "rate limiting" errors unless sleep is set appropriately. When parallel = TRUE, sleep is ignored.

By default, the only variables included in an "hourly pat" are: datetime, humidity, temperature, pm2.5_atm, pm2.5_atm_a, pm2.5_atm_b. These are sufficient for simple QC using pm2.5_atm_a, pm2.5_atm_b and simple correction using linear fit models based on pm2.5_atm, temperature, humidity.

pat_createHourly(
  api_key = NULL,
  pas = NULL,
  sensor_index = NULL,
  startdate = NULL,
  enddate = NULL,
  timezone = "UTC",
  fields = PurpleAir_PAT_EPA_HOURLY_FIELDS,
  sleep = 0.5,
  parallel = FALSE,
  baseUrl = "https://api.purpleair.com/v1/sensors",
  verbose = TRUE
)

Arguments

api_key

PurpleAir API Read Key. If api_key = NULL, it will be obtained using getAPIKey("PurpleAir-read"). See MazamaCoreUtils::setAPIKey.

pas

Previously generated pas object containing sensor_index.

sensor_index

PurpleAir sensor unique identifier.

startdate

Desired start time (ISO 8601) or POSIXct.

enddate

Desired end time (ISO 8601) or POSIXct.

timezone

Olson timezone used to interpret dates.

fields

Character string with PurpleAir field names for the Get Sensor Data API.

sleep

Seconds to sleep between API requests.

parallel

Logical specifying whether to attempt simultaneous downloads using parallel::mcparallel. (Not available on Windows.)

baseUrl

Base URL for the PurpleAir API.

verbose

Logical controlling the generation of warning and error messages.

Value

A PurpleAir Timeseries pat object.

Note

Parallel processing using parallel = TRUE is not available on Windows machines.

Examples

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

# AirSensor2 package
library(AirSensor2)

# Set user's PurpleAir_API_READ_KEY
source('global_vars.R')
setAPIKey("PurpleAir-read", PurpleAir_API_READ_KEY)

# Initialize spatial datasets
initializeMazamaSpatialUtils()

pat <-
  pat_createHourly(
    pas = example_pas_pm25,
    sensor_index = "76545",
    startdate = "2023-01-01",
    enddate = "2023-01-08",
    timezone = "UTC",
    verbose = TRUE
  )

View(pat$data[1:100,])

}, silent = FALSE)
#> Warning: cannot open file 'global_vars.R': No such file or directory
#> Error in file(filename, "r", encoding = encoding) : 
#>   cannot open the connection
# }