docs: add return options (#31)

+ General clean up of all functions on documentation consistency.

R/IV_report.R

@@ -29,7 +29,8 @@
 #' \dontrun{
 #' sq_data %>%
 #'   mutate(X = ifelse(Collaboration_hours > 12, 1, 0)) %>% # Simulate binary variable
-#'   IV_report(outcome =  "CH_binary", predictors = c("Email_hours", "Workweek_span"))
+#'   IV_report(outcome =  "CH_binary",
+#'             predictors = c("Email_hours", "Workweek_span"))
 #' }
 #'
 #' @family Reports

R/check_query.R

@@ -5,21 +5,36 @@
 
 #' @title Check a query to ensure that it is suitable for analysis
 #'
-#' @description
-#' Prints diagnostic data about the data query to the R console, with information
-#' such as date range, number of employees, HR attributes identified, etc.
+#' @description Prints diagnostic data about the data query to the R console,
+#' with information such as date range, number of employees, HR attributes
+#' identified, etc.
 #'
-#' @details
-#' This can be used with any person-level query, such as the standard person query,
-#' Ways of Working assessment query, and the hourly collaboration query. When run,
-#' this prints diagnostic data to the R console.
+#' @details This can be used with any person-level query, such as the standard
+#' person query, Ways of Working assessment query, and the hourly collaboration
+#' query. When run, this prints diagnostic data to the R console.
 #'
-#' @param data A person-level query in the form of a data frame, including the standard person query,
-#' Ways of Working assessment query, and the hourly collaboration query.
-#' @param return Character string to specify whether to return a console message ("message"),
-#' a character string ("text"), or a data frame. Defaults to "message".
-#' @param validation Logical value to specify whether to return a check used by the `validation_report()`.
-#' Defaults to FALSE.
+#' @param data A person-level query in the form of a data frame. This includes:
+#'   - Standard Person Query
+#'   - Ways of Working Assessment Query
+#'   - Hourly Collaboration Query
+#'
+#' All person-level query have a `PersonId` column and a `Date` column.
+#'
+#' @param return String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"message"` (default)
+#'   - `"text"`
+#'
+#' See `Value` for more information.
+#'
+#' @param validation Logical value to specify whether to return a check used by
+#'   the `validation_report()`. Defaults to `FALSE`.
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return`
+#' argument:
+#'   - `"message"`: a message is returned to the console.
+#'   - `"text"`: string containing the diagnostic message.
 #'
 #' @examples
 #' check_query(sq_data)

R/collaboration_area.R

@@ -17,11 +17,16 @@
 #' @param data A Standard Person Query dataset in the form of a data frame.
 #' A Ways of Working assessment dataset may also be provided, in which
 #' Unscheduled call hours would be included in the output.
-#' @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 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 String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"plot"`
+#'   - `"table"`
 #'
+#' See `Value` for more information.
 #'
 #' @import dplyr
 #' @import ggplot2
@@ -34,8 +39,9 @@
 #' collaboration_area(sq_data)
 #'
 #' @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.
+#' A different output is returned depending on the value passed to the `return` argument:
+#'   - `"plot"`: ggplot object. A stacked area plot for the metric.
+#'   - `"table"`: data frame. A summary table for the metric.
 #'
 #' @export
 

R/create_fizz.R

@@ -3,15 +3,15 @@
 # Licensed under the MIT License. See LICENSE.txt in the project root for license information.
 # --------------------------------------------------------------------------------------------
 
-#' @title Fizzy Drink / Jitter Scatter Plot for any metric
+#' @title Fizzy Drink / Jittered Scatter Plot for any metric
 #'
 #' @description
-#' Analyzes a selected metric and returns a a 'fizzy' scatter plot by default.
+#' Analyzes a selected metric and returns a 'fizzy' scatter plot by default.
 #' Additional options available to return a table with distribution elements.
 #'
 #' @details
 #' This is a general purpose function that powers all the functions
-#' in the package that produce 'fizzy drink' / jitter scatter plots.
+#' in the package that produce 'fizzy drink' / jittered scatter plots.
 #'
 #' @param data A Standard Person Query dataset in the form of a data frame.
 #' @param metric Character string containing the name of the metric,

R/create_line.R

@@ -36,10 +36,13 @@
 #' @family Flexible
 #'
 #' @examples
+#' # Return plot of Email Hours
 #' sq_data %>% create_line(metric = "Email_hours", return = "plot")
 #'
+#' # Return plot of Collaboration Hours
 #' sq_data %>% create_line(metric = "Collaboration_hours", return = "plot")
 #'
+#' # Return plot of Work week span and cut by `LevelDesignation`
 #' sq_data %>% create_line(metric = "Workweek_span", hrvar = "LevelDesignation")
 #'
 #' @return

R/flex_index.R

@@ -37,9 +37,8 @@
 #' Index of a team of 6 over time, where the possible values would range from 0
 #' to 1.
 #'
-#'
-#'
-#' @section Context: The central feature of flexible working arrangements is
+#' @section Context:
+#'   The central feature of flexible working arrangements is
 #'   that it is the employee rather the employer who chooses the working
 #'   arrangement. _Observed flexibility_ serves as a proxy to assess whether a
 #'   flexible working arrangement are in place. The Flexibility Index is an
@@ -62,15 +61,28 @@
 #'
 #' @param end_hour A character vector specifying end hours, e.g. "1700"
 #'
-#' @param return Character vector to specify what to return. Valid options
-#'   include "plot" (default), "data", and "table". When returning a plot, a
-#'   random of ten working patterns are displayed, with diagnostic data and the
-#'   Flexibility Index shown on the plot.
+#' @param return String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"plot"`
+#'   - `"data"`
+#'   - `"table"`
+#'
+#' See `Value` for more information.
 #'
 #' @param plot_method Character string for determining which plot to return.
-#'   Options include "sample", "common", and "time". "sample" plots a sample of
-#'   ten working patterns; "common" plots the ten most common working patterns;
-#'   "time" plots the Flexibility Index for the group over time.
+#'   - `"sample"` plots a sample of ten working pattern
+#'   - `"common"` plots the ten most common working patterns
+#'   - `"time"` plots the Flexibility Index for the group over time
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return`
+#' argument:
+#'   - `"plot"`: ggplot object. A random of ten working patterns are displayed,
+#'   with diagnostic data and the Flexibility Index shown on the plot.
+#'   - `"data"`: data frame. The original input data appended with the
+#'   Flexibility Index and the component scores.
+#'   - `"table"`: data frame. A summary table for the metric.
+#' hen returning a plot,
 #'
 #' @import dplyr
 #' @importFrom data.table ":=" "%like%" "%between%"
@@ -279,8 +291,11 @@ flex_index <- function(data,
   returnTable <-
     calculated_data %>%
     group_by(!!sym(hrvar)) %>%
-    summarise_at(vars(TakeBreaks, ChangeHours, ControlHours), ~mean(.), .groups = "drop_last") %>%
-    mutate(FlexibilityIndex = select(., TakeBreaks, ChangeHours, ControlHours) %>% apply(1, mean))
+    summarise_at(vars(TakeBreaks, ChangeHours, ControlHours),
+                 ~mean(.), .groups = "drop_last") %>%
+    mutate(FlexibilityIndex =
+             select(., TakeBreaks, ChangeHours, ControlHours) %>%
+             apply(1, mean))
 
   ## Main plot
 
@@ -293,12 +308,16 @@ flex_index <- function(data,
                     method = plot_method)
 
   } else if(return == "data"){
+
     calculated_data
+
   } else if(return == "table"){
 
     returnTable
 
   } else {
+
     stop("Check input for `return`.")
+
   }
 }

R/g2g_data.R

@@ -6,7 +6,7 @@
 #' @title Sample Group-to-Group dataset
 #'
 #' @description
-#' A dataset generated from a Group-to-Group Query from WpA.
+#' A demo dataset generated from a Group-to-Group Query from Workplace Analytics.
 #'
 #' @format A data frame with 3517 rows and 7 variables:
 #' \describe{

R/heat_colours.R

@@ -1,6 +1,10 @@
 #' @title
 #' Generate a vector of `n` contiguous colours, as a red-yellow-green palette.
 #'
+#' @description
+#' Takes a numeric value `n` and returns a character vector of colour HEX codes
+#' corresponding to the heat map palette.
+#'
 #' @param n the number of colors (>= 1) to be in the palette.
 #' @param alpha an alpha-transparency level in the range of 0 to 1
 #' (0 means transparent and 1 means opaque)
@@ -11,6 +15,10 @@
 #'
 #' barplot(rep(10, 50), col = heat_colours(n = 50, alpha = 0.5, rev = TRUE), border = NA)
 #'
+#' @return
+#' A character vector containing the HEX codes and the same length as `n` is
+#' returned.
+#'
 #' @export
 heat_colours <- function (n, alpha, rev = FALSE) {
 

R/hr_trend.R

@@ -10,8 +10,18 @@
 #' for unusual license growth / declines over time.
 #'
 #' @param data A Standard Person Query dataset in the form of a data frame.
-#' @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 line plot showing employee count over time.
+#'   - `"table"`: data frame containing a summary table.
 #'
 #' @import dplyr
 #' @import ggplot2
@@ -23,9 +33,7 @@
 #' # Return summary table
 #' hr_trend(dv_data, return = "table")
 #'
-#' @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.
+#' @family Data Validation
 #'
 #' @export
 hr_trend <- function(data, return = "plot"){

R/hrvar_count.R

@@ -15,8 +15,18 @@
 #' but accepts any character vector, e.g. "LevelDesignation".
 #' If a vector with more than one value is provided, the HR attributes are automatically
 #' concatenated.
-#' @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 containing a bar plot.
+#'   - `"table"`: data frame containing a count table.
 #'
 #' @import ggplot2
 #' @import dplyr

R/import_wpa.R

@@ -7,7 +7,7 @@
 #'
 #' @description
 #' Import a Workplace Analytics Query from a local CSV File, with variable classifications optimised
-#' for other **wpa** functions.
+#' for other 'wpa' functions.
 #'
 #' @details
 #' `import_wpa()` uses `data.table::fread()` to import CSV files for speed,
@@ -22,6 +22,8 @@
 #' will have no effect if the query being imported is not a Ways of Working Assessment query. Defaults
 #' as FALSE.
 #'
+#' @return A `tibble` is returned.
+#'
 #' @export
 import_wpa <- function(x, standardise = FALSE){
 

R/init.R

@@ -6,8 +6,8 @@
 .onAttach <- function(libname, pkgname) {
   message <- c("\n Thank you for using v1.4.0 of the {wpa} R package !",
                "\n \n Our analysts have taken every care to ensure that this package runs smoothly and bug-free.",
-               "\n However, if you do happen to encounter any, please go to https://github.com/microsoft/wpa/issues/",
-               "\n to report any issues.",
+               "\n \n However, if you do happen to encounter any, please report any issues at",
+               "\n https://github.com/microsoft/wpa/issues/",
                "\n \n Happy coding!")
   packageStartupMessage(message)
 }

R/meeting_skim.R

@@ -10,11 +10,22 @@
 #' when provided a standard query in the input.
 #'
 #' @param data A standard person query data in the form of a data frame.
-#' @param return A character string to specify whether to return a message
-#' or a text string. Defaults to "message". Valid options include "text" or
-#' "table".
+#'
+#' @param return String specifying what to return. This must be one of the following strings:
+#'   - `"message"`
+#'   - `"text"`
+#'   - `"table"`
+#'
+#' See `Value` for more information.
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return` argument:
+#'   - `"message"`: message in console.
+#'   - `"text"`: string.
+#'   - `"table"`: data frame.
 #'
 #' @import dplyr
+#'
 #' @examples
 #' meeting_skim(sq_data)
 #'

R/meeting_tm_report.R

@@ -6,9 +6,10 @@
 #' @param data A Meeting Query dataset in the form of a data frame.
 #' @param path Pass the file path and the desired file name, _excluding the file extension_.
 #' For example, "meeting text mining report".
-#' @param stopwords A single-column data frame labelled 'word' containing custom stopwords to remove.
-#' @param timestamp Logical vector specifying whether to include a timestamp in the file name.
-#' Defaults to TRUE.
+#' @param stopwords A single-column data frame labelled 'word' containing custom
+#'   stopwords to remove.
+#' @param timestamp Logical vector specifying whether to include a timestamp in
+#'   the file name. Defaults to TRUE.
 #' @param keep A numeric vector specifying maximum number of words to keep.
 #' @param seed A numeric vector to set seed for random generation.
 #'

R/validation_report.R

@@ -61,6 +61,7 @@
 #' @importFrom dplyr `%>%`
 #'
 #' @family Reports
+#' @inherit generate_report return
 #'
 #' @export
 validation_report <- function(data,

R/workpatterns_classify.R

@@ -8,8 +8,8 @@
 #' @description `r lifecycle::badge('experimental')`
 #'
 #' Apply a rule based algorithm to emails or instant messages sent by hour of
-#' day. Uses a binary week-based (bw) method by default, with options to use the
-#' the person-average volume-based (pav) method.
+#' day. Uses a binary week-based ('bw') method by default, with options to use the
+#' the person-average volume-based ('pav') method.
 #'
 #' @details This is a wrapper around `workpatterns_classify_bw()` and
 #' `workpatterns_classify_pav()`, and calls each function depending on what is
@@ -23,21 +23,31 @@
 #' @section Binary Week method:
 #'
 #'   This method classifies each **person-week** into one of the seven
-#'   archetypes: - 0 < 3 hours on - 1 Standard with breaks workday - 2 Standard
-#'   continuous workday - 3 Standard flexible workday - 4 Long flexible workday
-#'   - 5 Long continuous workday - 6 Always on (13h+)
+#'   archetypes:
+#'   - 0 < 3 hours on
+#'   - 1 Standard with breaks workday
+#'   - 2 Standard continuous workday
+#'   - 3 Standard flexible workday
+#'   - 4 Long flexible workday
+#'   - 5 Long continuous workday
+#'   - 6 Always on (13h+)
 #'
-#'   This is the recommended method over `pav` for several reasons: 1. `bw`
-#'   ignores _volume effects_, where activity volume can still bias the results
-#'   towards the 'standard working hours'. 2. It captures the intuition that
-#'   each individual can have 'light' and 'heavy' weeks with respect to
-#'   workload.
+#'   This is the recommended method over `pav` for several reasons:
+#'   1. `bw` ignores _volume effects_, where activity volume can still bias the
+#'   results towards the 'standard working hours'.
+#'   2. It captures the intuition that each individual can have 'light' and
+#'   'heavy' weeks with respect to workload.
 #'
 #' @section Person Average method:
 #'
 #'   This method classifies each **person** (based on unique `PersonId`) into
-#'   one of the six archetypes: - Absent - Extended Hours - Morning - Extended
-#'   Hours - Evening - Overnight workers - Standard Hours - Always On
+#'   one of the six archetypes:
+#'   - Absent
+#'   - Extended Hours - Morning
+#'   - Extended Hours - Evening
+#'   - Overnight workers
+#'   - Standard Hours
+#'   - Always On
 #'
 #' @section Flexibility Index: The Working Patterns archetypes as calculated
 #'   using the binary-week method shares many similarities with the Flexibility
@@ -52,12 +62,14 @@
 #'   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": 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 return String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"plot"`
+#'   - `"data"`
+#'   - `"table"`
+#'   - `"plot-area"`
+#'
+#' See `Value` for more information.
 #'
 #' @param method String to pass through specifying which method to use for
 #'   classification. By default, a binary week-based (bw) method is used, with
@@ -68,9 +80,12 @@
 #'   Valid values are "percent" (default) and "abs".
 #'
 #' @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")`
+#'   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 start_hour A character vector specifying starting hours, e.g. "0900".
 #'   Note that this currently only supports **hourly** increments.
@@ -81,6 +96,15 @@
 #' @import tidyselect
 #' @import ggplot2
 #'
+#' @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
+#'
 #' @examples
 #'
 #' # Returns a plot by default

R/workpatterns_report.R

@@ -14,7 +14,7 @@
 #' @param start_hour See `workpatterns_classify()`.
 #' @param end_hour See `workpatterns_classify()`.
 #' @param path Pass the file path and the desired file name, _excluding the file
-#'   extension_. For example, "scope report".
+#'   extension_. For example, `"scope report"`.
 #' @param timestamp Logical vector specifying whether to include a timestamp in
 #'   the file name. Defaults to TRUE.
 #'

man/IV_report.Rd

@@ -48,7 +48,8 @@ variable.
 \dontrun{
 sq_data \%>\%
   mutate(X = ifelse(Collaboration_hours > 12, 1, 0)) \%>\% # Simulate binary variable
-  IV_report(outcome =  "CH_binary", predictors = c("Email_hours", "Workweek_span"))
+  IV_report(outcome =  "CH_binary",
+            predictors = c("Email_hours", "Workweek_span"))
 }
 
 }

man/check_person_query.Rd

@@ -7,11 +7,23 @@
 check_person_query(data, return)
 }
 \arguments{
-\item{data}{A person-level query in the form of a data frame, including the standard person query,
-Ways of Working assessment query, and the hourly collaboration query.}
+\item{data}{A person-level query in the form of a data frame. This includes:
+\itemize{
+\item Standard Person Query
+\item Ways of Working Assessment Query
+\item Hourly Collaboration Query
+}
 
-\item{return}{Character string to specify whether to return a console message ("message"),
-a character string ("text"), or a data frame. Defaults to "message".}
+All person-level query have a \code{PersonId} column and a \code{Date} column.}
+
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"message"} (default)
+\item \code{"text"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Prints diagnostic data about the data query to the R console, with information

man/check_query.Rd

@@ -7,23 +7,44 @@
 check_query(data, return = "message", validation = FALSE)
 }
 \arguments{
-\item{data}{A person-level query in the form of a data frame, including the standard person query,
-Ways of Working assessment query, and the hourly collaboration query.}
+\item{data}{A person-level query in the form of a data frame. This includes:
+\itemize{
+\item Standard Person Query
+\item Ways of Working Assessment Query
+\item Hourly Collaboration Query
+}
 
-\item{return}{Character string to specify whether to return a console message ("message"),
-a character string ("text"), or a data frame. Defaults to "message".}
+All person-level query have a \code{PersonId} column and a \code{Date} column.}
 
-\item{validation}{Logical value to specify whether to return a check used by the \code{validation_report()}.
-Defaults to FALSE.}
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"message"} (default)
+\item \code{"text"}
+}
+
+See \code{Value} for more information.}
+
+\item{validation}{Logical value to specify whether to return a check used by
+the \code{validation_report()}. Defaults to \code{FALSE}.}
+}
+\value{
+A different output is returned depending on the value passed to the \code{return}
+argument:
+\itemize{
+\item \code{"message"}: a message is returned to the console.
+\item \code{"text"}: string containing the diagnostic message.
+}
 }
 \description{
-Prints diagnostic data about the data query to the R console, with information
-such as date range, number of employees, HR attributes identified, etc.
+Prints diagnostic data about the data query to the R console,
+with information such as date range, number of employees, HR attributes
+identified, etc.
 }
 \details{
-This can be used with any person-level query, such as the standard person query,
-Ways of Working assessment query, and the hourly collaboration query. When run,
-this prints diagnostic data to the R console.
+This can be used with any person-level query, such as the standard
+person query, Ways of Working assessment query, and the hourly collaboration
+query. When run, this prints diagnostic data to the R console.
 }
 \examples{
 check_query(sq_data)
@@ -35,6 +56,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/check_query_validation.Rd

@@ -7,11 +7,23 @@
 check_query_validation(data, return)
 }
 \arguments{
-\item{data}{A person-level query in the form of a data frame, including the standard person query,
-Ways of Working assessment query, and the hourly collaboration query.}
+\item{data}{A person-level query in the form of a data frame. This includes:
+\itemize{
+\item Standard Person Query
+\item Ways of Working Assessment Query
+\item Hourly Collaboration Query
+}
 
-\item{return}{Character string to specify whether to return a console message ("message"),
-a character string ("text"), or a data frame. Defaults to "message".}
+All person-level query have a \code{PersonId} column and a \code{Date} column.}
+
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"message"} (default)
+\item \code{"text"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Prints diagnostic data about the data query to the R console, with information

man/collaboration_area.Rd

@@ -14,16 +14,27 @@ collab_area(data, hrvar = "Organization", mingroup = 5, return = "plot")
 A Ways of Working assessment dataset may also be provided, in which
 Unscheduled call hours would be included in the output.}
 
