From 1b197c39e69561c9f290db9d817d79eabbdf5254 Mon Sep 17 00:00:00 2001
From: Ari Lamstein <alamstein@trulia.com>
Date: Sat, 8 Mar 2014 20:40:06 -0800
Subject: [PATCH] updates to support a workflow via shiny

---
 NAMESPACE                   |  1 +
 R/choroplethr_acs.R         | 50 ++++++++++++++++++++++++++-----------
 man/get_acs_column_names.Rd | 28 +++++++++++++++++++++
 man/get_acs_df.Rd           |  4 ++-
 4 files changed, 68 insertions(+), 15 deletions(-)
 create mode 100644 man/get_acs_column_names.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 5e75a53..caa620b 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,6 +1,7 @@
 export(bind_df_to_map)
 export(choroplethr)
 export(choroplethr_acs)
+export(get_acs_column_names)
 export(get_acs_df)
 export(render_choropleth)
 importFrom(Hmisc,cut2)
diff --git a/R/choroplethr_acs.R b/R/choroplethr_acs.R
index 7135b97..cbbbf91 100644
--- a/R/choroplethr_acs.R
+++ b/R/choroplethr_acs.R
@@ -58,34 +58,25 @@ choroplethr_acs = function(tableId, lod, num_buckets = 9, showLabels = T, states
 #' @param lod The level of geographic detail for the data.frame.  Must be one of "state", "county" or "zip". 
 #' @param endyear The end year of the survey.  Defaults to 2012.
 #' @param span The span of the survey.  Defaults to 5.
+#' @param column_idx An optional column index to specify.
 #' @return A data.frame 
 #' @export
 #' @seealso http://factfinder2.census.gov/faces/help/jsf/pages/metadata.xhtml?lang=en&type=survey&id=survey.en.ACS_ACS, which lists all ACS Surveys.
 #' @importFrom acs acs.fetch geography estimate geo.make
-get_acs_df = function(tableId, lod, endyear=2012, span=5)
+get_acs_df = function(tableId, lod, endyear=2012, span=5, column_idx = -1)
 {
   stopifnot(lod %in% c("state", "county", "zip"))
   
   acs.data   = acs.fetch(geography=make_geo(lod), table.number = tableId, col.names = "pretty", endyear = endyear, span = span)
-  column_idx = get_column_idx(acs.data, tableId) # some tables have multiple columns 
+  if (column_idx == -1) {
+    column_idx = get_column_idx(acs.data, tableId) # some tables have multiple columns 
+  }
   acs.df     = make_df(lod, acs.data, column_idx) # turn into df
   acs.df$region = as.character(acs.df$region)
   
   acs.df
 }
 
-make_geo = function(lod)
-{
-  stopifnot(lod %in% c("state", "county", "zip"))
-  if (lod == "state") {
-    geo.make(state = "*")
-  } else if (lod == "county") {
-    geo.make(state = "*", county = "*")
-  } else {
-    geo.make(zip.code = "*")
-  }
-}
-
 # support multiple column tables
 get_column_idx = function(acs.data, tableId)
 {
@@ -99,6 +90,37 @@ get_column_idx = function(acs.data, tableId)
   column_idx
 }
 
+#' Returns the column names of an ACS table.
+#' 
+#' @param tableId The id of an ACS table.
+#' @param lod The level of geographic detail for the data.frame.  Must be one of "state", "county" or "zip". 
+#' @param endyear The end year of the survey.  Defaults to 2012.
+#' @param span The span of the survey.  Defaults to 5.
+#' @return A vector of column names 
+#' @export
+#' @seealso http://factfinder2.census.gov/faces/help/jsf/pages/metadata.xhtml?lang=en&type=survey&id=survey.en.ACS_ACS, which lists all ACS Surveys.
+#' @importFrom acs acs.fetch geography estimate geo.make
+get_acs_column_names = function(tableId, lod, endyear=2012, span=5)
+{
+  stopifnot(lod %in% c("state", "county", "zip"))
+  stopifnot(span %in% c(1, 3, 5))
+  
+  acs.data = acs.fetch(geography=make_geo(lod), table.number = tableId, col.names = "pretty", endyear = endyear, span = span)
+  acs.data@acs.colnames
+}
+
+make_geo = function(lod)
+{
+  stopifnot(lod %in% c("state", "county", "zip"))
+  if (lod == "state") {
+    geo.make(state = "*")
+  } else if (lod == "county") {
+    geo.make(state = "*", county = "*")
+  } else {
+    geo.make(zip.code = "*")
+  }
+}
+
 make_df = function(lod, acs.data, column_idx) 
 {
   stopifnot(lod %in% c("state", "county", "zip"))
diff --git a/man/get_acs_column_names.Rd b/man/get_acs_column_names.Rd
new file mode 100644
index 0000000..080f5c9
--- /dev/null
+++ b/man/get_acs_column_names.Rd
@@ -0,0 +1,28 @@
+\name{get_acs_column_names}
+\alias{get_acs_column_names}
+\title{Returns the column names of an ACS table.}
+\usage{
+get_acs_column_names(tableId, lod, endyear = 2012, span = 5)
+}
+\arguments{
+  \item{tableId}{The id of an ACS table.}
+
+  \item{lod}{The level of geographic detail for the
+  data.frame.  Must be one of "state", "county" or "zip".}
+
+  \item{endyear}{The end year of the survey.  Defaults to
+  2012.}
+
+  \item{span}{The span of the survey.  Defaults to 5.}
+}
+\value{
+A vector of column names
+}
+\description{
+Returns the column names of an ACS table.
+}
+\seealso{
+http://factfinder2.census.gov/faces/help/jsf/pages/metadata.xhtml?lang=en&type=survey&id=survey.en.ACS_ACS,
+which lists all ACS Surveys.
+}
+
diff --git a/man/get_acs_df.Rd b/man/get_acs_df.Rd
index a795444..25b1276 100644
--- a/man/get_acs_df.Rd
+++ b/man/get_acs_df.Rd
@@ -2,7 +2,7 @@
 \alias{get_acs_df}
 \title{Returns a data.frame representing American Community Survey estimates.}
 \usage{
-get_acs_df(tableId, lod, endyear = 2012, span = 5)
+get_acs_df(tableId, lod, endyear = 2012, span = 5, column_idx = -1)
 }
 \arguments{
   \item{tableId}{The id of an ACS table.}
@@ -14,6 +14,8 @@ get_acs_df(tableId, lod, endyear = 2012, span = 5)
   2012.}
 
   \item{span}{The span of the survey.  Defaults to 5.}
+
+  \item{column_idx}{An optional column index to specify.}
 }
 \value{
 A data.frame