docs: improve documentation

R/flex_index.R

@@ -40,14 +40,15 @@
 #' em_data %>%
 #'   flex_index(return = "plot", plot_method = "time")
 #'
+#' # Return a summary table with the computed Flexibility Index
+#' em_data %>%
+#'   flex_index(hrvar = "Organization", return = "table")
+#'
 #' \dontrun{
 #' # Return the raw data with the computed Flexibility Index
 #' em_data %>%
 #'   flex_index(return = "data")
 #'
-#' # Return a summary table with the computed Flexibility Index
-#' em_data %>%
-#'   flex_index(return = "table")
 #'
 #' }
 #' @family Work Patterns
@@ -201,7 +202,7 @@ flex_index <- function(data,
     # hr_dt <- data2[, ..temp_str] # double dot prefix
 
     hr_dt <-
-      hr_dt %>%
+      data2 %>%
       as.data.frame() %>%
       select(temp_str)
   }

R/workpatterns_area.R

@@ -10,24 +10,31 @@
 #' Emails sent and IMs sent attended by hour of the day.
 #'
 #' @param data A data frame containing data from the Hourly Collaboration query.
+#'
 #' @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 signals Character vector to specify which collaboration metrics to use:
 #'   - "email" (default) for emails only
 #'   - "IM" for Teams messages only
 #'   - "unscheduled_calls" for Unscheduled Calls only
 #'   - "meetings" for Meetings only
 #'   - or a combination of signals, such as `c("email", "IM")`
-#' @param return Character vector to specify what to return.
-#' Valid options include "plot" (default) and "table".
-#' "plot" returns an overlapping area plot.
-#' "table" returns a summary table.
+#'
+#' @param return Character vector to specify what to return. Valid options include:
+#'   - "plot": returns an overlapping area plot (default)
+#'   - "table": returns a summary table
+#'
 #' @param values Character vector to specify whether to return percentages
-#' or absolute values in "data" and "plot". Valid values are "percent" (default)
-#' and "abs".
+#' or absolute values in "data" and "plot". Valid values are:
+#'   - "percent": percentage of signals divided by total signals (default)
+#'   - "abs": absolute count of signals
+#'
 #' @param start_hour A character vector specifying starting hours,
 #' e.g. "0900"
+#'
 #' @param end_hour A character vector specifying starting hours,
 #' e.g. "1700"
 #'
@@ -216,14 +223,6 @@ workpatterns_area <- function(data,
       left_join(count_tb, by = "group") %>%
       return()
 
-  } else if(return == "hclust"){
-
-    return(h_clust)
-
-  } else if(return == "dist"){
-
-    return(dist_m)
-
   } else {
 
     stop("Invalid input for `return`.")

R/workpatterns_classify.R

@@ -15,9 +15,11 @@
 #' Defaults to NULL. This only affects the function when "table" is returned,
 #' and is only applicable for method = "bw".
 #'
-#' @param return Character vector to specify what to return.
-#' Valid options include "plot" (default), "data", "table" and "plot-area".
-#' "plot" returns a bar plot, whilst "plot-area" returns an overlapping area plot.
+#' @param return Character vector to specify what to return. Valid options include:
+#'   - "plot": returns a heatmap plot of signal distribution by hour and archetypes (default)
+#'   - "data": returns the raw data with the classified archetypes
+#'   - "table": returns a summary table of the archetypes
+#'   - "plot-area": returns an area plot of the percentages of archetypes shown over time
 #'
 #' @param method String to pass through specifying which method to use for classification.
 #' By default, a binary week-based (bw) method is used, with options to use the

R/workpatterns_classify_bw.R

@@ -7,16 +7,26 @@
 #' using the binary week-based (bw) method.
 #'
 #' @param data A data frame containing email by hours data.
+#'
 #' @param hrvar A string specifying the HR attribute to cut the data by.
 #' Defaults to NULL. This only affects the function when "table" is returned.
-#' @param return Character vector to specify what to return.
-#' Valid options include "plot" (default), "data", "table" and "plot-area".
-#' "plot" returns a bar plot, whilst "plot-area" returns an overlapping area plot.
+#'
+#' @param return Character vector to specify what to return. Valid options include:
+#'   - "plot": returns a heatmap plot of signal distribution by hour and archetypes (default)
+#'   - "data": returns the raw data with the classified archetypes
+#'   - "table": returns a summary table of the archetypes
+#'   - "plot-area": returns an area plot of the percentages of archetypes shown over time
+#'
 #' @param signals Character vector to specify which collaboration metrics to use:
-#' You may use "email" for emails only, "IM" for Teams messages only,
-#' or a combination of the two `c("email", "IM")` (default).
+#'   - "email" (default) for emails only
+#'   - "IM" for Teams messages only,
+#'   - "unscheduled_calls" for Unscheduled Calls only
+#'   - "meetings" for Meetings only
+#'   - or a combination of signals, such as `c("email", "IM")`
+#'
 #' @param active_threshold A numeric value specifying the minimum number of signals to be greater than in
 #' order to qualify as _active_. Defaults to 0.
+#'
 #' @param start_hour A character vector specifying start hours,
 #' e.g. "0900"
 #' @param end_hour A character vector specifying finish hours,

R/workpatterns_report.R

@@ -1,8 +1,9 @@
 #' @title Generate a report on working patterns in HTML
 #'
 #' @description
+#' `r lifecycle::badge('experimental')`
 #' This function takes a Hourly Collaboration query and generates a HTML report on
-#' working patterns archetypes.
+#' working patterns archetypes. Archetypes are created using the binary-week method.
 #'
 #' @param data A Hourly Collaboration Query dataset in the form of a data frame.
 #' @param hrvar String specifying HR attribute to cut by archetypes. Defaults to `Organization`.
@@ -98,19 +99,23 @@ workpatterns_report <- function(data,
 
   ## Set outputs
   output_list <-
-    list(data %>% wpa::check_query(return = "text"),
-	     data %>% workpatterns_rank(start_hour = start_hour, end_hour = end_hour,return = "plot"),
-         personas_plot,
-		 wp_list$table,
-         wp_list$plot_area,
-         plot_rank_list[[1]],
-         plot_rank_list[[2]],
-         plot_rank_list[[3]],
-         plot_rank_list[[4]],
-         plot_rank_list[[5]],
-         plot_rank_list[[6]],
-         plot_rank_list[[7]]) %>% # Expand objects to this list
-    purrr::map_if(is.data.frame, wpa::create_dt) %>%
+    list(
+      data %>% wpa::check_query(return = "text"),
+      data %>%
+        workpatterns_rank(start_hour = start_hour,
+                          end_hour = end_hour,
+                          return = "plot"),
+      personas_plot,
+      wp_list$table,
+      wp_list$plot_area,
+      plot_rank_list[[1]],
+      plot_rank_list[[2]],
+      plot_rank_list[[3]],
+      plot_rank_list[[4]],
+      plot_rank_list[[5]],
+      plot_rank_list[[6]],
+      plot_rank_list[[7]]) %>% # Expand objects to this list
+    purrr::map_if(is.data.frame, wpa::create_dt, rounding = 2) %>%
     purrr::map_if(is.character, md2html)
 
   ## Set header titles

man/flex_index.Rd

@@ -61,14 +61,15 @@ em_data \%>\%
 em_data \%>\%
   flex_index(return = "plot", plot_method = "time")
 
+# Return a summary table with the computed Flexibility Index
+em_data \%>\%
+  flex_index(hrvar = "Organization", return = "table")
+
 \dontrun{
 # Return the raw data with the computed Flexibility Index
 em_data \%>\%
   flex_index(return = "data")
 
-# Return a summary table with the computed Flexibility Index
-em_data \%>\%
-  flex_index(return = "table")
 
 }
 }

man/workpatterns_area.Rd

@@ -32,14 +32,18 @@ defaults to "Organization" but accepts any character vector, e.g. "LevelDesignat
 \item or a combination of signals, such as \code{c("email", "IM")}
 }}
 
