Roadmap: convergence characterization → JOSS

[jc-macdonald]

Tracking issue for the convergence characterization work and JOSS paper. Task lists create "tracked by" relationships on referenced issues.

Phase 0 — Bug fixes (no dependencies)

• bug: _marginal_variance crashes with ValueError when columns were removed by rmempty #71 _marginal_variance crash when columns removed by rmempty
• bug: return_best_model=True yields VBPCA with variance_ (Vr) = None #72 return_best_model=True yields VBPCA with variance_ (Vr) = None
• bug: ARD prunes all components when refitting without xprobe on small-d blocks with missing data #73 ARD prunes all components when refitting without xprobe on small-d blocks with missing data

Phase 1 — Foundation (parallel, no dependencies)

• Expose prior hyperparameters (hp_va, hp_vb, hp_v) as user options #50 Expose prior hyperparameters (hp_va, hp_vb, hp_v)
• Store subspace angle in learning curves #52 Store subspace angle in learning curves
• Add get_params / set_params for sklearn Pipeline compatibility #34 Add get_params / set_params
• explained_variance_ratio_ not populated after fit #76 explained_variance_ratio_ not populated after fit
• reconstruction_ not set after fit #77 reconstruction_ not set after fit
• Expose xprobe_fraction parameter on VBPCA constructor #78 Expose xprobe_fraction parameter on VBPCA constructor

Phase 2 — API & profiling (depends on Phase 1)

• Inherit from sklearn BaseEstimator + TransformerMixin #36 Inherit BaseEstimator + expose learning_curves_, n_iter_, converged_ (depends on Store subspace angle in learning curves #52, Add get_params / set_params for sklearn Pipeline compatibility #34)
• Expose niter_broadprior as a configurable parameter #51 Profile convergence defaults across regimes (depends on Expose prior hyperparameters (hp_va, hp_vb, hp_v) as user options #50, Store subspace angle in learning curves #52)
• Implement transform(new_data) for out-of-sample projection #18 Out-of-sample projection via MAP with learned priors (depends on Expose prior hyperparameters (hp_va, hp_vb, hp_v) as user options #50)

Phase 3 — Validation & preprocessing (depends on Phase 2)

• Add K-fold cross-validation with 1-SE rule to model selection #75 K-fold cross-validated model selection
• Add missing-aware distributional transforms (log, winsorize, power) #80 Distributional transforms for preprocessing (log, winsorize, power)
• Add scaling/variance diagnostics for preflight validation #81 Preflight diagnostics (check_data)
• Input validation at the public API boundary #38 Input validation + pre-centering warning (depends on Expose niter_broadprior as a configurable parameter #51)
• Replace fragile float == comparisons in tests with pytest.approx / np.testing #33 Replace float == tests with pytest.approx
• Rerun stability study with full parameter sweep #45 200-rep stability rerun with profiled defaults (depends on Expose niter_broadprior as a configurable parameter #51)
• HPC sharding for stability analysis #44 HPC sharding for stability analysis (depends on Rerun stability study with full parameter sweep #45)

Phase 4 — Submission

• JOSS submission checklist #30 JOSS checklist + paper (depends on all above)

[jc-macdonald]

Note: This roadmap tracks VBPCApy library changes needed for the convergence study. The detailed experiment plan and sprint sequencing are tracked internally in a separate private repo to avoid cluttering this public issue.

This issue remains the canonical place for VBPCApy-specific milestones (Phases 0–4 above). Cross-references to VBPCApy issues here are intentional and correct.