CardamomOT.inference.mixture

Core routines for mixture model inference used in the CARDAMOM pipeline.

This module contains functions for estimating negative-binomial mixture parameters, kinetics inference, and related utilities. It was originally ported from legacy scripts; the refactored version centralizes logging, adds type hints, and provides comprehensive documentation.

Public functions include:

  • infer_mixture – primary routine for mixture parameter learning

  • infer_kinetics_temporal – estimate gamma-Poisson kinetics over time

  • infer_kinetics_temporal_scaled – scaled kinetics version

Auxiliary helpers and legacy utilities are retained for compatibility.

Functions

estim_gamma_poisson(x[, mod, a_init, b_init])

Estimate parameters a and b of the Gamma-Poisson(a,b) distribution.

infer_kinetics_temporal([b_init, max_iter, seuil, ...])

Original version used for initialization with discrete timepoints.

infer_kinetics_temporal_scaled([b_init, max_iter, ...])

Scaled version of infer_kinetics_temporal().

infer_kinetics_preserve_mean_values_assignment(...)

Adapted version of infer_kinetics_temporal for EM when

nb_logpmf_vectorized(x, ks, c[, s])

Vectorized log-PMF of a Negative Binomial with optional cell-specific scaling.

zinb_logpmf_vectorized(x, ks, c, pi_zero[, s])

ZINB log-pmf matrix.

predict_resp(→ tuple[Any, Any])

Compute the responsibilities.

hard_em_scaled(data, s, n_components, ks_init, c_init, ...)

Hard EM avec scaling cellulaire.

hard_em(data, n_components, ks_init, c_init, seuil[, ...])

Hard EM for a Negative Binomial mixture with temporal constraints.

neg_log_likelihood_logits(logits, data, r, p)

logits : array (K,)

infer_kinetics_scaled(→ tuple[Any, Any])

Analytical M-step for NB mixture with cell-specific read-depth factors s_i.

em_vectorized_nb_zinb_scaled(x, s, ks_init, c_init[, ...])

EM for NB mixture with cellular read depth factors s_i.

compute_aic_for_params_scaled(→ tuple[Any, float])

Compute the AIC with read depth for a given set of parameters.

em_vectorized_nb_zinb(→ Any)

EM for NB/ZINB mixture with ANALYTICAL M-step via Newton-Raphson.

compute_aic_for_params(→ tuple[Any, numpy.floating[Any]])

Compute the AIC for a given set of parameters.

Module Contents

CardamomOT.inference.mixture.estim_gamma_poisson(x, mod=0, a_init=0, b_init=0)

Estimate parameters a and b of the Gamma-Poisson(a,b) distribution.

CardamomOT.inference.mixture.infer_kinetics_temporal(x, times, a_init=np.ones(100), b_init=1, max_iter=100, seuil=0.001, tol=1e-06, verb=False) → tuple[Any, Any]

Original version used for initialization with discrete timepoints.

CardamomOT.inference.mixture.infer_kinetics_temporal_scaled(x, s, times, a_init=np.ones(100), b_init=1, max_iter=100, seuil=0.001, tol=1e-06, verb=False) → tuple[numpy.ndarray, numpy.floating[Any]]

Scaled version of infer_kinetics_temporal(). Model: X_i | basin k ∼ NB(a_k, b / s_i). The only differences with the original are:

  • the gradient uses log(b/s_i) instead of log(b)

  • the analytic update for b uses Σ x_i/s_i instead of Σ x_i

CardamomOT.inference.mixture.infer_kinetics_preserve_mean_values_assignment(x, resp, seuil=0.01, a_init=None, b_init=None, tol=1e-06, max_iter=100, damping=0.7, verb=False) → tuple[Any, Any]

Adapted version of infer_kinetics_temporal for EM when preserve_mean_values assignments are used.

Analytically optimizes parameters a[0],...,a[K-1] and b (called c in other parts of the code) by maximizing the weighted log- likelihood under the provided responsibilities.

Parameters:

xarray (N,)

Observations (counts)

resparray (N, K)

Responsibilities (probabilities of membership in each component)

seuilfloat

Lower bound for a and b

a_initarray (K,) or None

Initialization for a

b_initfloat or None

Initialization for b

dampingfloat

Damping factor for Newton–Raphson (0 < damping <= 1); smaller values increase stability at the cost of speed.

Returns:

aarray (K,)

Optimal shape parameters (ks in our notation)

bfloat

Common dispersion parameter (c in our notation)

CardamomOT.inference.mixture.nb_logpmf_vectorized(x, ks, c, s=None)