-\item{return}{Character vector to specify what to return.
-Valid options include "plot" (default) and "table".
-"plot" returns an overlapping area plot.
-"table" returns a summary table.}
+\item{return}{Character vector to specify what to return. Valid options include:
+\itemize{
+\item "plot": returns an overlapping area plot (default)
+\item "table": returns a summary table
+}}
 
 \item{values}{Character vector to specify whether to return percentages
-or absolute values in "data" and "plot". Valid values are "percent" (default)
-and "abs".}
+or absolute values in "data" and "plot". Valid values are:
+\itemize{
+\item "percent": percentage of signals divided by total signals (default)
+\item "abs": absolute count of signals
+}}
 
 \item{start_hour}{A character vector specifying starting hours,
 e.g. "0900"}

man/workpatterns_classify.Rd

@@ -46,9 +46,13 @@ e.g. "1700". Note that this currently only supports \strong{hourly} increments.}
 By default, a binary week-based (bw) method is used, with options to use the
 the person-average volume-based (pav) method.}
 
-\item{return}{Character vector to specify what to return.
-Valid options include "plot" (default), "data", "table" and "plot-area".
-"plot" returns a bar plot, whilst "plot-area" returns an overlapping area plot.}
+\item{return}{Character vector to specify what to return. Valid options include:
+\itemize{
+\item "plot": returns a heatmap plot of signal distribution by hour and archetypes (default)
+\item "data": returns the raw data with the classified archetypes
+\item "table": returns a summary table of the archetypes
+\item "plot-area": returns an area plot of the percentages of archetypes shown over time
+}}
 }
 \description{
 \ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}

man/workpatterns_classify_bw.Rd

@@ -22,8 +22,13 @@ workpatterns_classify_bw(
 Defaults to NULL. This only affects the function when "table" is returned.}
 
 \item{signals}{Character vector to specify which collaboration metrics to use:
-You may use "email" for emails only, "IM" for Teams messages only,
-or a combination of the two \code{c("email", "IM")} (default).}
+\itemize{
+\item "email" (default) for emails only
+\item "IM" for Teams messages only,
+\item "unscheduled_calls" for Unscheduled Calls only
+\item "meetings" for Meetings only
+\item or a combination of signals, such as \code{c("email", "IM")}
+}}
 
 \item{start_hour}{A character vector specifying start hours,
 e.g. "0900"}
@@ -34,9 +39,13 @@ e.g. "1700"}
 \item{active_threshold}{A numeric value specifying the minimum number of signals to be greater than in
 order to qualify as \emph{active}. Defaults to 0.}
 
-\item{return}{Character vector to specify what to return.
-Valid options include "plot" (default), "data", "table" and "plot-area".
-"plot" returns a bar plot, whilst "plot-area" returns an overlapping area plot.}
+\item{return}{Character vector to specify what to return. Valid options include:
+\itemize{
+\item "plot": returns a heatmap plot of signal distribution by hour and archetypes (default)
+\item "data": returns the raw data with the classified archetypes
+\item "table": returns a summary table of the archetypes
+\item "plot-area": returns an area plot of the percentages of archetypes shown over time
+}}
 }
 \description{
 \ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}

man/workpatterns_report.Rd

@@ -32,6 +32,7 @@ For example, "scope report".}
 Defaults to TRUE.}
 }
 \description{
+\ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}
 This function takes a Hourly Collaboration query and generates a HTML report on
-working patterns archetypes.
+working patterns archetypes. Archetypes are created using the binary-week method.
 }