peach.tl.conditional_associations

peach.tl.conditional_associations#

peach.tl.conditional_associations(adata, *, obs_column, archetype_assignments=None, obs_key='archetypes', test_method='hypergeometric', fdr_method='benjamini_hochberg', min_cells=5, verbose=True, **kwargs)[source]#

Test associations between archetypes and categorical metadata.

Performs hypergeometric tests to identify significant enrichment of archetypes within different categorical conditions (samples, treatments, cell types, etc.).

Parameters:

  • adata (AnnData) –

    Annotated data object with:

    • obs[obs_key] : Archetype assignments

    • obs[obs_column] : Categorical variable to test

  • obs_column (str) – Column name in adata.obs containing categorical variable.

  • archetype_assignments (None, optional) – Deprecated. Archetype assignments now read from adata.obs[obs_key].

  • obs_key (str, default: "archetypes") – Column in adata.obs containing archetypal assignments.

  • test_method (str, default: "hypergeometric") – Statistical test method (currently only ‘hypergeometric’).

  • fdr_method (str, default: "benjamini_hochberg") – FDR correction method.

  • min_cells (int, default: 5) – Minimum cells required per archetype-condition combination.

  • verbose (bool, default: True) – Whether to print progress.

Returns:

Results with columns:

  • archetype : str - Archetype identifier

  • condition : str - Condition value from obs_column

  • observed : int - Observed count in overlap

  • expected : float - Expected count under null

  • total_archetype : int - Total cells in archetype

  • total_condition : int - Total cells in condition

  • odds_ratio : float - Enrichment measure (>1 = enriched)

  • ci_lower : float - Lower 95% CI for odds ratio

  • ci_upper : float - Upper 95% CI for odds ratio

  • pvalue : float - Hypergeometric p-value

  • fdr_pvalue : float - FDR-corrected p-value

  • significant : bool - Whether significant

Return type:

pd.DataFrame

Examples

>>> # Test sample associations
>>> results = pc.tl.conditional_associations(adata, obs_column="sample")
>>> # Find enriched archetypes per condition
>>> enriched = results[(results["significant"]) & (results["odds_ratio"] > 2)]
>>> # Test treatment effects
>>> treatment_results = pc.tl.conditional_associations(adata, obs_column="treatment")

See also

peach._core.types.ConditionalAssociationResult

Result row structure