From 8e8a7bb3f538731753ad3e318fe68884721a1e5e Mon Sep 17 00:00:00 2001 From: Martin Chan Date: Fri, 5 Feb 2021 19:38:38 +0000 Subject: [PATCH] docs: return options (#31) --- R/afterhours_dist.R | 8 +++----- R/create_bar.R | 26 ++++++++++++++++---------- R/create_dist.R | 16 +++++++++++++--- R/create_fizz.R | 12 ++++++++++-- man/afterhours_dist.Rd | 16 ++++++++++++++-- man/afterhours_fizz.Rd | 9 +++++++-- man/afterhours_summary.Rd | 9 +++++++-- man/collaboration_dist.Rd | 9 +++++++-- man/collaboration_fizz.Rd | 9 +++++++-- man/create_bar.Rd | 24 ++++++++++++++++-------- man/create_dist.Rd | 18 +++++++++++++++--- man/create_fizz.Rd | 16 ++++++++++++++-- man/email_dist.Rd | 9 +++++++-- man/email_fizz.Rd | 9 +++++++-- man/email_summary.Rd | 9 +++++++-- man/meeting_dist.Rd | 9 +++++++-- man/meeting_fizz.Rd | 9 +++++++-- man/meeting_summary.Rd | 9 +++++++-- man/one2one_dist.Rd | 9 +++++++-- man/one2one_fizz.Rd | 9 +++++++-- man/one2one_sum.Rd | 9 +++++++-- man/workloads_dist.Rd | 9 +++++++-- man/workloads_fizz.Rd | 9 +++++++-- man/workloads_summary.Rd | 9 +++++++-- 24 files changed, 213 insertions(+), 67 deletions(-) diff --git a/R/afterhours_dist.R b/R/afterhours_dist.R index f3b50fc3..57e97aac 100644 --- a/R/afterhours_dist.R +++ b/R/afterhours_dist.R @@ -14,11 +14,9 @@ #' Uses the metric \code{After_hours_collaboration_hours}. #' See `create_dist()` for applying the same analysis to a different metric. #' -#' @param data A Standard Person Query dataset in the form of a data frame. -#' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation" -#' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5. -#' @param return Character vector specifying what to return, defaults to "plot". -#' Valid inputs are "plot" and "table". +#' @inheritParams create_dist +#' @inherit create_dist return +#' #' @param cut A vector specifying the cuts to use for the data, #' accepting "default" or "range-cut" as character vector, #' or a numeric value of length three to specify the exact breaks to use. e.g. c(1, 3, 5) diff --git a/R/create_bar.R b/R/create_bar.R index 7b453cc4..aadaf1c9 100644 --- a/R/create_bar.R +++ b/R/create_bar.R @@ -16,14 +16,24 @@ #' @param hrvar HR Variable by which to split metrics, defaults to "Organization" #' but accepts any character vector, e.g. "LevelDesignation" #' @param mingroup Numeric value setting the privacy threshold / minimum group size. Defaults to 5. -#' @param return Character vector specifying what to return, defaults to "plot". -#' Valid inputs are "plot" and "table". +#' +#' @param return String specifying what to return. This must be one of the following strings: +#' - `"plot"` +#' - `"table"` +#' +#' See `Value` for more information. +#' #' @param bar_colour String to specify colour to use for bars. -#' In-built accepted values include "default" (default), "alert" (red), and -#' "darkblue". Otherwise, hex codes are also accepted. You can also supply +#' In-built accepted values include `"default"` (default), `"alert"` (red), and +#' `"darkblue"`. Otherwise, hex codes are also accepted. You can also supply #' RGB values via `rgb2hex()`. -#' @param na.rm A logical value indicating whether NA values should be stripped -#' before the computation proceeds. Defaults to FALSE. +#' @param na.rm A logical value indicating whether `NA` should be stripped +#' before the computation proceeds. Defaults to `FALSE`. +#' +#' @return +#' A different output is returned depending on the value passed to the `return` argument: +#' - `"plot"`: ggplot object. A bar plot for the metric. +#' - `"table"`: data frame. A summary table for the metric. #' #' @import dplyr #' @import ggplot2 @@ -33,10 +43,6 @@ #' #' @family General #' -#' @return -#' Returns a ggplot object by default, where 'plot' is passed in `return`. -#' When 'table' is passed, a summary table is returned as a data frame. -#' #' @examples #' # Return a ggplot bar chart #' create_bar(sq_data, metric = "Collaboration_hours", hrvar = "LevelDesignation") diff --git a/R/create_dist.R b/R/create_dist.R index 64f83421..ba682164 100644 --- a/R/create_dist.R +++ b/R/create_dist.R @@ -11,18 +11,28 @@ #' Additional options available to return a table with distribution elements. #' #' @param data A Standard Person Query dataset in the form of a data frame. -#' @param metric Character string containing the name of the metric, +#' @param metric String containing the name of the metric, #' e.g. "Collaboration_hours" #' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation" #' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5. -#' @param return Character vector specifying what to return, defaults to "plot". -#' Valid inputs are "plot" and "table". +#' +#' @param return String specifying what to return. This must be one of the following strings: +#' - `"plot"` +#' - `"table"` +#' +#' See `Value` for more information. +#' #' @param cut A numeric vector of length three to specify the breaks for the distribution, #' e.g. c(10, 15, 20) #' @param dist_colours A character vector of length four to specify colour #' codes for the stacked bars. #' @param unit See `cut_hour()`. #' +#' @return +#' A different output is returned depending on the value passed to the `return` argument: +#' - `"plot"`: ggplot object. A stacked bar plot for the metric. +#' - `"table"`: data frame. A summary table for the metric. +#' #' @import dplyr #' @import ggplot2 #' @import reshape2 diff --git a/R/create_fizz.R b/R/create_fizz.R index 650a7e18..01d0c88f 100644 --- a/R/create_fizz.R +++ b/R/create_fizz.R @@ -18,8 +18,16 @@ #' e.g. "Collaboration_hours" #' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation" #' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5. -#' @param return Character vector specifying what to return, defaults to "plot". -#' Valid inputs are "plot" and "table". +#' @param return String specifying what to return. This must be one of the following strings: +#' - `"plot"` +#' - `"table"` +#' +#' See `Value` for more information. +#' +#' @return +#' A different output is returned depending on the value passed to the `return` argument: +#' - `"plot"`: ggplot object. A jittered scatter plot for the metric. +#' - `"table"`: data frame. A summary table for the metric. #' #' @import dplyr #' @import ggplot2 diff --git a/man/afterhours_dist.Rd b/man/afterhours_dist.Rd index c1f03ee2..7d211c3c 100644 --- a/man/afterhours_dist.Rd +++ b/man/afterhours_dist.Rd @@ -19,13 +19,25 @@ afterhours_dist( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A vector specifying the cuts to use for the data, accepting "default" or "range-cut" as character vector, or a numeric value of length three to specify the exact breaks to use. e.g. c(1, 3, 5)} } +\value{ +A different output is returned depending on the value passed to the \code{return} argument: +\itemize{ +\item \code{"plot"}: ggplot object. A stacked bar plot for the metric. +\item \code{"table"}: data frame. A summary table for the metric. +} +} \description{ Analyse the distribution of weekly after-hours collaboration time. Returns a stacked bar plot by default. diff --git a/man/afterhours_fizz.Rd b/man/afterhours_fizz.Rd index 3f091911..cca9e559 100644 --- a/man/afterhours_fizz.Rd +++ b/man/afterhours_fizz.Rd @@ -13,8 +13,13 @@ afterhours_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze weekly after-hours collaboration hours distribution, and returns diff --git a/man/afterhours_summary.Rd b/man/afterhours_summary.Rd index d9d56f95..877400c0 100644 --- a/man/afterhours_summary.Rd +++ b/man/afterhours_summary.Rd @@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \value{ Returns a ggplot object by default, where 'plot' is passed in \code{return}. diff --git a/man/collaboration_dist.Rd b/man/collaboration_dist.Rd index 60e7013b..c7f188fc 100644 --- a/man/collaboration_dist.Rd +++ b/man/collaboration_dist.Rd @@ -37,8 +37,13 @@ collaboration_distribution( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} diff --git a/man/collaboration_fizz.Rd b/man/collaboration_fizz.Rd index e77dcfd0..4b4d2151 100644 --- a/man/collaboration_fizz.Rd +++ b/man/collaboration_fizz.Rd @@ -16,8 +16,13 @@ collab_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze weekly collaboration hours distribution, and returns diff --git a/man/create_bar.Rd b/man/create_bar.Rd index 69eca8a8..bb62d8db 100644 --- a/man/create_bar.Rd +++ b/man/create_bar.Rd @@ -25,20 +25,28 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{bar_colour}{String to specify colour to use for bars. -In-built accepted values include "default" (default), "alert" (red), and -"darkblue". Otherwise, hex codes are also accepted. You can also supply +In-built accepted values include \code{"default"} (default), \code{"alert"} (red), and +\code{"darkblue"}. Otherwise, hex codes are also accepted. You can also supply RGB values via \code{rgb2hex()}.} -\item{na.rm}{A logical value indicating whether NA values should be stripped -before the computation proceeds. Defaults to FALSE.} +\item{na.rm}{A logical value indicating whether \code{NA} should be stripped +before the computation proceeds. Defaults to \code{FALSE}.} } \value{ -Returns a ggplot object by default, where 'plot' is passed in \code{return}. -When 'table' is passed, a summary table is returned as a data frame. +A different output is returned depending on the value passed to the \code{return} argument: +\itemize{ +\item \code{"plot"}: ggplot object. A bar plot for the metric. +\item \code{"table"}: data frame. A summary table for the metric. +} } \description{ Provides an overview analysis of a selected metric by calculating a mean per metric. diff --git a/man/create_dist.Rd b/man/create_dist.Rd index 05153c05..f5e5fac2 100644 --- a/man/create_dist.Rd +++ b/man/create_dist.Rd @@ -18,15 +18,20 @@ create_dist( \arguments{ \item{data}{A Standard Person Query dataset in the form of a data frame.} -\item{metric}{Character string containing the name of the metric, +\item{metric}{String containing the name of the metric, e.g. "Collaboration_hours"} \item{hrvar}{HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} @@ -36,6 +41,13 @@ codes for the stacked bars.} \item{unit}{See \code{cut_hour()}.} } +\value{ +A different output is returned depending on the value passed to the \code{return} argument: +\itemize{ +\item \code{"plot"}: ggplot object. A stacked bar plot for the metric. +\item \code{"table"}: data frame. A summary table for the metric. +} +} \description{ Provides an analysis of the distribution of a selected metric. Returns a stacked bar plot by default. diff --git a/man/create_fizz.Rd b/man/create_fizz.Rd index c8fc5f76..90864583 100644 --- a/man/create_fizz.Rd +++ b/man/create_fizz.Rd @@ -22,8 +22,20 @@ e.g. "Collaboration_hours"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} +} +\value{ +A different output is returned depending on the value passed to the \code{return} argument: +\itemize{ +\item \code{"plot"}: ggplot object. A jittered scatter plot for the metric. +\item \code{"table"}: data frame. A summary table for the metric. +} } \description{ Analyzes a selected metric and returns a a 'fizzy' scatter plot by default. diff --git a/man/email_dist.Rd b/man/email_dist.Rd index 24c1a5dc..2dc82a04 100644 --- a/man/email_dist.Rd +++ b/man/email_dist.Rd @@ -19,8 +19,13 @@ email_dist( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} diff --git a/man/email_fizz.Rd b/man/email_fizz.Rd index 7a53a103..a8067034 100644 --- a/man/email_fizz.Rd +++ b/man/email_fizz.Rd @@ -13,8 +13,13 @@ email_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze weekly email hours distribution, and returns diff --git a/man/email_summary.Rd b/man/email_summary.Rd index fe67de93..114c327f 100644 --- a/man/email_summary.Rd +++ b/man/email_summary.Rd @@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \value{ Returns a ggplot object by default, where 'plot' is passed in \code{return}. diff --git a/man/meeting_dist.Rd b/man/meeting_dist.Rd index ab702d56..12202d95 100644 --- a/man/meeting_dist.Rd +++ b/man/meeting_dist.Rd @@ -19,8 +19,13 @@ meeting_dist( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} diff --git a/man/meeting_fizz.Rd b/man/meeting_fizz.Rd index b716d417..6371163e 100644 --- a/man/meeting_fizz.Rd +++ b/man/meeting_fizz.Rd @@ -13,8 +13,13 @@ meeting_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze weekly meeting hours distribution, and returns diff --git a/man/meeting_summary.Rd b/man/meeting_summary.Rd index a89a57a9..baac1fa1 100644 --- a/man/meeting_summary.Rd +++ b/man/meeting_summary.Rd @@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \value{ Returns a ggplot object by default, where 'plot' is passed in \code{return}. diff --git a/man/one2one_dist.Rd b/man/one2one_dist.Rd index 2abec8dc..a2a5e17c 100644 --- a/man/one2one_dist.Rd +++ b/man/one2one_dist.Rd @@ -19,8 +19,13 @@ one2one_dist( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} diff --git a/man/one2one_fizz.Rd b/man/one2one_fizz.Rd index 5af22aa3..57581a46 100644 --- a/man/one2one_fizz.Rd +++ b/man/one2one_fizz.Rd @@ -13,8 +13,13 @@ one2one_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze weekly Manager 1:1 Time distribution, and returns diff --git a/man/one2one_sum.Rd b/man/one2one_sum.Rd index ce1d3181..57cf7f6a 100644 --- a/man/one2one_sum.Rd +++ b/man/one2one_sum.Rd @@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \value{ Returns a ggplot object by default, where 'plot' is passed in \code{return}. diff --git a/man/workloads_dist.Rd b/man/workloads_dist.Rd index e109a336..34ecbd2f 100644 --- a/man/workloads_dist.Rd +++ b/man/workloads_dist.Rd @@ -19,8 +19,13 @@ workloads_dist( \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} \item{cut}{A numeric vector of length three to specify the breaks for the distribution, e.g. c(10, 15, 20)} diff --git a/man/workloads_fizz.Rd b/man/workloads_fizz.Rd index 17c37a38..2aec1f01 100644 --- a/man/workloads_fizz.Rd +++ b/man/workloads_fizz.Rd @@ -13,8 +13,13 @@ workloads_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot") \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \description{ Analyze Work Week Span distribution, and returns diff --git a/man/workloads_summary.Rd b/man/workloads_summary.Rd index 4677bdd7..fe5f5dd2 100644 --- a/man/workloads_summary.Rd +++ b/man/workloads_summary.Rd @@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"} \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.} -\item{return}{Character vector specifying what to return, defaults to "plot". -Valid inputs are "plot" and "table".} +\item{return}{String specifying what to return. This must be one of the following strings: +\itemize{ +\item \code{"plot"} +\item \code{"table"} +} + +See \code{Value} for more information.} } \value{ Returns a ggplot object by default, where 'plot' is passed in \code{return}.