Add multiple-source transfer learning and separate row/column penalties

[Jodielidada]

Superseded by #5, which consolidates the current implementation into a clean review branch. This PR is closed without merging; its original branch and history are retained.

Summary

This PR brings the multiple-source and separate-penalty extensions from the preliminary learnerv2 0.3.0 implementation into the package's R/C++ code. These extensions correspond to the Supporting Information variants of LEARNER. The existing single-source, common-penalty interface is unchanged, and the existing tests from main pass without modification.

What's new

• Multiple sources. learner(), cv.learner(), and dlearner() now accept a list of aligned source matrices for Y_source, plus optional source_weights. Weights must be nonnegative and are normalized to sum to one. They combine the source projection operators as in Remark 2 of the paper.
• Separate row/column penalties. learner() gains lambda_1_row / lambda_1_col arguments, which penalize the U-space and V-space residuals separately. If the two are equal, the result is the same as the common-penalty fit.
• Cross-validation over separate penalties. cv.learner() gains lambda_1_row_all / lambda_1_col_all arguments. In that mode it returns a 3-D score array (row × column × balance grid). Common-penalty calls return the same structure and score scale as before.
• Performance and validation. Source SVDs are cached during CV, and parallel workers use C++ data. Sources, weights, penalties, ranks, and fold counts are validated, with informative error messages.
• Docs and examples. Argument documentation is expanded, and inst/examples/multiple-sources.R is new.

Behavior notes

• When r is not supplied, automatic rank selection (ScreeNOT) uses the first source. LEARNER initialization also uses the first source, even when r is supplied.
• Stopping rules are unchanged.

Backward compatibility

• The unmodified tests/testthat/test-main.R from main passes against this branch (11/11).

Testing

• R CMD check --no-manual: Status OK (0 errors, 0 warnings, 0 notes) on macOS, R 4.6.1.

• The test suite has 151 passing expectations. New test files:

  • test-separate-penalties.R
  • test-cv-multisource.R
  • test-stopping-behavior.R
  • test-reference-regression.R

• Regression tests compare the implementation against reference outputs from learnerv2 0.3.0 (tests/testthat/fixtures/multisource-v030.rds, tolerance 1e-8). The fixtures cover:

  • three weighted sources at a fixed rank (r = 2)
  • common and unequal row/column penalties, each with complete and missing targets
  • separate-penalty CV
  • multiple-source D-LEARNER

  Automatic rank selection is not covered. The generator script and its provenance are in tests/testthat/fixtures/.

GitHub CI also passes on macOS and Windows (R release), and Ubuntu (R release, devel, and oldrel-1).

Not tested locally: OpenMP multithreading; the local macOS build has no OpenMP support. Actual multithreaded execution in CI has not been independently verified. PDF manual generation was not checked (--no-manual).

[codecov]

Codecov Report

❌ Patch coverage is 96.11111% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.02%. Comparing base (f7076da) to head (d439afb).

Files with missing lines	Patch %	Lines
R/input-validation.R	91.30%	4 Missing ⚠️
R/learner.R	96.92%	2 Missing ⚠️
src/kernels.cpp	98.07%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #3      +/-   ##
==========================================
+ Coverage   90.22%   95.02%   +4.79%     
==========================================
  Files           4        5       +1     
  Lines         174      241      +67     
==========================================
+ Hits          157      229      +72     
+ Misses         17       12       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.