Add period-completeness helpers

NAMESPACE

@@ -7,20 +7,27 @@ export(bizday_of_period)
 export(bizdays_between)
 export(breaks_quarters)
 export(detect_hidden_logicals)
+export(filter_complete_periods)
 export(guess_col_fmts)
 export(is_bizday)
 export(is_ytd_comparable)
 export(label_quarters_short)
+export(last_complete_period_end)
+export(last_complete_period_start)
 export(local_calendar)
 export(most_recent_monday)
 export(most_recent_sunday)
 export(mutate_cagrs)
 export(normalize_logicals)
 export(passed_colnames)
+export(period_end_date)
+export(period_is_complete)
+export(period_start_date)
 export(periodic_bizdays)
 export(plot_accounts_by_status)
 export(py_dates)
 export(rename_cols_for_display)
+export(scale_alpha_logical)
 export(scale_x_integer)
 export(scale_y_integer)
 export(set_calendar)

NEWS.md

@@ -1,3 +1,37 @@
+# mcrutils (development version)
+
+## New
+- Period-completeness toolkit for reporting on partial periods:
+    - `period_is_complete()` tests whether the period (week/month/quarter/year)
+      containing each date is complete as of a cutoff date. Completeness is
+      business-day aware via a QuantLib calendar (default `"WeekendsOnly"`); pass
+      a national calendar such as `"UnitedStates"` for holiday accuracy, or
+      `"Null"` for pure calendar-day semantics.
+    - `period_start_date()` and `period_end_date()` return the canonical first and
+      last calendar day of the period containing each date.
+    - `filter_complete_periods()` keeps only rows whose period is complete;
+      `as_of` defaults to the maximum of the date column.
+    - `last_complete_period_start()` and `last_complete_period_end()` return the
+      boundaries of the most recent complete period as of a cutoff.
+    - `scale_alpha_logical()`, a ggplot2 alpha scale for fading incomplete
+      periods (pairs with `period_is_complete()`).
+- Completeness uses an inclusive convention: a period is complete once its end
+    date is reached (not strictly after it). For pure calendar-day semantics use
+    `calendar = "Null"` (the QuantLib id is `"Null"`, not `"NullCalendar"`).
+    `NA` dates propagate to `NA` (and are dropped by `filter_complete_periods()`).
+- `period_is_complete()`, `last_complete_period_start()`, and
+    `last_complete_period_end()` require an explicit `as_of`; there is no
+    wall-clock default, so completeness is never judged against the current date
+    unless you ask for it (pass `Sys.Date()` to opt in). `filter_complete_periods()`
+    still defaults `as_of` to the maximum of its date column.
+
+## Behavior changes
+- `most_recent_monday()` / `most_recent_sunday()`: the `ref_date` argument is
+    renamed `as_of`, matching the period-completeness functions (both name the
+    date that state is evaluated as of). The default (current date) is unchanged
+    and positional calls are unaffected, but callers passing `ref_date =` by name
+    must switch to `as_of =`.
+
 # mcrutils 0.0.0.9013
 
 ## Behavior changes

R/most_recent_day_of_week.R

@@ -3,8 +3,8 @@
 #' This function returns the date of the most recent Sunday or Monday that
 #' is on or before the current date or a specified reference date.
 #'
-#' @param ref_date A date object or a string representing a date.
-#' Defaults to NULL, which uses the current date.
+#' @param as_of A date object or a string representing the date to evaluate
+#' relative to. Defaults to NULL, which uses the current date.
 #'
 #' @return A Date object representing the most recent Sunday or Monday
 #' @examples
@@ -17,26 +17,26 @@ NULL
 
 #' @rdname most_recent_x_day
 #' @export
-most_recent_monday <- function(ref_date = NULL) {
-  if (!is.null(ref_date)) {
-    ref_date <- as.Date(ref_date)
+most_recent_monday <- function(as_of = NULL) {
+  if (!is.null(as_of)) {
+    as_of <- as.Date(as_of)
   } else {
-    ref_date <- Sys.Date()
+    as_of <- Sys.Date()
   }
-  weekday <- as.integer(format(ref_date, "%u")) # 1 = Monday, 7 = Sunday
+  weekday <- as.integer(format(as_of, "%u")) # 1 = Monday, 7 = Sunday
   days_to_subtract <- ifelse(weekday == 1, 0, weekday - 1)
-  ref_date - days_to_subtract
+  as_of - days_to_subtract
 }
 
 #' @rdname most_recent_x_day
 #' @export
-most_recent_sunday <- function(ref_date = NULL) {
-  if (!is.null(ref_date)) {
-    ref_date <- as.Date(ref_date)
+most_recent_sunday <- function(as_of = NULL) {
+  if (!is.null(as_of)) {
+    as_of <- as.Date(as_of)
   } else {
-    ref_date <- Sys.Date()
+    as_of <- Sys.Date()
   }
-  weekday <- as.integer(format(ref_date, "%u")) # 1 = Monday, 7 = Sunday
+  weekday <- as.integer(format(as_of, "%u")) # 1 = Monday, 7 = Sunday
   days_to_subtract <- ifelse(weekday == 7, 0, weekday)
-  ref_date - days_to_subtract
+  as_of - days_to_subtract
 }