Generic-indexing declarations, test coverage, docstrings, and documentation

[timholy]

This bundles the remaining substantive maintenance work ahead of a formatting-only PR.

Generic indexing

The pipeline runs through svd, nndsvd, nnmf, and sparse, all of which assume 1-based indexing, so the public entry points (gsvdnmf, gsvdrecover, and the truncating/joint_nnls strategies) now declare that assumption with Base.require_one_based_indexing. Offset-axes inputs fail at entry with a clear error instead of deep inside LinearAlgebra — or worse: an offset SVD wider than size(W0, 2) previously made the 1:n factor slices succeed on the wrong columns, silently returning wrong factors. A new "generic axes" testset locks in both the eager rejection of OffsetArray inputs and equality of results for view-wrapped inputs.

Test coverage

New testsets cover the integer-n2 convenience methods gsvdnmf(X, W, H, n2::Integer) (which compute tsvd(X, n2) internally) and the alg = :multmse branch, which floors the augmented factors at truncmult so multiplicative updates can polish them.

Docstrings

All public docstrings are rewritten to standard Julia conventions (prose "Return ..." sentence, bulleted arguments, consistent keyword style), and two errors are fixed: the return type is NMF.Result (not NMF.NMFResult), and ncomponents accepts any Pair{<:Integer,<:Integer}. The docstrings now document the n1 < n2 ≤ 2n1 constraint, the integer-for-f convenience form, and the duck-typed contract for X in gsvdrecover; the strategy docstrings cross-reference each other with cost/requirement tradeoffs. A module docstring is added. gsvdnmf (both forms) and gsvdrecover gain jldoctest examples, exercised in CI via a new Documenter.doctest testset.

Citation and README

The paper is now published as Guo & Holy, iScience 29(3):114708 (2026), doi:10.1016/j.isci.2026.114708. CITATION.cff titles the software itself and carries the article in a preferred-citation block (validated against the CFF 1.2.0 schema; the arXiv preprint remains as an identifier), and the README cites the article directly.

The README also gains a JuliaHub version badge and an installation section. Its demo is now runnable from an installed package (via pkgdir) rather than only from a repo clone, uses a finite maxiter and checks converged — demonstrating that NMF stops at the tolerance, not the iteration cap — and its outputs were re-verified against current package versions. The hand-copied "Functions" section, which had drifted from the source, is replaced by a brief API overview that defers to the doctested docstrings.

🤖 Generated with Claude Code