diff --git a/DESCRIPTION b/DESCRIPTION index 9b79bc9..9840bba 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: learner Type: Package Title: Latent Space-Based Transfer Learning -Version: 1.1.0 +Version: 1.1.0.9000 Authors@R: c(person("Sean", "McGrath", role = c("aut", "cre"), email = "sean.mcgrath514@gmail.com", comment = c(ORCID = "0000-0002-7281-3516")), diff --git a/NEWS.md b/NEWS.md index 013c5a8..69d8476 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,17 @@ ### learner version 1.1.0 (unreleased) +* Add an optional relative stopping rule to `learner()` and `cv.learner()`. Use + `control = list(stopping_rule = "relative")` to stop once the relative change in + the objective stays below `threshold` (default `1e-6`) for `window` updates in a + row (default 5). The default rule is unchanged. `window` also works with the + default absolute rule. `k` and `epsilon` are accepted as other names for + `window` and `threshold`. Giving both names for the same setting is an error. + +* Store candidate grids and observed-entry counts in CV results so that + `plot_cv()` can use them automatically; retain explicit arguments for older results. +* Use a sequential blue scale for CV heatmaps. +* Reorganize the advanced tutorial around usage and show compact diagnostic outputs. + * Add support for multiple source populations and optional source weights in `learner()`, `dlearner()`, and `cv.learner()`. * Add `dat_multisource`, an example dataset with one target and two source diff --git a/R/RcppExports.R b/R/RcppExports.R index d1b4b70..1258d92 100644 --- a/R/RcppExports.R +++ b/R/RcppExports.R @@ -1,12 +1,12 @@ # Generated by using Rcpp::compileAttributes() -> do not edit by hand # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393 -learner_cpp <- function(Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value) { - .Call(`_learner_learner_cpp`, Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value) +learner_cpp <- function(Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value, relative, window) { + .Call(`_learner_learner_cpp`, Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value, relative, window) } -cv_learner_cpp <- function(Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set) { - .Call(`_learner_cv_learner_cpp`, Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set) +cv_learner_cpp <- function(Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set, relative, window) { + .Call(`_learner_cv_learner_cpp`, Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set, relative, window) } omp_max_threads <- function() { diff --git a/R/data-asymmetric.R b/R/data-asymmetric.R index 2634eb9..ba5c5a2 100644 --- a/R/data-asymmetric.R +++ b/R/data-asymmetric.R @@ -1,8 +1,8 @@ #' Simulated data set: One shared latent space #' #' One source and one target with the same true U-space but different true -#' V-spaces. This example illustrates why the two space penalties in LEARNER -#' can be selected separately. +#' V-spaces. This example illustrates how to fit LEARNER +#' with separate penalties on the two spaces. #' #' @docType data #' @format A list of four aligned matrices, each with 100 rows and 50 columns: @@ -36,17 +36,13 @@ #' @examples #' data(dat_asymmetric) #' d <- dat_asymmetric -#' error <- function(fit) norm(fit$learner_estimate - d$Theta_target, "F") -#' # Equal penalties versus stronger borrowing on the shared U side. The values -#' # are illustrative and were not selected by cross-validation; see -#' # vignette("advanced-learner") for selecting them. -#' common <- learner(d$Y_source, d$Y_target, r = 3, lambda_1 = 10, -#' lambda_2 = 0.1, step_size = 0.003, -#' control = list(max_iter = 2000)) -#' separate <- learner(d$Y_source, d$Y_target, r = 3, lambda_1_row = 100, -#' lambda_1_col = 10, lambda_2 = 0.1, step_size = 0.003, -#' control = list(max_iter = 2000)) -#' c(common = error(common), separate = error(separate)) +#' # Demonstration penalties; use cv.learner() to select them from data. +#' fit <- learner(d$Y_source, d$Y_target, r = 3, lambda_1_row = 100, +#' lambda_1_col = 10, lambda_2 = 0.1, step_size = 0.003, +#' control = list(max_iter = 2000)) +#' dim(fit$learner_estimate) +#' fit$convergence_criterion +#' # See vignette("advanced-learner") for cross-validation and diagnostics. #' @seealso \code{\link{dat_highsim}}, \code{\link{dat_multisource}}, #' \code{\link{learner}}, \code{\link{cv.learner}} #' @keywords datasets diff --git a/R/input-validation.R b/R/input-validation.R index d942698..cae7835 100644 --- a/R/input-validation.R +++ b/R/input-validation.R @@ -60,17 +60,47 @@ validate_count <- function(value, name, lower = 1, upper = .Machine$integer.max) } } +# k and epsilon are accepted as other names for window and threshold. Only one +# name may be given for each setting. The value is stored under the main name, and +# the label tells the validators which name the user actually wrote. +use_control_alias <- function(control, name, alias) { + label <- paste0('control$', name) + alias_value <- control[[alias]] + if (is.null(alias_value)) return(list(control = control, label = label)) + if (!is.null(control[[name, exact = FALSE]])) { + stop('Give control$', name, ' or control$', alias, ', not both.', call. = FALSE) + } + control[[name]] <- alias_value + control[[alias]] <- NULL + list(control = control, label = paste0('control$', alias)) +} + prepare_control <- function(control, step_size) { if (!is.list(control)) stop('control must be a list.') if (!is.numeric(step_size) || length(step_size) != 1L || !is.finite(step_size) || step_size <= 0) { stop('step_size must be a finite positive number.') } + window_alias <- use_control_alias(control, 'window', 'k') + control <- window_alias$control + threshold_alias <- use_control_alias(control, 'threshold', 'epsilon') + control <- threshold_alias$control if (is.null(control$max_iter)) control$max_iter <- 100L - if (is.null(control$threshold)) control$threshold <- 0.001 + if (is.null(control$stopping_rule)) control$stopping_rule <- 'absolute' + if (!is.character(control$stopping_rule) || length(control$stopping_rule) != 1L || + is.na(control$stopping_rule) || !control$stopping_rule %in% c('absolute', 'relative')) { + stop("control$stopping_rule must be 'absolute' or 'relative'.") + } + if (is.null(control$window)) { + control$window <- if (control$stopping_rule == 'relative') 5L else 1L + } + validate_count(control$window, window_alias$label) + if (is.null(control$threshold)) { + control$threshold <- if (control$stopping_rule == 'relative') 1e-6 else 0.001 + } if (is.null(control$max_value)) control$max_value <- 10 validate_count(control$max_iter, 'control$max_iter') - validate_space_penalty(control$threshold, 'control$threshold') + validate_space_penalty(control$threshold, threshold_alias$label) if (!is.numeric(control$max_value) || length(control$max_value) != 1L || !is.finite(control$max_value) || control$max_value <= 0) { stop('control$max_value must be a finite positive number.') diff --git a/R/learner.R b/R/learner.R index 00fc67d..340583a 100644 --- a/R/learner.R +++ b/R/learner.R @@ -59,6 +59,11 @@ #' to the row, column, and balance grids, in that order. Divide by the number #' of observed target entries to obtain mean squared errors.} #' \item{r}{Rank used in the fits.} +#' \item{lambda_1_all, lambda_2_all, lambda_1_row_all, lambda_1_col_all}{The +#' candidate grids in their original order. Only grids used in the search are +#' returned. \code{\link{plot_cv}} reads these automatically.} +#' \item{n_observed}{Number of observed target entries, used to convert the +#' summed validation errors to mean squared errors when plotting.} #' #' @references #' McGrath, S., Zhu, C,. Guo, M. and Duan, R. (2024). \emph{LEARNER: A transfer learning method for low-rank matrix estimation}. arXiv preprint arXiv:2412.20605. @@ -151,7 +156,7 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, scores <- cv_learner_cpp(sources$matrices, Y_target, sources$weights, grid$row, grid$col, grid$balance, step_size, control$max_iter, control$threshold, n_cores, r, - control$max_value, index_set) + control$max_value, index_set, control$stopping_rule == "relative", control$window) if (!any(is.finite(scores))) stop('No candidate produced finite validation errors.') if (any(!is.finite(scores))) warning('Some candidates produced non-finite validation errors and were excluded.') scores[!is.finite(scores)] <- Inf @@ -160,11 +165,14 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, mse_all <- array(scores, dim = grid_dim) if (!separate) { return(list(lambda_1_min = grid$row[best], lambda_2_min = grid$balance[best], - mse_all = mse_all, r = r)) + mse_all = mse_all, r = r, lambda_1_all = lambda_1_all, + lambda_2_all = lambda_2_all, n_observed = n_indices)) } list(lambda_1_min = NA_real_, lambda_2_min = grid$balance[best], lambda_1_row_min = grid$row[best], lambda_1_col_min = grid$col[best], - mse_all = mse_all, r = r) + mse_all = mse_all, r = r, lambda_1_row_all = lambda_1_row_all, + lambda_1_col_all = lambda_1_col_all, lambda_2_all = lambda_2_all, + n_observed = n_indices) } #' Latent space-based transfer learning @@ -188,13 +196,26 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' \eqn{U} and \eqn{V} to have comparable scale. #' @param step_size Step size in the optimization algorithm. Smaller values may #' reduce oscillation but require more iterations. -#' @param control List of settings controlling when optimization stops: +#' @param control List of settings that decide when the fit stops. All are optional. #' \describe{ -#' \item{\code{max_iter}}{Maximum number of updates; default \code{100}.} -#' \item{\code{threshold}}{Stop when the absolute change between consecutive -#' objective values is smaller than this value; default \code{0.001}.} -#' \item{\code{max_value}}{Stop if the objective grows beyond this multiple of -#' its preceding value; default \code{10}.}} +#' \item{\code{max_iter}}{Maximum number of updates. Default \code{100}. This is +#' small: on the example data, a stopping rule was met only after several hundred +#' updates or more, so a larger value such as \code{1e4} is often needed. The fit +#' still stops early once the rule is met.} +#' \item{\code{stopping_rule}}{How a change in the objective is measured. +#' \code{"absolute"} (the default) uses \code{abs(L_t - L_{t-1})}. +#' \code{"relative"} uses \code{abs(L_t - L_{t-1}) / abs(L_{t-1})}, where +#' \code{L_t} is the objective after update \code{t}.} +#' \item{\code{window}}{Number of changes in a row that must be small before the +#' fit stops. Default \code{1} for \code{"absolute"} and \code{5} for \code{"relative"}. +#' Can also be written \code{k}. Giving both \code{window} and \code{k} is an error.} +#' \item{\code{threshold}}{A change is small if it is strictly less than this value. +#' Default \code{0.001} for \code{"absolute"} and \code{1e-6} for \code{"relative"}. +#' With \code{0}, no change is ever small, so the fit runs until \code{max_iter} +#' unless it stops with code 3. Can also be written \code{epsilon}. Giving both +#' \code{threshold} and \code{epsilon} is an error.} +#' \item{\code{max_value}}{Stop with code 3 if the objective becomes more than this +#' many times its previous value. Default \code{10}.}} #' @param lambda_1_row,lambda_1_col Separate source-space penalties for the row #' factor \eqn{U} and column factor \eqn{V}, respectively. Use these when the two #' sides should borrow different amounts of source information. Supply both @@ -236,7 +257,15 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' #' At each iteration, \eqn{U} and \eqn{V} are updated by a gradient #' descent step, starting from the truncated SVD of the source population data. -#' These updates are repeated until convergence. +#' These updates are repeated until the stopping rule in \code{control} is met or +#' \code{max_iter} updates have been made. +#' +#' The starting values are not recorded in \code{objective_values}, so the first +#' change is between the first and second recorded updates. A window of 5 therefore +#' needs at least 6 recorded updates, and if \code{max_iter} is less than +#' \code{window + 1} the stopping rule can never be met. With the relative rule, a +#' change from 0 to 0 counts as 0, and a change from 0 to anything else is never +#' small. #' #' \strong{Extensions:} #' @@ -267,7 +296,7 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' A list with the following elements: #' \item{learner_estimate}{matrix containing the LEARNER estimate of the target population knowledge graph.} #' \item{objective_values}{numeric vector containing the values of the objective function at each iteration.} -#' \item{convergence_criterion}{stopping code: \code{1}, the absolute objective-change threshold was met; \code{2}, the iteration limit was reached; \code{3}, excessive objective growth or non-finite objective/factors were detected.} +#' \item{convergence_criterion}{stopping code: \code{1}, the stopping rule in \code{control} was met; \code{2}, the iteration limit was reached; \code{3}, excessive objective growth or non-finite objective/factors were detected.} #' \item{r}{rank value used.} #' #' @references @@ -333,7 +362,8 @@ learner <- function(Y_source, Y_target, r, lambda_1 = NULL, lambda_2, step_size, result <- learner_cpp(sources$matrices, Y_target, sources$weights, r, lambda_1_row, lambda_1_col, lambda_2, step_size, - control$max_iter, control$threshold, control$max_value) + control$max_iter, control$threshold, control$max_value, + control$stopping_rule == "relative", control$window) return(result) } diff --git a/R/plotting.R b/R/plotting.R index 7bf3a82..ff964cd 100644 --- a/R/plotting.R +++ b/R/plotting.R @@ -88,20 +88,21 @@ plot_objective <- function(x, iterations = "all", main = NULL) { #' Plot the LEARNER cross-validation scores #' -#' Compare cross-validation errors across candidate penalties. Lighter cells -#' indicate lower error, and a black box marks the selected combination. +#' Compare cross-validation errors across candidate penalties. Pale blue cells +#' indicate lower error, darker blue cells indicate higher error, and a black +#' box marks the selected combination. #' #' @param x A result returned by \code{cv.learner()}. -#' @param lambda_1_all Candidate common penalties, in the same order as in -#' \code{cv.learner()}. Leave as \code{NULL} when separate penalties were used. -#' @param lambda_2_all Candidate balance penalties, in the same order as in -#' \code{cv.learner()}. -#' @param lambda_1_row_all,lambda_1_col_all Candidate row and column penalties, -#' in the same order as in \code{cv.learner()}. Both are needed when separate -#' penalties were used. -#' @param n_observed Number of observed target entries used in CV. If given, -#' the scores are shown as mean squared errors; otherwise as sums of squared -#' errors. Do not count missing entries. +#' @param lambda_1_all Candidate common penalties. Defaults to the grid stored +#' in \code{x}. Leave as \code{NULL} when separate penalties were used. +#' @param lambda_2_all Candidate balance penalties. Defaults to the grid stored +#' in \code{x}. +#' @param lambda_1_row_all,lambda_1_col_all Candidate row and column penalties. +#' Default to the grids stored in \code{x} when separate penalties were used. +#' @param n_observed Number of observed target entries. Defaults to the count +#' stored in \code{x}, so new CV results are shown as mean squared errors. +#' For older results without a stored count, supply it to obtain mean squared +#' errors; otherwise the plot uses sums of squared errors. #' @param lambda_2_index Which balance-penalty panels to draw when separate #' penalties were used, as positions in \code{lambda_2_all}. The default draws #' all of them. @@ -118,8 +119,10 @@ plot_objective <- function(x, iterations = "all", main = NULL) { #' boundary (\code{boundary}), and the ggplot pages (\code{plot} is the first #' page and \code{plots} holds all of them). #' -#' @details Supply the same penalty grids, in the same order, used in -#' \code{cv.learner()}. With a common space penalty, the axes show that penalty +#' @details Use \code{plot_cv(x)} for results from the current version of +#' \code{cv.learner()}. For older results without stored grids, supply the +#' original grids in their original order. Explicit arguments take precedence +#' over stored values. With a common space penalty, the axes show that penalty #' and the balance penalty. With separate penalties, the axes show row and #' column penalties, with one panel per balance penalty and shared colors. #' @@ -146,8 +149,7 @@ plot_objective <- function(x, iterations = "all", main = NULL) { #' lambda_1_col_all = col_grid, lambda_2_all = balance_grid, #' step_size = 0.0003, n_folds = 2, #' control = list(max_iter = 20)) -#' plot_cv(cv, lambda_1_row_all = row_grid, lambda_1_col_all = col_grid, -#' lambda_2_all = balance_grid, n_observed = sum(!is.na(target))) +#' plot_cv(cv) #' #' } #' @@ -217,7 +219,7 @@ plot_cv <- function(x, lambda_1_all = NULL, lambda_2_all = NULL, xlab <- bquote(log[10](.(xlab[[1]]))) ylab <- bquote(log[10](.(ylab[[1]]))) } - metric <- if (is.null(n_observed)) 'SSE' else 'MSE' + metric <- if (d$scale == 'Validation MSE') 'MSE' else 'SSE' selected_values <- vapply(seq_along(d$grids), function(i) d$grids[[i]][d$best_index[i]], numeric(1)) selected_names <- if (separate) c('row', 'col', 'balance') else c('lambda1', 'lambda2') subtitle <- paste0('Selected ', paste(paste0(selected_names, ' = ', @@ -250,7 +252,7 @@ plot_cv <- function(x, lambda_1_all = NULL, lambda_2_all = NULL, panel_labels <- stats::setNames(facet_labels, as.character(page)) plot <- ggplot2::ggplot(data, ggplot2::aes(x = x_index, y = y_index, fill = fill_value)) + ggplot2::geom_tile(color = 'white', linewidth = 0.35, width = 1, height = 1) + - ggplot2::scale_fill_viridis_c(option = 'magma', direction = -1, + ggplot2::scale_fill_gradient(low = '#EFF3FF', high = '#08519C', na.value = 'grey85', limits = limits, breaks = breaks, labels = key_labels, name = if (relative) paste0('CV ', metric, '\nabove minimum') else paste('CV', metric)) + ggplot2::scale_x_continuous(breaks = seq_along(labels_x), labels = labels_x, @@ -297,6 +299,12 @@ prepare_cv_plot <- function(x, lambda_1_all = NULL, lambda_2_all = NULL, if (!is.logical(log_labels) || length(log_labels) != 1L || is.na(log_labels)) { stop('log_labels must be TRUE or FALSE.') } + # Explicit arguments override metadata; older CV objects remain supported. + if (is.null(lambda_1_all)) lambda_1_all <- x[['lambda_1_all']] + if (is.null(lambda_2_all)) lambda_2_all <- x[['lambda_2_all']] + if (is.null(lambda_1_row_all)) lambda_1_row_all <- x[['lambda_1_row_all']] + if (is.null(lambda_1_col_all)) lambda_1_col_all <- x[['lambda_1_col_all']] + if (is.null(n_observed)) n_observed <- x[['n_observed']] scores <- x$mse_all finite <- is.finite(scores) if (!any(finite)) stop('No finite validation scores are available to plot.') diff --git a/README.Rmd b/README.Rmd index 4f8c385..e43c0f0 100644 --- a/README.Rmd +++ b/README.Rmd @@ -69,13 +69,12 @@ res_cv.learner$lambda_2_min ``` The heatmap shows the cross-validation error for each candidate combination. -Lighter cells indicate lower error; the black box marks the selected combination. +Pale blue cells indicate lower error and dark blue cells indicate higher error; +the black box marks the selected combination. This plot requires the optional package `ggplot2` (version 3.4.0 or later). ```{r cv-heatmap} -plot_cv(res_cv.learner, lambda_1_all = c(1, 10, 100), - lambda_2_all = c(1, 10, 100), - n_observed = sum(!is.na(dat_highsim$Y_target))) +plot_cv(res_cv.learner) ``` Next, we apply the `learner` function with these values of `lambda_1` and `lambda_2`: diff --git a/README.md b/README.md index e9ef4cf..7ddd5bd 100644 --- a/README.md +++ b/README.md @@ -86,14 +86,13 @@ res_cv.learner$lambda_2_min ``` The heatmap shows the cross-validation error for each candidate -combination. Lighter cells indicate lower error; the black box marks the -selected combination. This plot requires the optional package `ggplot2` -(version 3.4.0 or later). +combination. Pale blue cells indicate lower error and dark blue cells +indicate higher error; the black box marks the selected combination. +This plot requires the optional package `ggplot2` (version 3.4.0 or +later). ``` r -plot_cv(res_cv.learner, lambda_1_all = c(1, 10, 100), - lambda_2_all = c(1, 10, 100), - n_observed = sum(!is.na(dat_highsim$Y_target))) +plot_cv(res_cv.learner) ``` diff --git a/README_files/figure-gfm/cv-heatmap-1.png b/README_files/figure-gfm/cv-heatmap-1.png index 45931dc..f7a6eb2 100644 Binary files a/README_files/figure-gfm/cv-heatmap-1.png and b/README_files/figure-gfm/cv-heatmap-1.png differ diff --git a/inst/examples/advanced-learner.R b/inst/examples/advanced-learner.R new file mode 100644 index 0000000..dcd1330 --- /dev/null +++ b/inst/examples/advanced-learner.R @@ -0,0 +1,176 @@ +# Run from top to bottom with Source with Echo in RStudio, or: +# source("advanced-learner.R", echo = TRUE, max.deparse.length = Inf) +# Needs the development version of learner. Install it with: +# devtools::install_github("stmcg/learner") +# This compiles C++ code, so you need a compiler (Xcode Command Line Tools on +# macOS, Rtools on Windows). Restart R after installing. +# Resolve the first error before continuing. + +# load-package +install_help <- paste( + "Install the development version of learner with", + "devtools::install_github(\"stmcg/learner\"), then restart R and rerun", + "from the top.") +if (!requireNamespace("learner", quietly = TRUE)) { + stop(install_help, + call. = FALSE) +} +required_data <- c("dat_asymmetric", "dat_multisource") +available_data <- utils::data(package = "learner")$results[, "Item"] +missing_data <- setdiff(required_data, available_data) +if (length(missing_data)) { + stop(paste0("Your installed learner package is missing: ", + paste(missing_data, collapse = ", "), + ". ", install_help), call. = FALSE) +} +library(learner) +data("dat_asymmetric", "dat_multisource", package = "learner") + +if (!requireNamespace("ggplot2", quietly = TRUE) || + utils::packageVersion("ggplot2") < "3.4.0") { + stop('Install ggplot2 >= 3.4.0 with install.packages("ggplot2"), then rerun.', + call. = FALSE) +} +# Check behavior rather than relying on a development version number. +compatible <- local({ + y <- diag(c(4, 2, 1)) + target <- diag(c(4, 0, 0)) + cv <- cv.learner(y, target, r = 1, lambda_1_all = 1, lambda_2_all = 1, + step_size = 0.001, n_folds = 2, control = list(max_iter = 2)) + all(c("lambda_1_all", "lambda_2_all", "n_observed") %in% names(cv)) +}) +if (!compatible) { + stop(paste("This learner installation lacks the CV metadata used here.", + install_help), call. = FALSE) +} + + +# asymmetric-data +asym <- dat_asymmetric + +# asymmetric-cv +asym_space_grid <- c(0, 10, 100) +asym_balance_grid <- c(0.001, 0.01, 0.1, 1) +set.seed(815) +cv_separate <- cv.learner( + asym$Y_source, asym$Y_target, r = 3, + lambda_1_row_all = asym_space_grid, + lambda_1_col_all = asym_space_grid, + lambda_2_all = asym_balance_grid, + n_folds = 3, step_size = 0.003, control = list(max_iter = 2000)) +c(U = cv_separate$lambda_1_row_min, + V = cv_separate$lambda_1_col_min, + balance = cv_separate$lambda_2_min) + +# asymmetric-refit +fit_separate <- learner( + asym$Y_source, asym$Y_target, r = cv_separate$r, + lambda_1_row = cv_separate$lambda_1_row_min, + lambda_1_col = cv_separate$lambda_1_col_min, + lambda_2 = cv_separate$lambda_2_min, + step_size = 0.003, control = list(max_iter = 2000)) +dim(fit_separate$learner_estimate) +fit_separate$convergence_criterion + +# asymmetric-cv-plot +plot_cv(cv_separate) + +# multiple-data +sources <- dat_multisource$Y_source +target <- dat_multisource$Y_target +weights <- c(0.7, 0.3) + +# multiple-direct +fit_direct <- dlearner(sources, target, r = 3, source_weights = weights) +dim(fit_direct$dlearner_estimate) + +# multiple-cv +set.seed(815) +cv_multi <- cv.learner( + sources, target, r = 3, source_weights = weights, + lambda_1_all = c(0, 1, 10), lambda_2_all = c(0.1, 1), + n_folds = 3, step_size = 0.0003, control = list(max_iter = 2000)) +c(space = cv_multi$lambda_1_min, balance = cv_multi$lambda_2_min) + +# multiple-cv-plot +plot_cv(cv_multi) + +# multiple-refit +fit_multi <- learner( + sources, target, r = cv_multi$r, source_weights = weights, + lambda_1 = cv_multi$lambda_1_min, lambda_2 = cv_multi$lambda_2_min, + step_size = 0.0003, control = list(max_iter = 2000)) +dim(fit_multi$learner_estimate) +fit_multi$convergence_criterion + +# grid-boundaries +needed <- c("asym", "asym_space_grid", "asym_balance_grid", + "cv_separate", "fit_separate") +if (!all(vapply(needed, exists, logical(1), inherits = TRUE))) { + stop("Run Section 2 through the final refit before starting Section 4.", + call. = FALSE) +} +selected <- c(U = cv_separate$lambda_1_row_min, + V = cv_separate$lambda_1_col_min, + balance = cv_separate$lambda_2_min) +grids <- list(cv_separate$lambda_1_row_all, cv_separate$lambda_1_col_all, + cv_separate$lambda_2_all) +data.frame(parameter = names(selected), selected = unname(selected), + lower = vapply(grids, min, numeric(1)), + upper = vapply(grids, max, numeric(1)), + on_boundary = vapply(seq_along(grids), function(i) { + selected[i] %in% range(grids[[i]]) + }, logical(1))) + +# asymmetric-objective +plot_objective(fit_separate, iterations = "near_optimum") + +# sensitivity-checks +fit_summary <- function(cv, fit, step, budget) { + data.frame(step_size = step, max_iter = budget, + U = cv$lambda_1_row_min, V = cv$lambda_1_col_min, + balance = cv$lambda_2_min, + min_cv_mse = min(cv$mse_all) / cv$n_observed, + updates = length(fit$objective_values), + stop_code = fit$convergence_criterion) +} +check_setting <- function(step, budget) { + set.seed(815) + cv <- cv.learner( + asym$Y_source, asym$Y_target, r = 3, + lambda_1_row_all = asym_space_grid, + lambda_1_col_all = asym_space_grid, lambda_2_all = asym_balance_grid, + n_folds = 3, step_size = step, control = list(max_iter = budget)) + fit <- learner( + asym$Y_source, asym$Y_target, r = cv$r, + lambda_1_row = cv$lambda_1_row_min, lambda_1_col = cv$lambda_1_col_min, + lambda_2 = cv$lambda_2_min, step_size = step, + control = list(max_iter = budget)) + fit_summary(cv, fit, step, budget) +} +sensitivity <- rbind( + fit_summary(cv_separate, fit_separate, 0.003, 2000), + check_setting(0.003, 4000), + check_setting(0.0015, 4000)) +print(sensitivity, row.names = FALSE) + +# inner-cv-stopping +set.seed(815) +indices <- sample(which(!is.na(asym$Y_target))) +n <- length(indices) +folds <- lapply(1:3, function(k) { + indices[seq.int(floor((k - 1) * n / 3) + 1, floor(k * n / 3))] +}) +inner_fits <- do.call(rbind, lapply(1:3, function(k) { + training <- asym$Y_target + training[folds[[k]]] <- NA + fit <- learner( + asym$Y_source, training, r = cv_separate$r, + lambda_1_row = cv_separate$lambda_1_row_min, + lambda_1_col = cv_separate$lambda_1_col_min, + lambda_2 = cv_separate$lambda_2_min, + step_size = 0.003, control = list(max_iter = 2000)) + data.frame(fold = k, updates = length(fit$objective_values), + stop_code = fit$convergence_criterion) +})) +print(inner_fits, row.names = FALSE) diff --git a/inst/examples/multiple-sources.R b/inst/examples/multiple-sources.R index fd72a87..936f9d3 100644 --- a/inst/examples/multiple-sources.R +++ b/inst/examples/multiple-sources.R @@ -32,7 +32,7 @@ fit <- learner::learner( ) print(fit$learner_estimate[1:5, 1:5]) print(fit$convergence_criterion) -# 1: objective-change threshold; 2: iteration limit; 3: excessive growth/breakdown. +# 1: stopping rule met; 2: iteration limit; 3: excessive growth or non-finite values. # This example demonstrates the workflow, not scientific performance or convergence. # D-LEARNER also accepts multiple sources with the same weights. diff --git a/inst/examples/plot-diagnostics.R b/inst/examples/plot-diagnostics.R index 9dd32c1..765d079 100644 --- a/inst/examples/plot-diagnostics.R +++ b/inst/examples/plot-diagnostics.R @@ -19,9 +19,7 @@ cv <- learner::cv.learner( lambda_1_row_all = row_grid, lambda_1_col_all = col_grid, lambda_2_all = balance_grid, step_size = 0.0003, n_folds = 3, control = list(max_iter = 500)) -learner::plot_cv( - cv, lambda_1_row_all = row_grid, lambda_1_col_all = col_grid, - lambda_2_all = balance_grid, n_observed = sum(!is.na(target))) +learner::plot_cv(cv) fit <- learner::learner( sources, target, r = cv$r, source_weights = weights, @@ -37,7 +35,6 @@ common_cv <- learner::cv.learner( sources, target, r = 3, source_weights = weights, lambda_1_all = common_grid, lambda_2_all = balance_grid, step_size = 0.0003, n_folds = 3, control = list(max_iter = 500)) -learner::plot_cv(common_cv, lambda_1_all = common_grid, - lambda_2_all = balance_grid, n_observed = sum(!is.na(target))) +learner::plot_cv(common_cv) # Inspect stopping codes as well as curves. Plotting does not prove convergence. diff --git a/man/cv.learner.Rd b/man/cv.learner.Rd index 609ca27..dcbc4d8 100644 --- a/man/cv.learner.Rd +++ b/man/cv.learner.Rd @@ -63,6 +63,11 @@ For common penalties, rows correspond to \code{lambda_1_all} and columns to to the row, column, and balance grids, in that order. Divide by the number of observed target entries to obtain mean squared errors.} \item{r}{Rank used in the fits.} +\item{lambda_1_all, lambda_2_all, lambda_1_row_all, lambda_1_col_all}{The +candidate grids in their original order. Only grids used in the search are +returned. \code{\link{plot_cv}} reads these automatically.} +\item{n_observed}{Number of observed target entries, used to convert the +summed validation errors to mean squared errors when plotting.} } \description{ Performs k-fold cross-validation to select the source-space and balance diff --git a/man/dat_asymmetric.Rd b/man/dat_asymmetric.Rd index fea468b..b21c4f0 100644 --- a/man/dat_asymmetric.Rd +++ b/man/dat_asymmetric.Rd @@ -18,8 +18,8 @@ dat_asymmetric } \description{ One source and one target with the same true U-space but different true -V-spaces. This example illustrates why the two space penalties in LEARNER -can be selected separately. +V-spaces. This example illustrates how to fit LEARNER +with separate penalties on the two spaces. } \details{ The target signal is the rank-3 truncated SVD of a standard normal @@ -43,17 +43,13 @@ in the source repository. \examples{ data(dat_asymmetric) d <- dat_asymmetric -error <- function(fit) norm(fit$learner_estimate - d$Theta_target, "F") -# Equal penalties versus stronger borrowing on the shared U side. The values -# are illustrative and were not selected by cross-validation; see -# vignette("advanced-learner") for selecting them. -common <- learner(d$Y_source, d$Y_target, r = 3, lambda_1 = 10, - lambda_2 = 0.1, step_size = 0.003, - control = list(max_iter = 2000)) -separate <- learner(d$Y_source, d$Y_target, r = 3, lambda_1_row = 100, - lambda_1_col = 10, lambda_2 = 0.1, step_size = 0.003, - control = list(max_iter = 2000)) -c(common = error(common), separate = error(separate)) +# Demonstration penalties; use cv.learner() to select them from data. +fit <- learner(d$Y_source, d$Y_target, r = 3, lambda_1_row = 100, + lambda_1_col = 10, lambda_2 = 0.1, step_size = 0.003, + control = list(max_iter = 2000)) +dim(fit$learner_estimate) +fit$convergence_criterion +# See vignette("advanced-learner") for cross-validation and diagnostics. } \references{ McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). \emph{LEARNER: A transfer learning method for low-rank matrix estimation}. Statistics in Medicine, 45(15-17), e70669. \doi{10.1002/sim.70669}. diff --git a/man/learner.Rd b/man/learner.Rd index a56809b..e761243 100644 --- a/man/learner.Rd +++ b/man/learner.Rd @@ -38,13 +38,26 @@ Use \code{\link{cv.learner}} to select penalty values.} \item{step_size}{Step size in the optimization algorithm. Smaller values may reduce oscillation but require more iterations.} -\item{control}{List of settings controlling when optimization stops: +\item{control}{List of settings that decide when the fit stops. All are optional. \describe{ -\item{\code{max_iter}}{Maximum number of updates; default \code{100}.} -\item{\code{threshold}}{Stop when the absolute change between consecutive -objective values is smaller than this value; default \code{0.001}.} -\item{\code{max_value}}{Stop if the objective grows beyond this multiple of -its preceding value; default \code{10}.}}} +\item{\code{max_iter}}{Maximum number of updates. Default \code{100}. This is +small: on the example data, a stopping rule was met only after several hundred +updates or more, so a larger value such as \code{1e4} is often needed. The fit +still stops early once the rule is met.} +\item{\code{stopping_rule}}{How a change in the objective is measured. +\code{"absolute"} (the default) uses \code{abs(L_t - L_{t-1})}. +\code{"relative"} uses \code{abs(L_t - L_{t-1}) / abs(L_{t-1})}, where +\code{L_t} is the objective after update \code{t}.} +\item{\code{window}}{Number of changes in a row that must be small before the +fit stops. Default \code{1} for \code{"absolute"} and \code{5} for \code{"relative"}. +Can also be written \code{k}. Giving both \code{window} and \code{k} is an error.} +\item{\code{threshold}}{A change is small if it is strictly less than this value. +Default \code{0.001} for \code{"absolute"} and \code{1e-6} for \code{"relative"}. +With \code{0}, no change is ever small, so the fit runs until \code{max_iter} +unless it stops with code 3. Can also be written \code{epsilon}. Giving both +\code{threshold} and \code{epsilon} is an error.} +\item{\code{max_value}}{Stop with code 3 if the objective becomes more than this +many times its previous value. Default \code{10}.}}} \item{lambda_1_row, lambda_1_col}{Separate source-space penalties for the row factor \eqn{U} and column factor \eqn{V}, respectively. Use these when the two @@ -58,7 +71,7 @@ instead of \code{lambda_1}; equal values reproduce the common penalty.} A list with the following elements: \item{learner_estimate}{matrix containing the LEARNER estimate of the target population knowledge graph.} \item{objective_values}{numeric vector containing the values of the objective function at each iteration.} -\item{convergence_criterion}{stopping code: \code{1}, the absolute objective-change threshold was met; \code{2}, the iteration limit was reached; \code{3}, excessive objective growth or non-finite objective/factors were detected.} +\item{convergence_criterion}{stopping code: \code{1}, the stopping rule in \code{control} was met; \code{2}, the iteration limit was reached; \code{3}, excessive objective growth or non-finite objective/factors were detected.} \item{r}{rank value used.} } \description{ @@ -100,7 +113,15 @@ terms are unchanged. The same adjustment applies to the extensions below. At each iteration, \eqn{U} and \eqn{V} are updated by a gradient descent step, starting from the truncated SVD of the source population data. -These updates are repeated until convergence. +These updates are repeated until the stopping rule in \code{control} is met or +\code{max_iter} updates have been made. + +The starting values are not recorded in \code{objective_values}, so the first +change is between the first and second recorded updates. A window of 5 therefore +needs at least 6 recorded updates, and if \code{max_iter} is less than +\code{window + 1} the stopping rule can never be met. With the relative rule, a +change from 0 to 0 counts as 0, and a change from 0 to anything else is never +small. \strong{Extensions:} diff --git a/man/plot_cv.Rd b/man/plot_cv.Rd index 70e9d20..03f76b4 100644 --- a/man/plot_cv.Rd +++ b/man/plot_cv.Rd @@ -21,19 +21,19 @@ plot_cv( \arguments{ \item{x}{A result returned by \code{cv.learner()}.} -\item{lambda_1_all}{Candidate common penalties, in the same order as in -\code{cv.learner()}. Leave as \code{NULL} when separate penalties were used.} +\item{lambda_1_all}{Candidate common penalties. Defaults to the grid stored +in \code{x}. Leave as \code{NULL} when separate penalties were used.} -\item{lambda_2_all}{Candidate balance penalties, in the same order as in -\code{cv.learner()}.} +\item{lambda_2_all}{Candidate balance penalties. Defaults to the grid stored +in \code{x}.} -\item{lambda_1_row_all, lambda_1_col_all}{Candidate row and column penalties, -in the same order as in \code{cv.learner()}. Both are needed when separate -penalties were used.} +\item{lambda_1_row_all, lambda_1_col_all}{Candidate row and column penalties. +Default to the grids stored in \code{x} when separate penalties were used.} -\item{n_observed}{Number of observed target entries used in CV. If given, -the scores are shown as mean squared errors; otherwise as sums of squared -errors. Do not count missing entries.} +\item{n_observed}{Number of observed target entries. Defaults to the count +stored in \code{x}, so new CV results are shown as mean squared errors. +For older results without a stored count, supply it to obtain mean squared +errors; otherwise the plot uses sums of squared errors.} \item{lambda_2_index}{Which balance-penalty panels to draw when separate penalties were used, as positions in \code{lambda_2_all}. The default draws @@ -57,12 +57,15 @@ boundary (\code{boundary}), and the ggplot pages (\code{plot} is the first page and \code{plots} holds all of them). } \description{ -Compare cross-validation errors across candidate penalties. Lighter cells -indicate lower error, and a black box marks the selected combination. +Compare cross-validation errors across candidate penalties. Pale blue cells +indicate lower error, darker blue cells indicate higher error, and a black +box marks the selected combination. } \details{ -Supply the same penalty grids, in the same order, used in -\code{cv.learner()}. With a common space penalty, the axes show that penalty +Use \code{plot_cv(x)} for results from the current version of +\code{cv.learner()}. For older results without stored grids, supply the +original grids in their original order. Explicit arguments take precedence +over stored values. With a common space penalty, the axes show that penalty and the balance penalty. With separate penalties, the axes show row and column penalties, with one panel per balance penalty and shared colors. @@ -89,8 +92,7 @@ cv <- cv.learner(dat_highsim$Y_source[1:12, 1:8], target, lambda_1_col_all = col_grid, lambda_2_all = balance_grid, step_size = 0.0003, n_folds = 2, control = list(max_iter = 20)) -plot_cv(cv, lambda_1_row_all = row_grid, lambda_1_col_all = col_grid, - lambda_2_all = balance_grid, n_observed = sum(!is.na(target))) +plot_cv(cv) } diff --git a/src/RcppExports.cpp b/src/RcppExports.cpp index 0574cb1..d7465c6 100644 --- a/src/RcppExports.cpp +++ b/src/RcppExports.cpp @@ -12,8 +12,8 @@ Rcpp::Rostream& Rcpp::Rcerr = Rcpp::Rcpp_cerr_get(); #endif // learner_cpp -List learner_cpp(const Rcpp::List& Y_source, const Eigen::MatrixXd& Y_target, const std::vector& source_weights, int r, double lambda1_row, double lambda1_col, double lambda2, double step_size, int max_iter, double threshold, double max_value); -RcppExport SEXP _learner_learner_cpp(SEXP Y_sourceSEXP, SEXP Y_targetSEXP, SEXP source_weightsSEXP, SEXP rSEXP, SEXP lambda1_rowSEXP, SEXP lambda1_colSEXP, SEXP lambda2SEXP, SEXP step_sizeSEXP, SEXP max_iterSEXP, SEXP thresholdSEXP, SEXP max_valueSEXP) { +List learner_cpp(const Rcpp::List& Y_source, const Eigen::MatrixXd& Y_target, const std::vector& source_weights, int r, double lambda1_row, double lambda1_col, double lambda2, double step_size, int max_iter, double threshold, double max_value, bool relative, int window); +RcppExport SEXP _learner_learner_cpp(SEXP Y_sourceSEXP, SEXP Y_targetSEXP, SEXP source_weightsSEXP, SEXP rSEXP, SEXP lambda1_rowSEXP, SEXP lambda1_colSEXP, SEXP lambda2SEXP, SEXP step_sizeSEXP, SEXP max_iterSEXP, SEXP thresholdSEXP, SEXP max_valueSEXP, SEXP relativeSEXP, SEXP windowSEXP) { BEGIN_RCPP Rcpp::RObject rcpp_result_gen; Rcpp::RNGScope rcpp_rngScope_gen; @@ -28,13 +28,15 @@ BEGIN_RCPP Rcpp::traits::input_parameter< int >::type max_iter(max_iterSEXP); Rcpp::traits::input_parameter< double >::type threshold(thresholdSEXP); Rcpp::traits::input_parameter< double >::type max_value(max_valueSEXP); - rcpp_result_gen = Rcpp::wrap(learner_cpp(Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value)); + Rcpp::traits::input_parameter< bool >::type relative(relativeSEXP); + Rcpp::traits::input_parameter< int >::type window(windowSEXP); + rcpp_result_gen = Rcpp::wrap(learner_cpp(Y_source, Y_target, source_weights, r, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value, relative, window)); return rcpp_result_gen; END_RCPP } // cv_learner_cpp -std::vector cv_learner_cpp(const Rcpp::List& Y_source, const Eigen::MatrixXd& Y_target, const std::vector& source_weights, const std::vector& row_grid, const std::vector& col_grid, const std::vector& balance_grid, double step_size, int max_iter, double threshold, int n_cores, int r, double max_value, const std::vector>& index_set); -RcppExport SEXP _learner_cv_learner_cpp(SEXP Y_sourceSEXP, SEXP Y_targetSEXP, SEXP source_weightsSEXP, SEXP row_gridSEXP, SEXP col_gridSEXP, SEXP balance_gridSEXP, SEXP step_sizeSEXP, SEXP max_iterSEXP, SEXP thresholdSEXP, SEXP n_coresSEXP, SEXP rSEXP, SEXP max_valueSEXP, SEXP index_setSEXP) { +std::vector cv_learner_cpp(const Rcpp::List& Y_source, const Eigen::MatrixXd& Y_target, const std::vector& source_weights, const std::vector& row_grid, const std::vector& col_grid, const std::vector& balance_grid, double step_size, int max_iter, double threshold, int n_cores, int r, double max_value, const std::vector>& index_set, bool relative, int window); +RcppExport SEXP _learner_cv_learner_cpp(SEXP Y_sourceSEXP, SEXP Y_targetSEXP, SEXP source_weightsSEXP, SEXP row_gridSEXP, SEXP col_gridSEXP, SEXP balance_gridSEXP, SEXP step_sizeSEXP, SEXP max_iterSEXP, SEXP thresholdSEXP, SEXP n_coresSEXP, SEXP rSEXP, SEXP max_valueSEXP, SEXP index_setSEXP, SEXP relativeSEXP, SEXP windowSEXP) { BEGIN_RCPP Rcpp::RObject rcpp_result_gen; Rcpp::RNGScope rcpp_rngScope_gen; @@ -51,7 +53,9 @@ BEGIN_RCPP Rcpp::traits::input_parameter< int >::type r(rSEXP); Rcpp::traits::input_parameter< double >::type max_value(max_valueSEXP); Rcpp::traits::input_parameter< const std::vector>& >::type index_set(index_setSEXP); - rcpp_result_gen = Rcpp::wrap(cv_learner_cpp(Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set)); + Rcpp::traits::input_parameter< bool >::type relative(relativeSEXP); + Rcpp::traits::input_parameter< int >::type window(windowSEXP); + rcpp_result_gen = Rcpp::wrap(cv_learner_cpp(Y_source, Y_target, source_weights, row_grid, col_grid, balance_grid, step_size, max_iter, threshold, n_cores, r, max_value, index_set, relative, window)); return rcpp_result_gen; END_RCPP } @@ -67,8 +71,8 @@ END_RCPP } static const R_CallMethodDef CallEntries[] = { - {"_learner_learner_cpp", (DL_FUNC) &_learner_learner_cpp, 11}, - {"_learner_cv_learner_cpp", (DL_FUNC) &_learner_cv_learner_cpp, 13}, + {"_learner_learner_cpp", (DL_FUNC) &_learner_learner_cpp, 13}, + {"_learner_cv_learner_cpp", (DL_FUNC) &_learner_cv_learner_cpp, 15}, {"_learner_omp_max_threads", (DL_FUNC) &_learner_omp_max_threads, 0}, {NULL, NULL, 0} }; diff --git a/src/kernels.cpp b/src/kernels.cpp index f6d09b0..9779dca 100644 --- a/src/kernels.cpp +++ b/src/kernels.cpp @@ -59,7 +59,7 @@ FitResult learner_worker(const SourceSpaces &spaces, const Eigen::MatrixXd &Y_target, double lambda1_row, double lambda1_col, double lambda2, double step_size, int max_iter, double threshold, - double max_value) { + double max_value, bool relative, int window) { Eigen::MatrixXd U = spaces.initial_u; Eigen::MatrixXd V = spaces.initial_v; double perc_nonmissing = 1.0 - (static_cast((Y_target.array().isNaN()).count()) / Y_target.size()); @@ -86,6 +86,7 @@ FitResult learner_worker(const SourceSpaces &spaces, int convergence_criterion = 2; std::vector obj_values; obj_values.reserve(max_iter); + int small_changes = 0; for (int iter = 0; iter < max_iter; ++iter) { Eigen::MatrixXd U_tilde = U.transpose() * U; Eigen::MatrixXd V_tilde = V.transpose() * V; @@ -141,11 +142,27 @@ FitResult learner_worker(const SourceSpaces &spaces, V_best = V; } - // Checking for convergence conditions - if (iter > 0 && std::abs(obj - obj_values[iter - 1]) < threshold) { - convergence_criterion = 1; + // Relative convergence must not mask excessive objective growth. + if (relative && iter > 0 && obj > max_value * obj_init) { + convergence_criterion = 3; break; } + // Checking for convergence conditions + if (iter > 0) { + const double previous = obj_values[iter - 1]; + double change = std::abs(obj - previous); + if (relative) { + // A zero-to-zero change is zero; leaving zero cannot satisfy tolerance. + change = previous == 0.0 ? (obj == 0.0 ? 0.0 : + std::numeric_limits::infinity()) : change / std::abs(previous); + } + small_changes = change < threshold ? small_changes + 1 : 0; + // Initialization is excluded: K changes require at least K+1 records. + if (small_changes >= window) { + convergence_criterion = 1; + break; + } + } if (iter > 0 && obj > max_value * obj_init) { convergence_criterion = 3; break; @@ -160,10 +177,10 @@ FitResult learner_worker(const SourceSpaces &spaces, List learner_cpp(const Rcpp::List &Y_source, const Eigen::MatrixXd &Y_target, const std::vector &source_weights, int r, double lambda1_row, double lambda1_col, double lambda2, - double step_size, int max_iter, double threshold, double max_value) { + double step_size, int max_iter, double threshold, double max_value, bool relative, int window) { SourceSpaces spaces = prepare_spaces(Y_source, source_weights, r); FitResult out = learner_worker(spaces, Y_target, lambda1_row, lambda1_col, - lambda2, step_size, max_iter, threshold, max_value); + lambda2, step_size, max_iter, threshold, max_value, relative, window); return List::create(Named("learner_estimate") = out.estimate, Named("objective_values") = out.objective, Named("convergence_criterion") = out.criterion, @@ -180,7 +197,7 @@ std::vector cv_learner_cpp(const Rcpp::List &Y_source, const std::vector &balance_grid, double step_size, int max_iter, double threshold, int n_cores, int r, double max_value, - const std::vector> &index_set) { + const std::vector> &index_set, bool relative, int window) { SourceSpaces spaces = prepare_spaces(Y_source, source_weights, r); int p = Y_target.rows(); int n_grid = row_grid.size(); @@ -193,7 +210,7 @@ std::vector cv_learner_cpp(const Rcpp::List &Y_source, Eigen::MatrixXd training = Y_target; for (int idx : fold) training(idx % p, idx / p) = std::numeric_limits::quiet_NaN(); FitResult fit = learner_worker(spaces, training, row_grid[g], col_grid[g], - balance_grid[g], step_size, max_iter, threshold, max_value); + balance_grid[g], step_size, max_iter, threshold, max_value, relative, window); if (!fit.estimate.allFinite() || !std::all_of(fit.objective.begin(), fit.objective.end(), [](double x) { return std::isfinite(x); })) { diff --git a/tests/testthat/helper-stopping.R b/tests/testthat/helper-stopping.R new file mode 100644 index 0000000..3ec7b9c --- /dev/null +++ b/tests/testthat/helper-stopping.R @@ -0,0 +1,10 @@ +# Analytic examples distinguish a stopping code from optimization accuracy. +# The source has distinct singular values 4, 2, 1; its rank-one approximation +# and initial target estimate are exactly diag(4, 0, 0) in a 4-by-3 matrix. +stopping_example <- function() { + source <- matrix(0, 4, 3) + source[cbind(1:3, 1:3)] <- c(4, 2, 1) + target <- matrix(0, 4, 3) + target[1, 1] <- 4 + list(source = source, target = target) +} diff --git a/tests/testthat/test-cv-multisource.R b/tests/testthat/test-cv-multisource.R index 1351de5..5b77b0e 100644 --- a/tests/testthat/test-cv-multisource.R +++ b/tests/testthat/test-cv-multisource.R @@ -63,7 +63,8 @@ test_that("tied CV is the diagonal of the independent grid", { } tied <- fit(lambda_1_all = c(1, 3)) separate <- fit(lambda_1_row_all = c(1, 3), lambda_1_col_all = c(1, 3)) - expect_named(tied, c('lambda_1_min', 'lambda_2_min', 'mse_all', 'r')) + expect_named(tied, c('lambda_1_min', 'lambda_2_min', 'mse_all', 'r', + 'lambda_1_all', 'lambda_2_all', 'n_observed')) expect_equal(dim(tied$mse_all), c(2L, 2L)) for (i in 1:2) expect_equal(tied$mse_all[i, ], separate$mse_all[i, i, ], tolerance = 1e-10) single <- fit(lambda_1_row_all = 1, lambda_1_col_all = 3) diff --git a/tests/testthat/test-cv-plot-metadata.R b/tests/testthat/test-cv-plot-metadata.R new file mode 100644 index 0000000..68e0b65 --- /dev/null +++ b/tests/testthat/test-cv-plot-metadata.R @@ -0,0 +1,56 @@ +test_that('CV stores the exact grids and observed count in both modes', { + target <- dat_highsim$Y_target[1:8, 1:6] + source <- dat_highsim$Y_source[1:8, 1:6] + target[c(2, 9)] <- NA_real_ + for (separate in c(FALSE, TRUE)) { + grids <- if (separate) { + list(lambda_1_row_all = c(3, 0), lambda_1_col_all = c(2, 1)) + } else list(lambda_1_all = c(3, 0)) + set.seed(17) + cv <- do.call(cv.learner, c(list(Y_source = source, Y_target = target, + r = 2, lambda_2_all = c(.1, .01), step_size = .0003, + n_folds = 2, control = list(max_iter = 5)), grids)) + expect_equal(cv$n_observed, 46) + expect_equal(cv$lambda_2_all, c(.1, .01)) + for (name in names(grids)) expect_identical(cv[[name]], grids[[name]]) + auto <- prepare_cv_plot(cv) + expect_equal(auto$scores, cv$mse_all / 46) + expect_identical(auto$scale, 'Validation MSE') + old <- cv[setdiff(names(cv), c(names(grids), 'lambda_2_all', 'n_observed'))] + manual <- do.call(prepare_cv_plot, c(list(x = old, lambda_2_all = c(.1, .01), + n_observed = 46), grids)) + expect_equal(auto, manual) + raw <- do.call(prepare_cv_plot, c(list(x = old, lambda_2_all = c(.1, .01)), grids)) + expect_equal(raw$scores, cv$mse_all) + expect_identical(raw$scale, 'Validation SSE') + } +}) + +test_that('explicit plot inputs override metadata and stored inputs are validated', { + x <- list(mse_all = matrix(c(4, 8, 12, 16), 2), lambda_1_min = 1, + lambda_2_min = .1, lambda_1_all = c(1, 2), + lambda_2_all = c(.1, 1), n_observed = 4) + expect_equal(prepare_cv_plot(x, n_observed = 2)$minimum, 2) + x$lambda_1_all <- c(1, 2, 3) + expect_error(prepare_cv_plot(x), 'dimension') + expect_equal(prepare_cv_plot(x, lambda_1_all = c(1, 2))$minimum, 1) + x$lambda_1_all <- c(1, 2) + x$n_observed <- 0 + expect_error(prepare_cv_plot(x), 'n_observed') + expect_equal(prepare_cv_plot(x, n_observed = 4)$minimum, 1) +}) + +test_that('automatic MSE scaling is reflected in heatmap labels', { + skip_if_not_installed('ggplot2', minimum_version = '3.4.0') + path <- plot_device() + on.exit({grDevices::dev.off(); unlink(path)}, add = TRUE) + x <- list(mse_all = matrix(c(4, 4.1, 4.2, 4.3), 2), lambda_1_min = 1, + lambda_2_min = .1, lambda_1_all = c(1, 2), + lambda_2_all = c(.1, 1), n_observed = 4) + z <- plot_cv(x) + expect_equal(z$minimum, 1) + expect_match(z$plot$labels$subtitle, 'Minimum MSE = +1') + expect_match(z$plot$labels$caption, 'MSE range', fixed = TRUE) + expect_match(plot_cv(x, n_observed = 2)$plot$labels$subtitle, + 'Minimum MSE = +2') +}) diff --git a/tests/testthat/test-reference-regression.R b/tests/testthat/test-reference-regression.R index bbc28cb..21b140b 100644 --- a/tests/testthat/test-reference-regression.R +++ b/tests/testthat/test-reference-regression.R @@ -38,8 +38,10 @@ for (case_name in c('complete', 'missing')) { case <- fixture$cv[[case_name]] actual <- with_reference_rng(case$seed, fixture$provenance$rng_kind, do.call(cv.learner, case$args)) + # Compare historical numerical fields; new plotting metadata is tested separately. # Includes all eight scores and the selected penalties, not only dimensions. - expect_equal(actual, case$expected, tolerance = fixture$provenance$tolerance) + expect_equal(actual[names(case$expected)], case$expected, + tolerance = fixture$provenance$tolerance) }) } diff --git a/tests/testthat/test-relative-stopping.R b/tests/testthat/test-relative-stopping.R new file mode 100644 index 0000000..2f6353b --- /dev/null +++ b/tests/testthat/test-relative-stopping.R @@ -0,0 +1,128 @@ +test_that('relative stopping requires K consecutive changes, including at zero', { + source <- matrix(0, 4, 3); source[cbind(1:3,1:3)] <- c(4,2,1) + target <- matrix(0,4,3); target[1,1] <- 4 + fit <- function(...) learner(source,target,r=1,lambda_1=1,lambda_2=1, + step_size=.01,control=c(list(stopping_rule='relative',max_iter=10),list(...))) + expect_length(fit()$objective_values,6) + expect_equal(fit()$convergence_criterion,1) + expect_length(fit(window=1)$objective_values,2) + expect_length(fit(threshold=0)$objective_values,10) + expect_equal(fit(threshold=0)$convergence_criterion,2) + expect_equal(fit(window=20)$convergence_criterion,2) +}) + +test_that('stopping matches rolling maxima of recorded changes', { + source <- dat_highsim$Y_source[1:10,1:8] + target <- dat_highsim$Y_target[1:10,1:8] + run <- function(control) learner(source,target,r=2,lambda_1=1,lambda_2=.1, + step_size=.01,control=control) + full <- run(list(max_iter=80,threshold=0,max_value=1e10))$objective_values + for (rule in c('absolute','relative')) { + changes <- abs(diff(full)) + if (rule=='relative') changes <- changes/abs(head(full,-1)) + for (k in c(1,3,5)) { + threshold <- as.numeric(quantile(changes,.6)) + ends <- seq.int(k,length(changes)) + pass <- vapply(ends,function(i) max(changes[(i-k+1):i]) < threshold,logical(1)) + expected <- if (any(pass)) ends[which(pass)[1]]+1L else length(full) + fit <- run(list(max_iter=80,threshold=threshold,stopping_rule=rule, + window=k,max_value=1e10)) + expect_length(fit$objective_values,expected) + expect_equal(fit$objective_values,head(full,expected)) + expect_equal(fit$convergence_criterion,if(any(pass)) 1 else 2) + } + } +}) + +test_that('relative settings propagate into each CV fold', { + source <- dat_highsim$Y_source[1:8,1:6] + target <- dat_highsim$Y_target[1:8,1:6] + control <- list(stopping_rule='relative',window=3,threshold=.1,max_iter=20) + set.seed(91) + indices <- sample(seq_along(target)) + folds <- split(indices,rep(1:2,each=length(indices)/2)) + expected <- sum(vapply(folds,function(idx) { + train <- target;train[idx] <- NA + fit <- learner(source,train,r=2,lambda_1=1,lambda_2=.1, + step_size=.001,control=control) + sum((target[idx]-fit$learner_estimate[idx])^2) + },numeric(1))) + set.seed(91) + cv <- cv.learner(source,target,r=2,lambda_1_all=1,lambda_2_all=.1, + n_folds=2,step_size=.001,control=control) + expect_equal(as.numeric(cv$mse_all),expected) +}) + +test_that('invalid stopping options fail early', { + for (rule in list('other',NA_character_,c('relative','absolute'),1)) + expect_error(prepare_control(list(stopping_rule=rule),.01),'stopping_rule') + for (window in list(0,-1,1.5,Inf,NA,TRUE)) + expect_error(prepare_control(list(window=window),.01),'window') + expect_equal(prepare_control(list(stopping_rule='relative'),.01)$threshold,1e-6) +}) + +test_that('relative stopping retains failure protection even with a loose tolerance', { + d <- stopping_example() + fit <- learner(d$source,-d$target,r=1,lambda_1=1,lambda_2=1,step_size=10, + control=list(stopping_rule='relative',window=1,threshold=1e100, + max_value=2,max_iter=10)) + expect_equal(fit$convergence_criterion,3) +}) + +test_that('k and epsilon are other names for window and threshold', { + pc <- prepare_control(list(k=3,epsilon=1e-5),.01) + expect_equal(pc$window,3) + expect_equal(pc$threshold,1e-5) + expect_null(pc$k) + expect_null(pc$epsilon) + # Defaults still depend on the rule when only one of the two is given. + expect_equal(prepare_control(list(stopping_rule='relative',k=2),.01)$threshold,1e-6) + expect_equal(prepare_control(list(epsilon=0),.01)$window,1) + # A NULL alias counts as not given. + expect_equal(prepare_control(list(k=NULL,window=4),.01)$window,4) + source <- dat_highsim$Y_source[1:10,1:8] + target <- dat_highsim$Y_target[1:10,1:8] + fit <- function(control) learner(source,target,r=2,lambda_1=1,lambda_2=.1, + step_size=.01,control=control) + for (rule in c('absolute','relative')) { + by_main <- fit(list(stopping_rule=rule,window=3,threshold=1e-3,max_iter=200)) + by_alias <- fit(list(stopping_rule=rule,k=3,epsilon=1e-3,max_iter=200)) + expect_identical(by_alias,by_main) + } + # k really changes when the fit stops: a longer run of small changes is needed. + updates <- vapply(c(1,3,5),function(k) length(fit(list( + stopping_rule='relative',k=k,epsilon=1e-3,max_iter=200))$objective_values),numeric(1)) + expect_true(all(diff(updates) > 0)) +}) + +test_that('giving both names for one setting is an error', { + expect_error(prepare_control(list(window=3,k=3),.01),'not both') + expect_error(prepare_control(list(threshold=1e-3,epsilon=1e-3),.01),'not both') + expect_error(prepare_control(list(window=3,k=5),.01),'control\\$window or control\\$k') + expect_error(prepare_control(list(threshold=1e-3,epsilon=1e-5),.01), + 'control\\$threshold or control\\$epsilon') +}) + +test_that('errors name the setting the way the user wrote it', { + for (k in list(0,-1,1.5,Inf,NA,TRUE,c(1,2))) + expect_error(prepare_control(list(k=k),.01),'control\\$k') + for (epsilon in list(-1,Inf,NA,'a',c(1e-3,1e-4))) + expect_error(prepare_control(list(epsilon=epsilon),.01),'control\\$epsilon') + expect_error(prepare_control(list(window=0),.01),'control\\$window') + expect_error(prepare_control(list(threshold=-1),.01),'control\\$threshold') +}) + +test_that('k and epsilon reach every cross-validation fold', { + source <- dat_highsim$Y_source[1:8,1:6] + target <- dat_highsim$Y_target[1:8,1:6] + cv <- function(control) { + set.seed(91) + cv.learner(source,target,r=2,lambda_1_all=1,lambda_2_all=.1, + n_folds=2,step_size=.001,control=control) + } + by_main <- cv(list(stopping_rule='relative',window=3,threshold=.1,max_iter=20)) + by_alias <- cv(list(stopping_rule='relative',k=3,epsilon=.1,max_iter=20)) + expect_identical(by_alias$mse_all,by_main$mse_all) + loose <- cv(list(stopping_rule='relative',k=1,epsilon=1e100,max_iter=20)) + expect_false(isTRUE(all.equal(loose$mse_all,by_main$mse_all))) +}) diff --git a/tests/testthat/test-stopping-behavior.R b/tests/testthat/test-stopping-behavior.R index 7bfd930..8ed05bc 100644 --- a/tests/testthat/test-stopping-behavior.R +++ b/tests/testthat/test-stopping-behavior.R @@ -1,14 +1,3 @@ -# Analytic examples distinguish a stopping code from optimization accuracy. -# The source has distinct singular values 4, 2, 1; its rank-one approximation -# and initial target estimate are exactly diag(4, 0, 0) in a 4-by-3 matrix. -stopping_example <- function() { - source <- matrix(0, 4, 3) - source[cbind(1:3, 1:3)] <- c(4, 2, 1) - target <- matrix(0, 4, 3) - target[1, 1] <- 4 - list(source = source, target = target) -} - test_that('unchanged consecutive objectives meet a positive threshold', { d <- stopping_example() fit <- learner(d$source, d$target, r = 1, lambda_1 = 1, lambda_2 = 1, diff --git a/vignettes/advanced-learner.Rmd b/vignettes/advanced-learner.Rmd index ee875d0..35b6b9f 100644 --- a/vignettes/advanced-learner.Rmd +++ b/vignettes/advanced-learner.Rmd @@ -1,46 +1,138 @@ --- -title: "LEARNER and D-LEARNER: Multiple Sources, Source Weights, and Separate Penalties" +title: "LEARNER: Separate Penalties, Multiple Sources, and Diagnostics" output: rmarkdown::html_vignette: toc: true toc_depth: 2 + includes: + after_body: copy-code.html vignette: > - %\VignetteIndexEntry{LEARNER and D-LEARNER: Multiple Sources, Source Weights, and Separate Penalties} + %\VignetteIndexEntry{LEARNER: Separate Penalties, Multiple Sources, and Diagnostics} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5) +has_ggplot <- requireNamespace("ggplot2", quietly = TRUE) && + utils::packageVersion("ggplot2") >= "3.4.0" ``` -The README introduces estimation with one source population. This tutorial -explains two extensions, one at a time: using multiple sources, and allowing -different penalties for the two latent spaces. We first introduce source -weights shared by D-LEARNER and LEARNER, then explain how each method uses them. -Finally, we return to one source to study separate penalties in LEARNER. +The README introduces LEARNER with one source and a common space penalty. +Here we extend that analysis in two directions: allowing different penalties +for the two latent spaces, and borrowing information from multiple sources. +We then check the selected parameters and the optimization results. + +Paste each code block into the RStudio Console, or run it in an R script, +following the order below. The Copy buttons copy code +without the printed output; they do not run R in this page. The complete script +below uses the same examples and requires the package version accompanying this +vignette. Runtime depends on your machine and package build; the diagnostic section +repeats cross-validation (CV). To run the download, open `advanced-learner.R` +in RStudio and select Source with Echo, or run +`source("advanced-learner.R", echo = TRUE, max.deparse.length = Inf)` from +the directory where you saved it. Echo shows the code and printed results, +including selected penalties and stopping codes. Without `max.deparse.length`, +R may cut long echoed commands short with `[ TRUNCATED ]`; the printed +results are not affected. + +```{r download-script, echo=FALSE, results='asis'} +script_path <- "../inst/examples/advanced-learner.R" +if (!file.exists(script_path)) { + script_path <- system.file("examples", "advanced-learner.R", package = "learner") +} +script_text <- paste(readLines(script_path, warn = FALSE), collapse = "\n") +cat('

Download the complete R script

', sep = "") +``` -Weights determine how source-space information is combined. Penalties control -LEARNER's fit to the target and its departures from those spaces. D-LEARNER -uses source weights but has no penalty parameters to tune. +### Before you start + +This tutorial needs the development version of learner. Run the check below to +load the data and confirm that your installation supports the plotting calls. +If it fails, follow the installation instructions before continuing. ```{r load-package, message=FALSE} +install_help <- paste( + "Install the development version of learner with", + "devtools::install_github(\"stmcg/learner\"), then restart R and rerun", + "from the top.") +if (!requireNamespace("learner", quietly = TRUE)) { + stop(install_help, + call. = FALSE) +} +required_data <- c("dat_asymmetric", "dat_multisource") +available_data <- utils::data(package = "learner")$results[, "Item"] +missing_data <- setdiff(required_data, available_data) +if (length(missing_data)) { + stop(paste0("Your installed learner package is missing: ", + paste(missing_data, collapse = ", "), + ". ", install_help), call. = FALSE) +} library(learner) +data("dat_asymmetric", "dat_multisource", package = "learner") + +if (!requireNamespace("ggplot2", quietly = TRUE) || + utils::packageVersion("ggplot2") < "3.4.0") { + stop('Install ggplot2 >= 3.4.0 with install.packages("ggplot2"), then rerun.', + call. = FALSE) +} +# Check behavior rather than relying on a development version number. +compatible <- local({ + y <- diag(c(4, 2, 1)) + target <- diag(c(4, 0, 0)) + cv <- cv.learner(y, target, r = 1, lambda_1_all = 1, lambda_2_all = 1, + step_size = 0.001, n_folds = 2, control = list(max_iter = 2)) + all(c("lambda_1_all", "lambda_2_all", "n_observed") %in% names(cv)) +}) +if (!compatible) { + stop(paste("This learner installation lacks the CV metadata used here.", + install_help), call. = FALSE) +} + ``` -## 1. Starting Point: Two Methods and a Single Source +If this block reports errors, resolve the first error before running anything +else. Pasting several expressions into the Console can continue after an error; +later messages may only be consequences of the first failure. + +### Installation + +This tutorial needs the development version of learner. The version on CRAN +(1.0.0 at the time of writing) does not include the example datasets or the +plotting functions used here. Install the development version from GitHub: + +``` +# install.packages("devtools") +devtools::install_github("stmcg/learner") +``` + +Restart R after installing, then run the first code block again. The package +compiles C++ code, so you need a compiler: Xcode Command Line Tools on macOS or +Rtools on Windows. + +If the check still fails after installing, use `packageVersion("learner")` and +`find.package("learner")` to see which installation R is using. + + + +An OpenMP startup message means that multithreading is unavailable in that +installation. These examples use the default single core and can still run. + +## 1. Base Case: D-LEARNER and LEARNER with One Source Write the target estimate as $UV^\top$, with $U$ of size $p\times r$ and $V$ of size $q\times r$. Let $P_U$ and $P_V$ project onto the leading source singular-vector spaces. The columns of $U$ span the signal matrix's column -space, and the columns of $V$ span its row space. We use **U-space** and -**V-space** throughout. In the package interface, `lambda_1_row` acts on $U$ +space, and the columns of $V$ span its row space. We use U-space and +V-space throughout. In the package interface, `lambda_1_row` acts on $U$ and `lambda_1_col` acts on $V$. D-LEARNER estimates the target by direct projection, $P_UY_0P_V$, without -iterative optimization or penalty tuning. LEARNER instead fits target factors -while penalizing departures from the source spaces. With complete target data -$Y_0$, its single-source, common-penalty objective is +iterative optimization or penalty tuning. LEARNER fits target factors while +penalizing departures from the source spaces. With complete target data $Y_0$, +its single-source, common-penalty objective is $$ L(U,V)=\|UV^\top-Y_0\|_F^2 @@ -54,22 +146,116 @@ to follow the source spaces, with common strength `lambda_1`. The last term, controlled by `lambda_2`, balances the scales of the two factors. For missing target entries, the fit term uses only observed entries and is -divided by the observed fraction. Penalty terms stay the same. All examples +divided by the observed fraction. Penalty terms stay the same. The examples below have complete observed matrices and fix the rank at 3 to focus on the -extensions. See `?learner` for the optimization settings and stopping codes. +extensions. See `?learner` for optimization settings and stopping codes. + +## 2. Separate U- and V-Space Penalties + +### An asymmetric example + +`dat_asymmetric` contains one source and one target, each with 100 rows and 50 +columns. Their rank-3 true signals share the U-space but have different +V-spaces. Independent normal noise has variance 0.10 for the target and 0.01 +for the source. The estimated spaces are affected by noise, even on the shared +side. + +The construction follows the U-shared/V-perturbed setting in Section 2.4.1 of +the Supporting Information of McGrath et al. (2026), with smaller matrices and +rank 3. See `?dat_asymmetric` for details. The dataset includes the true signals, +but the fitting and tuning code below uses only the observed matrices. + +```{r asymmetric-data} +asym <- dat_asymmetric +``` + +### Specify separate penalties -## 2. Multiple Sources and Source Weights +A source may resemble the target more closely in one space than in the other. +Separate penalties let us control how strongly LEARNER borrows from each: -### Aligned populations and their precision +$$ +L_{\rm separate}(U,V)=\|UV^\top-Y_0\|_F^2 ++\lambda_{1,\rm row}\|(I_p-P_U)U\|_F^2 ++\lambda_{1,\rm col}\|(I_q-P_V)V\|_F^2 ++\lambda_2\|U^\top U-V^\top V\|_F^2. +$$ + +Use `lambda_1_row` for U and `lambda_1_col` for V. Equal values recover the +common-penalty objective. Larger values impose stronger constraints; the +penalties are not direct measurements of similarity. D-LEARNER has no penalty +parameters, so this extension applies to LEARNER. + +### Select penalties and refit -Multiple related populations can provide different information about the target. -Their usefulness depends on how well their spaces match the target and how -precisely those spaces can be estimated. +Supply both space grids to `cv.learner()` instead of `lambda_1_all`. It evaluates +all row, column, and balance combinations. Calling `set.seed()` makes the random +fold assignment reproducible. -`dat_multisource` contains one target and two aligned sources, each with 100 -rows and 50 columns. Their rank-3 true signals share latent spaces. Independent -normal noise has variance 0.10 for the target, 0.01 for A, and 0.50 for B. -Thus A is observed more precisely than B. +The default stopping rule checks whether the absolute change between successive +recorded objective values is below `0.001`. We raise the iteration limit from +100 to 2000 for both CV and the final fit, giving each fit more time to meet +that threshold. Fits can stop earlier. The step size is `0.003`; Section 4 +checks how the results change with a smaller step and a larger iteration limit. + +```{r asymmetric-cv} +asym_space_grid <- c(0, 10, 100) +asym_balance_grid <- c(0.001, 0.01, 0.1, 1) +set.seed(815) +cv_separate <- cv.learner( + asym$Y_source, asym$Y_target, r = 3, + lambda_1_row_all = asym_space_grid, + lambda_1_col_all = asym_space_grid, + lambda_2_all = asym_balance_grid, + n_folds = 3, step_size = 0.003, control = list(max_iter = 2000)) +c(U = cv_separate$lambda_1_row_min, + V = cv_separate$lambda_1_col_min, + balance = cv_separate$lambda_2_min) +``` + +Use the selected penalties to refit with all observed target entries: + +```{r asymmetric-refit} +fit_separate <- learner( + asym$Y_source, asym$Y_target, r = cv_separate$r, + lambda_1_row = cv_separate$lambda_1_row_min, + lambda_1_col = cv_separate$lambda_1_col_min, + lambda_2 = cv_separate$lambda_2_min, + step_size = 0.003, control = list(max_iter = 2000)) +dim(fit_separate$learner_estimate) +fit_separate$convergence_criterion +``` + +`learner_estimate` contains the fitted target matrix. The stopping code applies +to this final fit: 1 means the stopping criterion was met, 2 means the iteration +limit was reached, and 3 indicates excessive objective growth or non-finite +values. Section 4 checks the fits within CV separately. + +### View the CV results + +`plot_cv()` reads the grids and observed-entry count from the CV result. +It uses ggplot2, which we checked at the start. + +```{r asymmetric-cv-plot, eval=has_ggplot, fig.alt="CV errors across U and V penalties, with one panel per balance penalty and a black outline marking the selected candidate."} +plot_cv(cv_separate) +``` + +Each panel corresponds to one balance penalty. The axes show the U and V +penalties, and the black outline marks the selected combination. Pale blue +indicates lower error; dark blue indicates higher error, on the same scale +across panels. Cell labels give the percentage increase above the minimum CV +mean squared error (MSE). Values are rounded, so a label of zero does not +necessarily mean an exact tie. Gray cells, when present, mark unavailable +scores or scores above the plotting cutoff. + +## 3. Multiple Sources and Source Weights + +### Prepare aligned sources + +`dat_multisource` contains one target and two sources, each with 100 rows and 50 +columns. Their rank-3 true signals share latent spaces. Independent normal +noise has variance 0.10 for the target, 0.01 for A, and 0.50 for B, so A is +observed more precisely than B. ```{r multiple-data} sources <- dat_multisource$Y_source @@ -77,78 +263,49 @@ target <- dat_multisource$Y_target weights <- c(0.7, 0.3) ``` -These weights are illustrative, not estimated. They correspond to sources in -list order, are normalized to sum to one, and remain fixed during CV. Omitting -weights gives equal weights. Sources must already have matching rows and -columns in the same order. +Supply sources as a list of matrices, with rows and columns in the same order +as the target. The functions do not align them for you. Weights follow the list +order and are normalized to sum to one; omitting them gives equal weights. +Here we choose 0.7 for A and 0.3 for B as an example. CV does not select these +weights. -### Combining source-space information +### Combine source-space information For source $k$, let $\hat U_k$ and $\hat V_k$ contain its leading orthonormal -singular vectors at rank 3. The weights combine their projection matrices: +singular vectors at the chosen rank. Both methods use $$ \bar P_U=\sum_k w_k\hat U_k\hat U_k^\top,\qquad \bar P_V=\sum_k w_k\hat V_k\hat V_k^\top, -\quad w_k\geq 0,\quad \sum_k w_k=1. +\quad w_k\geq0,\quad\sum_k w_k=1. $$ -A larger weight gives a source more influence in these combinations; it does -not guarantee a more accurate estimate. The same weights are used on both sides. -The combined matrices need not themselves be orthogonal projectors. - -These weights do not directly average the observed source matrices or the -separately fitted estimates. Both methods below use the same combined spaces, -but turn that information into a target estimate differently. Weight selection -by cross-validation is outside this tutorial: all CV calls hold the weights fixed. - -## 3. D-LEARNER with Multiple Sources - -### Direct estimation without penalties - -D-LEARNER uses the same source list and weights without penalty tuning: +The same source weights apply to both sides. These are weighted combinations +of projection matrices, not averages of the observed source matrices. The +combined matrices need not themselves be orthogonal projectors. A larger weight +gives a source more influence, but does not guarantee greater accuracy. -$$\widehat\Theta_{\rm D}=\bar P_U Y_0\bar P_V.$$ +### Fit D-LEARNER -In general this is not the weighted average of the source-specific D-LEARNER -estimates: multiplying the two weighted matrices also produces cross-source -terms. The formula above is the operation implemented by `dlearner()`. +D-LEARNER uses the combined matrices directly: -### Compare source choices - -We compare sources using D-LEARNER at the same rank, so penalty tuning and -iterative optimization do not introduce additional differences. +$$ +\widehat\Theta_{\rm D}=\bar P_UY_0\bar P_V. +$$ ```{r multiple-direct} -direct <- dlearner(sources, target, r = 3, source_weights = weights) -estimates <- list( - Target_only = dlearner(target, target, r = 3)$dlearner_estimate, - A_only = dlearner(sources$A, target, r = 3)$dlearner_estimate, - B_only = dlearner(sources$B, target, r = 3)$dlearner_estimate, - Weighted_A_B = direct$dlearner_estimate) -source_errors <- vapply(estimates, function(estimate) { - norm(estimate - dat_multisource$Theta_target, "F") -}, numeric(1)) -round(source_errors, 3) +fit_direct <- dlearner(sources, target, r = 3, source_weights = weights) +dim(fit_direct$dlearner_estimate) ``` -Using the target as its own source gives its rank-3 truncated SVD. True signals -are known only because these data are simulated; they are not used for fitting -or CV. Smaller Frobenius error means a closer estimate of the true matrix. -In this example A alone is best; the weighted fit improves on B alone but does -not improve on A. These are single-dataset errors, not CV scores or a guarantee -that averaging sources helps. - -## 4. LEARNER with Multiple Sources +The result is stored in `dlearner_estimate`. No step size, iterative optimization, +or penalty selection is needed. Combining both sides in this way is generally +not the same as averaging separately fitted single-source estimates. -### From weights to penalties - -We now use the same data and fixed weights with LEARNER. Unlike D-LEARNER, -LEARNER can move away from the combined source spaces to fit the target data. -The penalties control that trade-off. We keep a common space penalty in this -section so that multiple sources are the only extension to the basic method. +### Select penalties and fit LEARNER -The objective becomes +LEARNER uses the same combined matrices in its space penalties. With a common +space penalty, the objective is $$ L_{\rm multi}(U,V)=\|UV^\top-Y_0\|_F^2 @@ -157,360 +314,184 @@ L_{\rm multi}(U,V)=\|UV^\top-Y_0\|_F^2 +\lambda_2\|U^\top U-V^\top V\|_F^2. $$ -Weights determine the combined source-space matrices; `lambda_1` controls the -penalty on departures from them. `lambda_2` balances the factor scales. A -source weight is therefore not interchangeable with a penalty value. LEARNER uses -the first source for initialization and, when rank is omitted, rank selection. - -### Select penalties and fit LEARNER +Source weights determine each source's contribution to the combined matrices; +the penalties determine how strongly the target factors are constrained by +them. LEARNER initializes from the first source and also uses that source to +choose the rank when `r` is omitted. -Keep the two space penalties equal in this first example. +We keep the weights fixed during CV and use a step size of `0.0003` for this +example. ```{r multiple-cv} -space_grid <- c(0, 1, 10) -balance_grid <- c(0.1, 1) set.seed(815) cv_multi <- cv.learner( sources, target, r = 3, source_weights = weights, - lambda_1_all = space_grid, lambda_2_all = balance_grid, + lambda_1_all = c(0, 1, 10), lambda_2_all = c(0.1, 1), n_folds = 3, step_size = 0.0003, control = list(max_iter = 2000)) c(space = cv_multi$lambda_1_min, balance = cv_multi$lambda_2_min) ``` -The heatmap compares the candidate penalties. Pale cells have lower error; -the black box marks the selected combination. `n_observed` converts held-out -sums of squared errors to mean squared errors. `plot_cv()` needs the ggplot2 -package (version 3.4.0 or later); if it is not installed, the two heatmap chunks -in this tutorial are skipped. - -```{r multiple-cv-plot, eval = requireNamespace("ggplot2", quietly = TRUE) && utils::packageVersion("ggplot2") >= "3.4.0"} -plot_cv(cv_multi, lambda_1_all = space_grid, lambda_2_all = balance_grid, - n_observed = sum(!is.na(target))) +```{r multiple-cv-plot, eval=has_ggplot, fig.alt="Multiple-source CV error heatmap; the selected candidate lies at the upper endpoints of both grids."} +plot_cv(cv_multi) ``` -Refit using all observed target entries: +The axes now show the common space penalty and the balance penalty. Both +selected values, 10 and 1, are the largest in their grids, hence the caption +"Selection on grid boundary". These small grids keep the example short; an +analysis using these data should check a wider range. + +Of the 18 internal CV fits, 4 reach the 2000-update limit, including 2 of the +3 folds for the selected candidate. Their final objective values alternate +between higher and lower values. A successful final fit therefore does not +establish that all CV fits met the stopping criterion. Check the step size as +well as the iteration limit when you see this pattern. + +Refit with the same weights and the selected penalties: ```{r multiple-refit} fit_multi <- learner( - sources, target, r = 3, source_weights = weights, + sources, target, r = cv_multi$r, source_weights = weights, lambda_1 = cv_multi$lambda_1_min, lambda_2 = cv_multi$lambda_2_min, step_size = 0.0003, control = list(max_iter = 2000)) +dim(fit_multi$learner_estimate) fit_multi$convergence_criterion ``` -The result reports stopping code `r fit_multi$convergence_criterion` after -`r length(fit_multi$objective_values)` updates. Code 1 means that the -objective-change threshold was met; code 2 means the iteration limit was -reached; code 3 indicates excessive growth or a non-finite update. - -In this run, CV selected space penalty `r cv_multi$lambda_1_min` and balance -penalty `r cv_multi$lambda_2_min`, both at the upper grid boundary. These are -choices within the supplied grid, not established optimal penalties. Section 6 -explains how to investigate boundaries and stopping behavior. - -## 5. LEARNER with Separate U- and V-Space Penalties - -We now return to a single source. Only the penalty structure changes in this -example; source weighting is not involved. D-LEARNER has no corresponding -penalty parameters. - -### An asymmetric example - -`dat_asymmetric` has one source and one target. Their true U-space is shared, -whereas their true V-spaces differ. It adapts the U-shared/V-perturbed -construction in the paper's simulation code, using 100 rows, 50 columns, -rank 3, and independent noise with variances 0.10 (target) and 0.01 (source). -See `?dat_asymmetric` for generation details. - -The simulation is adapted from Section 2.4.1 of the Supporting Information of -McGrath, Zhu, O'Dea, Guo and Duan (2026, *Statistics in Medicine* 45(15-17), -e70669), and separate row and column penalties are described in its Section 1.1. -That section calls this setting "same column spaces but different row spaces": -the span of U is the column space of the signal matrix, and the span of V is its -row space. The settings below (step size, penalty grids, iteration budget) were chosen for -this small example rather than taken from the paper, which used 500 by 500 -matrices of rank 4, a step size of 0.07 and 75 iterations. - -We might therefore want to borrow more strongly on the U side than on the V -side. This is a reason to try separate penalties, rather than imposing that -preference as the selected result. - -### What changes in the objective? - -With a single source, replace the common penalty by two values: - -$$ -L_{\rm separate}(U,V)=\|UV^\top-Y_0\|_F^2 -+\lambda_{1,\rm row}\|(I_p-P_U)U\|_F^2 -+\lambda_{1,\rm col}\|(I_q-P_V)V\|_F^2 -+\lambda_2\|U^\top U-V^\top V\|_F^2. -$$ - -Equal row and column penalties recover the common-penalty objective. Select -both penalties from the data rather than using the known simulation truth. +Multiple sources can also be combined with separate penalties: replace +`lambda_1_all` in the CV call by both separate grids, and refit with the selected +`lambda_1_row` and `lambda_1_col` as in Section 2. Source weights stay fixed in +both workflows; selecting weights by CV is outside this tutorial. -### Compare common and separate penalties +## 4. Diagnostics and Sensitivity Checks -Use the same rank, folds, step size, and iteration budget. The common grid is -the diagonal of the separate grid, so the separate search includes every common -candidate as well as unequal pairs. Resetting the seed makes the folds match. +Run Section 2 through the final refit before starting these checks. They use +`asym`, `asym_space_grid`, `asym_balance_grid`, `cv_separate`, and `fit_separate` +from that section. Section 3 is not needed. -```{r asymmetric-comparison} -# One source: the true U-space is shared, whereas the true V-spaces differ. -dat <- learner::dat_asymmetric -space_grid <- c(0, 10, 100) -balance_grid <- c(0.001, 0.01, 0.1, 1) -settings <- list(max_iter = 2000) +### Check grid boundaries and similar CV scores -# Reset the seed so both searches use the same validation folds. The common -# grid is the diagonal of the separate grid; rank and optimizer settings match. -set.seed(815) -cv_common <- learner::cv.learner( - dat$Y_source, dat$Y_target, r = 3, - lambda_1_all = space_grid, lambda_2_all = balance_grid, - n_folds = 3, step_size = 0.003, control = settings) -set.seed(815) -cv_separate <- learner::cv.learner( - dat$Y_source, dat$Y_target, r = 3, - lambda_1_row_all = space_grid, lambda_1_col_all = space_grid, - lambda_2_all = balance_grid, n_folds = 3, - step_size = 0.003, control = settings) - -fit_common <- learner::learner( - dat$Y_source, dat$Y_target, r = 3, - lambda_1 = cv_common$lambda_1_min, lambda_2 = cv_common$lambda_2_min, - step_size = 0.003, control = settings) -fit_separate <- learner::learner( - dat$Y_source, dat$Y_target, r = 3, - lambda_1_row = cv_separate$lambda_1_row_min, - lambda_1_col = cv_separate$lambda_1_col_min, - lambda_2 = cv_separate$lambda_2_min, step_size = 0.003, control = settings) - -comparison <- data.frame( - method = c('Common penalties', 'Separate penalties'), - lambda_row = c(cv_common$lambda_1_min, cv_separate$lambda_1_row_min), - lambda_col = c(cv_common$lambda_1_min, cv_separate$lambda_1_col_min), - lambda_balance = c(cv_common$lambda_2_min, cv_separate$lambda_2_min), - cv_mse = c(min(cv_common$mse_all), min(cv_separate$mse_all)) / length(dat$Y_target), - frobenius_error = c(norm(fit_common$learner_estimate - dat$Theta_target, 'F'), - norm(fit_separate$learner_estimate - dat$Theta_target, 'F')), - stop_code = c(fit_common$convergence_criterion, fit_separate$convergence_criterion)) -print(comparison, row.names = FALSE) -# This is one simulation, not a general performance claim. The minimum CV score -# was used for selection, so it is not an independent test error. Check stopping -# codes and grid boundaries before interpreting a selected fit. -``` +First, compare the selected penalties with the ends of their candidate grids: -A lower minimum CV score for the larger search is not independent evidence of -better prediction: that score was used to select parameters. Frobenius errors -compare refitted estimates with simulation truth. Interpret both alongside -stopping codes, and use repeated simulations or an independent test set for a -performance study. This single example does not guarantee unequal selected -penalties or improved estimation. - -In this run, the separate search selected a U-space penalty (`lambda_1_row`) of -`r cv_separate$lambda_1_row_min` and a V-space penalty (`lambda_1_col`) of -`r cv_separate$lambda_1_col_min`, placing a stronger penalty on -departures from the shared U-space, as the construction suggests. A penalty of -100 versus 10 does not mean that ten times as much information is transferred: -the penalty terms also depend on the factors and their departures from the -source spaces. The common search selected -`r cv_common$lambda_1_min` for both. The selected U penalty is the largest value -in the grid (`r max(space_grid)`), so a larger grid might change the choice; -the grid is kept small so that the example runs quickly. - -In this asymmetric-space example, separate penalties allow different borrowing -strength for the shared U space and the different V space. In this simulation -the separate fit had a -`r if (comparison$frobenius_error[2] < comparison$frobenius_error[1]) "lower" else "higher"` -estimation error than the common fit (Frobenius error -`r round(comparison$frobenius_error[2], 2)` compared with -`r round(comparison$frobenius_error[1], 2)`). The size of the difference depends -on the balance grid and on the cross-validation split, and this is one simulated -data set, so it should not be read as a general result. - -## 6. Diagnostics and Sensitivity Checks - -### Grid boundaries and balance-penalty sensitivity - -For the multiple-source example, both selected penalties are at their upper -grid endpoints. In exploratory runs, extending the space grid to 100 and the -balance grid to 10, then extending the space grid to 1000, moved the selection -to the upper endpoints again. This illustrates why a selected value should be -interpreted relative to the grid supplied, rather than as a best penalty. - -For the asymmetric example, the selected U penalty is also at the upper endpoint, -while the common balance penalty is at the lower endpoint. Extending a grid can -change both the selected parameters and the estimation-error comparison. - -The balance penalty is less well determined than the space penalties. The common -search selected `r cv_common$lambda_2_min`, which is -`r if (cv_common$lambda_2_min == min(balance_grid)) "the smallest value in the grid" else if (cv_common$lambda_2_min == max(balance_grid)) "the largest value in the grid" else "inside the grid"`, -and the separate search selected `r cv_separate$lambda_2_min`. At the selected -space penalties the CV scores for the `r length(balance_grid)` balance values are -close to one another (see the plot below, if ggplot2 is available), so the -selected balance penalty can change with the fold split or with `step_size`. A -grid that continues below `r min(balance_grid)` can also change the common -selection and the size of the difference between the two fits. - -```{r asymmetric-cv-plot, eval = requireNamespace("ggplot2", quietly = TRUE) && utils::packageVersion("ggplot2") >= "3.4.0"} -plot_cv(cv_separate, lambda_1_row_all = space_grid, - lambda_1_col_all = space_grid, lambda_2_all = balance_grid, - n_observed = sum(!is.na(dat$Y_target))) +```{r grid-boundaries} +needed <- c("asym", "asym_space_grid", "asym_balance_grid", + "cv_separate", "fit_separate") +if (!all(vapply(needed, exists, logical(1), inherits = TRUE))) { + stop("Run Section 2 through the final refit before starting Section 4.", + call. = FALSE) +} +selected <- c(U = cv_separate$lambda_1_row_min, + V = cv_separate$lambda_1_col_min, + balance = cv_separate$lambda_2_min) +grids <- list(cv_separate$lambda_1_row_all, cv_separate$lambda_1_col_all, + cv_separate$lambda_2_all) +data.frame(parameter = names(selected), selected = unname(selected), + lower = vapply(grids, min, numeric(1)), + upper = vapply(grids, max, numeric(1)), + on_boundary = vapply(seq_along(grids), function(i) { + selected[i] %in% range(grids[[i]]) + }, logical(1))) ``` -### Final refits and fits inside cross-validation - -The stop codes in the table (`r fit_common$convergence_criterion` for the common -refit, `r fit_separate$convergence_criterion` for the separate refit) describe -the two refits only. Code 1 means that the change in the objective fell below -the threshold, and code 2 that the iteration limit was reached. -`cv.learner()` does not report the stop codes of the fits it runs inside -cross-validation. When this example was prepared, about a third of those fits in -each search reached the iteration limit. Meeting the threshold does not by itself -show that a fit is close to its minimum, and a fit that reaches the limit can -still give a usable held-out score, so it is more informative to check whether -the selection is stable. Doubling `max_iter` or changing `step_size` to 0.002, -0.005, 0.001 or 0.0005 (with larger budgets for the smaller steps) left the -penalties selected by both searches unchanged. A larger step size of 0.01 (with -2000 updates) changed only the balance penalty chosen by the separate search. +The selected U penalty is at the upper end of its grid, as the heatmap caption +also notes. Try extending that grid while keeping the data and fold seed fixed. +When several CV scores are close, a small change in the folds or optimization +settings may change which candidate is selected. In that case, avoid attaching +too much importance to a single selected value. Also remember that the minimum +CV score was used for tuning; it is not an independent test error. +### Inspect the objective history -### Reproduce the sensitivity checks - -The following optional code uses the asymmetric data, rank, grids and fold seed -from Section 5. It repeats both searches and reports the selected penalties, -refit errors and stopping codes. It is not run when the vignette is built. -The smaller steps are paired with larger iteration budgets. +```{r asymmetric-objective, fig.alt="Objective values near the smallest recorded value, at the final update of a fit stopped by the tolerance criterion."} +plot_objective(fit_separate, iterations = "near_optimum") +``` -```{r sensitivity-checks, eval=FALSE} +The plot shows up to 41 recorded values near the minimum. Here the minimum is +at the last recorded update, so it appears at the right edge of the window. +The curve still slopes down, but the final change is below the tolerance: +the fit stopped at update 700 with code 1, before reaching the 2000-update limit. + +Use `iterations = "all"` to see the full history, or `iterations = 1:100` to +choose a range. If a fit reaches its limit with code 2 while the objective is +still decreasing, allow more updates. If successive values oscillate, try a +different step size. Neither a flat-looking curve nor code 1 establishes a +global minimum. + +### Repeat CV with a few optimization settings + +We compare the original settings with two alternatives: a larger iteration +limit, and a smaller step size with that larger limit. The data, rank, grids, +and CV folds stay fixed, so the comparison isolates the optimization settings. + +```{r sensitivity-checks} +fit_summary <- function(cv, fit, step, budget) { + data.frame(step_size = step, max_iter = budget, + U = cv$lambda_1_row_min, V = cv$lambda_1_col_min, + balance = cv$lambda_2_min, + min_cv_mse = min(cv$mse_all) / cv$n_observed, + updates = length(fit$objective_values), + stop_code = fit$convergence_criterion) +} check_setting <- function(step, budget) { - rows <- lapply(c(FALSE, TRUE), function(separate) { - grids <- if (separate) { - list(lambda_1_row_all = space_grid, lambda_1_col_all = space_grid) - } else { - list(lambda_1_all = space_grid) - } - set.seed(815) - cv <- do.call(cv.learner, c(list( - Y_source = dat$Y_source, Y_target = dat$Y_target, r = 3, - lambda_2_all = balance_grid, n_folds = 3, step_size = step, - control = list(max_iter = budget)), grids)) - u <- if (separate) cv$lambda_1_row_min else cv$lambda_1_min - v <- if (separate) cv$lambda_1_col_min else cv$lambda_1_min - fit <- learner(dat$Y_source, dat$Y_target, r = 3, - lambda_1_row = u, lambda_1_col = v, - lambda_2 = cv$lambda_2_min, step_size = step, - control = list(max_iter = budget)) - data.frame(method = if (separate) "Separate" else "Common", - step_size = step, max_iter = budget, - U_penalty = u, V_penalty = v, balance = cv$lambda_2_min, - error = norm(fit$learner_estimate - dat$Theta_target, "F"), - stop_code = fit$convergence_criterion) - }) - do.call(rbind, rows) + set.seed(815) + cv <- cv.learner( + asym$Y_source, asym$Y_target, r = 3, + lambda_1_row_all = asym_space_grid, + lambda_1_col_all = asym_space_grid, lambda_2_all = asym_balance_grid, + n_folds = 3, step_size = step, control = list(max_iter = budget)) + fit <- learner( + asym$Y_source, asym$Y_target, r = cv$r, + lambda_1_row = cv$lambda_1_row_min, lambda_1_col = cv$lambda_1_col_min, + lambda_2 = cv$lambda_2_min, step_size = step, + control = list(max_iter = budget)) + fit_summary(cv, fit, step, budget) } -configurations <- data.frame( - step = c(0.003, 0.003, 0.002, 0.005, 0.001, 0.0005, 0.01), - budget = c(2000, 4000, 6000, 4000, 10000, 20000, 2000)) -sensitivity <- do.call(rbind, lapply(seq_len(nrow(configurations)), function(i) { - check_setting(configurations$step[i], configurations$budget[i]) -})) +sensitivity <- rbind( + fit_summary(cv_separate, fit_separate, 0.003, 2000), + check_setting(0.003, 4000), + check_setting(0.0015, 4000)) print(sensitivity, row.names = FALSE) ``` -To inspect the fits *inside* CV, the next optional block reconstructs the three -folds and fits each candidate. Common-penalty candidates are the diagonal of -the separate grid, so they can be inspected from the same results. This uses -complete target data; with missing data, sample only observed entries. +Increasing the iteration limit leaves the selected penalties and CV score +unchanged, and the final fit still stops at update 700. With the smaller step, +the final fit takes 1352 updates; the selected penalties are the same and the +CV MSE is close to the original value. + +These three settings give a useful first check. For your own data, extend the +comparison if the selected penalties or scores change substantially. The final +stopping codes do not tell us how every fit inside CV ended. + +### Inspect the CV fits for the selected candidate -```{r inner-cv-stopping, eval=FALSE} +`cv.learner()` does not return the internal stopping codes. We can inspect the +selected candidate by recreating the three folds with the same seed and fitting +each training set again: + +```{r inner-cv-stopping} set.seed(815) -indices <- sample(which(!is.na(dat$Y_target))) +indices <- sample(which(!is.na(asym$Y_target))) n <- length(indices) folds <- lapply(1:3, function(k) { indices[seq.int(floor((k - 1) * n / 3) + 1, floor(k * n / 3))] }) -grid <- expand.grid(U = space_grid, V = space_grid, balance = balance_grid) -inner_fits <- do.call(rbind, lapply(seq_len(nrow(grid)), function(i) { - do.call(rbind, lapply(1:3, function(k) { - training <- dat$Y_target - training[folds[[k]]] <- NA - fit <- learner(dat$Y_source, training, r = 3, - lambda_1_row = grid$U[i], lambda_1_col = grid$V[i], - lambda_2 = grid$balance[i], step_size = 0.003, - control = list(max_iter = 2000)) - data.frame(U = grid$U[i], V = grid$V[i], balance = grid$balance[i], - fold = k, stop_code = fit$convergence_criterion) - })) +inner_fits <- do.call(rbind, lapply(1:3, function(k) { + training <- asym$Y_target + training[folds[[k]]] <- NA + fit <- learner( + asym$Y_source, training, r = cv_separate$r, + lambda_1_row = cv_separate$lambda_1_row_min, + lambda_1_col = cv_separate$lambda_1_col_min, + lambda_2 = cv_separate$lambda_2_min, + step_size = 0.003, control = list(max_iter = 2000)) + data.frame(fold = k, updates = length(fit$objective_values), + stop_code = fit$convergence_criterion) })) -table(inner_fits$stop_code) -with(subset(inner_fits, U == V), table(stop_code)) -``` - -Changing the penalty grids above also allows grid sensitivity to be explored. -For the multiple-source example, rerun Section 4 with expanded grids and keep -its data, weights and fold seed fixed. In either workflow, simulation truth is -used only to describe estimation error after selection, not to choose penalties. - -### Inspect the objective history - -```{r asymmetric-objective} -plot_objective(fit_separate) -``` - -The curve shows the recorded objective values of the separate-penalty fit, -`r length(fit_separate$objective_values)` updates in all (stop code -`r fit_separate$convergence_criterion`). A curve that ends at the iteration limit -cannot show whether more iterations would still change the fit. A larger -`max_iter` helps if the objective is still decreasing, and can help if an -alternation between two values is shrinking, though slowly. Changing `step_size` -can help as well. - -To inspect a specific range, use `iterations = 1:100`. The -`iterations = "near_optimum"` view shows up to 41 records around the smallest -recorded value. It draws the raw values, so a curve that zigzags between two -levels shows that the objective alternates from one iteration to the next -instead of settling. - -### Additional estimates and diagnostic views - -D-LEARNER still projects onto both source spaces directly, without separate -penalties. It provides another estimate to inspect, not a separate-penalty fit. -The target as its own source gives the target-only truncated SVD, shown as a -reference. In this example D-LEARNER has the larger error of the two, which can -happen when one source space differs from the target's, because D-LEARNER relies -on both. - -```{r asymmetric-direct} -direct_asymmetric <- dlearner(dat$Y_source, dat$Y_target, r = 3) -target_only <- dlearner(dat$Y_target, dat$Y_target, r = 3) -c(Target_only = norm(target_only$dlearner_estimate - dat$Theta_target, "F"), - D_LEARNER = norm(direct_asymmetric$dlearner_estimate - dat$Theta_target, "F")) -``` - -Additional diagnostic views are available: - -```{r additional-plots, eval=FALSE} -plot_source_spaces(dat$Y_target, dat$Y_source, r = 3) -plot_contributions(fit_separate) +print(inner_fits, row.names = FALSE) ``` -## 7. Practical Takeaways - -Use source weights to specify how multiple populations contribute to the -combined source-space information. D-LEARNER applies that information directly; -LEARNER also uses penalties to control departures from the spaces while fitting -the target. Separate U- and V-space penalties allow those departures to be -penalized differently when a common strength is too restrictive. - -Start with the single-source workflow in the README. Introduce multiple sources -when relevant aligned populations are available, and consider separate penalties -when the two spaces may differ in similarity. These extensions can be combined, -but are presented separately here to make their roles clear. Check grid -boundaries and stopping behavior before interpreting a selected fit. Simulation -truth helps explain these examples; it is not available for choosing parameters -in an application, and one example does not establish a general advantage. - -See [`?learner`](../help/learner), [`?cv.learner`](../help/cv.learner), [`?dlearner`](../help/dlearner), [`?dat_multisource`](../help/dat_multisource), and [`?dat_asymmetric`](../help/dat_asymmetric) for details. +All three fits meet the stopping criterion here. This check covers the selected +candidate only; checking the whole search would require repeating it for each +combination in the grids. If any fit reaches its iteration limit, inspect its +objective history and try a different budget or step size before relying on +the selection. diff --git a/vignettes/copy-code.html b/vignettes/copy-code.html new file mode 100644 index 0000000..f9973e7 --- /dev/null +++ b/vignettes/copy-code.html @@ -0,0 +1,46 @@ + +