Vectorized log-PMF of a Negative Binomial with optional cell-specific scaling.

Model: X_i | z=k ∼ NB(ks_k, c / s_i) so that E[X_i | k] = s_i * ks_k / c (scaling multiplies the mean).

Parameters:

  • x ((N,) observations (integer counts))

  • ks ((K,) shape parameters)

  • c (float dispersion parameter for the gene (shared across components))

  • s ((N,) cell read-depth factors (median = 1))

Returns:

logpmf

Return type:

(N, K)

CardamomOT.inference.mixture.zinb_logpmf_vectorized(x, ks, c, pi_zero, s=None)

ZINB log-pmf matrix.

CardamomOT.inference.mixture.predict_resp(x, ks, c, s=None, pi=None, pi_zero=None, zi=None, forcing=1.0) → tuple[Any, Any]

Compute the responsibilities.

CardamomOT.inference.mixture.hard_em_scaled(data, s, n_components, ks_init, c_init, seuil, tol=1e-06, max_iter_loop=200, basins_temporal=None, vect_t=None, preserve_mean_values=0, mean_forcing=1.0)

Hard EM avec scaling cellulaire. Seuls changements vs hard_em:

  • E-step via predict_resp

  • M-step via infer_kinetics_temporal_scaled

  • _apply_temporal_constraints travaille sur x/s pour les moyennes

CardamomOT.inference.mixture.hard_em(data, n_components, ks_init, c_init, seuil, tol=1e-06, max_iter_loop=200, basins_temporal=None, vect_t=None, preserve_mean_values=0, mean_forcing=1.0)

Hard EM for a Negative Binomial mixture with temporal constraints.

Parameters:

mean_forcing (float) – Weight of the temporal constraint (0 = no constraint, 1 = strict constraint)

CardamomOT.inference.mixture.neg_log_likelihood_logits(logits, data, r, p)

logits : array (K,) data : array (n,) r, p : NB parameters (K,)

CardamomOT.inference.mixture.infer_kinetics_scaled(x, s, resp, seuil=0.01, a_init=None, b_init=None, tol=1e-06, max_iter=100, damping=0.7, verb=False) → tuple[Any, Any]

Analytical M-step for NB mixture with cell-specific read-depth factors s_i.

Model: X_i | k ~ NB(a_k, c/s_i) The weighted log-likelihood under responsibilities resp is:

ℓ(a, c) = Σ_i Σ_k r_{ik} [
    log Γ(x_i + a_k) - log Γ(a_k) - log Γ(x_i+1)
    + a_k * log(c/s_i) - (x_i + a_k) * log(1 + c/s_i)
]

We optimize using Newton–Raphson on a_k and analytically close-form update for c.

Parameters:

  • x ((N,) counts)

  • s ((N,) read-depth factors (median = 1))

  • resp ((N, K) responsibilities)

Returns:

  • a ((K,) shape parameters)

  • b (float dispersion c (such that mean_k = s_i * a_k / c))

CardamomOT.inference.mixture.em_vectorized_nb_zinb_scaled(x, s, ks_init, c_init, pi_init=None, pi_zero_init=None, zi_mode=None, max_iter=200, tol=1e-06, seuil=0.01, damping=0.7, verbose=False)

EM for NB mixture with cellular read depth factors s_i.

Same as em_vectorized_nb_zinb() but uses nb_logpmf_vectorized() in the E-step and infer_kinetics_scaled() in the M-step.

Parameters:

  • x ((N,) counts (integers))

  • s ((N,) per-cell read depth (median normalized to 1))

  • em_vectorized_nb_zinb) ((other parameters are identical to)

CardamomOT.inference.mixture.compute_aic_for_params_scaled(x, s, ks, c, pi, pi_zero, zi_mode) → tuple[Any, float]

Compute the AIC with read depth for a given set of parameters.

CardamomOT.inference.mixture.em_vectorized_nb_zinb(x, ks_init, c_init, pi_init=None, pi_zero_init=None, zi_mode=None, max_iter=200, tol=1e-06, seuil=0.01, damping=0.7, verbose=False) → Any

EM for NB/ZINB mixture with ANALYTICAL M-step via Newton-Raphson.

Replaces moment-based estimates with direct optimization of the weighted log-likelihood, as in infer_kinetics_temporal().

CardamomOT.inference.mixture.compute_aic_for_params(x, ks, c, pi, pi_zero, zi_mode) → tuple[Any, numpy.floating[Any]]

Compute the AIC for a given set of parameters.