harreman.tools.compute_cell_communication

harreman.tools.compute_cell_communication#

harreman.tools.compute_cell_communication(adata, layer_key_p_test=None, layer_key_np_test=None, model=None, center_counts_for_np_test=False, subset_gene_pairs=None, M=1000, seed=42, test='both', mean='algebraic', check_analytic_null=False, device=device(type='cpu'), verbose=False)[source]#

Computes spatially-informed cell-type-agnostic cell-cell communication (CCC) scores and significance across all gene pairs using both parametric and non-parametric statistical tests.

Parameters:

  • adata (AnnData) –

    Annotated data object. Required fields include:

    • uns[“gene_pairs”]: list of gene pairs to evaluate.

    • uns[“gene_pairs_per_metabolite”]: dictionary mapping metabolites to gene pairs.

    • obsp[“weights”]: sparse matrix encoding spatial cell-cell proximity.

    • (Optional) uns[“LR_database”]: interaction metadata for pathway annotation.

    • (Optional) uns[“sample_key”]: if modeling includes sample-specific factors.

  • layer_key_p_test (str or "use_raw", optional) – Data layer to use for the parametric test. If “use_raw”, uses adata.raw.

  • layer_key_np_test (str or "use_raw", optional) – Data layer to use for the non-parametric test. If “use_raw”, uses adata.raw.

  • model (str, optional) – Normalization model to use for centering gene expression. Options include “none”, “normal”, “bernoulli”, or “danb”.

  • center_counts_for_np_test (bool, optional (default: False)) – Whether to center expression counts using the specified model before non-parametric testing.

  • subset_gene_pairs (list, optional) – If provided, restricts the analysis to this subset of gene pairs.

  • M (int, optional (default: 1000)) – Number of permutations to use if permutation_test is True.

  • seed (int, optional (default: 42)) – Random seed for permutation reproducibility.

  • test ({'parametric', 'non-parametric', 'both'}, optional (default: 'both')) – Specifies which statistical test(s) to run.

  • mean ({'algebraic', 'geometric'}, optional (default: 'algebraic')) – Averaging method for multi-gene interactions.

  • check_analytic_null (bool, optional (default: False)) – Whether to evaluate Z-scores under an analytic null distribution using permutation Z-scores.

  • device (torch.device, optional) – PyTorch device to run computations on. Defaults to CUDA if available.

  • verbose (bool, optional (default: False)) – Whether to print progress and status messages.

Returns:

Results are stored in the following adata.uns fields:

  • uns[“ccc_results”][“p”]: Parametric test results (gene pair and metabolite scores, Z, p-values, FDR).

  • uns[“ccc_results”][“np”]: Non-parametric test results (communication scores, empirical p-values, FDR).

  • uns[“lc_zs”]: Symmetric matrix of ligand-receptor Z-scores across genes.

  • uns[“gene_pair_dict”]: Dictionary mapping metabolites to index positions of gene pairs.

  • uns[“D”]: Vector of total node degrees per cell (spatial connectivity).

  • uns[“genes”]: Ordered list of involved genes.

  • uns[“gene_pairs_ind”]: Index-referenced version of uns[“gene_pairs”].

Return type:

None