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

Release: housekeeping and checks for `v1.8.0`

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 = "martin.chan@microsoft.com"),
     person(given = "Carlos", family = "Morales", role = "aut", email = "carlos.morales@microsoft.com"),

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)  %>%

R/supporting_functions.R

@@ -251,3 +251,19 @@ wrap_text <- function(x, threshold = 15){
     x = x
   )
 }
+
+#' @title
+#' Create the two-digit zero-padded format
+#'
+#' @param x numeric value or vector with maximum two characters.
+#'
+#' @return
+#' Numeric value containing two-digit zero-padded values.
+#'
+#' @export
+
+pad2 <- function(x){
+  x <- as.character(x)
+
+  ifelse(nchar(x) == 1, paste0("0", x), x)
+}

R/workpatterns_area.R

@@ -191,14 +191,6 @@ workpatterns_area <- function(data,
     mutate(Signals = sub(pattern = "_\\d.+", replacement = "", x = Signals)) %>%
     spread(Signals, Value)
 
-  ## Create the two-digit zero-padded format
-  ## Used in `scale_x_continuous()`
-  pad2 <- function(x){
-    x <- as.character(x)
-
-    ifelse(nchar(x) == 1, paste0("0", x), x)
-  }
-
   ## Return
   if(return == "data"){
 

R/workpatterns_hclust.R

@@ -295,14 +295,6 @@ plot_signal_clust <- function(data,
     mutate_at("Hours", ~sub(pattern = paste0(sig_label, "_"), replacement = "", x = .)) %>%
     mutate_at("Hours", ~sub(pattern = "_.+", replacement = "", x = .))
 
-  ## Create the two-digit zero-padded format
-  ## Used in `scale_x_continuous()`
-  pad2 <- function(x){
-    ifelse(nchar(x) == 1,
-           paste0(0, x),
-           x)
-  }
-
   ## bar plot
   output_bar <-
     plot_data %>%

R/workpatterns_rank.R

@@ -171,7 +171,7 @@ workpatterns_rank <- function(data,
         by = num_cols]
 
     ## 00, 01, 02, etc.
-    hours_col <- stringr::str_pad(seq(0,23), width = 2, pad = 0)
+    hours_col <- pad2(x = seq(0,23))
 
     # Wide table showing proportion of signals by hour
     # Ranked descending by `WeekCount`

README.md

@@ -66,6 +66,7 @@ See [NEWS.md](https://microsoft.github.io/wpa/news/index.html) for the package c
 - [Viva RMarkdown Report Marketplace](https://github.com/microsoft/VivaRMDReportMarketplace)
 - [Viva Insights Sample Code](https://github.com/microsoft/viva-insights-sample-code)
 - [Viva Insights Zoom Integration](https://github.com/microsoft/vivainsights_zoom_int)
+- [Viva Insights OData Query Download](https://github.com/microsoft/vivainsights-odatadl)
 
 ---
 

cran-comments.md

@@ -7,6 +7,10 @@
 
 0 errors | 0 warnings | 0 note
 
+## Submission 1.8.0
+
+New functions and improving outputs of existing functions
+
 ## Submission 1.7.0
 
 Bug fixes, new features, and removal of archived dependency 'portes'

man/external_dist.Rd

@@ -139,8 +139,10 @@ Other Visualization:
 \code{\link{workpatterns_area}()},
 \code{\link{workpatterns_rank}()}
 
-Other External: 
+Other External Collaboration: 
+\code{\link{external_fizz}()},
+\code{\link{external_line}()},
 \code{\link{external_sum}()}
 }
-\concept{External}
+\concept{External Collaboration}
 \concept{Visualization}

man/external_fizz.Rd

@@ -125,7 +125,9 @@ Other Visualization:
 \code{\link{workpatterns_rank}()}
 
 Other External Collaboration: 
-\code{\link{external_line}()}
+\code{\link{external_dist}()},
+\code{\link{external_line}()},
+\code{\link{external_sum}()}
 }
 \concept{External Collaboration}
 \concept{Visualization}

man/external_line.Rd

@@ -127,7 +127,9 @@ Other Visualization:
 \code{\link{workpatterns_rank}()}
 
 Other External Collaboration: 
-\code{\link{external_fizz}()}
+\code{\link{external_dist}()},
+\code{\link{external_fizz}()},
+\code{\link{external_sum}()}
 }
 \concept{External Collaboration}
 \concept{Visualization}

man/external_sum.Rd

@@ -46,7 +46,7 @@ Returns a stacked bar plot of internal and external collaboration.
 Additional options available to return a summary table.
 }
 \examples{
-# Return a  plot
+# Return a plot
 external_sum(sq_data, hrvar = "LevelDesignation")
 
 # Return summary table
@@ -130,8 +130,10 @@ Other Visualization:
 \code{\link{workpatterns_area}()},
 \code{\link{workpatterns_rank}()}
 
-Other External: 
-\code{\link{external_dist}()}
+Other External Collaboration: 
+\code{\link{external_dist}()},
+\code{\link{external_fizz}()},
+\code{\link{external_line}()}
 }
-\concept{External}
+\concept{External Collaboration}
 \concept{Visualization}

man/identify_datefreq.Rd

@@ -0,0 +1,85 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/identify_datefreq.R
+\name{identify_datefreq}
+\alias{identify_datefreq}
+\title{Identify date frequency based on a series of dates}
+\usage{
+identify_datefreq(x)
+}
+\arguments{
+\item{x}{Vector containing a series of dates.}
+}
+\value{
+String describing the detected date frequency, i.e.:
+\itemize{
+\item 'daily'
+\item 'weekly'
+\item 'monthly'
+}
+}
+\description{
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[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.
+}
+\details{
+Date frequency detection works as follows:
+\itemize{
+\item 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'
+\item If the total number of months in the series is equal to the length, then
+the series is classified as 'monthly'
+\item 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'.
+}
+
+\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)
+
+}

man/pad2.Rd

@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/supporting_functions.R
+\name{pad2}
+\alias{pad2}
+\title{Create the two-digit zero-padded format}
+\usage{
+pad2(x)
+}
+\arguments{
+\item{x}{numeric value or vector with maximum two characters.}
+}
+\value{
+Numeric value containing two-digit zero-padded values.
+}
+\description{
+Create the two-digit zero-padded format
+}

man/plot_hourly_pat.Rd

@@ -0,0 +1,56 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/plot_hourly_pat.R
+\name{plot_hourly_pat}
+\alias{plot_hourly_pat}
+\title{Internal function for plotting the hourly activity patterns.}
+\usage{
+plot_hourly_pat(
+  data,
+  start_hour,
+  end_hour,
+  legend,
+  legend_label,
+  legend_text = "Observed activity",
+  rows,
+  title,
+  subtitle,
+  caption,
+  ylab = paste("Top", rows, "activity patterns")
+)
+}
+\arguments{
+\item{data}{Data frame containing three columns:
+\itemize{
+\item \code{patternRank}
+\item \code{Hours}
+\item \code{Freq}
+}}
+
+\item{start_hour}{Numeric value to specify expected start hour.}
+
+\item{end_hour}{Numeric value to specify expected end hour.}
+
+\item{legend}{Data frame containing the columns:
+\itemize{
+\item \code{patternRank}
+\item Any column to be used in the grey label box, supplied to \code{legend_label}
+}}
+
+\item{legend_label}{String specifying column to display in the grey label
+box}
+
+\item{legend_text}{String to be used in the bottom legend label.}
+
+\item{rows}{Number of rows to show in plot.}
+
+\item{title}{String to specify plot title.}
+
+\item{subtitle}{String to specify plot subtitle.}
+
+\item{caption}{String to specify plot caption.}
+
+\item{ylab}{String to specify plot y-axis label.}
+}
+\description{
+This is used within \code{plot_flex_index()} and \code{workpatterns_rank()}.
+}