refactor: unify league update/summary entry points and fix params cross-refs (#42)

NAMESPACE

@@ -7,7 +7,6 @@ export(buildStats)
 export(cleanupPredictionsFile)
 export(colourDelta)
 export(compile_predictions)
-export(dailyPWHLSummary)
 export(dailySummary)
 export(daily_odds_table)
 export(dcPredictMultipleDays)
@@ -84,10 +83,7 @@ export(tweetMetrics)
 export(tweetPace)
 export(tweetPlayoffOdds)
 export(tweetSeries)
-export(updateDC)
 export(updateModel)
-export(updatePWHLDC)
-export(updatePWHLModel)
 export(updatePWHLScheduleAPI)
 export(updatePWHLScoresAPI)
 export(updatePredictions)

NEWS.md

@@ -1,5 +1,7 @@
 # HockeyModel 2026.0.1.9000 (development version)
 
+* All internal (non-exported) functions now use a leading dot prefix (e.g. `.DCweights()` instead of `DCweights()`), following the R convention for package-internal helpers; 71 functions were renamed across `R/`, `tests/`, and `vignettes/` (@pbulsink, #42).
+* `updateModel()` and `dailySummary()` are now the single entry points for updating and summarising both leagues; the former league-specific exports `updateDC()`, `updatePWHLDC()`, `updatePWHLModel()`, and `dailyPWHLSummary()` are now internal (`.update_dc_nhl()`, `.update_dc_pwhl()`, `.update_model_pwhl()`, `.daily_summary_pwhl()`), and the `params` argument in the NHL prediction/simulation/social-media functions now documents the correct source of the params list (#42).
 * `simulateSeasonParallel()` no longer copies the invariant odds columns into the per-simulation score table on every iteration (the sampled outcome columns are built separately via a new internal `sim_odds_results()`), removing the redundant per-iteration data copying; its parallel branch now runs simulations in `cores` batched tasks (each worker handling several simulations) instead of one task per simulation, so the invariant table is serialised to each worker only `cores` times rather than `nsims` times (@pbulsink, #45).
 * `loopless_sim()`'s parallel branch now distributes exactly `nsims` simulations across `cores` chunks (remainder spread over the first `nsims %% cores` workers) via a new internal `simulation_chunks()` helper, instead of the previous `floor(nsims / cores)` per task that silently dropped the remainder and produced a total that rarely matched the requested `nsims` (@pbulsink, #51).
 * `simulateSeasonParallel()` and `loopless_sim()` parallel branches batch simulations into `cores` tasks (via `simulation_chunks()`) instead of one task per simulation, reducing serialisation round-trips across the worker cluster (@pbulsink, #49).

R/constants.R

@@ -1,6 +1,6 @@
 # Package-level weighting constants for the Dixon-Coles model.
 #
-# These values control how `DCweights()` (and therefore `getM()`) decays the
+# These values control how `.DCweights()` (and therefore `getM()`) decays the
 # influence of historical games.  Two separate components are used:
 #
 #   1. **Sigmoid within-season decay** (parameters xi and upsilon)
@@ -16,7 +16,7 @@
 #
 # NHL values were originally tuned on full NHL history; PWHL values use
 # nu = 2 as a starting point to reflect the high year-to-year roster churn
-# from expansion drafts. Run `tune_dc_weight(league = "PWHL")` to find the
+# from expansion drafts. Run `.tune_dc_weight(league = "PWHL")` to find the
 # optimal values.
 
 #' Default NHL Dixon-Coles sigmoid time-decay slope
@@ -35,7 +35,7 @@ DC_UPSILON_NHL <- 365
 #'
 #' `nu = 0` disables cross-season discounting for NHL (seasons are relatively
 #' stable year-to-year).  Increase to down-weight older seasons more
-#' aggressively.  Tune with [tune_dc_weight()].
+#' aggressively.  Tune with [.tune_dc_weight()].
 #' @keywords internal
 DC_NU_NHL <- 0
 
@@ -53,6 +53,6 @@ DC_UPSILON_PWHL <- 461.0156
 #'
 #' `nu = 2` provides moderate cross-season discounting for PWHL, reflecting
 #' the high year-to-year roster volatility from expansion drafts.  Tune with
-#' `tune_dc_weight(league = "PWHL")`.
+#' `.tune_dc_weight(league = "PWHL")`.
 #' @keywords internal
 DC_NU_PWHL <- 5

R/data.R

@@ -159,7 +159,7 @@
 #' PWHL Dixon-Coles model `m`
 #'
 #' Fitted GLM capturing each PWHL team's attack and defence strength plus home
-#' ice advantage. Populated by [updatePWHLDC()].
+#' ice advantage. Populated by [.update_dc_pwhl()].
 #'
 #' @format a glm model fit, or `NULL` when not yet fitted
 "pwhl_m"
@@ -168,7 +168,7 @@
 #' PWHL Dixon-Coles `rho`
 #'
 #' Low-score correction parameter for the PWHL model. Populated by
-#' [updatePWHLDC()].
+#' [.update_dc_pwhl()].
 #'
 #' @format a single numeric value, or `NULL` when not yet fitted
 "pwhl_rho"
@@ -177,7 +177,7 @@
 #' PWHL `beta`
 #'
 #' Weibull shape parameter for PWHL tie-game enhancement. Populated by
-#' [updatePWHLDC()].
+#' [.update_dc_pwhl()].
 #'
 #' @format a single numeric value, or `NULL` when not yet fitted
 "pwhl_beta"
@@ -186,7 +186,7 @@
 #' PWHL `eta`
 #'
 #' Weibull scale parameter for PWHL tie-game enhancement. Populated by
-#' [updatePWHLDC()].
+#' [.update_dc_pwhl()].
 #'
 #' @format a single numeric value, or `NULL` when not yet fitted
 "pwhl_eta"
@@ -195,7 +195,7 @@
 #' PWHL `k`
 #'
 #' Weibull multiplier for PWHL tie-game enhancement. Populated by
-#' [updatePWHLDC()].
+#' [.update_dc_pwhl()].
 #'
 #' @format a single numeric value, or `NULL` when not yet fitted
 "pwhl_k"
@@ -224,7 +224,7 @@
 #' @returns `NULL` (invisibly). Writes updated data when `usethis` is
 #'   available.
 #' @keywords internal
-buildTeamColours <- function() {
+.buildTeamColours <- function() {
   teamColours <- utils::read.csv(
     "./data-raw/logos/team_colours.csv",
     stringsAsFactors = FALSE

R/frontend-core.R

@@ -157,7 +157,7 @@
   cli::cli_inform("Updating Scores")
   scores <- updateScoresAPI(schedule = schedule, save_data = save_data)
   cli::cli_inform("Refitting Model Parameters")
-  params <- updateDC(scores = scores, save_data = save_data)
+  params <- .update_dc_nhl(scores = scores, save_data = save_data)
   list(
     scores = scores,
     schedule = schedule,
@@ -185,7 +185,7 @@ updateModel <- function(save_data = TRUE, league = NULL) {
     result$nhl <- .update_model_nhl(save_data = save_data)
   }
   if ("PWHL" %in% leagues) {
-    result$pwhl <- updatePWHLModel(save_data = save_data)
+    result$pwhl <- .update_model_pwhl(save_data = save_data)
   }
 
   .simplify_frontend_result(result, leagues)
@@ -215,7 +215,7 @@ updateModel <- function(save_data = TRUE, league = NULL) {
   if (scores$Date[nrow(scores)] < (Sys.Date())) {
     updateScoresAPI(save_data = TRUE)
   }
-  pdates <- get_prediction_dates(data_dir)
+  pdates <- .get_prediction_dates(data_dir)
   lastp <- if (length(pdates) == 0L) {
     as.Date(getSeasonStartDate()) - 1L
   } else {
@@ -251,7 +251,7 @@ updateModel <- function(save_data = TRUE, league = NULL) {
   schedule = HockeyModel::pwhlSchedule,
   params = NULL
 ) {
-  params <- parse_pwhl_dc_params(params)
+  params <- .parse_pwhl_dc_params(params)
 
   if (!dir.exists(data_dir)) {
     dir.create(data_dir, recursive = TRUE)
@@ -281,7 +281,7 @@ updateModel <- function(save_data = TRUE, league = NULL) {
 #' @param data_dir directory of predictions
 #' @param scores HockeyModel::scores or a custom value
 #' @param schedule HockeyModel::schedule or a custom value
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #' @param league which league front-end to run: `NULL`, `NA`, or `"both"` runs
 #'   both leagues; `"nhl"` and `"pwhl"` run one league only
 #'

R/frontend-daily-summary.R

@@ -4,7 +4,7 @@
 #'
 #' @param graphic_dir Directory for graphic files
 #' @param subdir subdirectory to `graphic_dir` for pace plots
-#' @param delay delay between tweet posts
+#' @param delay delay between .tweet posts
 #' @returns (`data.frame`) A combined summary of every attempted social post
 #'   across the run (see `.summarize_post_results()` in `frontend-social.R`),
 #'   invisibly.
@@ -42,7 +42,8 @@
     today <- todayOddsPlot(
       params = params,
       schedule = modelparams$schedule,
-      scores = modelparams$scores, league = "NHL"
+      scores = modelparams$scores,
+      league = "NHL"
     )
     # save to files.
     grDevices::png(
@@ -197,7 +198,7 @@
   }
 
   message("Posting Tweets...")
-  post_results[[length(post_results) + 1]] <- tweet(
+  post_results[[length(post_results) + 1]] <- .tweet(
     graphic_dir = graphic_dir,
     delay = delay
   )
@@ -320,7 +321,7 @@ dailySummary <- function(
         .default_pwhl_graphics_dir()
       )
     }
-    result$pwhl <- dailyPWHLSummary(
+    result$pwhl <- .daily_summary_pwhl(
       graphic_dir = pwhl_graphic_dir,
       delay = delay
     )

R/frontend-plots.R

@@ -49,7 +49,7 @@
   schedule = HockeyModel::pwhlSchedule,
   scores = HockeyModel::pwhlScores
 ) {
-  params <- parse_pwhl_dc_params(params)
+  params <- .parse_pwhl_dc_params(params)
 
   if (nrow(scores) > 0 && scores$Date[nrow(scores)] < (date - 7)) {
     cli::cli_alert_info(
@@ -72,7 +72,7 @@
 #' Today's game odds graphic
 #'
 #' @param date date to predict odds. Default today
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #' @param schedule HockeyModel::schedule or a custom value
 #' @param scores HockeyModel::scores or a custom value
 #' @param league which league front-end to run: `NULL`, `NA`, or `"both"` runs

R/frontend-social.R

@@ -79,7 +79,7 @@
 #' @returns (`data.frame`) A summary of each attempted post (see
 #'   `.summarize_post_results()`), invisibly.
 #' @keywords internal
-tweet <- function(
+.tweet <- function(
   graphic_dir = .default_nhl_graphics_dir(),
   delay = stats::runif(1, min = 2, max = 6) * 60
 ) {
@@ -172,7 +172,7 @@ tweetPace <- function(
     scores = scores
   )
 
-  pdates <- get_prediction_dates(prediction_dir)
+  pdates <- .get_prediction_dates(prediction_dir)
   if (length(pdates) == 0L) {
     cli::cli_abort("No prediction files found in {.path {prediction_dir}}.")
   }
@@ -271,7 +271,7 @@ tweetPace <- function(
     scores = scores
   )
 
-  for (division in getDivisions()) {
+  for (division in .getDivisions()) {
     status <- paste(
       "Current Points compared to predicted (at season start) for #NHL teams in the",
       division,
@@ -318,7 +318,7 @@ tweetLikelihoods <- function(
   # make likelihood plots
   plot_point_likelihood(graphic_dir = graphic_dir, subdir = subdir)
 
-  for (conf in getConferences()) {
+  for (conf in .getConferences()) {
     if (
       file.exists(file.path(
         graphic_dir,
@@ -364,10 +364,10 @@ tweetLikelihoods <- function(
 
 #' Tweet Game Plots
 #'
-#' @param games Games to tweet graphics from
+#' @param games Games to .tweet graphics from
 #' @param delay Delay between tweets
 #' @param graphic_dir the graphics directory
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #'
 #' @returns (`data.frame`) A summary of each attempted post (see
 #'   `.summarize_post_results()`), invisibly.
@@ -382,12 +382,12 @@ tweetGames <- function(
   post_results <- list()
   # Tweet each game
   if (is.null(games)) {
-    message("No games to tweet")
+    message("No games to .tweet")
     return(invisible(.summarize_post_results(post_results)))
   }
 
   if (nrow(games) == 0) {
-    message("No games to tweet")
+    message("No games to .tweet")
     return(invisible(.summarize_post_results(post_results)))
   }
 
@@ -417,9 +417,9 @@ tweetGames <- function(
       " at ",
       teamColours[teamColours$Team == home, "Hashtag"],
       " predicted goals. #",
-      getShortTeam(away),
+      .getShortTeam(away),
       "vs",
-      getShortTeam(home),
+      .getShortTeam(home),
       " #HockeyTwitter"
     )
 
@@ -475,7 +475,7 @@ tweetMetrics <- function() {
 #' @description Tweet the series odds graphics
 #'
 #' @param graphic_dir directory to save the image
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #' @param delay Delay in seconds between posts. Default is a random value between 1 and 3 minutes.
 #'
 #' @return (`data.frame`) A summary of each attempted post (see
@@ -563,7 +563,7 @@ tweetSeries <- function(
 #' @param summary_results the summary results file, otherwise the most recent will be loaded
 #' @param graphic_dir graphic dir
 #' @param trimcup trim to just cup winners
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #'
 #' @return (`data.frame`) A summary of each attempted post (see
 #'   `.summarize_post_results()`), invisibly.
@@ -591,7 +591,7 @@ tweetPlayoffOdds <- function(
     return(invisible(.summarize_post_results(post_results)))
   }
 
-  playoffodds$Conference <- getTeamConferences(playoffodds$Team)
+  playoffodds$Conference <- .getTeamConferences(playoffodds$Team)
   if (trimcup) {
     plt <- format_playoff_odds(
       playoff_odds = playoffodds,

R/graphics-odds.R

@@ -3,7 +3,7 @@
 #' Plot Today's Odds
 #'
 #' @param today The day's odds to plot. Default today.
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #' @param schedule HockeyModel::schedule or a custom value
 #' @param teamColours HockeyModel::teamColours or a custom value
 #' @param league League identifier. `"NHL"` (default) or `"PWHL"`. When
@@ -25,20 +25,20 @@ plot_odds_today <- function(
     )
   }
   params <- .parse_dc_params(params)
-  todayodds <- todayDC(today = today, params, schedule = schedule)
+  todayodds <- .todayDC(today = today, params, schedule = schedule)
   if (is.null(todayodds)) {
     return(NULL)
   }
   todayodds$HomeWinOT <- todayodds$AwayWinOT <- 0
 
   # add odds for each team in OT/SO
   for (g in seq_len(nrow(todayodds))) {
-    todayodds$HomeWinOT[g] <- extraTimeSolver(
+    todayodds$HomeWinOT[g] <- .extraTimeSolver(
       home_win = todayodds$HomeWin[g],
       away_win = todayodds$AwayWin[g],
       draw = todayodds$Draw[g]
     )[2]
-    todayodds$AwayWinOT[g] <- extraTimeSolver(
+    todayodds$AwayWinOT[g] <- .extraTimeSolver(
       home_win = todayodds$HomeWin[g],
       away_win = todayodds$AwayWin[g],
       draw = todayodds$Draw[g]
@@ -207,7 +207,7 @@ plot_odds_today <- function(
 #' Plot Today's Playoff Series Odds
 #'
 #' @param series A data frame of home team, away team, home wins, away wins
-#' @param params The named list containing m, rho, beta, eta, and k. See [updateDC] for information on the params list
+#' @param params The named list containing m, rho, beta, eta, and k. See [updateModel()] for information on the params list
 #' @param teamColours HockeyModel::teamColours or a custom value
 #' @param league League identifier. `"NHL"` (default) or `"PWHL"`. When
 #'   `"PWHL"`, PWHL-specific labels are used.