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