rnassqs v0.5.0

0

Monthly downloads

0th

Percentile

Access the NASS 'Quick Stats' API

Interface to access data via the United States Department of Agriculture's National Agricultural Statistical Service (NASS) 'Quick Stats' web API <https://quickstats.nass.usda.gov/api>. Convenience functions facilitate building queries based on available parameters and valid parameter values.

Readme

rnassqs Usage Release Development
rnassqs hexsticker (Wheat image from here) License CRAN Last Change
downloads Zenodo Build Status
Coverage Status
ORCID Project Status: Active – The project has reached a stable, usable state and is being actively developed.
Project Status: Maturing.


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://ropensci.github.io/rnassqs/.

Installing

Install the package via devtools or CRAN:

    # 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. 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:

    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 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, you can use:

    library(nassqs)

    # 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:

    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:

    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:

    # 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:

    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 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/.
  • File an issue: If there is functionality you’d like to see added or something that is confusing, consider creating an issue. The best issue contains an example of the problem or feature. Consider the excellent package 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. Following this style makes the pull request and review go more smoothly.

Alternatives

In June 2019 the usdarnass package was released on CRAN and is also available to install via github. 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 FTP site.

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.

Acknowledgements

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!

ropensci\_footer

Functions in rnassqs

Name Description
nassqs_auth Get/Set the environmental variable NASSQS_TOKEN to the API key
nassqs_params Return list of NASS QS parameters.
rnassqs-package rnassqs-package: Access the NASS 'Quick Stats' API
nassqs_param_values Get all values for a specific parameter.
nassqs_yields Get yield records for a specified crop.
nassqs_check Check the response.
nassqs_fields Deprecated: Return list of NASS QS parameters.
nassqs_parse Parse a response object from nassqs_GET().
nassqs_record_count Get a count of number of records for given parameters.
nassqs_acres Get NASS Area given a set of parameters.
nassqs_GET Issue a GET request to the NASS 'Quick Stats' API
nassqs Get data and return a data frame
No Results!

Vignettes of rnassqs

Name
rnassqs.Rmd
No Results!

Last month downloads

Details

Type Package
URL https://github.com/ropensci/rnassqs
BugReports http://www.github.com/ropensci/rnassqs/issues
License MIT + file LICENSE
LazyData TRUE
Language en-US
RoxygenNote 6.1.1
Encoding UTF-8
VignetteBuilder knitr
NeedsCompilation no
Packaged 2019-08-19 16:29:15 UTC; potterzot
Repository CRAN
Date/Publication 2019-08-19 19:10:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/rnassqs)](http://www.rdocumentation.org/packages/rnassqs)