doc ready!

Author: jbkunst

DESCRIPTION

@@ -6,7 +6,7 @@ Description: A wrapper for the 'Highcharts' library including
   shortcut functions to plot R objects. 'Highcharts' 
   <http://www.highcharts.com/> is a charting library offering
   numerous chart types with a simple configuration syntax.
-Date: 2015-12-11
+Date: 2016-01-12
 Author: Joshua Kunst <[email protected]>
 Maintainer: Joshua Kunst <[email protected]>
 License: MIT + file LICENSE

R/api.R

@@ -1,7 +1,7 @@
-#' @import rlist assertthat
+#' @import rlist
 .hc_opt <- function(hc, name, ...) {
 
-  assert_that(.is_highchart(hc))
+  assertthat::assert_that(.is_highchart(hc))
 
   if (is.null(hc$x$hc_opts[[name]])) {
 
@@ -204,9 +204,10 @@ hc_tooltip <- function(hc, ...) {
 #' The plotOptions is a wrapper object for config objects for each series type. The config 
 #' objects for each series can also be overridden for each series item as given in the series array.
 #' 
-#' Configuration options for the series are given in three levels. Options for all series in a chart are given in the 
-#' plotOptions object. Then options for all series of a specific type are given in the plotOptions of that type, for example 
-#' \code{hc_plotOptions(line = list(...))}. Next, options for one single series are given in the series array.
+#' Configuration options for the series are given in three levels. Options for all series in a 
+#' chart are given with the \code{hc_plotOptions} function. Then options for all series of a specific
+#' type are given in the plotOptions of that type, for example  \code{hc_plotOptions(line = list(...))}.
+#' Next, options for one single series are given in the series array.
 #' 
 #' @param hc A \code{highchart} \code{htmlwidget} object. 
 #' @param ... Arguments are defined in \url{http://api.highcharts.com/highcharts#plotOptions}.
@@ -232,7 +233,7 @@ hc_tooltip <- function(hc, ...) {
 #' 
 #' hc
 #' 
-#' #' override the `blue` option with the explicit parameter
+#' # override the `blue` option with the explicit parameter
 #' hc %>% 
 #'   hc_add_serie(name = "London",
 #'                data = citytemp$new_york,
@@ -247,12 +248,24 @@ hc_plotOptions  <- function(hc, ...) {
 
 #' Adding credits options to highchart objects
 #'
-#' \code{highcarter} by default don't put credits label. You can add credits
-#' using these options.
+#' \code{highcarter} by default don't put credits in the chart.
+#' You can add credits using these options.
 #' 
 #' @param hc A \code{highchart} \code{htmlwidget} object. 
 #' @param ... Arguments defined in \url{http://api.highcharts.com/highcharts#credits}. 
-#'
+#' 
+#' @examples 
+#' 
+#' require("dplyr")
+#' 
+#' data("citytemp")
+#' 
+#' highchart() %>% 
+#'   hc_xAxis(categories = citytemp$month) %>% 
+#'   hc_add_serie(name = "Tokyo", data = citytemp$tokyo, type = "bar") %>% 
+#'   hc_credits(enabled = TRUE, text = "htmlwidgets.org",
+#'              href = "http://www.htmlwidgets.org/")
+#'              
 #' @export
 hc_credits <- function(hc, ...) {
 
@@ -266,7 +279,41 @@ hc_credits <- function(hc, ...) {
 #' 
 #' @param hc A \code{highchart} \code{htmlwidget} object. 
 #' @param ... Arguments are defined in \url{http://www.highcharts.com/docs/maps/color-axis}. 
-#'
+#' 
+#' @examples 
+#' 
+#' require("dplyr")
+#' 
+#' nyears <- 5
+#' 
+#' df <- expand.grid(seq(12) - 1, seq(nyears) - 1)
+#' df$value <- abs(seq(nrow(df)) + 10 * rnorm(nrow(df))) + 10
+#' df$value <- round(df$value, 2)
+#' ds <- setNames(list.parse2(df), NULL)
+#' 
+#' 
+#' hc <- highchart() %>% 
+#'   hc_chart(type = "heatmap") %>% 
+#'   hc_title(text = "Simulated values by years and months") %>% 
+#'   hc_xAxis(categories = month.abb) %>% 
+#'   hc_yAxis(categories = 2016 - nyears + seq(nyears)) %>% 
+#'   hc_add_serie(name = "value", data = ds)
+#' 
+#' hc_colorAxis(hc, minColor = "#FFFFFF", maxColor = "#434348")
+#' 
+#' hc_colorAxis(hc, minColor = "#FFFFFF", maxColor = "#434348",
+#'              type = "logarithmic") 
+#' 
+#' 
+#' require("viridisLite")
+#' 
+#' n <- 4
+#' stops <- data_frame(q = 0:n/n,
+#'                     c = substring(viridis(n + 1), 0, 7))
+#' stops <- list.parse2(stops)
+#' 
+#' hc_colorAxis(hc, stops = stops, max = 75) 
+#' 
 #' @export
 hc_colorAxis  <- function(hc, ...) {
 
@@ -292,14 +339,8 @@ hc_colorAxis  <- function(hc, ...) {
 #'   hc_xAxis(categories = citytemp$month) %>% 
 #'   hc_add_serie(name = "Tokyo", data = citytemp$tokyo) %>% 
 #'   hc_add_serie(name = "London", data = citytemp$london) %>% 
-#'   hc_exporting(enabled = FALSE)
-#' 
-#' 
-#' highchart() %>% 
-#'   hc_xAxis(categories = citytemp$month) %>% 
-#'   hc_add_serie(name = "Tokyo", data = citytemp$tokyo) %>% 
-#'   hc_add_serie(name = "London", data = citytemp$london) %>% 
-#'   hc_exporting(filename = "custom-file-name")
+#'   hc_exporting(enabled = TRUE,
+#'                filename = "custom-file-name")
 #' 
 #' @export
 hc_exporting  <- function(hc, ...) {
@@ -341,11 +382,9 @@ hc_add_serie <- function(hc, ...) {
 
 #' Removing series to highchart objects
 #'
-#' @param hc A \code{highchart} \code{htmlwidget} object. 
 #' @param name The serie's name to delete.
 #' 
 #' @rdname hc_add_serie
-#'
 #' @export
 hc_rm_serie <- function(hc, name = NULL) {
 

R/assertthat.R

@@ -1,5 +1,6 @@
+#' @import assertthat
 .is_highchart <- function(hc){
-  are_equal(class(hc), c("highchart", "htmlwidget"))
+  assertthat::are_equal(class(hc), c("highchart", "htmlwidget"))
 }
 
 assertthat::on_failure(.is_highchart) <- function(call, env) {
@@ -9,11 +10,11 @@ assertthat::on_failure(.is_highchart) <- function(call, env) {
 }
 
 .is_hc_theme <- function(hc_theme){
-  are_equal(class(hc_theme), "hc_theme")
+  assertthat::are_equal(class(hc_theme), "hc_theme")
 }
 
 assertthat::on_failure(.is_highchart) <- function(call, env) {
 
-  "The theme used is not a hc_theme object"
+  "The theme used is not from hc_theme class"
 
 }

R/data-citytemp.R

@@ -18,7 +18,6 @@
 #' @name citytemp
 #' @usage citytemp
 #' @format A \code{data frame} with 12 observations and 5 variables.
-#' @rdname data
 #' @examples
 #' data(citytemp)
 #' citytemp

R/data-favorite_bars.R

@@ -15,7 +15,6 @@
 #' @name favorite_bars
 #' @usage favorite_bars
 #' @format A \code{data frame} with 5 observations and 2 variables.
-#' @rdname data
 #' @examples
 #' data(favorite_bars)
 #' favorite_bars

R/data-favorite_pies.R

@@ -15,7 +15,6 @@
 #' @name favorite_pies
 #' @usage favorite_pies
 #' @format A \code{data frame} with 5 observations and 2 variables.
-#' @rdname data
 #' @examples
 #' data(favorite_pies)
 #' favorite_pies

R/helpers.R

@@ -2,14 +2,20 @@
 #'
 #' This function is similiar to \code{rlist::list.parse} but this removes names. 
 #' 
-#' @param df A data frame to 
+#' @param df A data frame to parse to list
 #' 
-#' @importFrom stats setNames
+#' @examples 
+#' 
+#' x <- data.frame(a=1:3,type=c('A','C','B'))
+#' 
+#' list.parse2(x)
 #' 
-#' @rdname helpers
+#' @importFrom stats setNames
 #' @export
 list.parse2 <- function(df) {
 
+  assertthat::assert_that(is.data.frame(df))
+  
   setNames(apply(df, 1, function(r) as.list(as.vector(r))), NULL)
 
 }
@@ -20,26 +26,33 @@ list.parse2 <- function(df) {
 #' 
 #' @param x A vector string.
 #' 
+#' @examples 
+#' 
+#' str_to_id(" A string _ with    Underscores   ")
+#' 
 #' @importFrom stringr str_to_lower str_replace_all
-#' @rdname helpers
 #' @export
 str_to_id <- function(x) {
 
-  assert_that(is.character(x))
+  assertthat::assert_that(is.character(x))
 
   x %>% 
     str_trim() %>%
     str_to_lower() %>% 
     str_replace_all("\\s+", "_") %>% 
-    iconv("latin1", "ASCII", sub="")
+    str_replace_all("_+", "_") %>% 
+    iconv("latin1", "ASCII", sub = "")
 
 }
 
 #' Get default colors for Highcharts theme
 #'
 #' Get color used in highcharts charts.
 #' 
-#' @rdname helpers
+#' @examples 
+#' 
+#' hc_get_colors()[1:5]
+#' 
 #' @export
 hc_get_colors <- function() {
 
@@ -50,13 +63,16 @@ hc_get_colors <- function() {
 
 #' Get dash styles
 #'
-#' Get dash style to use on hichartrs objects.
+#' Get dash style to use on highcharts objects.
+#' 
+#' @examples 
+#' 
+#' hc_get_dash_styles()[1:5]
 #' 
-#' @rdname helpers
 #' @export
 hc_get_dash_styles <- function() {
 
-  c("Solid", "ShortDash", "ShortDot", "ShortDashDot", "ShortDashDotDot", "Dot",
-    "Dash", "LongDash", "DashDot", "LongDashDot", "LongDashDotDot")
+  c("Solid", "ShortDash", "ShortDot", "ShortDashDot", "ShortDashDotDot",
+    "Dot", "Dash", "LongDash", "DashDot", "LongDashDot", "LongDashDotDot")
 
 }

R/highcharter-package.R

@@ -1,5 +1,10 @@
 #' An \code{htmlwidget} interface to the
-#' \href{http://www.highcharts.com/}{Highcharts} javascript chart library
+#' Highcharts javascript chart library
+#' 
+#' Highcarts \url{http://www.highcharts.com/} is a mature javascript
+#' charting library. Highcharts provide a various type of charts, from
+#' scatters to heatmaps or treemaps. 
+#' 
 #' @name hicharter
 #' @docType package
 #' @author Joshua Kunst (@@jbkunst)

R/shortcuts.R

@@ -29,7 +29,7 @@
 #' @export 
 hc_add_serie_ts2 <- function(hc, ts, ...) {
 
-  assert_that(is.ts(ts), .is_highchart(hc))
+  assertthat::assert_that(is.ts(ts), .is_highchart(hc))
 
   # http://stackoverflow.com/questions/29202021/r-how-to-extract-dates-from-a-time-series
   dates <- time(ts) %>% 
@@ -59,8 +59,8 @@ hc_add_serie_ts2 <- function(hc, ts, ...) {
 #' require("ggplot2")
 #' data(economics, package = "ggplot2")
 #' 
-#' hc_add_serie_ts(highchart(),
-#'                 economics$psavert, economics$date,
+#' hc_add_serie_ts(hc = highchart(),
+#'                 values = economics$psavert, dates = economics$date,
 #'                 name = "Personal Savings Rate")
 #' }
 #' 
@@ -69,7 +69,7 @@ hc_add_serie_ts2 <- function(hc, ts, ...) {
 #' @export 
 hc_add_serie_ts <- function(hc, values, dates, ...) {
 
-  assert_that(.is_highchart(hc), is.numeric(values), is.date(dates))
+  assertthat::assert_that(.is_highchart(hc), is.numeric(values), is.date(dates))
 
   timestamps <- dates %>% 
     zoo::as.Date() %>%
@@ -148,8 +148,8 @@ hc_add_serie_ts <- function(hc, values, dates, ...) {
 hc_add_serie_scatter <- function(hc, x, y, z = NULL, color = NULL, label = NULL,
                                  showInLegend = FALSE, viridis.option = "D", ...) {
 
-  assert_that(.is_highchart(hc), length(x) == length(y),
-              is.numeric(x), is.numeric(y))
+  assertthat::assert_that(.is_highchart(hc), length(x) == length(y),
+                          is.numeric(x), is.numeric(y))
 
   df <- data_frame(x, y)
 
@@ -228,9 +228,9 @@ hc_add_serie_scatter <- function(hc, x, y, z = NULL, color = NULL, label = NULL,
 #' @export
 hc_add_serie_labels_values <- function(hc, labels, values, colors = NULL, ...) {
 
-  assert_that(.is_highchart(hc),
-              is.numeric(values),
-              length(labels) == length(values))
+  assertthat::assert_that(.is_highchart(hc),
+                          is.numeric(values),
+                          length(labels) == length(values))
 
   df <- data_frame(name = labels, y = values)
 
@@ -292,8 +292,8 @@ hc_add_serie_labels_values <- function(hc, labels, values, colors = NULL, ...) {
 #' @export 
 hc_add_serie_treemap <- function(hc, tm, ...) {
 
-  assert_that(.is_highchart(hc),
-              is.list(tm))
+  assertthat::assert_that(.is_highchart(hc),
+                          is.list(tm))
 
   df <- tm$tm %>% 
     tbl_df() %>% 

R/theme.R

@@ -2,6 +2,8 @@
 #' 
 #' Function to create highcharts themes.
 #' 
+#' More examples are in http://www.highcharts.com/docs/chart-design-and-style/themes.
+#' 
 #' @param ... A named list with the parameters.
 #' 
 #' @examples 
@@ -64,6 +66,16 @@ hc_theme <- function(...){
 #' @param hc A highchart object
 #' @param hc_thm A highchart theme object (\code{"hc_theme"} class)
 #' 
+#' @examples 
+#' 
+#' require("dplyr")
+#' 
+#' highchart() %>% 
+#'   hc_add_serie(data = c(7.0, 6.9, 9.5, 14.5, 18.2, 21.5, 25.2,
+#'                         26.5, 23.3, 18.3, 13.9, 9.6),
+#'                         type = "column") %>% 
+#'   hc_add_theme(hc_theme_sandsignika())
+#'   
 #' @export
 hc_add_theme <- function(hc, hc_thm){
 
@@ -84,6 +96,24 @@ hc_add_theme <- function(hc, hc_thm){
 #' 
 #' @param ... A \code{hc_theme} objects.
 #' 
+#' @examples 
+#' 
+#' thm <- hc_theme_merge(
+#'   hc_theme_darkunica(),
+#'   hc_theme(
+#'     chart = list(
+#'       backgroundColor = "transparent",
+#'       divBackgroundImage = "http://cdn.wall-pix.net/albums/art-3Dview/00025095.jpg"
+#'     ),
+#'     title = list(
+#'       style = list(
+#'         color = 'white',
+#'         fontFamily = "Erica One"
+#'       )
+#'     )
+#'   )
+#' )
+#' 
 #' @export
 hc_theme_merge <- function(...){