Exact and sequential-importance-sampling fixed-margin samplers

[mkborregaard]

Adds two new fixed-margin matrix samplers alongside curveball, plus a weighted importance sampler, and updates dependencies. The public API (randomize_matrix!, matrixrandomizer) is extended with a method keyword; weighted sampling gets its own importance_sampler entry point.

New methods

• exact — exact uniform sampling and counting (Miller & Harrison 2013). Ported from the authors' reference exact_pure.py; counts with BigInt, samples row-by-row from the cached count. Feasible for small matrices (rows + cols ≲ 100, or very sparse); the generator counts once and reuses it.
• sis — the sequential importance sampling heuristic (Harrison & Miller 2013), uniform case. Builds a matrix column-by-column via a banded dynamic program over per-row Canfield odds and Gale–Ryser feasibility. Independent draws, scales to large matrices.

Both are exposed through the existing generator, which now dispatches a single draw on a per-method sampler type (CurveballSampler / SISSampler / ExactCounts) rather than branching on the enum.

Weighted importance sampling

importance_sampler(m, w) targets P*(z) ∝ ∏ w[i,j]^z[i,j] over fixed-margin binary matrices (uniform sis is the w ≡ 1 case). Each rand returns (matrix, logweight), so estimates reweight by exp(logweight) — mean(exp(logweight)) estimates the weighted count κ, and a weight-weighted average estimates E[h(Z)].

• Per-row odds are scaled by a factor vᵢ built from the elementary symmetric polynomials of the row's remaining weights (carried in logs).
• Structural zeros (w[i,j]=0, e.g. a zero diagonal for directed graphs) forbid a one there; an uncompletable draw returns logweight = -Inf and is discarded.
• Weights are Sinkhorn-canonicalised by default (canonicalize=false to opt out); P* is invariant to it.
• Verified: the mean importance weight recovers brute-force κ within noise (including zero-diagonal targets), the uniform case reduces to the plain matrix count, and cv² stays low (≈0.002–0.11).

Curveball improvements

The curveball generator now warm-starts its chain from an independent SIS draw, so the first sample is decorrelated from the (often atypical) input matrix, and a trades keyword controls how many trades separate successive draws (thinning). Empirically the running chain samples uniformly (χ² ≈ df).

Other

• Dependency bump (StatsBase 0.34); resolves to the latest releases.
• Fixed a latent bug: MatrixGenerator's show defined a shadowing local instead of extending Base.show.
• Tests: curveball (9), sis (6), exact (11), weighted sis (10) — all green, with brute-force κ/count cross-checks.

Not included (efficiency-only)

The paper's variance-based column ordering for the weighted sampler; the importance weights are already correct and low-variance without it.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.90576% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.31%. Comparing base (798b019) to head (8a1349e).

Files with missing lines	Patch %	Lines
src/RandomBooleanMatrices.jl	86.66%	4 Missing ⚠️
src/weights.jl	97.29%	2 Missing ⚠️
src/exact.jl	98.97%	1 Missing ⚠️
src/sis.jl	99.31%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #6      +/-   ##
==========================================
+ Coverage   90.78%   97.31%   +6.52%     
==========================================
  Files           2        6       +4     
  Lines          76      447     +371     
==========================================
+ Hits           69      435     +366     
- Misses          7       12       +5     

Flag	Coverage Δ
unittests	97.31% <97.90%> (+6.52%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.