nstat.extras.spatial.dpp_bridge

Determinantal point process (DPP) sampling — DPPy bridge + NumPy fallback.

The repulsive foil to the LGCP’s clustering: a discrete DPP on a finite ground set, where \(\Pr(Y = A) = \det(L_A)/\det(L + I)\) for a PSD \(L\)-ensemble, and the inclusion kernel is \(K = L(L+I)^{-1}\). Drawing from such an ensemble produces a repulsive pattern whose pair correlation sits below the Poisson null (\(g(r) < 1\)), mirroring an LGCP draw that sits above it.

Two paths:

  • sample_dpp() — preferred DPPy backend when installed (pip install nstat-toolbox[dpp]), exposing its broader sampler catalogue.

  • sample_l_ensemble() — a small inline NumPy eigen-sampler (Hough-Krishnapur-Peres-Virag 2006) that is always available — no optional dependency. Kept dependency-free so the repulsive foil runs anywhere.

References

  • Kulesza A, Taskar B (2012). Determinantal Point Processes for Machine Learning. Foundations and Trends in ML 5(2-3):123.

  • Hough JB, Krishnapur M, Peres Y, Virag B (2006). Determinantal processes and independence. Probability Surveys 3:206.

Functions

sample_dpp(L[, rng, backend])

Sample a discrete DPP, preferring DPPy when available.

sample_l_ensemble(L[, rng])

Exact DPP sample from an \(L\)-ensemble (HKPV 2006 eigen-sampler).
nstat.extras.spatial.dpp_bridge.sample_l_ensemble(L, rng=None)[source]

Exact DPP sample from an \(L\)-ensemble (HKPV 2006 eigen-sampler).

Pure NumPy — no optional dependency. Implements the two-stage spectral algorithm: (1) include each eigenvector \(v_k\) of \(L\) with probability \(\eta_k/(1+\eta_k)\); (2) sample the elementary DPP on the chosen eigenvectors by iterative projection.

Parameters:

  • L (ndarray) – (M, M) symmetric PSD \(L\)-ensemble matrix over the ground set of M candidate sites.

  • rng (Generator | None) – NumPy random generator.

Returns:

Sorted integer indices of the selected subset.

Return type:

np.ndarray

nstat.extras.spatial.dpp_bridge.sample_dpp(L, rng=None, *, backend='auto')[source]

Sample a discrete DPP, preferring DPPy when available.

Parameters:

  • L (ndarray) – (M, M) symmetric PSD \(L\)-ensemble matrix.

  • rng (Generator | None) – NumPy random generator (used by the NumPy fallback; DPPy uses its own seeding).

  • backend (str) – "auto" (default) tries DPPy then falls back to the inline NumPy sampler; "dppy" forces the optional backend (raising the install hint if absent); "numpy" forces the inline sampler.

Returns:

Sorted integer indices of the selected subset.

Return type:

np.ndarray