Add plotting diagnostics for fits, cross-validation, and latent spaces

[Jodielidada]

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

Stacked on #3. Please review/merge that one first; this diff shows only the plotting changes.

Summary

This PR adds exported plotting helpers for checking convergence, inspecting CV tuning grids, and visualizing latent spaces. They follow the displays used in the paper and its Supporting Information. ggplot2 is an optional dependency (Suggests), and only plot_cv() needs it. All estimation functions and the other plots work without it.

New functions

Function	Purpose	Graphics
plot_objective()	Objective history (full or most recent iterations), with the stopping code and the recorded minimum	base
plot_cv()	CV heatmap for common or separate penalty grids. Fill shows relative error above the minimum, and a black box marks the selected cell. The caption reports the absolute score range, ties, and selections on the grid boundary	ggplot2
plot_cv_profile()	Penalty sensitivity curves, including separate row/column penalties	base
plot_source_spaces()	Target vs. source projector submatrices (in the style of Figure 4)	base
plot_contributions()	Squared singular-vector contribution scores (in the style of Figure 5)	base
plot_simulation_results()	Replicate-level estimation error, with optional SD/SE bars (in the style of Figures 1–3)	base

Each function validates its inputs. plot_cv() returns a list containing the first ggplot page in $plot and all pages in $plots, so users can customize or export individual pages with ggsave().

Design notes

• plot_cv() labels finite scores above relative_limit as "high error" instead of "diverged", since a high CV score alone does not prove the optimizer diverged. If the minimum score is zero, the plot falls back to absolute scores.
• These are diagnostic displays. They do not establish convergence, assign biological labels, or reproduce the published experiments. The documentation says this explicitly.
• cv.learner() does not store the candidate grids, so plot_cv() / plot_cv_profile() take the grids as arguments. If you'd like, a follow-up could add the grids to the cv.learner() output so that plot_cv(cv) works on its own.

Dependencies

• ggplot2 (>= 3.4.0) is in Suggests. plot_cv() checks for it with requireNamespace() and stops with an install hint if it is missing. Tests that need ggplot2 use skip_if_not_installed(), and the Rd examples are guarded the same way.
• graphics, grDevices, and stats are added to Imports. They are base R packages, so this adds no new installs. The minimum R version stays at 2.10.

Testing

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

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

  • test-plotting.R
  • test-cv-heatmap-style.R
  • test-paper-plots.R

• New runnable examples: inst/examples/plot-diagnostics.R and inst/examples/plot-paper-displays.R. There is also a short guide in inst/examples/plotting-guide.md.

• I also tested an isolated R library without ggplot2. Estimation and the other plotting functions worked, and plot_cv() returned an installation message.

Question for review

plot_simulation_results() and plot_source_spaces() are closer to paper-reproduction tools than general diagnostics. I'm happy to move them to learner-paper if you'd prefer to keep the package API smaller.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.92%. Comparing base (d439afb) to head (fb8b7ea).

Additional details and impacted files

@@                           Coverage Diff                           @@
##           multiple-sources-separate-penalties       #4      +/-   ##
=======================================================================
+ Coverage                                95.02%   97.92%   +2.89%     
=======================================================================
  Files                                        5        7       +2     
  Lines                                      241      577     +336     
=======================================================================
+ Hits                                       229      565     +336     
  Misses                                      12       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.