-\item{hrvar}{HR Variable by which to split metrics, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"}
+\item{hrvar}{HR Variable by which to split metrics, 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{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}.
-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 stacked area plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+}
 }
 \description{
 Provides an overview analysis of Weekly Digital Collaboration.

man/create_fizz.Rd

@@ -2,7 +2,7 @@
 % Please edit documentation in R/create_fizz.R
 \name{create_fizz}
 \alias{create_fizz}
-\title{Fizzy Drink / Jitter Scatter Plot for any metric}
+\title{Fizzy Drink / Jittered Scatter Plot for any metric}
 \usage{
 create_fizz(
   data,
@@ -38,12 +38,12 @@ A different output is returned depending on the value passed to the \code{return
 }
 }
 \description{
-Analyzes a selected metric and returns a a 'fizzy' scatter plot by default.
+Analyzes a selected metric and returns a 'fizzy' scatter plot by default.
 Additional options available to return a table with distribution elements.
 }
 \details{
 This is a general purpose function that powers all the functions
-in the package that produce 'fizzy drink' / jitter scatter plots.
+in the package that produce 'fizzy drink' / jittered scatter plots.
 }
 \examples{
 # Create a fizzy plot for Work Week Span by Level Designation

man/create_line.Rd

@@ -49,10 +49,13 @@ This is a general purpose function that powers all the functions
 in the package that produce faceted line plots.
 }
 \examples{
+# Return plot of Email Hours
 sq_data \%>\% create_line(metric = "Email_hours", return = "plot")
 
+# Return plot of Collaboration Hours
 sq_data \%>\% create_line(metric = "Collaboration_hours", return = "plot")
 
+# Return plot of Work week span and cut by `LevelDesignation`
 sq_data \%>\% create_line(metric = "Workweek_span", hrvar = "LevelDesignation")
 
 }

man/flag_ch_ratio.Rd

@@ -48,6 +48,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/flag_em_ratio.Rd

@@ -30,6 +30,7 @@ Other Data Validation:
 \code{\link{flag_ch_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/flag_extreme.Rd

@@ -40,6 +40,7 @@ Other Data Validation:
 \code{\link{flag_ch_ratio}()},
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/flag_outlooktime.Rd

@@ -28,6 +28,7 @@ Other Data Validation:
 \code{\link{flag_ch_ratio}()},
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/flex_index.Rd

@@ -32,15 +32,34 @@ signals to be greater than in order to qualify as \emph{active}. Defaults to 0.}
 
 \item{end_hour}{A character vector specifying end hours, e.g. "1700"}
 
-\item{return}{Character vector to specify what to return. Valid options
-include "plot" (default), "data", and "table". When returning a plot, a
-random of ten working patterns are displayed, with diagnostic data and the
-Flexibility Index shown on the plot.}
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"data"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{plot_method}{Character string for determining which plot to return.
-Options include "sample", "common", and "time". "sample" plots a sample of
-ten working patterns; "common" plots the ten most common working patterns;
-"time" plots the Flexibility Index for the group over time.}
+\itemize{
+\item \code{"sample"} plots a sample of ten working pattern
+\item \code{"common"} plots the ten most common working patterns
+\item \code{"time"} plots the Flexibility Index for the group over time
+}}
+}
+\value{
+A different output is returned depending on the value passed to the \code{return}
+argument:
+\itemize{
+\item \code{"plot"}: ggplot object. A random of ten working patterns are displayed,
+with diagnostic data and the Flexibility Index shown on the plot.
+\item \code{"data"}: data frame. The original input data appended with the
+Flexibility Index and the component scores.
+\item \code{"table"}: data frame. A summary table for the metric.
+hen returning a plot,
+}
 }
 \description{
 \ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}
@@ -74,7 +93,8 @@ Index of a team of 6 over time, where the possible values would range from 0
 to 1.
 }
 \section{Context}{
- The central feature of flexible working arrangements is
+
+The central feature of flexible working arrangements is
 that it is the employee rather the employer who chooses the working
 arrangement. \emph{Observed flexibility} serves as a proxy to assess whether a
 flexible working arrangement are in place. The Flexibility Index is an

man/g2g_data.Rd

@@ -25,6 +25,6 @@ A data frame with 3517 rows and 7 variables:
 g2g_data
 }
 \description{
-A dataset generated from a Group-to-Group Query from WpA.
+A demo dataset generated from a Group-to-Group Query from Workplace Analytics.
 }
 \keyword{datasets}

