diff --git a/NEWS.md b/NEWS.md index 704cb8b..b7e398b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,14 @@ ### learner version 1.1.0 (unreleased) +* Multiple-source fitting now defaults to automatic inverse subspace-distance + weights (Equation 3 of McGrath et al., 2026). Use `source_weights = "equal"` + or explicit `NULL` for historical equal weights; numeric weights still work. + Single-source estimates are unchanged. +* Automatic CV weights use training entries only and are cached per fold. + Results return `source_weights`, `source_weight_method`, and, for CV, + `fold_source_weights`. Full-data weights are recomputed for the final refit. + Missing entries are zero-filled only for the target spectral pilot. + + * Fix blank CV heatmaps in RStudio when followed by `plot_objective()` by avoiding explicit graphics-parameter changes in the objective plot. The plot diff --git a/R/RcppExports.R b/R/RcppExports.R index 1258d92..2cc5e7f 100644 --- a/R/RcppExports.R +++ b/R/RcppExports.R @@ -5,8 +5,8 @@ learner_cpp <- function(Y_source, Y_target, source_weights, r, lambda1_row, lamb .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, 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) +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, fold_source_weights) { + .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, fold_source_weights) } omp_max_threads <- function() { diff --git a/R/dlearner.R b/R/dlearner.R index 014d9ad..e2eeab8 100644 --- a/R/dlearner.R +++ b/R/dlearner.R @@ -13,8 +13,10 @@ #' are not allowed. #' @param r Rank of the knowledge graphs. If omitted, ScreeNOT (Donoho et al. 2023) #' is applied to the source population data to select the rank. -#' @param source_weights Relative weights of the sources, in the order of -#' \code{Y_source}. Default is equal weights. +#' @param source_weights Source weighting rule: \code{"auto"} (default), +#' \code{"equal"}, or a numeric vector of nonnegative relative weights in source +#' order. Explicit \code{NULL} retains equal weighting. Numeric weights are +#' normalized to sum to one. See Details for automatic weighting. #' #' @details #' \strong{Data and notation:} @@ -54,12 +56,31 @@ #' \code{source_weights}. If \code{r} is not specified, the rank is selected #' using the first source. #' +#' \strong{Automatic source weights:} +#' +#' With \code{source_weights = "auto"}, weights follow Equation (3) of McGrath +#' et al. (2026): \eqn{w_k \propto 1/(d_k+10^{-12})}, where +#' \deqn{d_k=\|\hat U_k\hat U_k^\top-\hat U_0\hat U_0^\top\|_F^2+ +#' \|\hat V_k\hat V_k^\top-\hat V_0\hat V_0^\top\|_F^2.} +#' All bases use rank \code{r}. The small constant stabilizes coincident spaces. +#' A single source receives weight one. The same weights apply to both spaces. +#' For an incomplete target, the spectral pilot replaces missing entries by zero +#' solely for this SVD; the fitting loss still uses only observed entries. +#' This pilot extends the complete-data rule and can be sensitive to structured +#' missingness. Supply numeric weights or \code{"equal"} to bypass it. +#' #' @return #' A list with the following components: #' \item{dlearner_estimate}{matrix containing the D-LEARNER estimate of the target population knowledge graph.} #' \item{r}{rank value used.} +#' \item{source_weights}{Normalized source weights used for this fit.} +#' \item{source_weight_method}{Weighting rule: auto, equal, or manual.} #' #' @references +#' McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). +#' LEARNER: A transfer learning method for low-rank matrix estimation. +#' Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. +#' #' Donoho, D., Gavish, M. and Romanov, E. (2023). \emph{ScreeNOT: Exact MSE-optimal singular value thresholding in correlated noise}. The Annals of Statistics, 51(1), pp.122-148. #' #' @seealso @@ -79,11 +100,12 @@ #' #' @export -dlearner <- function(Y_source, Y_target, r, source_weights = NULL) { +dlearner <- function(Y_source, Y_target, r, source_weights = "auto") { sources <- prepare_sources(Y_source, Y_target, source_weights, allow_missing_target = FALSE) r <- resolve_rank(if (missing(r)) NULL else r, sources$matrices[[1]]) bases <- lapply(sources$matrices, svd, nu = r, nv = r) + sources$weights <- resolve_source_weights(sources, Y_target, r, bases) if (length(bases) == 1L) { # Preserve the original single-source multiplication order. s <- bases[[1]] @@ -102,5 +124,6 @@ dlearner <- function(Y_source, Y_target, r, source_weights = NULL) { } } dimnames(estimate) <- dimnames(sources$matrices[[1]]) - list(dlearner_estimate = estimate, r = r) + list(dlearner_estimate = estimate, r = r, source_weights = sources$weights, + source_weight_method = sources$mode) } diff --git a/R/input-validation.R b/R/input-validation.R index cae7835..5db4b64 100644 --- a/R/input-validation.R +++ b/R/input-validation.R @@ -24,14 +24,26 @@ prepare_sources <- function(Y_source, Y_target, source_weights = NULL, stop('All source matrices and Y_target must have the same dimensions.') } } - if (is.null(source_weights)) source_weights <- rep(1, length(sources)) + mode <- "manual" + if (is.character(source_weights)) { + if (length(source_weights) != 1L || is.na(source_weights) || + !source_weights %in% c("auto", "equal")) { + stop("source_weights must be 'auto', 'equal', NULL, or numeric relative weights.") + } + mode <- source_weights + source_weights <- rep(1, length(sources)) + } else if (is.null(source_weights)) { + # Explicit NULL retains the historical equal-weight behavior. + mode <- "equal" + source_weights <- rep(1, length(sources)) + } if (!is.numeric(source_weights) || length(source_weights) != length(sources) || any(!is.finite(source_weights)) || any(source_weights < 0) || !any(source_weights > 0)) { stop('source_weights must have one finite nonnegative value per source and a positive total.') } weights <- source_weights / max(source_weights) - list(matrices = sources, weights = weights / sum(weights)) + list(matrices = sources, weights = weights / sum(weights), mode = mode) } resolve_rank <- function(r, source) { @@ -107,3 +119,29 @@ prepare_control <- function(control, step_size) { } control } + +# Equation (3): inverse summed squared distances of row/column projectors. +# Use thin bases to avoid allocating p-by-p or q-by-q projection matrices. +source_subspace_weights <- function(bases, target, r) { + if (length(bases) == 1L) return(1) + # A spectral pilot for incomplete targets: only observed values enter the SVD. + # The inverse observation-fraction scaling would not change singular vectors. + target[is.na(target)] <- 0 + pilot <- svd(target, nu = r, nv = r) + distances <- vapply(bases, function(b) { + du <- pilot$u - b$u %*% crossprod(b$u, pilot$u) + dv <- pilot$v - b$v %*% crossprod(b$v, pilot$v) + 2 * (sum(du^2) + sum(dv^2)) + }, numeric(1)) + # Same 1e-12 stabilizer as learner-paper's multisource simulation helper. + inverse <- 1 / (distances + 1e-12) + unname(inverse / sum(inverse)) +} + +resolve_source_weights <- function(sources, target, r, bases = NULL) { + if (sources$mode != "auto" || length(sources$matrices) == 1L) { + return(sources$weights) + } + if (is.null(bases)) bases <- lapply(sources$matrices, svd, nu = r, nv = r) + source_subspace_weights(bases, target, r) +} diff --git a/R/learner.R b/R/learner.R index 2a8614f..613f759 100644 --- a/R/learner.R +++ b/R/learner.R @@ -22,8 +22,10 @@ #' @param lambda_1_row_all,lambda_1_col_all Candidate values for separate #' penalties on the row and column factors. Supply both instead of #' \code{lambda_1_all}; all combinations with \code{lambda_2_all} are evaluated. -#' @param source_weights Relative source weights, as in \code{\link{learner}}. The weights -#' are not selected by cross-validation. Default is equal weights. +#' @param source_weights Source weighting rule: \code{"auto"} (default), +#' \code{"equal"}, or a numeric vector of nonnegative relative weights in source +#' order. Explicit \code{NULL} retains equal weighting. Numeric weights are +#' normalized to sum to one. See Details for automatic weighting. #' #' @details #' Given sets of candidate values of \eqn{\lambda_1} and \eqn{\lambda_2}, this @@ -37,6 +39,11 @@ #' the entries in the test data sets with those imputed from the LEARNER #' estimates. See McGrath et al. (2024) for further details. #' +#' With automatic weights, each fold estimates weights using only its training +#' target entries, then holds them fixed across penalty candidates. The weights +#' returned in \code{source_weights} are recomputed using all observed target +#' entries for the final refit. Numeric weights remain fixed across folds. +#' #' With separate penalties, the procedure selects the row, column, and balance #' penalties together. Both modes can be used with multiple sources. Call #' \code{set.seed()} first to reproduce the random partition. @@ -74,10 +81,19 @@ #' objective values. If a candidate fails with non-finite values, its remaining #' folds are skipped and have \code{NA} for updates and stopping codes. #' These diagnostics are saved during CV; no additional fits are performed.} +#' \item{source_weights}{Normalized weights computed from all observed target +#' entries, for use in the final refit.} +#' \item{fold_source_weights}{Matrix of weights used during CV; rows are folds +#' and columns follow source order.} +#' \item{source_weight_method}{Weighting rule: auto, equal, or manual.} #' \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., O'Dea, R., Guo, M. and Duan, R. (2026). +#' LEARNER: A transfer learning method for low-rank matrix estimation. +#' Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. +#' #' 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. #' #' @seealso @@ -125,7 +141,7 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, step_size, n_folds = 4, n_cores = 1, control = list(), lambda_1_row_all = NULL, lambda_1_col_all = NULL, - source_weights = NULL) { + source_weights = "auto") { sources <- prepare_sources(Y_source, Y_target, source_weights) r <- resolve_rank(if (missing(r)) NULL else r, sources$matrices[[1]]) control <- prepare_control(control, step_size) @@ -165,10 +181,20 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, index_set[[fold]] <- indices[seq.int(start, end)] } + bases <- if (sources$mode == "auto" && length(sources$matrices) > 1L) + lapply(sources$matrices, svd, nu = r, nv = r) else NULL + fold_weights <- t(matrix(vapply(index_set, function(held_out) { + training <- Y_target + training[held_out + 1L] <- NA_real_ + resolve_source_weights(sources, training, r, bases) + }, numeric(length(sources$matrices))), nrow = length(sources$matrices))) + final_weights <- resolve_source_weights(sources, Y_target, r, bases) + cv_result <- 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$stopping_rule == "relative", control$window) + control$max_value, index_set, control$stopping_rule == "relative", control$window, + fold_weights) scores <- cv_result$scores 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.') @@ -186,13 +212,16 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, return(list(lambda_1_min = grid$row[best], lambda_2_min = grid$balance[best], mse_all = mse_all, r = r, lambda_1_all = lambda_1_all, lambda_2_all = lambda_2_all, n_observed = n_indices, - cv_diagnostics = cv_diagnostics)) + cv_diagnostics = cv_diagnostics, source_weights = final_weights, + fold_source_weights = fold_weights, source_weight_method = sources$mode)) } 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, 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, cv_diagnostics = cv_diagnostics) + n_observed = n_indices, cv_diagnostics = cv_diagnostics, + source_weights = final_weights, fold_source_weights = fold_weights, + source_weight_method = sources$mode) } #' Latent space-based transfer learning @@ -240,8 +269,10 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' factor \eqn{U} and column factor \eqn{V}, respectively. Use these when the two #' sides should borrow different amounts of source information. Supply both #' instead of \code{lambda_1}; equal values reproduce the common penalty. -#' @param source_weights Relative weights of the sources, in the order of -#' \code{Y_source}. Default is equal weights. +#' @param source_weights Source weighting rule: \code{"auto"} (default), +#' \code{"equal"}, or a numeric vector of nonnegative relative weights in source +#' order. Explicit \code{NULL} retains equal weighting. Numeric weights are +#' normalized to sum to one. See Details for automatic weighting. #' #' @details #' \strong{Data and notation:} @@ -287,6 +318,19 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' change from 0 to 0 counts as 0, and a change from 0 to anything else is never #' small. #' +#' \strong{Automatic source weights:} +#' +#' With \code{source_weights = "auto"}, weights follow Equation (3) of McGrath +#' et al. (2026): \eqn{w_k \propto 1/(d_k+10^{-12})}, where +#' \deqn{d_k=\|\hat U_k\hat U_k^\top-\hat U_0\hat U_0^\top\|_F^2+ +#' \|\hat V_k\hat V_k^\top-\hat V_0\hat V_0^\top\|_F^2.} +#' All bases use rank \code{r}. The small constant stabilizes coincident spaces. +#' A single source receives weight one. The same weights apply to both spaces. +#' For an incomplete target, the spectral pilot replaces missing entries by zero +#' solely for this SVD; the fitting loss still uses only observed entries. +#' This pilot extends the complete-data rule and can be sensitive to structured +#' missingness. Supply numeric weights or \code{"equal"} to bypass it. +#' #' \strong{Extensions:} #' #' Separate penalties \code{lambda_1_row} and \code{lambda_1_col} replace @@ -318,8 +362,14 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' \item{objective_values}{numeric vector containing the values of the objective function at each iteration.} #' \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.} +#' \item{source_weights}{Normalized source weights used for this fit.} +#' \item{source_weight_method}{Weighting rule: auto, equal, or manual.} #' #' @references +#' McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). +#' LEARNER: A transfer learning method for low-rank matrix estimation. +#' Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. +#' #' 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. #' #' Donoho, D., Gavish, M. and Romanov, E. (2023). \emph{ScreeNOT: Exact MSE-optimal singular value thresholding in correlated noise}. The Annals of Statistics, 51(1), pp.122-148. @@ -355,7 +405,7 @@ cv.learner <- function(Y_source, Y_target, r, lambda_1_all = NULL, lambda_2_all, #' @export learner <- function(Y_source, Y_target, r, lambda_1 = NULL, lambda_2, step_size, control = list(), lambda_1_row = NULL, lambda_1_col = NULL, - source_weights = NULL) { + source_weights = "auto") { sources <- prepare_sources(Y_source, Y_target, source_weights) r <- resolve_rank(if (missing(r)) NULL else r, sources$matrices[[1]]) control <- prepare_control(control, step_size) @@ -380,10 +430,13 @@ learner <- function(Y_source, Y_target, r, lambda_1 = NULL, lambda_2, step_size, } validate_space_penalty(lambda_2, 'lambda_2') + sources$weights <- resolve_source_weights(sources, Y_target, r) 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$stopping_rule == "relative", control$window) + result$source_weights <- sources$weights + result$source_weight_method <- sources$mode return(result) } diff --git a/README.Rmd b/README.Rmd index e43c0f0..72a7d4f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -110,3 +110,21 @@ res_dlearner$dlearner_estimate[1:5, 1:5] For multiple sources, source weights, and separate row and column penalties, see the [advanced tutorial](vignettes/advanced-learner.Rmd). + +### Automatic source weights + +For multiple sources, `source_weights = "auto"` is the default in `learner()`, +`cv.learner()`, and `dlearner()`. Weights are inversely proportional to the sum +of squared source-target column- and row-projector distances, using Equation 3 +of McGrath et al. (2026), with a `1e-12` denominator stabilizer. + +CV recomputes weights from each fold's training target entries, holds them +fixed over that fold's penalty grid, and reports them in `fold_source_weights`. +The `source_weights` returned by CV are computed from all observed target +entries for the final refit. Missing target values are zero-filled only for the +spectral pilot used to obtain weights; the fitting loss ignores missing values. +This pilot can be sensitive to structured missingness. + +Pass numeric weights to use a specified combination, or `"equal"` (also +explicit `NULL`) to reproduce equal weighting. See +`inst/examples/automatic-source-weights.R` for a complete CV and refit example. diff --git a/README.md b/README.md index 7ddd5bd..6f9b274 100644 --- a/README.md +++ b/README.md @@ -155,3 +155,21 @@ res_dlearner$dlearner_estimate[1:5, 1:5] For multiple sources, source weights, and separate row and column penalties, see the [advanced tutorial](vignettes/advanced-learner.Rmd). + +### Automatic source weights + +For multiple sources, `source_weights = "auto"` is the default in `learner()`, +`cv.learner()`, and `dlearner()`. Weights are inversely proportional to the sum +of squared source-target column- and row-projector distances, using Equation 3 +of McGrath et al. (2026), with a `1e-12` denominator stabilizer. + +CV recomputes weights from each fold's training target entries, holds them +fixed over that fold's penalty grid, and reports them in `fold_source_weights`. +The `source_weights` returned by CV are computed from all observed target +entries for the final refit. Missing target values are zero-filled only for the +spectral pilot used to obtain weights; the fitting loss ignores missing values. +This pilot can be sensitive to structured missingness. + +Pass numeric weights to use a specified combination, or `"equal"` (also +explicit `NULL`) to reproduce equal weighting. See +`inst/examples/automatic-source-weights.R` for a complete CV and refit example. diff --git a/inst/examples/automatic-source-weights.R b/inst/examples/automatic-source-weights.R new file mode 100644 index 0000000..fa773d6 --- /dev/null +++ b/inst/examples/automatic-source-weights.R @@ -0,0 +1,19 @@ +library(learner) +sources <- dat_multisource$Y_source +target <- dat_multisource$Y_target +set.seed(815) +cv <- cv.learner(sources, target, r = 3, source_weights = 'auto', + lambda_1_all = c(0, 1, 10), lambda_2_all = c(.1, 1), + step_size = .0003, n_folds = 3, + control = list(max_iter = 2000)) +cv$fold_source_weights # Training-only weights, one row per fold. +cv$source_weights # All-observed-data weights for final refitting. +fit <- learner(sources, target, r = cv$r, source_weights = 'auto', + lambda_1 = cv$lambda_1_min, lambda_2 = cv$lambda_2_min, + step_size = .0003, control = list(max_iter = 2000)) +stopifnot(isTRUE(all.equal(fit$source_weights, cv$source_weights))) +fit$convergence_criterion +cv$cv_diagnostics +# User-specified weights remain available; explicit NULL means equal weights. +direct <- dlearner(sources, target, r = 3) +direct$source_weights diff --git a/man/cv.learner.Rd b/man/cv.learner.Rd index 2051773..e3cd6b6 100644 --- a/man/cv.learner.Rd +++ b/man/cv.learner.Rd @@ -16,7 +16,7 @@ cv.learner( control = list(), lambda_1_row_all = NULL, lambda_1_col_all = NULL, - source_weights = NULL + source_weights = "auto" ) } \arguments{ @@ -47,8 +47,10 @@ combinations in parallel. Default is \code{1}, i.e., no parallelization.} penalties on the row and column factors. Supply both instead of \code{lambda_1_all}; all combinations with \code{lambda_2_all} are evaluated.} -\item{source_weights}{Relative source weights, as in \code{\link{learner}}. The weights -are not selected by cross-validation. Default is equal weights.} +\item{source_weights}{Source weighting rule: \code{"auto"} (default), +\code{"equal"}, or a numeric vector of nonnegative relative weights in source +order. Explicit \code{NULL} retains equal weighting. Numeric weights are +normalized to sum to one. See Details for automatic weighting.} } \value{ A list containing: @@ -77,6 +79,11 @@ Stopping codes have the same meaning as in \code{\link{learner}}: objective values. If a candidate fails with non-finite values, its remaining folds are skipped and have \code{NA} for updates and stopping codes. These diagnostics are saved during CV; no additional fits are performed.} +\item{source_weights}{Normalized weights computed from all observed target +entries, for use in the final refit.} +\item{fold_source_weights}{Matrix of weights used during CV; rows are folds +and columns follow source order.} +\item{source_weight_method}{Weighting rule: auto, equal, or manual.} \item{n_observed}{Number of observed target entries, used to convert the summed validation errors to mean squared errors when plotting.} } @@ -97,6 +104,11 @@ applied to each training data set. The held out error is computed by comparing the entries in the test data sets with those imputed from the LEARNER estimates. See McGrath et al. (2024) for further details. +With automatic weights, each fold estimates weights using only its training +target entries, then holds them fixed across penalty candidates. The weights +returned in \code{source_weights} are recomputed using all observed target +entries for the final refit. Numeric weights remain fixed across folds. + With separate penalties, the procedure selects the row, column, and balance penalties together. Both modes can be used with multiple sources. Call \code{set.seed()} first to reproduce the random partition. @@ -147,6 +159,10 @@ fit$convergence_criterion } \references{ +McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). +LEARNER: A transfer learning method for low-rank matrix estimation. +Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. + 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. } \seealso{ diff --git a/man/dlearner.Rd b/man/dlearner.Rd index 4d9bbbb..7eae581 100644 --- a/man/dlearner.Rd +++ b/man/dlearner.Rd @@ -4,7 +4,7 @@ \alias{dlearner} \title{Direct projection transfer learning} \usage{ -dlearner(Y_source, Y_target, r, source_weights = NULL) +dlearner(Y_source, Y_target, r, source_weights = "auto") } \arguments{ \item{Y_source}{Matrix containing the source population data, with the same rows @@ -17,13 +17,17 @@ are not allowed.} \item{r}{Rank of the knowledge graphs. If omitted, ScreeNOT (Donoho et al. 2023) is applied to the source population data to select the rank.} -\item{source_weights}{Relative weights of the sources, in the order of -\code{Y_source}. Default is equal weights.} +\item{source_weights}{Source weighting rule: \code{"auto"} (default), +\code{"equal"}, or a numeric vector of nonnegative relative weights in source +order. Explicit \code{NULL} retains equal weighting. Numeric weights are +normalized to sum to one. See Details for automatic weighting.} } \value{ A list with the following components: \item{dlearner_estimate}{matrix containing the D-LEARNER estimate of the target population knowledge graph.} \item{r}{rank value used.} +\item{source_weights}{Normalized source weights used for this fit.} +\item{source_weight_method}{Weighting rule: auto, equal, or manual.} } \description{ This function applies the Direct projection LatEnt spAce-based tRaNsfer @@ -68,6 +72,19 @@ where \eqn{\hat U_k} and \eqn{\hat V_k} come from the truncated SVD of the \eqn{k}th source and the weights \eqn{w_k} are given by \code{source_weights}. If \code{r} is not specified, the rank is selected using the first source. + +\strong{Automatic source weights:} + +With \code{source_weights = "auto"}, weights follow Equation (3) of McGrath +et al. (2026): \eqn{w_k \propto 1/(d_k+10^{-12})}, where +\deqn{d_k=\|\hat U_k\hat U_k^\top-\hat U_0\hat U_0^\top\|_F^2+ +\|\hat V_k\hat V_k^\top-\hat V_0\hat V_0^\top\|_F^2.} +All bases use rank \code{r}. The small constant stabilizes coincident spaces. +A single source receives weight one. The same weights apply to both spaces. +For an incomplete target, the spectral pilot replaces missing entries by zero +solely for this SVD; the fitting loss still uses only observed entries. +This pilot extends the complete-data rule and can be sensitive to structured +missingness. Supply numeric weights or \code{"equal"} to bypass it. } \examples{ res <- dlearner(Y_source = dat_highsim$Y_source, @@ -82,6 +99,10 @@ dim(res_multi$dlearner_estimate) } \references{ +McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). +LEARNER: A transfer learning method for low-rank matrix estimation. +Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. + Donoho, D., Gavish, M. and Romanov, E. (2023). \emph{ScreeNOT: Exact MSE-optimal singular value thresholding in correlated noise}. The Annals of Statistics, 51(1), pp.122-148. } \seealso{ diff --git a/man/learner.Rd b/man/learner.Rd index e761243..6c01123 100644 --- a/man/learner.Rd +++ b/man/learner.Rd @@ -14,7 +14,7 @@ learner( control = list(), lambda_1_row = NULL, lambda_1_col = NULL, - source_weights = NULL + source_weights = "auto" ) } \arguments{ @@ -64,8 +64,10 @@ factor \eqn{U} and column factor \eqn{V}, respectively. Use these when the two sides should borrow different amounts of source information. Supply both instead of \code{lambda_1}; equal values reproduce the common penalty.} -\item{source_weights}{Relative weights of the sources, in the order of -\code{Y_source}. Default is equal weights.} +\item{source_weights}{Source weighting rule: \code{"auto"} (default), +\code{"equal"}, or a numeric vector of nonnegative relative weights in source +order. Explicit \code{NULL} retains equal weighting. Numeric weights are +normalized to sum to one. See Details for automatic weighting.} } \value{ A list with the following elements: @@ -73,6 +75,8 @@ A list with the following elements: \item{objective_values}{numeric vector containing the values of the objective function at each iteration.} \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.} +\item{source_weights}{Normalized source weights used for this fit.} +\item{source_weight_method}{Weighting rule: auto, equal, or manual.} } \description{ This function applies the LatEnt spAce-based tRaNsfer lEaRning (LEARNER) @@ -123,6 +127,19 @@ needs at least 6 recorded updates, and if \code{max_iter} is less than change from 0 to 0 counts as 0, and a change from 0 to anything else is never small. +\strong{Automatic source weights:} + +With \code{source_weights = "auto"}, weights follow Equation (3) of McGrath +et al. (2026): \eqn{w_k \propto 1/(d_k+10^{-12})}, where +\deqn{d_k=\|\hat U_k\hat U_k^\top-\hat U_0\hat U_0^\top\|_F^2+ +\|\hat V_k\hat V_k^\top-\hat V_0\hat V_0^\top\|_F^2.} +All bases use rank \code{r}. The small constant stabilizes coincident spaces. +A single source receives weight one. The same weights apply to both spaces. +For an incomplete target, the spectral pilot replaces missing entries by zero +solely for this SVD; the fitting loss still uses only observed entries. +This pilot extends the complete-data rule and can be sensitive to structured +missingness. Supply numeric weights or \code{"equal"} to bypass it. + \strong{Extensions:} Separate penalties \code{lambda_1_row} and \code{lambda_1_col} replace @@ -174,6 +191,10 @@ res_multi$convergence_criterion } \references{ +McGrath, S., Zhu, C., O'Dea, R., Guo, M. and Duan, R. (2026). +LEARNER: A transfer learning method for low-rank matrix estimation. +Statistics in Medicine, 45, e70669. doi:10.1002/sim.70669. + 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. Donoho, D., Gavish, M. and Romanov, E. (2023). \emph{ScreeNOT: Exact MSE-optimal singular value thresholding in correlated noise}. The Annals of Statistics, 51(1), pp.122-148. diff --git a/src/RcppExports.cpp b/src/RcppExports.cpp index 6cb1d4e..5b51a23 100644 --- a/src/RcppExports.cpp +++ b/src/RcppExports.cpp @@ -35,8 +35,8 @@ BEGIN_RCPP END_RCPP } // cv_learner_cpp -List 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) { +List 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, const Eigen::MatrixXd& fold_source_weights); +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, SEXP fold_source_weightsSEXP) { BEGIN_RCPP Rcpp::RObject rcpp_result_gen; Rcpp::RNGScope rcpp_rngScope_gen; @@ -55,7 +55,8 @@ BEGIN_RCPP Rcpp::traits::input_parameter< const std::vector>& >::type index_set(index_setSEXP); 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)); + Rcpp::traits::input_parameter< const Eigen::MatrixXd& >::type fold_source_weights(fold_source_weightsSEXP); + 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, fold_source_weights)); return rcpp_result_gen; END_RCPP } @@ -72,7 +73,7 @@ END_RCPP static const R_CallMethodDef CallEntries[] = { {"_learner_learner_cpp", (DL_FUNC) &_learner_learner_cpp, 13}, - {"_learner_cv_learner_cpp", (DL_FUNC) &_learner_cv_learner_cpp, 15}, + {"_learner_cv_learner_cpp", (DL_FUNC) &_learner_cv_learner_cpp, 16}, {"_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 df58a57..a5d8007 100644 --- a/src/kernels.cpp +++ b/src/kernels.cpp @@ -57,6 +57,7 @@ struct FitResult { FitResult learner_worker(const SourceSpaces &spaces, const Eigen::MatrixXd &Y_target, + const std::vector &weights, double lambda1_row, double lambda1_col, double lambda2, double step_size, int max_iter, double threshold, double max_value, bool relative, int window) { @@ -72,8 +73,8 @@ FitResult learner_worker(const SourceSpaces &spaces, diff = diff.array().isNaN().select(Eigen::MatrixXd::Zero(diff.rows(), diff.cols()), diff); } obj_init = diff.squaredNorm() / perc_nonmissing + - lambda1_row * space_residual(spaces.u, spaces.weights, U).squaredNorm() + - lambda1_col * space_residual(spaces.v, spaces.weights, V).squaredNorm() + + lambda1_row * space_residual(spaces.u, weights, U).squaredNorm() + + lambda1_col * space_residual(spaces.v, weights, V).squaredNorm() + lambda2 * (U.transpose() * U - V.transpose() * V).squaredNorm(); } @@ -97,14 +98,14 @@ FitResult learner_worker(const SourceSpaces &spaces, adjusted_theta = adjusted_theta.array().isNaN().select(temp, adjusted_theta); } - Eigen::MatrixXd residual_u = space_residual(spaces.u, spaces.weights, U); - Eigen::MatrixXd residual_v = space_residual(spaces.v, spaces.weights, V); + Eigen::MatrixXd residual_u = space_residual(spaces.u, weights, U); + Eigen::MatrixXd residual_v = space_residual(spaces.v, weights, V); // A weighted average of projectors is generally not idempotent. // The derivative of ||A U||^2 is 2 A' A U; here A is symmetric. Eigen::MatrixXd penalty_u = spaces.u.size() == 1 ? residual_u : - space_residual(spaces.u, spaces.weights, residual_u); + space_residual(spaces.u, weights, residual_u); Eigen::MatrixXd penalty_v = spaces.v.size() == 1 ? residual_v : - space_residual(spaces.v, spaces.weights, residual_v); + space_residual(spaces.v, weights, residual_v); Eigen::MatrixXd grad_U = (2.0 / perc_nonmissing) * (U * V_tilde - adjusted_theta * V) + lambda1_row * 2 * penalty_u + lambda2 * 4 * U * (U_tilde - V_tilde); @@ -127,8 +128,8 @@ FitResult learner_worker(const SourceSpaces &spaces, diff = diff.array().isNaN().select(Eigen::MatrixXd::Zero(diff.rows(), diff.cols()), diff); } obj = diff.squaredNorm() / perc_nonmissing + - lambda1_row * space_residual(spaces.u, spaces.weights, U).squaredNorm() + - lambda1_col * space_residual(spaces.v, spaces.weights, V).squaredNorm() + + lambda1_row * space_residual(spaces.u, weights, U).squaredNorm() + + lambda1_col * space_residual(spaces.v, weights, V).squaredNorm() + lambda2 * (U.transpose() * U - V.transpose() * V).squaredNorm(); } obj_values.push_back(obj); @@ -179,7 +180,7 @@ List learner_cpp(const Rcpp::List &Y_source, const Eigen::MatrixXd &Y_target, double lambda1_row, double lambda1_col, double lambda2, 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, + FitResult out = learner_worker(spaces, Y_target, source_weights, lambda1_row, lambda1_col, lambda2, step_size, max_iter, threshold, max_value, relative, window); return List::create(Named("learner_estimate") = out.estimate, Named("objective_values") = out.objective, @@ -197,12 +198,22 @@ List 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, bool relative, int window) { + const std::vector> &index_set, bool relative, int window, + const Eigen::MatrixXd &fold_source_weights) { SourceSpaces spaces = prepare_spaces(Y_source, source_weights, r); int p = Y_target.rows(); int n_grid = row_grid.size(); std::vector scores(n_grid, 0.0); const int n_folds = index_set.size(); + if (fold_source_weights.rows() != n_folds || + fold_source_weights.cols() != Y_source.size()) { + stop("fold_source_weights has incompatible dimensions."); + } + std::vector> fold_weights(n_folds); + for (int f = 0; f < n_folds; ++f) { + for (int k = 0; k < fold_source_weights.cols(); ++k) + fold_weights[f].push_back(fold_source_weights(f, k)); + } std::vector stopping_codes(n_grid * n_folds, NA_INTEGER); std::vector updates(n_grid * n_folds, NA_INTEGER); @@ -213,7 +224,7 @@ List cv_learner_cpp(const Rcpp::List &Y_source, const auto &fold = index_set[f]; 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], + FitResult fit = learner_worker(spaces, training, fold_weights[f], row_grid[g], col_grid[g], balance_grid[g], step_size, max_iter, threshold, max_value, relative, window); const int diagnostic_index = g * n_folds + f; stopping_codes[diagnostic_index] = fit.criterion; diff --git a/tests/testthat/helper-cv-scores.R b/tests/testthat/helper-cv-scores.R new file mode 100644 index 0000000..badb5ea --- /dev/null +++ b/tests/testthat/helper-cv-scores.R @@ -0,0 +1,24 @@ +# Rebuild the held-out predictions explicitly to check grid axes and masking. +manual_cv_scores <- function(sources, target, row, col, balance, weights = NULL, + seed = 92, folds = 3) { + set.seed(seed) + observed <- which(!is.na(target)) + indices <- sample(observed, length(observed), replace = FALSE) + groups <- lapply(seq_len(folds), function(fold) { + indices[seq.int(floor((fold - 1) * length(indices) / folds) + 1, + floor(fold * length(indices) / folds))] + }) + scores <- array(NA_real_, c(length(row), length(col), length(balance))) + for (i in seq_along(row)) for (j in seq_along(col)) for (k in seq_along(balance)) { + scores[i, j, k] <- sum(vapply(groups, function(held_out) { + train <- target + train[held_out] <- NA_real_ + fit <- learner(sources, train, r = 2, lambda_1_row = row[i], + lambda_1_col = col[j], lambda_2 = balance[k], + source_weights = weights, step_size = 0.01, + control = list(max_iter = 9, threshold = 0)) + sum((fit$learner_estimate[held_out] - target[held_out])^2) + }, numeric(1))) + } + scores +} diff --git a/tests/testthat/test-automatic-weights.R b/tests/testthat/test-automatic-weights.R new file mode 100644 index 0000000..63eb5f2 --- /dev/null +++ b/tests/testthat/test-automatic-weights.R @@ -0,0 +1,122 @@ +auto_fixture <- function() { + set.seed(191) + list(sources = list(matrix(rnorm(48), 8, 6), matrix(rnorm(48), 8, 6)), + target = matrix(rnorm(48), 8, 6)) +} + +# Independent reference: construct full projectors as in the paper/helper. +reference_weights <- function(sources, target, r) { + target[is.na(target)] <- 0 + b0 <- svd(target, nu = r, nv = r) + d <- vapply(sources, function(x) { + b <- svd(x, nu = r, nv = r) + sum((tcrossprod(b$u) - tcrossprod(b0$u))^2) + + sum((tcrossprod(b$v) - tcrossprod(b0$v))^2) + }, numeric(1)) + w <- 1 / (d + 1e-12) + unname(w / sum(w)) +} + +test_that('automatic weights match Equation 3 with complete and missing targets', { + d <- auto_fixture() + for (missing in c(FALSE, TRUE)) { + y <- d$target + if (missing) y[c(1, 9, 35)] <- NA + expected <- reference_weights(d$sources, y, 2) + fit <- learner(d$sources, y, 2, 1, 1, 0.01, control = list(max_iter = 4)) + expect_equal(fit$source_weights, expected, tolerance = 1e-12) + expect_equal(fit$source_weight_method, 'auto') + fixed <- learner(d$sources, y, 2, 1, 1, 0.01, source_weights = expected, + control = list(max_iter = 4)) + expect_equal(fit$learner_estimate, fixed$learner_estimate, tolerance = 1e-12) + } + direct <- dlearner(d$sources, d$target, 2) + expected <- reference_weights(d$sources, d$target, 2) + expect_equal(direct$source_weights, expected, tolerance = 1e-12) + expect_equal(direct$dlearner_estimate, + dlearner(d$sources, d$target, 2, expected)$dlearner_estimate, + tolerance = 1e-12) +}) + +test_that('weights handle coincident, orthogonal, and full-rank spaces', { + a <- diag(c(4, 0, 0, 0)); b <- diag(c(0, 3, 0, 0)) + fit <- dlearner(list(a, b), a, r = 1) + expect_gt(fit$source_weights[1], 1 - 1e-10) + expect_true(all(is.finite(fit$source_weights))) + expect_equal(sum(fit$source_weights), 1) + expect_equal(dlearner(list(a, 2*a), a, 1)$source_weights, c(.5, .5)) + expect_equal(dlearner(list(a, b), a, 4)$source_weights, c(.5, .5)) + expect_equal(dlearner(a, a, 1)$source_weights, 1) + expect_equal(dlearner(list(a, b), a, 1, 'equal')$source_weights, c(.5, .5)) + expect_equal(dlearner(list(a, b), a, 1, NULL)$source_weights, c(.5, .5)) + expect_equal(dlearner(list(a, b), a, 1, c(2, 1))$source_weights, c(2/3, 1/3)) + expect_equal(dlearner(list(b, a), a, 1)$source_weights, rev(fit$source_weights)) +}) + +test_that('automatic CV scores and weights match independent fold-specific fits', { + d <- auto_fixture(); d$target[c(1, 10)] <- NA + set.seed(92) + cv <- cv.learner(d$sources, d$target, r = 2, lambda_1_row_all = c(0, 2), + lambda_1_col_all = c(1, 3), lambda_2_all = c(0, .1), + step_size = .01, n_folds = 3, + control = list(max_iter = 9, threshold = 0)) + expected <- manual_cv_scores(d$sources, d$target, c(0, 2), c(1, 3), + c(0, .1), weights = 'auto') + expect_equal(cv$mse_all, expected, tolerance = 1e-10) + expect_equal(cv$source_weights, reference_weights(d$sources, d$target, 2), + tolerance = 1e-12) + set.seed(92) + observed <- which(!is.na(d$target)) + indices <- sample(observed, length(observed), replace = FALSE) + for (fold in 1:3) { + held <- indices[seq.int(floor((fold-1)*length(indices)/3)+1, + floor(fold*length(indices)/3))] + train <- d$target; train[held] <- NA + expect_equal(cv$fold_source_weights[fold, ], + reference_weights(d$sources, train, 2), tolerance = 1e-12) + # Changing held-out values cannot affect that fold's training weights. + changed <- d$target; changed[held] <- changed[held] + 1e4 + set.seed(92) + perturbed <- cv.learner(d$sources, changed, 2, 1, 1, .01, n_folds = 3, + control = list(max_iter = 2)) + expect_equal(perturbed$fold_source_weights[fold, ], + cv$fold_source_weights[fold, ], tolerance = 1e-12) + } +}) + +test_that('automatic weighting does not change RNG and rejects invalid modes', { + d <- auto_fixture(); seed <- .Random.seed + dlearner(d$sources, d$target, 2) + expect_identical(.Random.seed, seed) + for (mode in list('automatic', NA_character_, c('auto','equal'), character())) { + expect_error(dlearner(d$sources, d$target, 2, mode), 'source_weights') + } +}) + +test_that('single-source weighting helper needs no target decomposition', { + d <- auto_fixture() + bases <- list(svd(d$sources[[1]], nu = 2, nv = 2)) + # A single source must receive weight one even without observed target data; + # the helper should return before attempting a target SVD. + expect_identical(source_subspace_weights(bases, d$target * NA_real_, 2), 1) +}) + +test_that('CV kernel rejects incompatible fold-weight matrix dimensions', { + d <- auto_fixture() + call_kernel <- function(weights) { + cv_learner_cpp( + Y_source = d$sources, Y_target = d$target, + source_weights = c(.5, .5), row_grid = 1, col_grid = 1, + balance_grid = 1, step_size = .01, max_iter = 2L, + threshold = 0, n_cores = 1L, r = 2L, max_value = 10, + index_set = list(0:23, 24:47), relative = FALSE, window = 1L, + fold_source_weights = weights) + } + expect_error(call_kernel(matrix(.5, 1, 2)), + 'fold_source_weights has incompatible dimensions', fixed = TRUE) + expect_error(call_kernel(matrix(1, 2, 1)), + 'fold_source_weights has incompatible dimensions', fixed = TRUE) + expect_error(call_kernel(matrix(numeric(), 0, 2)), + 'fold_source_weights has incompatible dimensions', fixed = TRUE) + expect_no_error(call_kernel(matrix(.5, 2, 2))) +}) diff --git a/tests/testthat/test-cv-multisource.R b/tests/testthat/test-cv-multisource.R index 72bc262..7136575 100644 --- a/tests/testthat/test-cv-multisource.R +++ b/tests/testthat/test-cv-multisource.R @@ -4,31 +4,6 @@ multi_example <- function() { y = matrix(rnorm(35), 7, 5)) } -# Rebuild the held-out predictions explicitly to check grid axes and masking. -manual_cv_scores <- function(sources, target, row, col, balance, weights = NULL, - seed = 92, folds = 3) { - set.seed(seed) - observed <- which(!is.na(target)) - indices <- sample(observed, length(observed), replace = FALSE) - groups <- lapply(seq_len(folds), function(fold) { - indices[seq.int(floor((fold - 1) * length(indices) / folds) + 1, - floor(fold * length(indices) / folds))] - }) - scores <- array(NA_real_, c(length(row), length(col), length(balance))) - for (i in seq_along(row)) for (j in seq_along(col)) for (k in seq_along(balance)) { - scores[i, j, k] <- sum(vapply(groups, function(held_out) { - train <- target - train[held_out] <- NA_real_ - fit <- learner(sources, train, r = 2, lambda_1_row = row[i], - lambda_1_col = col[j], lambda_2 = balance[k], - source_weights = weights, step_size = 0.01, - control = list(max_iter = 9, threshold = 0)) - sum((fit$learner_estimate[held_out] - target[held_out])^2) - }, numeric(1))) - } - scores -} - test_that("independent CV axes and scores match explicit held-out predictions", { d <- multi_example() for (multi in c(FALSE, TRUE)) for (missing in c(FALSE, TRUE)) { @@ -64,7 +39,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', - 'lambda_1_all', 'lambda_2_all', 'n_observed', 'cv_diagnostics')) + 'lambda_1_all', 'lambda_2_all', 'n_observed', 'cv_diagnostics', + 'source_weights', 'fold_source_weights', 'source_weight_method')) 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) @@ -78,7 +54,8 @@ test_that("source representations and normalized weights are consistent", { fit <- function(source, weights = NULL) { learner(source, d$y, r = 2, lambda_1_row = 3, lambda_1_col = 0.5, lambda_2 = 1, step_size = 0.01, source_weights = weights, - control = list(max_iter = 12, threshold = 0)) + control = list(max_iter = 12, threshold = 0))[c('learner_estimate', + 'objective_values', 'convergence_criterion', 'r')] } expect_equal(fit(d$a), fit(list(d$a)), tolerance = 1e-12) expect_equal(fit(d$a), fit(list(d$a, d$a)), tolerance = 1e-10) @@ -99,8 +76,10 @@ test_that("D-LEARNER matches weighted projectors and preserves matrix calls", { result <- dlearner(list(d$a, d$b), d$y, 2, c(7, 3)) expect_equal(result$dlearner_estimate, pu %*% d$y %*% pv, tolerance = 1e-12) expect_equal(dlearner(d$a, d$y, 2), dlearner(list(d$a), d$y, 2), tolerance = 1e-12) - expect_equal(dlearner(d$a, d$y, 2), dlearner(list(d$a, d$b), d$y, 2, c(1, 0)), tolerance = 1e-12) - expect_equal(result, dlearner(list(d$b, d$a), d$y, 2, c(3, 7)), tolerance = 1e-12) + expect_equal(dlearner(d$a, d$y, 2)$dlearner_estimate, + dlearner(list(d$a, d$b), d$y, 2, c(1, 0))$dlearner_estimate, tolerance = 1e-12) + expect_equal(result$dlearner_estimate, + dlearner(list(d$b, d$a), d$y, 2, c(3, 7))$dlearner_estimate, tolerance = 1e-12) }) test_that("invalid sources, weights, ranks, folds, and grids are rejected", { diff --git a/tests/testthat/test-reference-regression.R b/tests/testthat/test-reference-regression.R index 21b140b..0df32d7 100644 --- a/tests/testthat/test-reference-regression.R +++ b/tests/testthat/test-reference-regression.R @@ -28,7 +28,7 @@ for (case_name in c('complete_common', 'complete_separate', case <- fixture$fit[[case_name]] actual <- do.call(learner, case$args) # Includes every estimated entry, every objective value, rank, and stop code. - expect_equal(actual, case$expected, tolerance = fixture$provenance$tolerance) + expect_equal(actual[names(case$expected)], case$expected, tolerance = fixture$provenance$tolerance) }) } @@ -48,6 +48,6 @@ for (case_name in c('complete', 'missing')) { test_that('multisource D-LEARNER matches the saved reference', { fixture <- reference_fixture() actual <- do.call(dlearner, fixture$direct$args) - expect_equal(actual, fixture$direct$expected, + expect_equal(actual[names(fixture$direct$expected)], fixture$direct$expected, tolerance = fixture$provenance$tolerance) }) diff --git a/vignettes/advanced-learner.Rmd b/vignettes/advanced-learner.Rmd index 100f00b..f50fd22 100644 --- a/vignettes/advanced-learner.Rmd +++ b/vignettes/advanced-learner.Rmd @@ -267,9 +267,10 @@ weights <- c(0.7, 0.3) 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. +order and are normalized to sum to one. Omitting `source_weights` now uses +automatic subspace-distance weights. Here we explicitly choose 0.7 for A and +0.3 for B to retain the fixed-weight demonstration. CV does not change these +supplied numeric weights. Use `"equal"` or explicit `NULL` for equal weights. ### Combine source-space information @@ -362,7 +363,31 @@ fit_multi$convergence_criterion 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. +this fixed-weight example. For automatic weighting, use `source_weights = "auto"`: + +```{r automatic-weights, eval=FALSE} +set.seed(815) +cv_auto <- cv.learner( + sources, target, r = 3, source_weights = "auto", + 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)) +cv_auto$fold_source_weights +cv_auto$source_weights +fit_auto <- learner( + sources, target, r = cv_auto$r, source_weights = "auto", + lambda_1 = cv_auto$lambda_1_min, lambda_2 = cv_auto$lambda_2_min, + step_size = 0.0003, control = list(max_iter = 2000)) +``` + +Automatic weights use the inverse sum of squared source-target projector +distances (Equation 3 of McGrath et al., 2026), with a `1e-12` stabilizer. +For missing target entries, the target SVD uses a zero-filled spectral pilot; +missing entries remain excluded from the fitting loss. Each CV fold estimates +weights using only its training entries, keeping them fixed across penalty +candidates. The final fit recomputes weights from all observed target entries. +`cv_auto$source_weights` also provides these full-data weights. The automatic +rule is not a grid search over weights. The pilot may be sensitive to structured +missingness, in which case supplied weights remain available. ## 4. Diagnostics and Sensitivity Checks