[Jodielidada]

This PR brings the plotting functions into main, makes the README and help-page changes we discussed, and adds an example dataset and an advanced tutorial.

#6 was merged into multisource-penalties-clean after #5 had already gone into main, so the plotting code is not in main yet. The first commit here brings it over, which means the diff also contains code you have already reviewed. The subsequent commits contain the documentation, plotting, dataset, and tutorial updates.

README, plots and help pages

• The README is back to the original single-source walkthrough. I added plot_cv() for the CV results, plot_objective() in place of the base R plot, a note that plot_cv() needs ggplot2, and a link to the tutorial. The final learner() call uses the penalties chosen by CV (the same values as before), and I set a seed so they can be reproduced.
• plot_objective() now draws the raw objective values in the near-optimum view instead of the shaded band and average line. That view shows at most 41 records, so the raw values can be drawn directly, and an objective that alternates between two levels shows up as a zigzag. I also dropped the legend, since the subtitle already gives the minimum, and each iteration gets a dot when 100 or fewer are shown. This is the only change to the code from Add plots for objectives, CV, latent spaces, and contributions #6; the rest of the PR is docs and data. The near-optimum view below shows iterations 38–78 from the README fit. Each blue dot is a recorded objective value, and the red dot marks the smallest recorded value at iteration 58.
  
• The plotting help pages are shorter and start with what each plot shows and how to read it. plot_contributions() now documents its own limits argument.

Example data and tutorial

• dat_asymmetric has one source and one target (100 × 50, rank 3). The U-spaces are shared and the V-spaces differ. The paper's Supporting Information calls this "same column spaces but different row spaces", since the span of U is the column space of the signal matrix. In the package, lambda_1_row penalizes U and lambda_1_col penalizes V. The data follow the low-similarity scenario in Section 2.4.1 of the Supporting Information (set_theta_Ushared_Vdiff() with dif_factor_v = 2), with noise variance 0.01 for the source and 0.10 for the target. The generating script is data-raw/gen-asymmetric.R, and there is a help page with an example and a test.
• vignettes/advanced-learner.Rmd, titled LEARNER and D-LEARNER: Multiple Sources, Source Weights, and Separate Penalties, introduces the source data and fixed weights, then explains D-LEARNER and LEARNER in separate sections. D-LEARNER uses the weighted source spaces without penalty tuning; LEARNER holds those weights fixed while selecting penalties by CV. A single-source asymmetric example then introduces separate U- and V-space penalties. Formulas, runnable examples, and detailed interpretation are retained, with a table of contents.
• Grid boundaries, stopping behavior, objective plots, and sensitivity checks are grouped in a diagnostics section. Optional runnable code reproduces the step-size/budget comparisons and the inner-CV stopping counts without adding them to the default vignette build. The data, fitting algorithms, weights, and main example settings are unchanged.
• knitr and rmarkdown are now in Suggests, with a NEWS.md entry. The heatmap chunks in the tutorial are skipped if ggplot2 is missing or older than 3.4.0, which is what plot_cv() requires.

On dat_asymmetric, CV with separate penalties picks U = 100 and V = 10, and a common penalty picks 10 for both. The separate fit has the lower Frobenius error (4.07 against 4.76), and both final fits meet the stopping rule. The tutorial also says what is not settled: about a third of the CV fits reach the iteration limit, and the chosen U penalty (100) and the common balance penalty (0.001) sit at the edge of their grids. The choices did not change when I doubled the iteration budget or used step sizes from 0.0005 to 0.005 (with more iterations for the smaller steps), but with step size 0.01 the separate search chose a different balance penalty. This is one simulated dataset, so I treat it as an illustration and not a performance comparison.

Questions

• I picked the name, size and noise levels of dat_asymmetric for the tutorial. We can also try other choices.
• The tutorial is a first draft. Does this order—shared data and weights, D-LEARNER, LEARNER, then separate penalties—make the roles of weights and penalties clear?

Checks

R CMD check --no-manual gives Status OK on macOS (R 4.6.1), 401 expectations pass, and the tutorial builds in under 20 seconds. GitHub Actions checks pass on macOS, Windows, and Linux (code revision 440757c). I have not checked the PDF manual or multithreaded runs locally.

The revised vignette was rendered locally, and both optional diagnostic code blocks were executed successfully. The main asymmetric comparison remains 4.07 versus 4.76; the reconstructed inner-CV counts remain 33/108 for the separate search and 12/36 for the common search. Checks for the new documentation commit will run on GitHub Actions.

Please merge with a regular merge commit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.11%. Comparing base (37ed8f0) to head (d3965ec).

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #7      +/-   ##
==========================================
+ Coverage   97.95%   99.11%   +1.15%     
==========================================
  Files           5        7       +2     
  Lines         244      562     +318     
==========================================
+ Hits          239      557     +318     
  Misses          5        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.