New Create_Density function

NAMESPACE

@@ -44,6 +44,7 @@ export(create_bar)
 export(create_bar_asis)
 export(create_boxplot)
 export(create_bubble)
+export(create_density)
 export(create_dist)
 export(create_dt)
 export(create_fizz)

R/create_density.R

@@ -0,0 +1,171 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+#' @title Create a density plot for any metric
+#'
+#' @description
+#' Provides an analysis of the distribution of a selected metric.
+#' Returns a faceted density plot by default.
+#' Additional options available to return the underlying frequency table.
+#'
+#' @template spq-params
+#' @param metric String containing the name of the metric,
+#' e.g. "Collaboration_hours"
+#'
+#'
+#' @param return String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"plot"`
+#'   - `"table"`
+#'   - `"data"`
+#'   - `"frequency"`
+#'
+#' See `Value` for more information.
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return`
+#' argument:
+#'   - `"plot"`: 'ggplot' object. A faceted density plot for the metric.
+#'   - `"table"`: data frame. A summary table for the metric.
+#'   - `"data"`: data frame. Data with calculated person averages.
+#'   - `"frequency`: list of data frames. Each data frame contains the
+#'   frequencies used in each panel of the plotted histogram.
+#'
+#' @import dplyr
+#' @import ggplot2
+#' @import reshape2
+#' @import scales
+#' @importFrom tidyr spread
+#' @importFrom stats median
+#' @importFrom stats sd
+#'
+#' @family Flexible
+#'
+#' @examples
+#' # Return plot for whole organization
+#' create_density(sq_data, metric = "Collaboration_hours", hrvar = NULL)
+#'
+#' # Return plot
+#' create_density(sq_data, metric = "Collaboration_hours", hrvar = "Organization")
+#'
+#' # Return summary table
+#' create_density(sq_data,
+#'             metric = "Collaboration_hours",
+#'             hrvar = "Organization",
+#'             return = "table")
+#' @export
+
+create_density <- function(data,
+                        metric,
+                        hrvar = "Organization",
+                        mingroup = 5,
+                        return = "plot") {
+
+  ## Check inputs
+  required_variables <- c("Date",
+                          metric,
+                          "PersonId")
+
+  ## Error message if variables are not present
+  ## Nothing happens if all present
+  data %>%
+    check_inputs(requirements = required_variables)
+
+  ## Clean metric name
+  clean_nm <- us_to_space(metric)
+
+  ## Handling NULL values passed to hrvar
+  if(is.null(hrvar)){
+    data <- totals_col(data)
+    hrvar <- "Total"
+  }
+
+  ## Basic Data for bar plot
+  ## Calculate person-averages
+  plot_data <-
+    data %>%
+    rename(group = !!sym(hrvar)) %>%
+    group_by(PersonId, group) %>%
+    summarise(!!sym(metric) := mean(!!sym(metric))) %>%
+    ungroup() %>%
+    left_join(data %>%
+                rename(group = !!sym(hrvar)) %>%
+                group_by(group) %>%
+                summarise(Employee_Count = n_distinct(PersonId)),
+              by = "group") %>%
+    filter(Employee_Count >= mingroup)
+
+  ## Employee count / base size table
+  plot_legend <-
+    plot_data %>%
+    group_by(group) %>%
+    summarize(Employee_Count = first(Employee_Count)) %>%
+    mutate(Employee_Count = paste("n=",Employee_Count))
+
+  ## Bar plot
+
+  plot_object <-
+    plot_data %>%
+    ggplot(aes(x = !!sym(metric))) +
+	geom_density(lwd = 1, colour = 4, fill = 4, alpha = 0.25) +
+    facet_wrap(group ~ .) +
+    theme_wpa_basic() +
+    theme(strip.background = element_rect(color = "#1d627e",
+                                          fill = "#1d627e"),
+          strip.text = element_text(size = 10,
+                                    colour = "#FFFFFF",
+                                    face = "bold")) +
+    labs(title = clean_nm,
+         subtitle = paste("Distribution of", tolower(clean_nm), "by", tolower(camel_clean(hrvar)))) +
+    xlab(clean_nm) +
+    ylab("Density") +
+    labs(caption = extract_date_range(data, return = "text"))
+
+  ## Table to return
+  return_table <-
+    plot_data %>%
+    group_by(group) %>%
+    summarise(
+      mean = mean(!!sym(metric), na.rm = TRUE),
+      median = median(!!sym(metric), na.rm = TRUE),
+      max = max(!!sym(metric), na.rm = TRUE),
+      min = min(!!sym(metric), na.rm = TRUE)
+    ) %>%
+    left_join(data %>%
+                rename(group = !!sym(hrvar)) %>%
+                group_by(group) %>%
+                summarise(Employee_Count = n_distinct(PersonId)),
+              by = "group")
+
+
+  if(return == "table"){
+
+    return_table
+
+  } else if(return == "plot"){
+
+    return(plot_object)
+
+  } else if(return == "frequency"){
+
+    ggplot2::ggplot_build(plot_object)$data[[1]] %>%
+      select(group,
+             PANEL,
+             x,
+             xmin,
+             xmax,
+             y) %>%
+      group_split(group)
+
+  } else if(return == "data"){
+
+    plot_data
+
+  } else {
+
+    stop("Please enter a valid input for `return`.")
+
+  }
+}

