From c7173580687270250b6a69bc7e8acc4c0da0cd1d Mon Sep 17 00:00:00 2001 From: pvictor Date: Wed, 17 Nov 2021 12:13:25 +0100 Subject: [PATCH] updated facets documentation --- R/facets.R | 26 ++++++++++++++++++-------- examples/facet-wrap-shiny.R | 13 +++++++------ man/apex-facets.Rd | 12 +++++++++--- man/apexcharter-shiny-facets.Rd | 18 +++++++++++------- 4 files changed, 45 insertions(+), 24 deletions(-) diff --git a/R/facets.R b/R/facets.R index 87022c1..1ceb431 100644 --- a/R/facets.R +++ b/R/facets.R @@ -206,17 +206,24 @@ get_last_row <- function(mat) { -#' Facet wrap for ApexCharts +#' @title Facets for ApexCharts +#' +#' @description Create matrix of charts by row and column faceting variable (`ax_facet_grid`), +#' or by specified number of row and column for faceting variable(s) (`ax_facet_wrap`). #' #' @param ax An [apexchart()] `htmlwidget` object. -#' @param facets Variable(s) to use for facetting, wrapped in \code{vars(...)}. +#' @param facets Variable(s) to use for facetting, wrapped in `vars(...)`. #' @param nrow,ncol Number of row and column in output matrix. -#' @param scales Should scales be fixed (\code{"fixed"}, the default), -#' free (\code{"free"}), or free in one dimension (\code{"free_x"}, \code{"free_y"})? +#' @param scales Should scales be fixed (`"fixed"`, the default), +#' free (`"free"`), or free in one dimension (`"free_x"`, `"free_y"`)? #' @param labeller A function with one argument containing for each facet the value of the faceting variable. #' @param chart_height Individual chart height. #' #' @return An [apexchart()] `htmlwidget` object with an additionnal class `"apex_facet"`. +#' +#' @details # Warning +#' To properly render in Shiny applications, use [apexfacetOutput()] (in UI) and [renderApexfacet()] (in Server). +#' #' @export #' #' @name apex-facets @@ -250,7 +257,8 @@ ax_facet_wrap <- function(ax, } -#' @param rows,cols A set of variables or expressions quoted by vars() and defining faceting groups on the rows or columns dimension. +#' @param rows,cols A set of variables or expressions quoted by `vars()` +#' and defining faceting groups on the rows or columns dimension. #' @export #' #' @rdname apex-facets @@ -450,10 +458,12 @@ apexfacetOutput <- function(outputId) { ) } -#' @param expr An expression that generates a apexcharter facet. -#' @param env The environment in which to evaluate \code{expr}. -#' @param quoted Is \code{expr} a quoted expression (with \code{quote()})? This +#' @param expr An expression that generates a apexcharter facet with [ax_facet_wrap()] or [ax_facet_grid()]. +#' @param env The environment in which to evaluate `expr`. +#' @param quoted Is `expr` a quoted expression (with `quote()`)? This #' is useful if you want to save an expression in a variable. +#' +#' @seealso [ax_facet_wrap()], [ax_facet_grid()] #' #' @export #' diff --git a/examples/facet-wrap-shiny.R b/examples/facet-wrap-shiny.R index 6390a52..f555f96 100644 --- a/examples/facet-wrap-shiny.R +++ b/examples/facet-wrap-shiny.R @@ -4,7 +4,9 @@ library(apexcharter) data("unhcr_ts") refugees <- unhcr_ts %>% - subset(population_type == "Refugees (incl. refugee-like situations)") %>% + subset( + population_type == "Refugees (incl. refugee-like situations)" + ) %>% transform(date = as.Date(paste0(year, "-01-01"))) @@ -21,14 +23,13 @@ server <- function(input, output, session) { output$myfacet <- renderApexfacet({ apex(refugees, aes(date, n), type = "column") %>% ax_yaxis(tickAmount = 5) %>% - ax_facet_wrap(vars(continent_origin), scales = "free") + ax_facet_wrap( + vars(continent_origin), + scales = "free" + ) }) } if (interactive()) shinyApp(ui, server) - - - - diff --git a/man/apex-facets.Rd b/man/apex-facets.Rd index c49d9d5..93a69af 100644 --- a/man/apex-facets.Rd +++ b/man/apex-facets.Rd @@ -4,7 +4,7 @@ \alias{apex-facets} \alias{ax_facet_wrap} \alias{ax_facet_grid} -\title{Facet wrap for ApexCharts} +\title{Facets for ApexCharts} \usage{ ax_facet_wrap( ax, @@ -39,14 +39,20 @@ free (\code{"free"}), or free in one dimension (\code{"free_x"}, \code{"free_y"} \item{chart_height}{Individual chart height.} -\item{rows, cols}{A set of variables or expressions quoted by vars() and defining faceting groups on the rows or columns dimension.} +\item{rows, cols}{A set of variables or expressions quoted by \code{vars()} +and defining faceting groups on the rows or columns dimension.} } \value{ An \code{\link[=apexchart]{apexchart()}} \code{htmlwidget} object with an additionnal class \code{"apex_facet"}. } \description{ -Facet wrap for ApexCharts +Create matrix of charts by row and column faceting variable (\code{ax_facet_grid}), +or by specified number of row and column for faceting variable(s) (\code{ax_facet_wrap}). } +\section{Warning}{ +To properly render in Shiny applications, use \code{\link[=apexfacetOutput]{apexfacetOutput()}} (in UI) and \code{\link[=renderApexfacet]{renderApexfacet()}} (in Server). +} + \examples{ ### Wrap -------- diff --git a/man/apexcharter-shiny-facets.Rd b/man/apexcharter-shiny-facets.Rd index 1f917cb..79256c7 100644 --- a/man/apexcharter-shiny-facets.Rd +++ b/man/apexcharter-shiny-facets.Rd @@ -13,7 +13,7 @@ renderApexfacet(expr, env = parent.frame(), quoted = FALSE) \arguments{ \item{outputId}{output variable to read from} -\item{expr}{An expression that generates a apexcharter facet.} +\item{expr}{An expression that generates a apexcharter facet with \code{\link[=ax_facet_wrap]{ax_facet_wrap()}} or \code{\link[=ax_facet_grid]{ax_facet_grid()}}.} \item{env}{The environment in which to evaluate \code{expr}.} @@ -34,7 +34,9 @@ library(apexcharter) data("unhcr_ts") refugees <- unhcr_ts \%>\% - subset(population_type == "Refugees (incl. refugee-like situations)") \%>\% + subset( + population_type == "Refugees (incl. refugee-like situations)" + ) \%>\% transform(date = as.Date(paste0(year, "-01-01"))) @@ -51,15 +53,17 @@ server <- function(input, output, session) { output$myfacet <- renderApexfacet({ apex(refugees, aes(date, n), type = "column") \%>\% ax_yaxis(tickAmount = 5) \%>\% - ax_facet_wrap(vars(continent_origin), scales = "free") + ax_facet_wrap( + vars(continent_origin), + scales = "free" + ) }) } if (interactive()) shinyApp(ui, server) - - - - +} +\seealso{ +\code{\link[=ax_facet_wrap]{ax_facet_wrap()}}, \code{\link[=ax_facet_grid]{ax_facet_grid()}} }