-
Notifications
You must be signed in to change notification settings - Fork 18
/
README.Rmd
254 lines (189 loc) · 10.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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
---
output:
md_document:
variant: gfm
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<table class="table">
<thead>
<tr class="header">
<th align="left">
rnassqs
</th>
<th align="left">
Usage
</th>
<th align="left">
Release
</th>
<th align="left">
Development
</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td rowspan="5">
<a href="https://docs.ropensci.org/rnassqs/"><img src="man/figures/logo.png" alt="rnassqs" align="right" height="139"></a>
<p style="font-size:xx-small;">(Wheat image from <a href="https://www.flickr.com/photos/53018729@N00/2669034542">here</a>.)</p>
</td>
<td align="left">
<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/github/license/mashape/apistatus.svg" alt="License"></a>
</td>
<td align="left">
<a href="https://cran.r-project.org/package=rnassqs"><img src="https://www.r-pkg.org/badges/version-last-release/rnassqs" alt="CRAN"></a>
</td>
<td align="left">
<a href="https://github.com/ropensci/rnassqs/commits/main"><img src="https://img.shields.io/badge/last%20change-`r gsub('-', '--', Sys.Date())`-brightgreen.svg" alt="Last Change"></a>
</td>
</tr>
<tr class="even">
<td align="left">
<a href="https://CRAN.R-project.org/package=rnassqs"><img src="https://cranlogs.r-pkg.org/badges/rnassqs" alt="downloads"></a>
</td>
<td align="left">
<a href="https://zenodo.org/badge/latestdoi/37335585"><img src="https://zenodo.org/badge/37335585.svg" alt="Zenodo"></a>
</td>
<td align="left">
<a href="https://github.com/ropensci/rnassqs/actions/workflows/R-CMD-check.yaml"><img src="https://github.com/ropensci/rnassqs/actions/workflows/R-CMD-check.yaml/badge.svg" alt="R CMD Check"></a>
</td>
</tr>
<tr class="odd">
<td align="left">
</td>
<td align="left">
<a href="https://github.com/ropensci/software-review/issues/298" alt="rOpensci reviewed!"><img src="https://badges.ropensci.org/298_status.svg"></a>
</td>
<td align="left">
<a href="https://app.codecov.io/gh/ropensci/rnassqs?branch=main"><img src="https://codecov.io/gh/ropensci/rnassqs/branch/main/graph/badge.svg" alt="Codecov test status"></a>
</td>
</tr>
<tr class="even">
<td align="left">
</td>
<td align="left">
<a href="https://orcid.org/0000-0002-3410-3732"><img src="https://img.shields.io/badge/ORCiD-0000--0002--3410--3732-green.svg" alt="ORCID"></a>
</td>
<td align="left">
<a href="https://www.repostatus.org/#active"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Project Status: Active – The project has reached a stable, usable state and is being actively developed." /></a>
</td>
</tr>
<tr class="even">
<td align="left">
</td>
<td align="left">
<a style="border-width:0" href="https://joss.theoj.org/papers/10.21105/joss.01880">
<img src="https://joss.theoj.org/papers/10.21105/joss.01880/status.svg" alt="DOI:10.21105/joss.01880" >
</a>
</td>
<td align="left">
<a href="https://lifecycle.r-lib.org/articles/stages.html#maturing"><img src="https://img.shields.io/badge/lifecycle-maturing-blue.svg" alt="Project Status: Maturing." /></a>
</td>
<td align="left">
</td>
</tr>
<tr class="odd">
<td align="left">
</td>
<td align="left">
</td>
<td align="left">
</td>
</tr>
</tbody>
</table>
<br>
__As required by the NASS Terms of Use: This product uses the NASS API but is not endorsed or certified by NASS.__
## rnassqs (R NASS Quick Stats)
`rnassqs` allows users to access the USDA's National Agricultural Statistics Service (NASS) Quick Stats data through their API. It is simple and easy to use, and provides some functions to help navigate the bewildering complexity of some Quick Stats data.
For docs and code examples, visit the package web page here: [https://docs.ropensci.org/rnassqs/](https://docs.ropensci.org/rnassqs/).
## Installing
Install the package via `devtools` or CRAN:
```{r eval=FALSE}
# Via devtools
library(devtools)
install_github('ropensci/rnassqs')
# Via CRAN
install.packages("rnassqs")
```
## API Key
To use the NASS Quick Stats API you need an [API key](https://quickstats.nass.usda.gov/api/). The API key should in general not be included in scripts. One way of making the key available without defining it in a script is by setting it in your `.Renviron` file, which is usually located in your home directory. If you are an `rstudio` user, you can use `usethis::edit_r_environ()` to open your `.Renviron` file and add a line that looks like:
```{r eval=FALSE}
NASSQS_TOKEN="<your api key here>"
```
Alternatively, you can set it explicitly in the console with `nassqs_auth(key = <your api key>)`. This will set the environmental variable NASSQS_TOKEN, which is used to access the API. You can also set this directly with `Sys.setenv("NASSQS_TOKEN" = <your api key>)`.
## Usage
See the examples in [inst/examples](inst/examples) for quick recipes to download data.
The primary function is `nassqs()`, with which you can make any query of variables.
For example, to mirror the request that is on the [NASS API documentation](https://quickstats.nass.usda.gov/api/), you can use:
```{r eval=FALSE}
library(rnassqs)
# You must set your api key before requesting data
nassqs_auth(key = <your api key>)
# Parameters to query on and data call
params <- list(commodity_desc = "CORN", year__GE = 2012, state_alpha = "VA")
d <- nassqs(params)
```
Parameters __do not__ need to be capitalized, and also do not need to be in a list format. The following works just as well:
```{r eval=FALSE}
d <- nassqs(commodity_desc = "corn", year__GE = 2012, state_alpha = "va")
```
You can request data for multiple values of the same parameter by using a simple list as follows:
```{r eval=FALSE}
params <- list(commodity_desc = "CORN", year__GE = 2012, state_alpha = c("VA", "WA"))
d <- nassqs(params)
```
NASS does not allow GET requests that pull more than 50,000 records in one request. The function will inform you if you try to do that. It will also inform you if you've requested a set of parameters for which there are no records.
Other useful functions include:
```{r eval=FALSE}
# returns a set of unnique values for the parameter "STATISTICCAT_DESC"
nassqs_param_values("statisticcat_desc")
# returns a count of the number of records for a given query
nassqs_record_count(params=params)
# Get yields specifically
# Equivalent to including "'statisticat_desc' = 'YIELD'" in your parameter list.
nassqs_yields(params)
# Get acres specifically
# Equivalent to including all "AREA" values in statisticcat_desc
nassqs_acres(params)
# Specifies just "AREA HARVESTED" values of statisticcat_desc
nassqs_acres(params, area = "AREA HARVESTED")
```
### Handling inequalities and operators other than "="
The NASS API handles other operators by modifying the variable name. The API can accept the following modifications:
* __LE: <=
* __LT: <
* __GT: >
* __GE: >=
* __LIKE: like
* __NOT_LIKE: not like
* __NE: not equal
For example, to request corn yields in Virginia and Pennsylvania for all years since 2000, you would use something like:
```{r eval=FALSE}
params <- list(commodity_desc = "CORN",
year__GE = 2000,
state_alpha = c("VA", "PA"),
statisticcat_desc = "YIELD")
df <- nassqs(params) #returns data as a data frame.
```
See the [vignette](https://docs.ropensci.org/rnassqs/articles/rnassqs.html) for more examples and details on usage.
## Contributing
Contributions are more than welcome, and there are several ways to contribute:
- Examples: More examples are always helpful. If you use `rnassqs` to query data from 'Quick Stats' and would like to contribute your query, consider submitting a pull request adding your query as a file in [inst/examples/](https://github.com/ropensci/rnassqs/tree/main/inst/examples).
- File an issue: If there is functionality you'd like to see added or something that is confusing, consider [creating an issue](https://github.com/ropensci/rnassqs/issues/new). The best issue contains an example of the problem or feature. Consider the excellent package [reprex](https://github.com/tidyverse/reprex) in creating a reproducible example.
- Contributing documentation: Clarifying and expanding the documentation is always appreciated, especially if you find an area that is lacking and would like to improve it. `rnassqs` uses roxygen2, which means the documentation is at the top of each function definition. Please submit any improvements as a pull request.
- Contributing code: if you see something that needs improving and you'd like to make the changes, contributed code is very welcome. Begin by filing a new issue to discuss the proposed change, and then submit a pull request to address the issue. `rnassqs` follows the style outlined in Hadley Wickham's [R Packages](https://r-pkgs.org/code.html#code-style). Following this style makes the pull request and review go more smoothly.
## Alternatives
In June 2019 the `usdarnass` package was released on [CRAN](https://cran.r-project.org/package=usdarnass) and is also available to install via [github](https://github.com/rdinter/usdarnass). `usdarnass` has similar functionality to this package.
NASS also provides a daily tarred and gzipped file of their entire dataset. At the time of writing it is approaching 1 GB. You can download that file via their [data site](https://www.nass.usda.gov/datasets/).
The FTP link also contains builds for: NASS census (every 5 years ending with 2 and 7), or data for one of their specific sectors (CROPS, ECONOMICS, ANIMALS & PRODUCTS). At the time of this writing, specific files for the ENVIRONMENTAL and DEMOGRAPHICS sectors are not available.
### Acknowledgments
Thank you to rOpensci reviewers Adam Sparks and Neal Richardson and editor Lincoln Mullen, for their fantastic feedback and assistance. User feedback and use case contributions have been a huge help to make `rnassqs` more accessible and user-friendly. More use cases or feature requests are always welcome!
[](https://ropensci.org)
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```