ArchetypAX Architecture

Package Structure

ArchetypAX is organized into a modular structure to enhance maintainability and extensibility:

archetypax/
├── __init__.py              # Package initialization and exports
├── models/                  # Core model implementations
│   ├── __init__.py          # Models namespace
│   ├── base.py              # Base archetypal analysis implementation
│   ├── archetypes.py        # Improved archetypal analysis implementation
│   ├── biarchetypes.py      # Biarchetypal analysis implementation
│   └── sparse_archetypes.py # Sparse archetypal analysis implementation
└── tools/                   # Utility modules
    ├── __init__.py          # Tools namespace
    ├── evaluation.py        # Evaluation metrics and analysis
    ├── interpret.py         # Interpretation methods
    ├── tracker.py           # Archetype optimization tracking utilities
    └── visualization.py     # Visualization utilities

Design Philosophy

The package follows a modular design with clear separation of concerns:

1. Core Models (models/): Contains the fundamental algorithmic implementations of archetypal analysis variants.

   • base.py: Provides the foundational implementation with essential functionality

   • archetypes.py: Extends the base with improved optimization and features

   • biarchetypes.py: Implements the dual-archetype approach for more expressive modeling

   • sparse_archetypes.py: Implements the sparse archetypal analysis

2. Utility Tools (tools/): Houses supporting functionality for analysis and visualization.

   • evaluation.py: Metrics and methods to assess model quality and performance

   • interpret.py: Methods to interpret and explain model results

   • tracker: Archetypes tracking

   • visualization.py: Comprehensive visualization tools for model exploration

Import Patterns

ArchetypAX supports multiple import patterns for flexibility:

Direct Class Imports

from archetypax import ArchetypalAnalysis, ImprovedArchetypalAnalysis

Explicit Module Imports

from archetypax.models.base import ArchetypalAnalysis
from archetypax.tools.evaluation import ArchetypalAnalysisEvaluator

Module-Level Imports

from archetypax.models import ArchetypalAnalysis
from archetypax.tools import ArchetypalAnalysisVisualizer

Backward Compatibility

The package maintains backward compatibility with code written for earlier versions through a transparent module aliasing system. This ensures that existing code continues to function without modification while encouraging the adoption of the new, more organized structure for new development.