modified continuous scale version + added docs

R/statebins-package.R

@@ -1,5 +1,5 @@
 #' statebins is an alternative to choropleth maps for US States
-#' @name statebins
+#' @name statebins-package
 #' @docType package
 #' @author Bob Rudis (@@hrbrmstr)
 #' @import ggplot2 scales grid gridExtra RColorBrewer

R/statebins.R

@@ -1,21 +1,39 @@
-
+#' Create a new ggplot-based "statebin" chart
-#' Create ggplot-based "statebin" charts in the style of \url{http://www.washingtonpost.com/wp-srv/special/business/states-most-threatened-by-trade/}
+#'
+#' \code{statebins()} creates "statebin" charts in the style of \url{http://bit.ly/statebins}
+#'
+#' This version uses discrete \link{RColorBrewer} scales, binned by the "breaks" parameter.
+#'
+#' The function minimally expects the caller to pass in a data frame that:
 #'
-#' This version uses a discrete scale, binned by the "breaks" parameter
+#' \itemize{
+#'   \item has one column of all state abbreviationis (all caps, including \code{DC} or a column of state names (standard capitalization) named \code{state}
+#'   \item has another column of values named \code{value}
+#' }
+#'
+#' Doing so will create a "statebin" chart with 5 breaks and return a \link{ggplot2} object.
+#'
+#' You can use a different column for the state names and values by changing \code{state_col}
+#' and \code{value_col} accordingly.
+#'
+#' To add a title, change \code{plot_title} to anything but an empty atomic string vector (i.e. \code{""})
+#' and set \code{title_positioin} to "\code{top}" or "\code{bottom}". Choosing "\code{bottom}"
+#' will cause \code{statebins} to use \link{arrangeGrob} to position the title via \code{sub} and
+#' return a frame grob instead of a ggplot2 object.
 #'
 #' @param state_data data frame of states and values to plot
-#' @param state_col column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "Maine") or abbreviatons (e.g. "ME")
+#' @param state_col column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "\code{Maine}") or abbreviatons (e.g. "\code{ME}")
 #' @param value_col column name in \code{state_data} that holds the values to be plotted
-#' @param text_color default "white"
+#' @param text_color default "\code{white}"
-#' @param font_size font size (default = 2)
+#' @param font_size font size (default = \code{2})
-#' @param state_border_col default "white" - this creates the "spaces" between boxes
+#' @param state_border_col default "\code{white}" - this creates the "spaces" between boxes
 #' @param breaks a single number (greater than or equal to 2) giving the number of intervals into which data values are to be cut.
 #' @param labels labels for the levels \code{breaks}
 #' @param legend_title title for the legend
-#' @param legend_position "none", "top" or "bottom" (defaults to "top")
+#' @param legend_position "\code{none}", "\code{top}", "\code{left}", "\code{right}" or "\code{bottom}" (defaults to "\code{top}")
-#' @param brewer_pal which named RColorBrewer palette to use
+#' @param brewer_pal which named \link{RColorBrewer} palette to use (defaults to "PuBu")
 #' @param plot_title title for the plot
