Update to version 0.2.0. Includes:

* standardize terminology for 'field' and 'parameter'
* add examples for multiple variables
* update readme for clearer description
* add a vignette to explain use.

.gitignore

@@ -3,3 +3,4 @@
 .RData
 *.Rproj
 .secret
+inst/doc

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: rnassqs
 Type: Package
 Title: R package to pull data from NASS Quickstats
-Version: 0.1.1
+Version: 0.2.0
 Date: 2015-06-12
 Authors@R: person('Nicholas', 'Potter', email='[email protected]', role = c('aut', 'cre'))
 Maintainer: Nicholas Potter <[email protected]>
@@ -14,5 +14,8 @@ Imports:
   httr,
   jsonlite,
 Suggests:
-  testthat
+  testthat,
+    knitr,
+    rmarkdown
 RoxygenNote: 6.0.1
+VignetteBuilder: knitr

NAMESPACE

@@ -5,8 +5,10 @@ export(nassqs.multi)
 export(nassqs.single)
 export(nassqs_GET)
 export(nassqs_area)
+export(nassqs_field_values)
 export(nassqs_fields)
 export(nassqs_param_values)
+export(nassqs_params)
 export(nassqs_parse)
 export(nassqs_record_count)
 export(nassqs_token)

R/data.R

@@ -1,6 +1,6 @@
-#' Return list of NASS QS fields.
+#' Return list of NASS QS parameters.
 #' @export
