peach.tl.tradeoff_patterns

peach.tl.tradeoff_patterns#

peach.tl.tradeoff_patterns(adata, *, data_obsm_key='pathway_scores', obs_key='archetypes', tradeoffs='pairs', test_method='mannwhitneyu', fdr_method='benjamini_hochberg', fdr_scope='global', min_cells=10, min_effect_size=0.1, verbose=True, **kwargs)[source]#

Identify mutual exclusivity and tradeoff patterns.

Finds features showing opposing patterns between archetypes, indicating biological tradeoffs or mutually exclusive states.

Parameters:

  • adata (AnnData) – Annotated data object with archetypal assignments.

  • data_obsm_key (str, default: "pathway_scores") – Key in adata.obsm for scores.

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

  • tradeoffs ({'pairs', 'patterns'}, default: 'pairs') –

    Type of tradeoff analysis:

    • 'pairs' : Binary pairwise (A high, B low)

    • 'patterns' : Complex multi-archetype (AB high, CD low)

  • test_method (str, default: "mannwhitneyu") – Statistical test method.

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

  • fdr_scope ({'global', 'per_archetype', 'none'}, default: 'global') – Scope of FDR correction.

  • min_cells (int, default: 10) – Minimum cells per group.

  • min_effect_size (float, default: 0.1) – Minimum effect size for tradeoffs.

  • verbose (bool, default: True) – Print progress.

  • **kwargs –

    Additional parameters:

    • max_pattern_sizeint, default: 2

      Maximum archetypes per group for complex patterns.

    • exclude_archetype_0bool, default: True

      Exclude archetype_0 from tradeoff patterns.

    • specific_patternsList[str], optional

      Test only specific patterns (e.g., [‘2v3’, ‘1v45’]).

Returns:

Results with tradeoff patterns:

  • pattern_code : Visual pattern code

  • high_archetypes, low_archetypes : Groups

  • mean_high, mean_low : Group means

  • log_fold_change : Effect size

  • pattern_complexity : Number of archetypes involved

Return type:

pd.DataFrame

Examples

>>> # Find pairwise tradeoffs
>>> pairs = pc.tl.tradeoff_patterns(adata, tradeoffs="pairs")
>>> # Find complex patterns
>>> patterns = pc.tl.tradeoff_patterns(adata, tradeoffs="patterns", max_pattern_size=3)
>>> # Test specific hypothesis
>>> specific = pc.tl.tradeoff_patterns(adata, specific_patterns=["2v3", "1v4"])

See also

peach.tl.archetype_exclusive_patterns

Exclusive pattern analysis

peach._core.types.PatternAssociationResult

Result row structure