CardamomOT.inference.network

Core routines for network inference used in trajectory-based loops.

This module implements the optimization objectives, gradients, and penalization schemes required to learn regulatory interactions from multi-modal single-cell data. It is designed to be imported lazily in order to avoid heavy dependencies when only other parts of the package are needed.

Functions

base_kon(→ numpy.ndarray)	More robust version with clipping of exponentials to avoid overflow.
objective(X, weights_samples, ys, ypr, yp, ypm, yk, ...)	Loss function for a single gene — joint over all samples.
grad_theta(X, weights_samples, ys, ypr, yp, ypm, yk, ...)	Gradient of objective w.r.t. X = theta.ravel().
objective_refinement(X, correc_ref, inter, basal, ...)	Loss for the refinement step with per-sample basal.
grad_correc(X, correc_ref, inter, basal, ...)	Gradient of objective_refinement w.r.t. correction factors X.
core_inference(y_samples, y_proba, y_prot, y_prot_mod, ...)	Joint L-BFGS-B optimisation of interactions + per-sample basals for one gene.
refine_inference(y_samples, y_proba, y_prot, ...[, ...])	Refinement step: optimise multiplicative correction factors over inter and per-sample basal.
main_loop_inference(g, y_samples, y_proba, y_prot, ...)	Joint inference (inter + per-sample basal) for a single gene g.
inference_network(→ tuple[numpy.ndarray, ...)	Joint network inference: interactions shared across samples, basal per sample.

Module Contents

CardamomOT.inference.network.base_kon(theta_basal, theta_inter, y_prot) → numpy.ndarray

More robust version with clipping of exponentials to avoid overflow.

CardamomOT.inference.network.objective(X, weights_samples, ys, ypr, yp, ypm, yk, ks, G, g, n_networks, n_samples, theta_ref, ref_network, l_pen, proba, weight_prev, loss, final, constrain_basal_uniform=0.0, basal_free_mask=None)

Loss function for a single gene — joint over all samples.

theta shape: (G + n_samples, n_networks)

rows 0..G-1 : interaction weights rows G..G+ns-1 : per-sample basal values

constrain_basal_uniformfloat >= 0

Penalty strength that pushes free-sample basals toward their mean. Samples whose basal is pinned by a KO/OV prior are excluded (basal_free_mask).

basal_free_mask(n_samples,) bool array or None

True for samples that are NOT pinned by basal_ref for this gene.

CardamomOT.inference.network.grad_theta(X, weights_samples, ys, ypr, yp, ypm, yk, ks, G, g, n_networks, n_samples, theta_ref, ref_network, l_pen, proba, weight_prev, loss, final, constrain_basal_uniform=0.0, basal_free_mask=None)

Gradient of objective w.r.t. X = theta.ravel().

CardamomOT.inference.network.objective_refinement(X, correc_ref, inter, basal, weights_samples, ys, ypr, yp, ypm, yk, ks, diag, G, g, n_networks, n_samples, l_pen, proba, weight_prev, loss, final)

Loss for the refinement step with per-sample basal.

correc shape: (G + n_samples, n_networks)

rows 0..G-1 : multiplicative corrections for inter rows G..G+ns-1 : multiplicative corrections for per-sample basal

basal : (n_samples, n_networks)

CardamomOT.inference.network.grad_correc(X, correc_ref, inter, basal, weights_samples, ys, ypr, yp, ypm, yk, ks, diag, G, g, n_networks, n_samples, l_pen, proba, weight_prev, loss, final)

Gradient of objective_refinement w.r.t. correction factors X.

CardamomOT.inference.network.core_inference(y_samples, y_proba, y_prot, y_prot_mod, y_kon, theta_init, theta_ref, ref_network, ks, G, g, n_networks, n_samples, proba, l_pen, weight_prev=0.5, loss='CE', final=0, constrain_basal_uniform=0.0, basal_free_mask=None, G_tol=None, hard_forcing_ref=False, ref_constraint_pct=0.1, seuil_min_network=0.01)

Joint L-BFGS-B optimisation of interactions + per-sample basals for one gene.

theta_init shape: (G + n_samples, n_networks)

rows 0..G-1 : interaction weights rows G..G+ns-1 : per-sample basal values

Returns theta_final of same shape.

CardamomOT.inference.network.refine_inference(y_samples, y_proba, y_prot, y_prot_mod, y_kon, inter, basal, theta_ref, ks, G, g, n_networks, n_samples, proba, l_pen, weight_prev=0.5, loss='CE', correc_ref=0, final=0, G_tol=None, hard_forcing_ref=False, ref_constraint_pct=0.1)

Refinement step: optimise multiplicative correction factors over inter and per-sample basal.

basal : (n_samples, n_networks) Returns updated (inter, basal).

CardamomOT.inference.network.main_loop_inference(g, y_samples, y_proba, y_prot, y_prot_mod, y_kon, theta_init, theta_ref, ks, G, n_networks, n_samples, proba, l_gen, scale, inter_tmp, basal_tmp, inter, basal, ref_network, weight_prev=0.5, loss='CE', final=0, constrain_basal_uniform=0.0, basal_free_mask=None, G_tol=None, hard_forcing_ref=False, ref_constraint_pct=0.1, seuil_min_network=0.01)

Joint inference (inter + per-sample basal) for a single gene g.

theta_init : (G + n_samples, n_networks) basal : (n_samples, n_networks) — will be updated in-place (copy returned) inter : (G, n_networks) — will be updated in-place (copy returned) basal_free_mask : (n_samples,) bool — True for samples NOT pinned by basal_ref for gene g Returns (basal, inter, basal_tmp, inter_tmp).

CardamomOT.inference.network.inference_network(y_samples, y_kon, y_proba, y_prot, y_prot_mod, ks, n_stimuli=1, proba=0, ref_network=None, basal_init=None, inter_init=None, basal_ref=None, inter_ref=None, scale=100, weight_prev=0.5, loss='CE', final=0, samples_id=None, constrain_basal_uniform=0.0, hard_forcing_ref=False, ref_constraint_pct=0.1, seuil_min_network=0.01) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Joint network inference: interactions shared across samples, basal per sample.

Returns (basal, inter, basal_tmp, inter_tmp). basal shape: (n_samples, G, n_networks)

constrain_basal_uniformfloat >= 0

When > 0, adds a penalty that pushes per-sample basals toward their common mean for each gene. Samples whose basal is pinned by a non-zero basal_ref (KO/OV priors) are excluded from the penalty for that gene.