man/heat_colours.Rd

@@ -14,8 +14,13 @@ heat_colours(n, alpha, rev = FALSE)
 
 \item{rev}{logical indicating whether the ordering of the colors should be reversed.}
 }
+\value{
+A character vector containing the HEX codes and the same length as \code{n} is
+returned.
+}
 \description{
-Generate a vector of \code{n} contiguous colours, as a red-yellow-green palette.
+Takes a numeric value \code{n} and returns a character vector of colour HEX codes
+corresponding to the heat map palette.
 }
 \examples{
 barplot(rep(10, 50), col = heat_colours(n = 50), border = NA)

man/hr_trend.Rd

@@ -9,12 +9,22 @@ hr_trend(data, return = "plot")
 \arguments{
 \item{data}{A Standard Person Query dataset in the form of a data frame.}
 
-\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}.
-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 line plot showing employee count over time.
+\item \code{"table"}: data frame containing a summary table.
+}
 }
 \description{
 Returns a line chart showing the change in
@@ -29,3 +39,25 @@ hr_trend(dv_data)
 hr_trend(dv_data, return = "table")
 
 }
+\seealso{
+Other Data Validation: 
+\code{\link{check_query}()},
+\code{\link{flag_ch_ratio}()},
+\code{\link{flag_em_ratio}()},
+\code{\link{flag_extreme}()},
+\code{\link{flag_outlooktime}()},
+\code{\link{hrvar_count_all}()},
+\code{\link{hrvar_count}()},
+\code{\link{identify_holidayweeks}()},
+\code{\link{identify_inactiveweeks}()},
+\code{\link{identify_nkw}()},
+\code{\link{identify_outlier}()},
+\code{\link{identify_privacythreshold}()},
+\code{\link{identify_query}()},
+\code{\link{identify_tenure}()},
+\code{\link{remove_outliers}()},
+\code{\link{subject_validate_report}()},
+\code{\link{subject_validate}()},
+\code{\link{track_HR_change}()}
+}
+\concept{Data Validation}

