CardamomOT.model.base

Core implementation of the NetworkModel used for inference and simulation.

This module defines the NetworkModel class which encapsulates parameters, state, and algorithms for fitting gene regulatory networks from single-cell expression data, performing stochastic or deterministic simulations, and managing mixture models. All documentation and comments are maintained in English.

Classes

NetworkModel

Encapsulates the state and parameters of a regulatory network.

Module Contents

class CardamomOT.model.base.NetworkModel(n_genes=None, n_stimuli=1, times=None)

Encapsulates the state and parameters of a regulatory network.

The class stores kinetic, mixture and network parameters as well as trajectories produced during inference. It provides methods for initialization, calibration and simulation used by the higher-level pipeline script.

core_binarization(data_rna, gene_names, vect_t, G_tot, min_components=1, max_components=5, refilter=0, max_iter_kinetics=100, cell_rd=None, verb=True, kov_cell_mask=None, scboolseq_matrix=None, scboolseq_dropouts=None)
Parameters:

  • cell_rd ((N_cells,) array or None)

  • kov_cell_mask ((N_cells, G_tot) int8 array or None) –

    Per-cell KO/OV constraints derived from KO_OV_inference.

    • -1: gene is KO for this cell (force to lowest mode)

    • +1: gene is OV for this cell (force to highest mode)

    • 0: no constraint

fit_mixture(data, refilter=0, gene_names=np.arange(1, 50000), min_components=2, max_components=2, max_iter_kinetics=0, cell_rd=None, verb=True, stimulus_schedule=None, time_key='time', kov_cell_mask=None)

Fit the mixture model parameters to the data.

Parameters:

  • cell_rd ((N_cells,) array, pd.Series, ou None) – Facteurs de read depth par cellule, typiquement issus de adata.obs[‘rd’] (calculés par infer_rd.py). Si None, le modèle NB classique sans correction est utilisé.

  • depth:: (Exemple d'appel avec correction de read) – rd = np.asarray(adata.obs[‘rd’]) model.fit_mixture(data_rna, …, cell_rd=rd)

estimate_trajectories_given_model(vect_t, times, vect_samples_id, samples_id, vect_rna, y_prot_old, prot_formodes, y_kon_old, y_rna_old, y_proba_old, alpha_old, vect_samples_id_modified, basal, inter, s1, ks, nb_cells, init_cells, R_opt_traj, to_keep_for_update, offset_init=[0], n_iter=1, N_full=[100], N_samples=[100], intensity_prior=10)

Infer the protein trajectories when d1 is known and theta is not.

loop_trajectories(data_rna, vect_t, vect_samples_id, times, samples_id, ks, s1, init_cells_full, nb_cells, N_full, N_samples, G_tot, min_n_loops, count_max, intensity_prior, basal_init=None, inter_init=None, basal_ref=None, inter_ref=None, verb=True, compute_theta=True, initialize_alpha=True, kov_cell_mask=None, hard_forcing_ref=False, ref_constraint_pct=0.1)

Alternating optimization of trajectories and network (theta).

basal_init / inter_init(G_tot, n_networks) / (G_tot, G_tot, n_networks) or None

Starting point for theta. Zeros if None.

kov_cell_mask(N_cells, G_tot) int8 array or None

Per-cell KO/OV constraints. -1 → KO (force lowest mode), +1 → OV (force highest mode), 0 → no constraint. Applied after each update_modes step as a hard override.

basal_ref / inter_refsame shape or None

Regularization target passed to inference_network. Zeros if None (no prior).

fit_network(data, intensity_prior=10, vect_samples_id=None, basal_init=None, inter_init=None, basal_ref=None, inter_ref=None, verb=True, stimulus_schedule=None, transition_rates=None, time_key='time', hard_forcing_ref=None, ref_constraint_pct=None)

Fit the gene regulatory network to the RNA expression data.

Parameters:

  • data (ndarray or AnnData) – RNA expression matrix (cells × genes).

  • intensity_prior (float) – Regularization intensity for optimal transport.

  • vect_samples_id (ndarray or None) – Array of sample labels (same size as data), or None if only one sample.

  • basal_init (ndarray or None) – Initial basal rates: shape (G,) broadcast to all networks, or (G, n_networks).

  • inter_init (ndarray or None) – Initial interaction matrix: shape (G, G) or (G, G, n_networks).

  • basal_ref (ndarray or None) – Regularization target for basal rates, same shape rules as basal_init. Defaults to zeros (no penalization towards a prior).

  • inter_ref (ndarray or None) – Regularization target for interactions, same shape rules as inter_init. Defaults to zeros.

  • verb (bool) – Whether to print progress.

estimate_trajectories(y_prot, times, d1, N=100, kon_beta=None, s=None)

Estimate protein trajectories when d1, theta, and alpha are known.

Parameters:

  • kon_beta (array of shape (T*N, G_tot), optional) – Pre-computed burst frequencies. If None, uses self.kon_beta.

  • s (float or array of shape (G_genes,), optional) – Per-gene protein scale. Defaults to self.scale_proteins. Must match the s used in my_otdistance when building y_prot; pass s to reproduce protein trajectories exactly.

refine_network_degradations(verb=True, stimulus_schedule=None, test=False)

Refine network parameters and infer degradation rates for simulation.

When test=True, only runs the trajectory estimation step and recomputes kon_theta using the current (pre-loaded simul) network. No inference, MLP training, or parameter update is performed.

simulate_trajectories_unitary(times, times_train, ks, N=100, verb=True, samples_data=None)

Simulate protein trajectories with unitary scale

simulate_trajectories_full(times, times_train, ks, N=100, verb=True, samples_data=None)

Simulate protein AND mRNA trajectories using the Harissa bursty PDMP.

Uses the inferred basal_t / inter_t (in absolute burst-rate units when simulate_full_with_harissa=True) as the Harissa network. Mimics simulate_trajectories_unitary but returns mRNA levels in addition to proteins. Only supports ns == 1.

Returns:

  • prot_modified ((N * len(times), G_tot))

  • mrna_modified ((N * len(times), G_tot))

  • kon_vector ((N * len(times), G_tot))

  • times_simulation ((N * len(times),))

simulate_network(times, verb=True, stimulus_schedule=None)

Simulate the protein trajectories using the final inferred network.

fit_mixture_test(data_rna, ks, c, verb=False)

Classify test cells into mixture modes using fixed kinetic parameters.

Sets self.modes, self.proba, self.proba_init, and self.pi_init so that update_modes in loop_trajectories works on test data without re-fitting kz/c.

infer_test(data, vect_samples_id=None, verb=True, stimulus_schedule=None, basal_ref=None, transition_rates=None, time_key='time')

Run inference pipeline on test data: kon estimation, trajectory inference, and alpha initialization.

basal_ref(n_samples, G_tot, n_networks) array or None

Per-sample KO/OV prior (±100 entries) used to build kov_cell_mask.

transition_ratesDataFrame or array or None

Cell-type transition rate matrix for OT cost adjustment.