peach.tl.pattern_analysis

peach.tl.pattern_analysis#

peach.tl.pattern_analysis(adata, *, data_obsm_key='pathway_scores', obs_key='archetypes', include_individual_tests=True, include_pattern_tests=True, include_exclusivity_analysis=True, verbose=True, **kwargs)[source]#

Comprehensive archetypal pattern analysis.

Performs systematic analysis combining three complementary approaches:

  1. Individual tests: Standard 1-vs-all archetype characterization

  2. Pattern tests: Systematic archetype combination testing (specialists, binary tradeoffs, complex patterns)

  3. Exclusivity analysis: Features with opposing patterns

Parameters:

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

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

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

  • include_individual_tests (bool, default: True) – Run individual archetype 1-vs-all tests.

  • include_pattern_tests (bool, default: True) – Run systematic pattern tests (specialists, tradeoffs).

  • include_exclusivity_analysis (bool, default: True) – Analyze mutual exclusivity patterns.

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

Returns:

Dictionary with keys:

  • 'individual' : Individual archetype results

  • 'patterns' : Pattern-based test results

  • 'exclusivity' : Mutual exclusivity results

Return type:

dict[str, pd.DataFrame]

Notes

Pattern Types in ‘patterns’ DataFrame:

  • specialization : Archetype vs archetype_0 (centroid)

  • tradeoff : Multi-archetype high vs low groups

Pattern Code Format: “12xxx_xx345”

  • Position = archetype number (0, 1, 2…)

  • Numbers = high archetypes

  • ‘x’ = low archetypes

  • Underscore separates high from low group

Examples

>>> # Run comprehensive analysis
>>> results = pc.tl.pattern_analysis(adata)
>>> # Access individual results
>>> individual = results["individual"]
>>> # Find specialists (exclusive to one archetype)
>>> patterns = results["patterns"]
>>> specialists = patterns[patterns["pattern_type"] == "specialization"]
>>> # Find mutual exclusivity patterns
>>> if not results["exclusivity"].empty:
...     exclusive = results["exclusivity"]
...     top_tradeoffs = exclusive.nlargest(10, "effect_range")

See also

peach.tl.archetype_exclusive_patterns

Focused exclusive pattern analysis

peach.tl.specialization_patterns

Centroid comparison analysis

peach.tl.tradeoff_patterns

Mutual exclusivity analysis

peach._core.types.ComprehensivePatternResults

Return type structure