man/hrvar_count.Rd

@@ -17,8 +17,22 @@ but accepts any character vector, e.g. "LevelDesignation".
 If a vector with more than one value is provided, the HR attributes are automatically
 concatenated.}
 
-\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 containing a bar plot.
+\item \code{"table"}: data frame containing a count table.
+}
 }
 \description{
 This function enables you to create a count of the distinct people
@@ -50,6 +64,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{identify_holidayweeks}()},
 \code{\link{identify_inactiveweeks}()},

man/hrvar_count_all.Rd

@@ -47,6 +47,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},
 \code{\link{identify_inactiveweeks}()},

man/identify_holidayweeks.Rd

@@ -44,6 +44,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_inactiveweeks}()},

man/identify_inactiveweeks.Rd

@@ -31,6 +31,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/identify_nkw.Rd

@@ -31,6 +31,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/identify_outlier.Rd

@@ -48,6 +48,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/identify_privacythreshold.Rd

@@ -38,6 +38,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/identify_query.Rd

@@ -35,6 +35,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/identify_tenure.Rd

@@ -49,6 +49,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/import_wpa.Rd

@@ -16,9 +16,12 @@ Assessment query's columns name standard and consistent with a Standard Person Q
 will have no effect if the query being imported is not a Ways of Working Assessment query. Defaults
 as FALSE.}
 }
