feat: repeated permutation null for get_pseudo_correlation (v2.3.2)

[Arshammik]

Summary

Adds repeated-permutation null support to get_pseudo_correlation() and the R6 method SplikitObject$getPseudoCorrelation(), controlled by two new arguments:

• permutation_count (default 100L) — number of times the cells (columns) of ZDB_matrix are permuted and the pseudo correlation recomputed. Each permutation yields one null value per event, forming a per-event empirical null. permutation_count = 1 reproduces the original single-permutation behaviour.
• permutation_seed (default NULL) — seeds the permutations for reproducible nulls/empirical p-values. The caller's global RNG stream is saved and restored, so a seed here does not perturb downstream randomness.

The observed correlation is computed once; only the null pass scales with permutation_count.

Output changes

null_distribution is now the mean of the per-event null draws (equal to the single draw when permutation_count = 1 → backward compatible). New columns:

column	meaning
null_sd	SD of per-event null draws (NA if < 2 valid draws)
n_perm_valid	number of permutations with a non-NA null for the event
emp_pvalue	two-sided empirical p, (b + 1) / (n_perm_valid + 1)
emp_padj	Benjamini-Hochberg adjusted emp_pvalue

The full per-event draws (events × permutation_count) are attached as attr(result, "null_draws"). pseudo_correlation is unchanged.

Design notes

• Permutation loop lives in R (reuses the existing 4-way dense/sparse/mixed C++ dispatch via a shared compute_kernel() closure); the kernel is not row-parallelised, so a C++ loop would buy nothing while creating an OpenMP RNG-determinism trap.
• Empirical p-value uses the (b+1)/(m+1) Phipson–Smyth correction with the denominator counting only valid (non-NA) draws.

Validation

• R CMD check --as-cran: no ERRORs/WARNINGs; only the 4 pre-existing local-environment NOTEs (cluster -march flag, .so size, network-time, CRAN-incoming) — none introduced by this change. No "no visible binding" / undocumented-args / code-doc-mismatch notes.
• devtools::test(): 113 passed, 0 failed. New dedicated test covers empirical-p validity, seed reproducibility, global-RNG isolation, permutation_count = 1 equivalence, and input validation.
• The full-data R6 test uses a small permutation_count; the \donttest example subsets cells (runs in ~0.2s).

Version

Bumped to 2.3.2; NEWS.md and the RELEASENOTES.md logbook updated; docs/vignettes regenerated.