Add multiple sources, separate penalties, and example data

[Jodielidada]

Summary

Adds weighted multiple-source fitting to learner(), dlearner(), and cv.learner(), plus separate row/column penalties and cross-validation over them. Adds dat_multisource with Y_target and Y_source = list(A, B), independently generated noise, documented generation code using usethis::use_data(), and an example comparing the source choices. Method documentation and NEWS are revised. Replaces #3; plotting is in #6.

Adds a second example comparing noisier sources in inst/examples/multiple-sources.R, without changing the built-in dataset. In this example, the weighted combination has lower error than either source alone, but higher error than SVD using only the target data.

Behavior changes

Existing single-source call patterns are retained, but validation and failure handling are stricter: negative penalties and ranks above the smaller matrix dimension are rejected; non-finite optimization updates stop immediately with code 3 and retain the best estimate; CV excludes non-finite scores, warns if some candidates fail, and errors if all fail. dlearner() now returns r as an integer. For finite updates, the objective change and growth stopping rules and their defaults are unchanged. Automatic rank selection and LEARNER initialization use the first source.

Testing

Tests cover compatibility, weighted projections, CV, gradients, stopping/failure behavior, and reference outputs from learnerv2 0.3.0. Local R CMD check --no-manual --no-build-vignettes: Status OK (macOS, R 4.6.1). GitHub Actions pass on macOS, Windows, and Ubuntu (release, devel, oldrel). PDF manual generation and actual OpenMP multithreading were not verified locally.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.95%. Comparing base (f7076da) to head (a72af46).

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #5      +/-   ##
==========================================
+ Coverage   90.22%   97.95%   +7.72%     
==========================================
  Files           4        5       +1     
  Lines         174      244      +70     
==========================================
+ Hits          157      239      +82     
+ Misses         17        5      -12     

☔ 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.