cellink.tl.external.infer_livi

cellink.tl.external.infer_livi(adata_or_dd, checkpoint_path, *, individual_col=None, layer_key=None, batch_size=50000, variance_threshold=None, device=None, runner=None)

Extract latent factors from a trained LIVI model.

Runs batch-wise inference to obtain cell-state latent factors for every cell and donor-level embeddings for every unique individual.

Parameters:

• adata_or_dd (AnnData or DonorData) – Single-cell data to perform inference on. Uses dd.C when DonorData is provided. The data should contain the same donors (in the same factorisation order) as the training data so that donor embedding indices align with the trained model.

• checkpoint_path (str) – Path to a LIVI .ckpt checkpoint file.

• individual_col (str, optional) – Column in adata.obs with donor IDs. Auto-inferred from DonorData.

• layer_key (str, optional) – Layer key for raw counts. If None, uses adata.X.

• batch_size (int) – Cells per inference batch (default 50 000).

• variance_threshold (float, optional) – When set, only D factors with cross-donor variance ≥ this threshold are retained in the returned "D_embedding" DataFrame.

• device (str, optional) – Override device for inference ("cpu" or "cuda"). Defaults to the runner’s device.

• runner (LIVIRunner, optional) – Runner instance. Uses the global runner when None.

Return type:

dict[str, DataFrame]

Returns:

dict Dictionary with the following DataFrames (keys absent when the corresponding model component was not trained):

"cell_state_latent"

(n_cells × z_dim) — cell-state latent factors per cell.

"cell_state_decoder"

(n_genes × z_dim) — gene loadings of the cell-state decoder.

"D_embedding"

(n_donors × n_DxC) — donor × cell-state interaction embeddings.

"DxC_decoder"

(n_genes × n_DxC) — gene loadings of the DxC decoder.

"V_embedding"

(n_donors × n_persistent) — persistent donor factor embeddings.

"V_decoder"

(n_genes × n_persistent) — gene loadings of the V decoder.

"assignment_matrix"

(z_dim × n_DxC) — assignment matrix A mapping cell-state factors to DxC factors.

Examples

>>> results = cl.tl.external.infer_livi(dd, "livi_out/checkpoints/best.ckpt")
>>> cell_state = results["cell_state_latent"]  # cells × z_dim
>>> D_embed = results["D_embedding"]  # donors × DxC