-#' @param title_position where to put the title ("bottom" or "top" or " " for none); if "bottom", you get back a grob vs a ggplot object
+#' @param title_position where to put the title ("\code{bottom}" or "\code{top}" or "" for none); if "\code{bottom}", you get back a grob vs a ggplot object
 #' @return ggplot2 object or grob
 #' @export
 statebins <- function(state_data, state_col="state", value_col="value",
@@ -26,7 +44,7 @@ statebins <- function(state_data, state_col="state", value_col="value",
 
   stopifnot(breaks > 0 && breaks < 10)
   stopifnot(title_position %in% c("", "top", "bottom"))
-  stopifnot(legend_position %in% c("", "none", "top", "bottom"))
+  stopifnot(legend_position %in% c("", "none", "left", "right", "top", "bottom"))
 
   if (max(nchar(state_data[,state_col])) == 2) {
     merge.x <- "abbrev"
@@ -74,22 +92,41 @@ statebins <- function(state_data, state_col="state", value_col="value",
 }
 
 
-
+#' Create ggplot-based "statebin" charts in the style of \url{http://bit.ly/statebins}
-#' Create ggplot-based "statebin" charts in the style of \url{http://www.washingtonpost.com/wp-srv/special/business/states-most-threatened-by-trade/}
+#'
+#' \code{statebins()} creates "statebin" charts in the style of \url{http://bit.ly/statebins}
+#'
+#' This version uses a continuous scale based on \link{RColorBrewer} scales
+#' (passing in a 6 element \code{RColorBrewer} palette to \link{scale_fill_gradientn}).
+#'
+#' The function minimally expects the caller to pass in a data frame that:
+#'
+#' \itemize{
+#'   \item has one column of all state abbreviationis (all caps, including \code{DC}) or a column of state names (standard capitalization) named \code{state}
+#'   \item has another column of values named \code{value}
+#' }
+#'
+#' Doing so will create a "statebin" chart with 5 breaks and return a \link{ggplot2} object.
+#'
+#' You can use a different column for the state names and values by changing \code{state_col}
+#' and \code{value_col} accordingly.
 #'
-#' This version uses a continuous scale akin to \link{scale_fill_distiller}
+#' To add a title, change \code{plot_title} to anything but an empty atomic string vector (i.e. \code{""})
+#' and set \code{title_positioin} to "\code{top}" or "\code{bottom}". Choosing "\code{bottom}"
+#' will cause \code{statebins} to use \link{arrangeGrob} to position the title via \code{sub} and
+#' return a frame grob instead of a ggplot2 object.
 #'
 #' @param state_data data frame of states and values to plot
-#' @param state_col column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "Maine") or abbreviatons (e.g. "ME")
+#' @param state_col column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "\code{Maine}") or abbreviatons (e.g. "\code{ME}")
 #' @param value_col column name in \code{state_data} that holds the values to be plotted
-#' @param text_color default "white"
+#' @param text_color default "\code{white}"
-#' @param font_size font size (default = 2)
+#' @param font_size font size (default = \code{2})
-#' @param state_border_col default "white" - this creates the "spaces" between boxes
+#' @param state_border_col default "\code{white}" - this creates the "spaces" between boxes
 #' @param legend_title title for the legend
-#' @param legend_position "none", "top" or "bottom" (defaults to "top")
+#' @param legend_position "\code{none}", "\code{top}", "\code{left}", "\code{right}" or "\code{bottom}" (defaults to "\code{top}")
-#' @param brewer_pal which named RColorBrewer palette to use
+#' @param brewer_pal which named \link{RColorBrewer} palette to use (defaults to "PuBu")
 #' @param plot_title title for the plot
-#' @param title_position where to put the title ("bottom" or "top" or " " for none); if "bottom", you get back a grob vs a ggplot object
+#' @param title_position where to put the title ("\code{bottom}" or "\code{top}" or "" for none); if "\code{bottom}", you get back a grob vs a ggplot object
 #' @return ggplot2 object or grob
 #' @export
 statebins_continuous <- function(state_data, state_col="state", value_col="value",
@@ -118,8 +155,7 @@ statebins_continuous <- function(state_data, state_col="state", value_col="value
                        aes_string(fill=value_col), size=3, show_guide=FALSE)
   gg <- gg + geom_text(color=text_color, size=font_size)
   gg <- gg + scale_y_reverse()
-  gg <- gg + continuous_scale("fill", "distiller",
+  gg <- gg + scale_fill_gradientn(colours = brewer.pal(6, brewer_pal), name=legend_title)
-                   gradient_n_pal(brewer_pal("seq", brewer_pal)(6), NULL, "Lab"), na.value = "grey50", name=legend_title)
   gg <- gg + coord_equal()
   gg <- gg + labs(x="", y="", title="")
   gg <- gg + theme_bw()

_README.Rmd

@@ -49,16 +49,16 @@ gg <- statebins(dat, "state", "avgshare94_00", breaks=4,
 gg
 
 gg2 <- statebins_continuous(dat, "state", "avgshare01_07",
-                legend_title="States", legend_position="none",
+                            legend_title="State Data", legend_position="top",
-                brewer_pal="OrRd", text_color="black", font_size=3, 
+                            brewer_pal="OrRd", text_color="black", font_size=3, 
-                plot_title="2001-2007", title_position="bottom")
+                            plot_title="2001-2007", title_position="bottom")
 
 gg2
 
 gg3 <- statebins_continuous(dat, "state", "avgshare08_12",
-                legend_title="States", legend_position="none",
+                            legend_title="States", legend_position="none",
-                brewer_pal="Purples", text_color="black", font_size=3, 
+                            brewer_pal="Purples", text_color="black", font_size=3, 
-                plot_title="2008-2012", title_position="bottom")
+                            plot_title="2008-2012", title_position="bottom")
 
 gg3
 

man/statebins-package.Rd

@@ -0,0 +1,12 @@
+% Generated by roxygen2 (4.0.1.99): do not edit by hand
+\docType{package}
+\name{statebins-package}
+\alias{statebins-package}
+\title{statebins is an alternative to choropleth maps for US States}
+\description{
+statebins is an alternative to choropleth maps for US States
+}
+\author{
+Bob Rudis (@hrbrmstr)
+}
+

man/statebins.Rd

@@ -1,9 +1,7 @@
 % Generated by roxygen2 (4.0.1.99): do not edit by hand
-\docType{package}
 \name{statebins}
 \alias{statebins}
-\alias{statebins-package}
+\title{Create a new ggplot-based "statebin" chart}
-\title{statebins is an alternative to choropleth maps for US States}
 \usage{
 statebins(state_data, state_col = "state", value_col = "value",
   text_color = "white", font_size = 2, state_border_col = "white",
@@ -14,15 +12,15 @@ statebins(state_data, state_col = "state", value_col = "value",
 \arguments{
 \item{state_data}{data frame of states and values to plot}
 
-\item{state_col}{column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "Maine") or abbreviatons (e.g. "ME")}
+\item{state_col}{column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "\code{Maine}") or abbreviatons (e.g. "\code{ME}")}
 
 \item{value_col}{column name in \code{state_data} that holds the values to be plotted}
 
-\item{text_color}{default "white"}
+\item{text_color}{default "\code{white}"}
 
-\item{font_size}{font size (default = 2)}
+\item{font_size}{font size (default = \code{2})}
 
-\item{state_border_col}{default "white" - this creates the "spaces" between boxes}
+\item{state_border_col}{default "\code{white}" - this creates the "spaces" between boxes}
 
 \item{breaks}{a single number (greater than or equal to 2) giving the number of intervals into which data values are to be cut.}
 
@@ -30,23 +28,38 @@ statebins(state_data, state_col = "state", value_col = "value",
 
 \item{legend_title}{title for the legend}
 
-\item{legend_position}{"none", "top" or "bottom" (defaults to "top")}
+\item{legend_position}{"\code{none}", "\code{top}", "\code{left}", "\code{right}" or "\code{bottom}" (defaults to "\code{top}")}
 
-\item{brewer_pal}{which named RColorBrewer palette to use}
+\item{brewer_pal}{which named \link{RColorBrewer} palette to use (defaults to "PuBu")}
 
 \item{plot_title}{title for the plot}
 
-\item{title_position}{where to put the title ("bottom" or "top" or " " for none); if "bottom", you get back a grob vs a ggplot object}
+\item{title_position}{where to put the title ("\code{bottom}" or "\code{top}" or "" for none); if "\code{bottom}", you get back a grob vs a ggplot object}
 }
 \value{
 ggplot2 object or grob
 }
 \description{
-statebins is an alternative to choropleth maps for US States
+\code{statebins()} creates "statebin" charts in the style of \url{http://bit.ly/statebins}
+}
+\details{
+This version uses discrete \link{RColorBrewer} scales, binned by the "breaks" parameter.
+
+The function minimally expects the caller to pass in a data frame that:
 
-This version uses a discrete scale, binned by the "breaks" parameter
+\itemize{
+  \item has one column of all state abbreviationis (all caps, including \code{DC} or a column of state names (standard capitalization) named \code{state}
+  \item has another column of values named \code{value}
 }
-\author{
+
-Bob Rudis (@hrbrmstr)
+Doing so will create a "statebin" chart with 5 breaks and return a \link{ggplot2} object.
+
+You can use a different column for the state names and values by changing \code{state_col}
+and \code{value_col} accordingly.
+
+To add a title, change \code{plot_title} to anything but an empty atomic string vector (i.e. \code{""})
+and set \code{title_positioin} to "\code{top}" or "\code{bottom}". Choosing "\code{bottom}"
+will cause \code{statebins} to use \link{arrangeGrob} to position the title via \code{sub} and
+return a frame grob instead of a ggplot2 object.
 }
 

man/statebins_continuous.Rd

@@ -1,7 +1,7 @@
 % Generated by roxygen2 (4.0.1.99): do not edit by hand
 \name{statebins_continuous}
 \alias{statebins_continuous}
-\title{Create ggplot-based "statebin" charts in the style of \url{http://www.washingtonpost.com/wp-srv/special/business/states-most-threatened-by-trade/}}
+\title{Create ggplot-based "statebin" charts in the style of \url{http://bit.ly/statebins}}
 \usage{
 statebins_continuous(state_data, state_col = "state", value_col = "value",
   text_color = "white", font_size = 2, state_border_col = "white",
@@ -11,30 +11,51 @@ statebins_continuous(state_data, state_col = "state", value_col = "value",
 \arguments{
 \item{state_data}{data frame of states and values to plot}
 
-\item{state_col}{column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "Maine") or abbreviatons (e.g. "ME")}
+\item{state_col}{column name in \code{state_data} that has the states. no duplicates and can be names (e.g. "\code{Maine}") or abbreviatons (e.g. "\code{ME}")}
 
 \item{value_col}{column name in \code{state_data} that holds the values to be plotted}
 
-\item{text_color}{default "white"}
+\item{text_color}{default "\code{white}"}
 
-\item{font_size}{font size (default = 2)}
+\item{font_size}{font size (default = \code{2})}
 
-\item{state_border_col}{default "white" - this creates the "spaces" between boxes}
+\item{state_border_col}{default "\code{white}" - this creates the "spaces" between boxes}
 
 \item{legend_title}{title for the legend}
 
-\item{legend_position}{"none", "top" or "bottom" (defaults to "top")}
+\item{legend_position}{"\code{none}", "\code{top}", "\code{left}", "\code{right}" or "\code{bottom}" (defaults to "\code{top}")}
 
-\item{brewer_pal}{which named RColorBrewer palette to use}
+\item{brewer_pal}{which named \link{RColorBrewer} palette to use (defaults to "PuBu")}
 
 \item{plot_title}{title for the plot}
 
-\item{title_position}{where to put the title ("bottom" or "top" or " " for none); if "bottom", you get back a grob vs a ggplot object}
+\item{title_position}{where to put the title ("\code{bottom}" or "\code{top}" or "" for none); if "\code{bottom}", you get back a grob vs a ggplot object}
 }
 \value{
 ggplot2 object or grob
 }
 \description{
-This version uses a continuous scale akin to \link{scale_fill_distiller}
+\code{statebins()} creates "statebin" charts in the style of \url{http://bit.ly/statebins}
+}
+\details{
+This version uses a continuous scale based on \link{RColorBrewer} scales
+(passing in a 6 element \code{RColorBrewer} palette to \link{scale_fill_gradientn}).
+
+The function minimally expects the caller to pass in a data frame that:
+
+\itemize{
+  \item has one column of all state abbreviationis (all caps, including \code{DC}) or a column of state names (standard capitalization) named \code{state}
+  \item has another column of values named \code{value}
+}
+
+Doing so will create a "statebin" chart with 5 breaks and return a \link{ggplot2} object.
+
+You can use a different column for the state names and values by changing \code{state_col}
+and \code{value_col} accordingly.
+
+To add a title, change \code{plot_title} to anything but an empty atomic string vector (i.e. \code{""})
+and set \code{title_positioin} to "\code{top}" or "\code{bottom}". Choosing "\code{bottom}"
+will cause \code{statebins} to use \link{arrangeGrob} to position the title via \code{sub} and
+return a frame grob instead of a ggplot2 object.
 }