-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
182 lines (148 loc) · 8.1 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)
library(aqsr)
```
# aqsr
R Package for Accessing EPA AQS data
This package provides an R interface for the EPA Air Quality System (AQS) API. Information about the API, including Terms of Service, is available at https://aqs.epa.gov/aqsweb/documents/data_api.html.
### Installation
The `aqsr` package can be installed by running
```{r echo=TRUE, eval=FALSE}
devtools::install_github("jpkeller/aqsr")
```
### Creating a User Key
The AQS API requires an email address and key for all queries. The key is not used for authentication (as in a password), but it is used for identification. Sign-up using the `aqs_signup()` function, and your key phrase will be emailed.
Once an email address and key are registered, assign them to a list in the working environment using `create_user()`. For example:
```{r echo=TRUE, eval=F}
myuser <- create_user(email="myemail@mydomain",
key="mykeyhere")
```
Alternatively, the email address and key can be stored as the environment variables `AQS_EMAIL` and `AQS_KEY`, respectively, to avoid directly storing the values in code that might be part of a public repository. To do this, add the lines
```{r echo=TRUE, eval=FALSE}
AQS_EMAIL="myemail@mydomain"
AQS_KEY="mykeyhere"
```
to the `.Renviron` file in your home directory.
Calling `create_user()` without any argument will then read from these values:
```{r eval=TRUE}
myuser <- create_user() # Use stored credentials for user
```
Care should still be taken to avoid storing the resulting object in a public repository.
All functions for requesting data from the API require that the list generated by `create_user()` be provided in the `aqs_user` argument.
### Available Services
A full list of services provided by the AQS API can be accessed by calling `list_services()`. These services include `sampleData`, `signup`, `list`, and `metaData`, among others. The endpoints for each service are listed in `list_endpoints()`, and the variables required for each endpoint are listed in `list_required_vars()`. For example:
```{r}
# List all services
list_services()
# List endpoints for "dailyData" service
list_endpoints(service="dailyData")
# List variables needed for obtaining data using the "byCounty" endpoint
list_required_vars(endpoint="byCounty")
```
### Available Data
Information on parameter codes and required input for defining data requests can be obtained from the API using `aqs_list()`, `aqs_list_parameters()`, and the related functions.
For example, to list the available parameter classes (groups of parameters), use the function
```{r echo=TRUE, eval=FALSE}
> aqs_list_classes(aqs_user=myuser)
code value_represented
2 AIRNOW MAPS The parameters represented on AirNow maps (88101, 88502, and 44201)
27 ALL Select all Parameters Available
3 AQI POLLUTANTS Pollutants that have an AQI Defined
4 CORE_HAPS Urban Air Toxic Pollutants
5 CRITERIA Criteria Pollutants
6 CSN DART List of CSN speciation parameters to populate the STI DART tool
7 FORECAST Parameters routinely extracted by AirNow (STI)
8 HAPS Hazardous Air Pollutants
9 IMPROVE CARBON IMPROVE Carbon Parameters
10 IMPROVE_SPECIATION PM2.5 Speciated Parameters Measured at IMPROVE sites
11 MET Meteorological Parameters
12 NATTS CORE HAPS The core list of toxics of interest to the NATTS program.
13 NATTS REQUIRED Required compounds to be collected in the National Air Toxics Network
14 PAMS Photochemical Assessment Monitoring System
15 PAMS_VOC Volatile Organic Compound subset of the PAMS Parameters
16 PM COARSE PM between 2.5 and 10 micrometers
17 PM10 SPECIATION PM10 Speciated Parameters
18 PM2.5 CONT NONREF PM2.5 Continuous, Nonreference Methods
19 PM2.5 MASS/QA PM2.5 Mass and QA Parameters
20 SCHOOL AIR TOXICS School Air Toxics Program Parameters
21 SPECIATION PM2.5 Speciated Parameters
22 SPECIATION CARBON PM2.5 Speciation Carbon Parameters
23 SPECIATION CATION/ANION PM2.5 Speciation Cation/Anion Parameters
24 SPECIATION METALS PM2.5 Speciation Metal Parameters
25 UATMP CARBONYL Urban Air Toxics Monitoring Program Carbonyls
26 UATMP VOC Urban Air Toxics Monitoring Program VOCs
```
To list the codes for the criteria air pollutants, use:
```{r echo=TRUE}
aqs_list_parameters(myuser, pc="CRITERIA")
```
### Requesting Data
The primary functions for requesting measurements stored in the AQS database are `aqs_annualData()`, `aqs_dailyData()`, and `aqs_sampleData()`. Variations of each function exist for queries targeting a specific criteria, e.g. `aqs_annualData_byState()`. The underlying function that queries the API is `aqs_get()`, which can be called directly if desired.
### Example Data Requests
#### Example 1
Requesting all PM2.5 measurements (parameter code `88101`) for California (state code `06`) from January 1, 2017 through January 4, 2017:
```{r}
# Sample Data -- By State
s1 <- aqs_sampleData(aqs_user=myuser,
endpoint="byState",
state="06",
bdate="20170101",
edate="20170104",
param="88101")
dim(s1)
s1[1:2,]
```
#### Example 2
Requesting all NO2 measurements (parameter code `42602`) for King County, WA from January 1, 2017 through January 4, 2017. First, we find out the state code for Washington:
```{r eval=TRUE}
state_fips <- aqs_list_states(myuser)
tail(state_fips, 10)
```
From this list, we get that the state code for Washington is `"53"`. Now we find the code for King County:
```{r eval=TRUE}
wa_counties <- aqs_list_counties(myuser, state="53")
head(wa_counties)
```
From these results we see the King County code is `"033"`.We now request the sample:
```{r}
s2 <- aqs_sampleData(aqs_user=myuser,
endpoint="byCounty",
state="53",
county="033",
bdate="20170101",
edate="20170110",
param="42602")
s2[1:2,]
```
#### Example 3
We could also request data for site `530330030` in King County:
```{r}
s3 <- aqs_sampleData(aqs_user=myuser,
endpoint="bySite",
state="53",
county="033",
site="0030",
bdate="20170201",
edate="20170210",
param="42602")
s3[1:2,]
```
#### Example 4
Data can be requested by metropolitan area, specifically Core-based Statistical Area (CBSA).
```{r eval=FALSE}
aqs_list(myuser, endpoint="cbsas")
```
From this output (hidden here for brevity), we see that the CBSA code for the greater Atlanta, GA region is `12060`. We can now request all PM2.5 observations from March 1, 2017 in the Atlanta-Sandy Springs-Roswell CBSA:
```{r}
s4 <- aqs_sampleData(aqs_user=myuser,
endpoint="byCBSA",
cbsa="12060",
bdate="20170301",
edate="20170301",
param="88101")
s4[1:2,]
```