+\value{
+A \code{tibble} is returned.
+}
 \description{
 Import a Workplace Analytics Query from a local CSV File, with variable classifications optimised
-for other \strong{wpa} functions.
+for other 'wpa' functions.
 }
 \details{
 \code{import_wpa()} uses \code{data.table::fread()} to import CSV files for speed,

man/meeting_skim.Rd

@@ -9,9 +9,22 @@ meeting_skim(data, return = "message")
 \arguments{
 \item{data}{A standard person query data in the form of a data frame.}
 
-\item{return}{A character string to specify whether to return a message
-or a text string. Defaults to "message". Valid options include "text" or
-"table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"message"}
+\item \code{"text"}
+\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{"message"}: message in console.
+\item \code{"text"}: string.
+\item \code{"table"}: data frame.
+}
 }
 \description{
 This function returns a skim summary in the console

man/meeting_tm_report.Rd

@@ -19,10 +19,11 @@ meeting_tm_report(
 \item{path}{Pass the file path and the desired file name, \emph{excluding the file extension}.
 For example, "meeting text mining report".}
 
-\item{stopwords}{A single-column data frame labelled 'word' containing custom stopwords to remove.}
+\item{stopwords}{A single-column data frame labelled 'word' containing custom
+stopwords to remove.}
 
-\item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
-Defaults to TRUE.}
+\item{timestamp}{Logical vector specifying whether to include a timestamp in
+the file name. Defaults to TRUE.}
 
 \item{keep}{A numeric vector specifying maximum number of words to keep.}
 

man/remove_outliers.Rd

@@ -43,6 +43,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/subject_validate.Rd

@@ -31,6 +31,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/subject_validate_report.Rd

@@ -41,6 +41,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/track_HR_change.Rd

@@ -57,6 +57,7 @@ Other Data Validation:
 \code{\link{flag_em_ratio}()},
 \code{\link{flag_extreme}()},
 \code{\link{flag_outlooktime}()},
+\code{\link{hr_trend}()},
 \code{\link{hrvar_count_all}()},
 \code{\link{hrvar_count}()},
 \code{\link{identify_holidayweeks}()},

man/validation_report.Rd

@@ -30,6 +30,11 @@ argument within \code{hrvar_count_all()}.}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
 Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 The function generates an interactive HTML report using
 Standard Person Query data as an input. The report contains checks on

man/workpatterns_classify.Rd

@@ -27,9 +27,14 @@ whether to return percentages or absolute values in "data" and "plot".
 Valid values are "percent" (default) and "abs".}
 
 \item{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 \code{c("email", "IM")}}