-nassqs_fields <- function() {
+nassqs_params <- function() {
   c(
     "agg_level_desc",
     "asd_code",
@@ -42,3 +42,10 @@ nassqs_fields <- function() {
     "year",
     "zip_5")
 }
+
+#' Depreciated: Return list of NASS QS parameters.
+#' 
+#' Depreciated. Use \code{nassqs_params()} instead.
+#' @export
+nassqs_fields <- function() { nassqs_params() }
+

R/helpers.R

@@ -4,15 +4,24 @@
 #'
 #' @export
 #'
-#' @param param the name of a NASS quickstats parameter.
-#' @param ... additional parameters passed to \code{\link{nassqs_parse}}.
-#' @return single column data frame containing values for that parameter.
+#' @param field the name of a NASS quickstats field.
+#' @return a list containing values for that parameter.
 #' @examples \dontrun{
 #'   #See all values available for the statisticcat_desc field.
 #'   #Note that this does not provide any filtering, so for a specific
 #'   #set of parameters, not all of the values may be available.
-#'   nassqs_param_values("statisticcat_desc")
+#'   nassqs_field_values("statisticcat_desc")
 #' }
+nassqs_field_values <- function(field) {
+  params = list("field"=field)
+  nassqs_parse(nassqs_GET(params, api_path="get_param_values"), as="list")
+}
+
+#' Depreciated: Get all values for a specific parameter.
+#'
+#' Use \code{nassqs_field_values()} instead.
+#' 
+#' @export
 nassqs_param_values <- function(param, ...) {
   params = list("param"=param)
   nassqs_parse(nassqs_GET(params, ..., api_path="get_param_values"), as="list")

R/nassqs.R

@@ -55,6 +55,8 @@ nassqs_GET <- function(params, # a named list of queries
 }
 
 #' Check the request.
+#' 
+#' Check that the request is valid, i.e. that it doesn't exceed 50,000 records and that all the parameter values are valid. This is helpful for checking a query before submitting it so that you don't have to wait for the query to fail.
 #'
 #' @importFrom jsonlite fromJSON
 #'

README.Rmd

@@ -7,7 +7,7 @@ output:
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 [![ORCiD](https://img.shields.io/badge/ORCiD-0000--0002--3410--3732-green.svg)](http://orcid.org/0000-0002-3410-3732) 
-[![DOI](https://zenodo.org/badge/37335585.svg)](https://zenodo.org/badge/latestdoi/37335585)
+[![DOI](https://zenodo.org/badge/1117419.svg)](https://zenodo.org/badge/latestdoi/1117419)
 [![Licence](https://img.shields.io/github/license/mashape/apistatus.svg)](http://choosealicense.com/licenses/mit/) 
 
 [![Build Status](https://travis-ci.org/potterzot/rnassqs.svg?branch=master)](https://travis-ci.org/potterzot/rnassqs)
@@ -62,13 +62,14 @@ NASS does not allow GET requests that pull more than 50,000 records in one reque
 
 ###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 __LE = <= 
+
+* __LE: <= 
+* __LT: < 
+* __GT: > 
+* __GE: >= 
+* __LIKE: like 
+* __NOT_LIKE: not like 
+* __NE: not equal 
 
 For example, to request corn yields for all years since 2000, you would use something like:
 

README.md

@@ -1,61 +1,89 @@
 <!-- README.md is generated from README.Rmd. Please edit that file -->
-[![ORCiD](https://img.shields.io/badge/ORCiD-0000--0002--3410--3732-green.svg)](http://orcid.org/0000-0002-3410-3732) [![DOI](https://zenodo.org/badge/37335585.svg)](https://zenodo.org/badge/latestdoi/37335585) [![Licence](https://img.shields.io/github/license/mashape/apistatus.svg)](http://choosealicense.com/licenses/mit/)
+[![ORCiD](https://img.shields.io/badge/ORCiD-0000--0002--3410--3732-green.svg)](http://orcid.org/0000-0002-3410-3732)
+[![DOI](https://zenodo.org/badge/1117419.svg)](https://zenodo.org/badge/latestdoi/1117419)
+[![Licence](https://img.shields.io/github/license/mashape/apistatus.svg)](http://choosealicense.com/licenses/mit/)
 
-[![Build Status](https://travis-ci.org/potterzot/rnassqs.svg?branch=master)](https://travis-ci.org/potterzot/rnassqs) [![Last-changedate](https://img.shields.io/badge/last%20change-2017--11--28-brightgreen.svg)](https://github.com/potterzot/rnassqs/commits/master) [![Coverage Status](https://coveralls.io/repos/github/potterzot/rnassqs/badge.svg?branch=master)](https://coveralls.io/github/potterzot/rnassqs?branch=master)
+[![Build
+Status](https://travis-ci.org/potterzot/rnassqs.svg?branch=master)](https://travis-ci.org/potterzot/rnassqs)
+[![Last-changedate](https://img.shields.io/badge/last%20change-2017--12--17-brightgreen.svg)](https://github.com/potterzot/rnassqs/commits/master)
+[![Coverage
+Status](https://coveralls.io/repos/github/potterzot/rnassqs/badge.svg?branch=master)](https://coveralls.io/github/potterzot/rnassqs?branch=master)
 
-rnassqs (R NASS QuickStats)
----------------------------
+\#\#rnassqs (R NASS QuickStats)
 
-This is a package that allows users to access the NASS quickstats data through their API. It is fairly low level and does not include a lot of scaffolding or setup. Some things may change, but at this point it is relatively stable.
+This is a package that allows users to access the NASS quickstats data
+through their API. It is fairly low level and does not include a lot of
+scaffolding or setup. Some things may change, but at this point it is
+relatively stable.
 
-Installing
-----------
+\#\#Installing
 
 Install like any R package from github:
 
     library(devtools)
     install_github('potterzot/rnassqs')
 
-API Key
--------
-
-To use the NASS Quickstats API you need an [API key](http://quickstats.nass.usda.gov/api). There are several ways of clueing the rnassqs package in to your api key. You can set the variable explicitly and pass it to functions, like so
+\#\#API Key To use the NASS Quickstats API you need an [API
+key](http://quickstats.nass.usda.gov/api). There are several ways of
+clueing the rnassqs package in to your api key. You can set the variable
+explicitly and pass it to functions, like so
 
     params <- list(...)                    # parameters for query 
     api_key <- "<your api key here>"       # api key
     data <- nassqs(params, key = api_key)  # query and return data
 
-Alternatively, you can set the api key as an environmental variable either by adding it to your `.Renviron` like so:
+Alternatively, you can set the api key as an environmental variable
+either by adding it to your `.Renviron` like so:
 
     NASSQS_TOKEN="<your api key here>"
 
-or by setting it explicitly in the console by calling `rnassqs::nassqs_token()`. This will prompt you to enter the api key if not set, and return the value of the api key if it is set. If you do not set the key and you are running the session interactively, R will ask you for the key when you try to issue a query.
+or by setting it explicitly in the console by calling
+`rnassqs::nassqs_token()`. This will prompt you to enter the api key if
+not set, and return the value of the api key if it is set. If you do not
+set the key and you are running the session interactively, R will ask
+you for the key when you try to issue a query.
 
-Usage
------
+\#\#Usage
 
-See the examples in [inst/examples](inst/examples) for quick recipes to download data.
+See the examples in [inst/examples](inst/examples) for quick recipes to
+download data.
 
-The most basic level of access is with `nassqs_GET()`, with which you can make any query of variables. For example, to mirror the request that is on the [NASS API documentation](http://quickstats.nass.usda.gov/api), you can do:
+The most basic level of access is with `nassqs_GET()`, with which you
+can make any query of variables. For example, to mirror the request that
+is on the [NASS API documentation](http://quickstats.nass.usda.gov/api),
+you can do:
 
     library(nassqs)
     params = list("commodity_desc"="CORN", "year__GE"=2012, "state_alpha"="VA")
     req = nassqs_GET(params=params, key=your_api_key)
     qsJSON = nassqs_parse(req)
 
-Note that you can request data for multiple values of the same parameter by as follows:
+Note that you can request data for multiple values of the same parameter
+by as follows:
 
     params = list("commodity_desc"="CORN", "year__GE"=2012, "state_alpha"="VA", "state_alpha"="WA")
     req = nassqs_GET(params=params, key=your_api_key)
     qsJSON = nassqs_parse(req)
 
-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.
+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.
 
-### Handling inequalities and operators other than "="
+\#\#\#Handling inequalities and operators other than “=” The NASS API
+handles other operators by modifying the variable name. The API can
+accept the following modifications:
 
-The NASS API handles other operators by modifying the variable name. The API can accept the following modifications: \* \_\_LE = &lt;= \* \_\_LT = &lt; \* \_\_GT = &gt; \* \_\_GE = &gt;= \* \_\_LIKE = like \* \_\_NOT\_LIKE = not like \* \_\_NE = not equal \_\_LE = &lt;=
+-   \_\_LE: &lt;=
+-   \_\_LT: &lt;
+-   \_\_GT: &gt;
+-   \_\_GE: &gt;=
+-   \_\_LIKE: like
+-   \_\_NOT\_LIKE: not like
+-   \_\_NE: not equal
 
-For example, to request corn yields for all years since 2000, you would use something like:
+For example, to request corn yields for all years since 2000, you would
+use something like:
 
     params = list("commodity_desc"="CORN", 
                   "year__GE"=2000, 
@@ -67,11 +95,13 @@ You could also use the helper function `nassqs_yield()`:
 
     nassqs_yield(list("commodity_desc"="CORN", "agg_level_desc"="NATIONAL")) #gets US yields
 
-Alternatives
-------------
-
-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 from their FTP:
+\#\#Alternatives 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 from their FTP:
 
 <ftp://ftp.nass.usda.gov/quickstats>
 
-The FTP link also contains builds for: NASS' census (every 5 years, the next is 2017), 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.
+The FTP link also contains builds for: NASS’ census (every 5 years, the
+next is 2017), 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.

inst/examples/combining_multiple_variables.R

@@ -0,0 +1,92 @@
+# A more complex example that creates a data.frame from several variables.
+#
+# Here we fetch several variables at a county level, checking that each query
+# does not exceed the 50000 API record limit, and appending the query results
+# to a single data frame
+
+# Libraries --------------------------------------------------------------------
+library(rnassqs)
+library(jsonlite)
+
+# Functions to get data --------------------------------------------------------
+
+#' wrapper to download quickstats data for different parameters
+#' 
+#' @param params a named list of parameters.
+#' @param api_key character api key for nass quickstats.
+#' @return a data.frame.
+get_data <- function(params, api_key) {
+  n_records <- as.integer(nassqs_record_count(params, key=api_key)[[1]])
+  if(n_records <= 50000) {
+    df_raw <- nassqs(params=params, key = api_key)
+    return(df_raw)
+  } else {stop("Too many records requested. Revise your query.")}
+}
+
+# Need an API key from NASS ----------------------------------------------------
+# Get one here: https://quickstats.nass.usda.gov/api
+api_key <- fromJSON(file(".secret"))$nassqs
+
+## The set of queries, includes ------------------------------------------------
+# 1. Cash rents by county since 2000
+# 2. acres of cropland by county since 1997
+# 3. irrigated acres of cropland by county since 1997
+# 4. acres of pastureland by county since 1997
+# 5. acres of all irrigated land by county since 1997
+# 6. Total ag sales by county since 1997
+
+param_list <- list(
+  cash_rents = list(sector_desc = "ECONOMICS",
+                    commodity_desc = "RENT",
+                    agg_level_desc = "COUNTY",
+                    year__GE = 2000),
+  ag_cropland = list(sector_desc = "ECONOMICS",
+                     commodity_desc = "AG LAND",
+                     agg_level_desc = "COUNTY",
+                     class_desc = "CROPLAND",
+                     unit_desc = "ACRES",
+                     statisticcat_desc = "AREA",
+                     year__GE = 1997),
+  ag_cropland_irr = list(sector_desc = "ECONOMICS",
+                         commodity_desc = "AG LAND",
+                         agg_level_desc = "COUNTY",
+                         class_desc = "CROPLAND",
+                         unit_desc = "ACRES",
+                         prodn_practice_desc = "IRRIGATED",
+                         statisticcat_desc = "AREA",
+                         year__GE = 1997),
+  ag_pastureland = list(sector_desc = "ECONOMICS",
+                        commodity_desc = "AG LAND",
+                        agg_level_desc = "COUNTY",
+                        class_desc = "PASTURELAND",
+                        unit_desc = "ACRES",
+                        statisticcat_desc = "AREA",
+                        year__GE = 1997),
+  ag_irrigatedland = list(sector_desc = "ECONOMICS",
+                          commodity_desc = "AG LAND",
+                          agg_level_desc = "COUNTY",
+                          prodn_practice_desc = "IRRIGATED",
+                          class_desc = "ALL CLASSES",
+                          unit_desc = "ACRES",
+                          domain_desc = "TOTAL",
+                          year__GE = 1997),
+  ag_sales = list(sector_desc = "ECONOMICS",
+                  commodity_desc = "COMMODITY TOTALS",
+                  agg_level_desc = "COUNTY",
+                  statisticcat_desc = "SALES",
+                  util_practice_desc = "ALL UTILIZATION PRACTICES",
+                  unit_desc = "$",
+                  domain_desc = "TOTAL",
+                  domaincat_desc = "NOT SPECIFIED",
+                  year__GE = 1997)
+  )
+
+# Fetch and aggregate the data
+data <- rbindlist(
+  lapply(names(param_list), function(data_source) {
+    print(paste0("Downloading ", data_source, "..."))
+    d <- get_data(param_list[[data_source]], api_key)
+    d$variable <- data_source
+    return(d)
+  })
+)

inst/examples/wa_operators_2012.R

@@ -1,4 +1,5 @@
 # Get NASS farm operators in the state of WA for 2012
+library(rnassqs)
 
 # Set the api key
 api_key = "<put your api key here>"