man/create_bar.Rd

@@ -190,6 +190,7 @@ Other Flexible:
 \code{\link{create_bar_asis}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_bar_asis.Rd

@@ -168,6 +168,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_boxplot.Rd

@@ -144,6 +144,7 @@ Other Flexible:
 \code{\link{create_bar_asis}()},
 \code{\link{create_bar}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_bubble.Rd

@@ -140,6 +140,7 @@ Other Flexible:
 \code{\link{create_bar_asis}()},
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_density.Rd

@@ -0,0 +1,89 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/create_density.R
+\name{create_density}
+\alias{create_density}
+\title{Create a density plot for any metric}
+\usage{
+create_density(
+  data,
+  metric,
+  hrvar = "Organization",
+  mingroup = 5,
+  return = "plot"
+)
+}
+\arguments{
+\item{data}{A Standard Person Query dataset in the form of a data frame.}
+
+\item{metric}{String containing the name of the metric,
+e.g. "Collaboration_hours"}
+
+\item{hrvar}{String containing the name of the HR Variable by which to split
+metrics. Defaults to \code{"Organization"}. To run the analysis on the total
+instead of splitting by an HR attribute, supply \code{NULL} (without quotes).}
+
+\item{mingroup}{Numeric value setting the privacy threshold / minimum group
+size. Defaults to 5.}
+
+\item{return}{String specifying what to return. This must be one of the
+following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+\item \code{"data"}
+\item \code{"frequency"}
+}
+
+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 faceted density plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+\item \code{"data"}: data frame. Data with calculated person averages.
+\item \verb{"frequency}: list of data frames. Each data frame contains the
+frequencies used in each panel of the plotted histogram.
+}
+}
+\description{
+Provides an analysis of the distribution of a selected metric.
+Returns a faceted density plot by default.
+Additional options available to return the underlying frequency table.
+}
+\examples{
+# Return plot for whole organization
+create_density(sq_data, metric = "Collaboration_hours", hrvar = NULL)
+
+# Return plot
+create_density(sq_data, metric = "Collaboration_hours", hrvar = "Organization")
+
+# Return summary table
+create_density(sq_data,
+            metric = "Collaboration_hours",
+            hrvar = "Organization",
+            return = "table")
+}
+\seealso{
+Other Flexible: 
+\code{\link{create_bar_asis}()},
+\code{\link{create_bar}()},
+\code{\link{create_boxplot}()},
+\code{\link{create_bubble}()},
+\code{\link{create_dist}()},
+\code{\link{create_fizz}()},
+\code{\link{create_hist}()},
+\code{\link{create_inc}()},
+\code{\link{create_line_asis}()},
+\code{\link{create_line}()},
+\code{\link{create_period_scatter}()},
+\code{\link{create_rank}()},
+\code{\link{create_sankey}()},
+\code{\link{create_scatter}()},
+\code{\link{create_stacked}()},
+\code{\link{create_tracking}()},
+\code{\link{create_trend}()},
+\code{\link{period_change}()}
+}
+\concept{Flexible}

man/create_dist.Rd

@@ -176,6 +176,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},
 \code{\link{create_inc}()},

man/create_fizz.Rd

@@ -135,6 +135,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_hist}()},
 \code{\link{create_inc}()},

man/create_hist.Rd

@@ -75,6 +75,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_inc}()},

man/create_inc.Rd

@@ -166,6 +166,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_line.Rd

@@ -138,6 +138,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_line_asis.Rd

@@ -143,6 +143,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_period_scatter.Rd

@@ -154,6 +154,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_rank.Rd

@@ -181,6 +181,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_sankey.Rd

@@ -117,6 +117,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_scatter.Rd

@@ -133,6 +133,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_stacked.Rd

@@ -179,6 +179,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_tracking.Rd

@@ -119,6 +119,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/create_trend.Rd

@@ -142,6 +142,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},

man/period_change.Rd

@@ -146,6 +146,7 @@ Other Flexible:
 \code{\link{create_bar}()},
 \code{\link{create_boxplot}()},
 \code{\link{create_bubble}()},
+\code{\link{create_density}()},
 \code{\link{create_dist}()},
 \code{\link{create_fizz}()},
 \code{\link{create_hist}()},