Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 2 additions & 2 deletions R/RcppExports.R
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
31 changes: 27 additions & 4 deletions R/dlearner.R
Original file line number Diff line number Diff line change
Expand Up @@ -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:}
Expand Down Expand Up @@ -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
Expand All @@ -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]]
Expand All @@ -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)
}
42 changes: 40 additions & 2 deletions R/input-validation.R
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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)
}
71 changes: 62 additions & 9 deletions R/learner.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.')
Expand All @@ -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
Expand Down Expand Up @@ -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:}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand All @@ -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)
}

Expand Down
18 changes: 18 additions & 0 deletions README.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -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.
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading
Loading