Merge pull request #229 from microsoft/release/checks-for-v1.8.0

Release: housekeeping and checks for `v1.8.0`

Author: martinctc

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 1.7.0
-Date: 2022-06-06 13:37:15 UTC
-SHA: 7aefaa599891ef7c20db669a8f52b59e80ef48ef
+Version: 1.8.0
+Date: 2022-07-05 14:56:34 UTC
+SHA: da3ceafbd54598a196fe0c3c1b29f58f1adc728d

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: wpa
 Type: Package
 Title: Tools for Analysing and Visualising Viva Insights Data
-Version: 1.7.0.9000
+Version: 1.8.0
 Authors@R: c(
     person(given = "Martin", family = "Chan", role = c("aut", "cre"), email = "[email protected]"),
     person(given = "Carlos", family = "Morales", role = "aut", email = "[email protected]"),

NAMESPACE

@@ -96,6 +96,7 @@ export(hrvar_count)
 export(hrvar_count_all)
 export(hrvar_trend)
 export(identify_churn)
+export(identify_datefreq)
 export(identify_holidayweeks)
 export(identify_inactiveweeks)
 export(identify_nkw)
@@ -147,6 +148,7 @@ export(one2one_summary)
 export(one2one_trend)
 export(p2p_data_sim)
 export(p_test)
+export(pad2)
 export(pairwise_count)
 export(period_change)
 export(personas_hclust)

NEWS.md

@@ -1,7 +1,9 @@
-# wpa (development version)
+# wpa 1.8.0
 
 - Updated and improved output and algorithm for `workpatterns_classify()`
 - Additional visual options for `workpatterns_classify()` and `flex_index()`
+- Added the `external_*` family of functions to visualize the metric `Collaboration_hours_external`
+- Added experimental function `identify_datefreq()` for detecting date frequency (#131)
 
 # wpa 1.7.0
 

R/external_dist.R

@@ -18,7 +18,7 @@
 #' @inherit create_dist return
 #'
 #' @family Visualization
-#' @family External
+#' @family External Collaboration
 #'
 #' @examples
 #' # Return plot
@@ -38,13 +38,18 @@ external_dist <- function(data,
                        return = "plot",
                        cut = c(5, 10, 15)) {
 
-# Calculate Internal / External Collaboration time 
-plot_data <-  data %>% mutate(External_collaboration_hours = Collaboration_hours_external) 
+  # Rename metric
+  plot_data <-
+    data %>%
+    mutate(External_collaboration_hours = Collaboration_hours_external)
 
-plot_data  %>% create_dist(metric = "External_collaboration_hours",
-              hrvar = hrvar,
-              mingroup = mingroup,
-              return = return,
-              cut = cut,
-			  dist_colours = c("#3F7066", "#64B4A4", "#B1EDE1","#CBF3EB"))
+  plot_data  %>%
+    create_dist(
+      metric = "External_collaboration_hours",
+      hrvar = hrvar,
+      mingroup = mingroup,
+      return = return,
+      cut = cut,
+      dist_colours = c("#3F7066", "#64B4A4", "#B1EDE1","#CBF3EB")
+      )
 }

R/external_sum.R

@@ -14,10 +14,10 @@
 #' @inherit create_stacked return
 #'
 #' @family Visualization
-#' @family External
+#' @family External Collaboration
 #'
 #' @examples
-#' # Return a  plot
+#' # Return a plot
 #' external_sum(sq_data, hrvar = "LevelDesignation")
 #'
 #' # Return summary table
@@ -32,9 +32,9 @@ external_sum <- function(data,
                                 return = "plot"){
 
 
-# Calculate Internal / External Collaboration time 
-plot_data <-  data %>% mutate(Internal_hours=  Collaboration_hours - Collaboration_hours_external)   %>%  mutate(External_hours=  Collaboration_hours_external) 
-  
+# Calculate Internal / External Collaboration time
+plot_data <-  data %>% mutate(Internal_hours=  Collaboration_hours - Collaboration_hours_external)   %>%  mutate(External_hours=  Collaboration_hours_external)
+
 # Plot Internal / External Collaboration time by Organization
 plot_data %>%  create_stacked(hrvar = hrvar, metrics = c("Internal_hours", "External_hours"),   plot_title = "Internal and External Collaboration Hours",  stack_colours = stack_colours, mingroup = mingroup, return = return)
 

R/globals.R

@@ -257,6 +257,9 @@ utils::globalVariables(
     "HRAttribute",
     "identifier",
     "PersonasNet",
-    "Unique values"
+    "Unique values",
+    "Collaboration_hours_external",
+    ".GRP",
+    "Id"
     )
 )

R/identify_datefreq.R

@@ -0,0 +1,118 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+#' @title Identify date frequency based on a series of dates
+#'
+#' @description
+#' `r lifecycle::badge('experimental')`
+#'
+#' Takes a vector of dates and identify whether the frequency is 'daily',
+#' 'weekly', or 'monthly'. The primary use case for this function is to provide
+#' an accurate description of the query type used and for raising errors should
+#' a wrong date grouping be used in the data input.
+#'
+#' @param x Vector containing a series of dates.
+#'
+#' @details
+#' Date frequency detection works as follows:
+#'   - If at least three days of the week are present (e.g., Monday, Wednesday,
+#'   Thursday) in the series, then the series is classified as 'daily'
+#'   - If the total number of months in the series is equal to the length, then
+#'   the series is classified as 'monthly'
+#'   - If the total number of sundays in the series is equal to the length of
+#'   the series, then the series is classified as 'weekly
+#'
+#' @section Limitations:
+#' One of the assumptions made behind the classification is that weeks are
+#' denoted with Sundays, hence the count of sundays to measure the number of
+#' weeks. In this case, weeks where a Sunday is missing would result in an
+#' 'unable to classify' error.
+#'
+#' Another assumption made is that dates are evenly distributed, i.e. that the
+#' gap between dates are equal. If dates are unevenly distributed, e.g. only two
+#' days of the week are available for a given week, then the algorithm will fail
+#' to identify the frequency as 'daily'.
+#'
+#' @return
+#' String describing the detected date frequency, i.e.:
+#'   - 'daily'
+#'   - 'weekly'
+#'   - 'monthly'
+#'
+#' @examples
+#' start_date <- as.Date("2022/06/26")
+#' end_date <- as.Date("2022/11/27")
+#'
+#' # Daily
+#' day_seq <-
+#'   seq.Date(
+#'     from = start_date,
+#'     to = end_date,
+#'     by = "day"
+#'   )
+#'
+#' identify_datefreq(day_seq)
+#'
+#' # Weekly
+#' week_seq <-
+#'   seq.Date(
+#'     from = start_date,
+#'     to = end_date,
+#'     by = "week"
+#'   )
+#'
+#' identify_datefreq(week_seq)
+#'
+#' # Monthly
+#' month_seq <-
+#'   seq.Date(
+#'     from = start_date,
+#'     to = end_date,
+#'     by = "month"
+#'   )
+#' identify_datefreq(month_seq)
+#'
+#' @export
+
+identify_datefreq <- function(x){
+
+  # Data frame for checking
+  date_df <- data.frame(
+    weekdays = names(table(weekdays(x))),
+    n = as.numeric(table(weekdays(x)))
+  )
+
+
+  dweekchr <- c(
+    "Sunday",
+    "Saturday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday"
+  )
+
+  # At least 3 days of the week must be present
+  check_wdays <- ifelse(
+    sum(dweekchr %in% date_df$weekdays) >= 3, TRUE, FALSE)
+
+  # Check number of Sundays - should equal number of weeks if weekly
+  check_nsun <- sum(date_df$n[date_df$weekdays == "Sunday"])
+
+  ifelse(
+    length(months(x)) == length(x),
+    "monthly",
+    ifelse(
+      check_nsun == length(x),
+      "weekly",
+      ifelse(
+        check_wdays,
+        "daily",
+        "Unable to identify date frequency."
+      )
+    )
+  )
+}

R/plot_flex_index.R

@@ -151,7 +151,7 @@ plot_flex_index <- function(data,
       )
 
       ## 00, 01, 02, etc.
-      hours_col <- stringr::str_pad(seq(0,23), width = 2, pad = 0)
+      hours_col <- pad2(x = seq(0,23))
 
       # Use `mutate()` method
       # Will get 10 IDs, not 10 rows

R/plot_hourly_pat.R

@@ -22,7 +22,10 @@
 #' @param legend_text String to be used in the bottom legend label.
 #'
 #' @param rows Number of rows to show in plot.
-#' @noRd
+#' @param title String to specify plot title.
+#' @param subtitle String to specify plot subtitle.
+#' @param caption String to specify plot caption.
+#' @param ylab String to specify plot y-axis label.
 #'
 #' @export
 
@@ -41,7 +44,7 @@ plot_hourly_pat <- function(
 ){
 
   ## 00, 01, 02, etc.
-  hours_col <- stringr::str_pad(seq(0,23), width = 2, pad = 0)
+  hours_col <- pad2(x = seq(0,23))
 
   data %>%
     utils::head(rows)  %>%