Skip to content
Merged
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
2 changes: 1 addition & 1 deletion DESCRIPTION
Original file line number Diff line number Diff line change
@@ -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")),
Expand Down
12 changes: 12 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 4 additions & 4 deletions R/RcppExports.R
Original file line number Diff line number Diff line change
@@ -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() {
Expand Down
22 changes: 9 additions & 13 deletions R/data-asymmetric.R
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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
Expand Down
34 changes: 32 additions & 2 deletions R/input-validation.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.')
Expand Down
54 changes: 42 additions & 12 deletions R/learner.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:}
#'
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
}

Expand Down
44 changes: 26 additions & 18 deletions R/plotting.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
#'
Expand All @@ -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)
#'
#' }
#'
Expand Down Expand Up @@ -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, ' = ',
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.')
Expand Down
7 changes: 3 additions & 4 deletions README.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand Down
Loading
Loading