+use:
+\itemize{
+\item \code{"email"} (default) for emails only
+\item \code{"IM"} for Teams messages only
+\item \code{"unscheduled_calls"} for Unscheduled Calls only
+\item \code{"meetings"} for Meetings only
+\item or a combination of signals, such as \code{c("email", "IM")}
+}}
 
 \item{start_hour}{A character vector specifying starting hours, e.g. "0900".
 Note that this currently only supports \strong{hourly} increments.}
@@ -41,19 +46,35 @@ Note that this currently only supports \strong{hourly} increments.}
 classification. 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": 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}
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"data"}
+\item \code{"table"}
+\item \code{"plot-area"}
+}
+
+See \code{Value} for more information.}
+}
+\value{
+Character vector to specify what to return. Valid options
+include:
+\itemize{
+\item \code{"plot"}: returns a heatmap plot of signal distribution by hour
+and archetypes (default)
+\item \code{"data"}: returns the raw data with the classified archetypes
+\item \code{"table"}: returns a summary table of the archetypes
+\item \code{"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}}
 
 Apply a rule based algorithm to emails or instant messages sent by hour of
-day. Uses a binary week-based (bw) method by default, with options to use the
-the person-average volume-based (pav) method.
+day. Uses a binary week-based ('bw') method by default, with options to use the
+the person-average volume-based ('pav') method.
 }
 \details{
 This is a wrapper around \code{workpatterns_classify_bw()} and
@@ -69,25 +90,39 @@ implementations.
 
 
 This method classifies each \strong{person-week} into one of the seven
-archetypes: - 0 < 3 hours on - 1 Standard with breaks workday - 2 Standard
-continuous workday - 3 Standard flexible workday - 4 Long flexible workday
+archetypes:
 \itemize{
-\item 5 Long continuous workday - 6 Always on (13h+)
+\item 0 < 3 hours on
+\item 1 Standard with breaks workday
+\item 2 Standard continuous workday
+\item 3 Standard flexible workday
+\item 4 Long flexible workday
+\item 5 Long continuous workday
+\item 6 Always on (13h+)
 }
 
-This is the recommended method over \code{pav} for several reasons: 1. \code{bw}
-ignores \emph{volume effects}, where activity volume can still bias the results
-towards the 'standard working hours'. 2. It captures the intuition that
-each individual can have 'light' and 'heavy' weeks with respect to
-workload.
+This is the recommended method over \code{pav} for several reasons:
+\enumerate{
+\item \code{bw} ignores \emph{volume effects}, where activity volume can still bias the
+results towards the 'standard working hours'.
+\item It captures the intuition that each individual can have 'light' and
+'heavy' weeks with respect to workload.
+}
 }
 
 \section{Person Average method}{
 
 
 This method classifies each \strong{person} (based on unique \code{PersonId}) into
-one of the six archetypes: - Absent - Extended Hours - Morning - Extended
-Hours - Evening - Overnight workers - Standard Hours - Always On
+one of the six archetypes:
+\itemize{
+\item Absent
+\item Extended Hours - Morning
+\item Extended Hours - Evening
+\item Overnight workers
+\item Standard Hours
+\item Always On
+}
 }
 
 \section{Flexibility Index}{

man/workpatterns_report.Rd

@@ -27,7 +27,7 @@ workpatterns_report(
 \item{end_hour}{See \code{workpatterns_classify()}.}
 
 \item{path}{Pass the file path and the desired file name, \emph{excluding the file
-extension}. For example, "scope report".}
+extension}. For example, \code{"scope report"}.}
 
 \item{timestamp}{Logical vector specifying whether to include a timestamp in
 the file name. Defaults to TRUE.}