From a3580ac62071e98a9b29969e18b4c836e0f5c015 Mon Sep 17 00:00:00 2001
From: Michael McCarthy <51542091+mccarthy-m-g@users.noreply.github.com>
Date: Tue, 20 Jan 2026 15:43:28 -0800
Subject: [PATCH] add residuals to `run_eval()` results

---
 DESCRIPTION                      |  2 +-
 R/calculate_bayesian_impact.R    |  4 ++--
 R/calculate_shrinkage.R          |  8 ++++----
 R/calculate_stats.R              | 10 +++++-----
 R/plot.R                         |  6 +++---
 R/run_eval_core.R                | 15 ++++++++++++---
 man/calculate_bayesian_impact.Rd |  4 ++--
 man/calculate_shrinkage.Rd       |  4 ++--
 man/calculate_stats.Rd           |  4 ++--
 tests/testthat/test-run_eval.R   |  6 +++---
 10 files changed, 36 insertions(+), 27 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 5e0ae21..ca32725 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -42,6 +42,6 @@ Remotes:
 Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 VignetteBuilder: knitr
 LazyData: true
diff --git a/R/calculate_bayesian_impact.R b/R/calculate_bayesian_impact.R
index 29332b0..233fd29 100644
--- a/R/calculate_bayesian_impact.R
+++ b/R/calculate_bayesian_impact.R
@@ -11,9 +11,9 @@
 #'
 #' @export
 calculate_bayesian_impact <- function(
-  res
+  .res
 ) {
-  out <- res$stats_summ |>
+  out <- .res$stats_summ |>
     dplyr::filter(!.data$apriori) |>
     dplyr::select("type", "apriori", "rmse", "mape") |>
     tidyr::pivot_wider(names_from = "type", values_from = c("rmse", "mape")) |>
diff --git a/R/calculate_shrinkage.R b/R/calculate_shrinkage.R
index 6604634..1c21701 100644
--- a/R/calculate_shrinkage.R
+++ b/R/calculate_shrinkage.R
@@ -22,12 +22,12 @@
 #' @returns tibble
 #'
 #' @export
-calculate_shrinkage <- function(res) {
-  om <- get_omega_for_parameters(res$mod_obj)
-  out <- res$results |>
+calculate_shrinkage <- function(.res) {
+  om <- get_omega_for_parameters(.res$mod_obj)
+  out <- .res$results |>
     dplyr::mutate(dplyr::across(
       .cols = names(om),
-      .fns  = ~ calc_eta(.x, dplyr::cur_column(), res$mod_obj$parameters),
+      .fns  = ~ calc_eta(.x, dplyr::cur_column(), .res$mod_obj$parameters),
       .names = "eta_{.col}"
     )) |>
     dplyr::group_by(.data$`_iteration`) |>
diff --git a/R/calculate_stats.R b/R/calculate_stats.R
index fd94c7f..bfb3e66 100644
--- a/R/calculate_stats.R
+++ b/R/calculate_stats.R
@@ -1,6 +1,6 @@
 #' Calculate basic statistics, like RMSE, MPE, MAPE for forecasted data
 #'
-#' @param res output object (`mipdeval_results`) from `run_eval()`, or
+#' @param .res output object (`mipdeval_results`) from `run_eval()`, or
 #' `data.frame` with raw results.
 #' @param rounding number of decimals to round to.
 #' @param acc_error_abs,acc_error_rel For calculating [accuracy()]: Positive number
@@ -12,15 +12,15 @@
 #'
 #' @export
 calculate_stats <- function(
-    res,
+    .res,
     rounding = 3,
     acc_error_abs = NULL,
     acc_error_rel = NULL
 ) {
-  if(inherits(res, "mipdeval_results")) {
-    res <- res$results
+  if(inherits(.res, "mipdeval_results")) {
+    .res <- .res$results
   }
-  out <- res |>
+  out <- .res |>
     tidyr::pivot_longer(
       cols = c("pred", "map_ipred", "iter_ipred"), names_to = "type"
     ) |>
diff --git a/R/plot.R b/R/plot.R
index b6f834d..ce0562f 100644
--- a/R/plot.R
+++ b/R/plot.R
@@ -20,12 +20,12 @@ plot.mipdeval_results <- function(x, type = "vpc", ...) {
   plot_fun(x, ...)
 }
 
-plot_vpc <- function(res, ...) {
+plot_vpc <- function(.res, ...) {
   rlang::check_installed("vpc", reason = "for VPC plotting.")
   rlang::check_dots_used()
   vpc::vpc(
-    sim = res$sim,
-    obs = dplyr::filter(res$data, .data$EVID == 0),
+    sim = .res$sim,
+    obs = dplyr::filter(.res$data, .data$EVID == 0),
     ...
   )
 }
diff --git a/R/run_eval_core.R b/R/run_eval_core.R
index 08bbdf9..a730c34 100644
--- a/R/run_eval_core.R
+++ b/R/run_eval_core.R
@@ -74,7 +74,12 @@ run_eval_core <- function(
       t = obs_data$t,
       dv = fit$dv,
       ipred = fit$ipred,
+      ires = fit$ires,
+      iwres = fit$iwres,
       pred = fit$pred,
+      res = fit$res,
+      wres = fit$wres,
+      cwres = fit$cwres,
       ofv = fit$fit$value,
       ss_w = ss(fit$dv, fit$ipred, weights),
       `_iteration` = iterations[i],
@@ -112,7 +117,12 @@ run_eval_core <- function(
       t = obs_data$t,
       dv = fit_map$dv,
       ipred = fit_map$ipred,
+      ires = fit_map$ires,
+      iwres = fit_map$iwres,
       pred = fit_map$pred,
+      res = fit_map$res,
+      wres = fit_map$wres,
+      cwres = fit_map$cwres,
       ofv = fit_map$fit$value,
       ss_w = ss(fit_map$dv, fit_map$ipred, w = NULL),
       `_iteration` = iterations[i],
@@ -149,9 +159,8 @@ run_eval_core <- function(
       apriori = (.data$`_iteration` == 0)
     ) |>
     dplyr::select(
-      "id", "_iteration", "_grouper", "t", "dv", "pred", "map_ipred",
-      "ofv", "ss_w",
-      "iter_ipred", "apriori",
+      "id", "_iteration", "_grouper", "t", "dv", "pred", "res", "wres", "cwres",
+      "map_ipred", "ofv", "ss_w", "iter_ipred", "ires", "iwres", "apriori",
       !!names(mod_obj$parameters)
     )
 
diff --git a/man/calculate_bayesian_impact.Rd b/man/calculate_bayesian_impact.Rd
index b4c0edf..b6a8509 100644
--- a/man/calculate_bayesian_impact.Rd
+++ b/man/calculate_bayesian_impact.Rd
@@ -4,10 +4,10 @@
 \alias{calculate_bayesian_impact}
 \title{Calculate the impact of using Bayesian updating compared to population estimates}
 \usage{
-calculate_bayesian_impact(res)
+calculate_bayesian_impact(.res)
 }
 \arguments{
-\item{res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
+\item{.res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
 \code{data.frame} with raw results.}
 }
 \value{
diff --git a/man/calculate_shrinkage.Rd b/man/calculate_shrinkage.Rd
index 98c48f6..519300e 100644
--- a/man/calculate_shrinkage.Rd
+++ b/man/calculate_shrinkage.Rd
@@ -4,10 +4,10 @@
 \alias{calculate_shrinkage}
 \title{Calculate eta-shrinkage}
 \usage{
-calculate_shrinkage(res)
+calculate_shrinkage(.res)
 }
 \arguments{
-\item{res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
+\item{.res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
 \code{data.frame} with raw results.}
 }
 \value{
diff --git a/man/calculate_stats.Rd b/man/calculate_stats.Rd
index 9f15f17..cc08c98 100644
--- a/man/calculate_stats.Rd
+++ b/man/calculate_stats.Rd
@@ -4,10 +4,10 @@
 \alias{calculate_stats}
 \title{Calculate basic statistics, like RMSE, MPE, MAPE for forecasted data}
 \usage{
-calculate_stats(res, rounding = 3, acc_error_abs = NULL, acc_error_rel = NULL)
+calculate_stats(.res, rounding = 3, acc_error_abs = NULL, acc_error_rel = NULL)
 }
 \arguments{
-\item{res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
+\item{.res}{output object (\code{mipdeval_results}) from \code{run_eval()}, or
 \code{data.frame} with raw results.}
 
 \item{rounding}{number of decimals to round to.}
diff --git a/tests/testthat/test-run_eval.R b/tests/testthat/test-run_eval.R
index 69493ed..f45f595 100644
--- a/tests/testthat/test-run_eval.R
+++ b/tests/testthat/test-run_eval.R
@@ -22,9 +22,9 @@ test_that("Basic run with vanco data + model works", {
   expect_s3_class(res$stats_summ, c("tbl_df", "tbl", "data.frame"))
   expect_equal(
     names(res$results),
-    c("id", "_iteration", "_grouper", "t", "dv", "pred", "map_ipred",
-      "ofv", "ss_w", "iter_ipred", "apriori", "CL", "V", "TH_CRCL",
-      "Q", "V2")
+    c("id", "_iteration", "_grouper", "t", "dv", "pred", "res", "wres", "cwres",
+      "map_ipred", "ofv", "ss_w", "iter_ipred", "ires", "iwres", "apriori", "CL",
+      "V", "TH_CRCL", "Q", "V2")
   )
   expect_equal(
     round(res$results$CL[1:5], 3),