# m2aia/pym2aia architecture

> Architecture diagram of the GitHub repository m2aia/pym2aia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m2aia/pym2aia
- Repository: https://github.com/m2aia/pym2aia

## Overview

##### Project type and purpose
- This is a Python library (pyM2aia) for mass spectrometry imaging (MSI) data access, signal processing, and batch generation. It exposes a high-level Python API and wraps a native C++ MITK-based backend for reading/writing imzML files and performing heavy-duty processing.

##### File structure
- src/m2aia/
- ImageIO.py – imzML reader/writer interface
- Dataset.py, Library.py – high-level data structures
- Generators.py – base batch-generation classes
- src/m2aia/keras & src/m2aia/torch
- Framework-specific batch generators (TensorFlow/PyTorch)
- src/m2aia/utils – signal-processing utilities (binning, peaks, volcano plot)
- setup.py, requirements.txt – packaging and dependencies
- tests/ – integration and unit tests with sample data
- docs/ – Sphinx documentation

##### README for additional insights
- Core features: imzML I/O, baseline correction, normalization, smoothing, batch generators, continuous centroid writing
- External dependencies: SimpleITK for image handling, TensorFlow and PyTorch for training pipelines, native MITK/C++ libraries via m2PythonWrapper

##### Main components
a. Python API Layer (green)
- m2aia.ImageIO – ImzMLReader/Writer
- m2aia.Dataset & m2aia.Library – data abstractions
- m2aia.Generators – abstract BatchGenerator
- m2aia.keras.KerasGenerators & m2aia.torch.PyTorchGenerators – framework-specific generators
- m2aia.utils – signal-processing modules (binning, peaks, volcano)

b. Native Backend Layer (blue)
- C++ MITK-based core libraries (libMitkXY.so/.dll)
- m2PythonWrapper.cpp – SWIG/pybind11 wrapper that exposes C++ to Python

c. External Dependencies (orange)
- SimpleITK – grayscale image objects
- TensorFlow / PyTorch – model training loops consuming batch generators
- imzML files (input) and continuous centroid imzML (output)

##### Relationships and data flow
1. User code calls Python API (ImzMLReader)
2. Python API invokes C++ backend via m2PythonWrapper
3. C++ backend reads imzML metadata/spectra and returns image arrays (SimpleITK objects)
4. Python utilities apply baseline correction, normalization, smoothing
5. BatchGenerators fetch data (spatial, spectral, spatio-spectral) either in-memory or streaming from disk
6. Generators feed TensorFlow or PyTorch training pipelines
7. Python API calls WriteContinuousCentroidImzML → forwards to C++ writer → outputs imzML file

##### Architectural patterns and design principles
- Layered architecture:
- Presentation (Python API)
- Processing (Python utilities & generators)
- Persistence/IO (C++ MITK libraries)
- Separation of concerns: distinct modules for I/O, processing, and framework integration
- Adapter/Wrapper pattern: m2PythonWrapper exposes native C++ to Python seamlessly
- Strategy pattern: interchangeable signal-processing functions and batch-generator backends

##### Details to capture
- Package entry points (m2aia/__init__.py) and setup scripts
- CI workflows (.github/workflows) and test harness (tests/) as auxiliary components
- Config files (requirements.txt, .devcontainer) ensuring reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python API Layer
    subgraph "Python API Layer"
        IO["m2aia.ImageIO\n(ImzML Reader/Writer)"]:::python
        DS["m2aia.Dataset\n(Data Abstraction)"]:::python
        LIB["m2aia.Library\n(Library Abstraction)"]:::python
        GEN["m2aia.Generators\n(Abstract BatchGenerator)"]:::python
        KG["m2aia.keras.KerasGenerators"]:::python
        PG["m2aia.torch.PyTorchGenerators"]:::python
    end

    %% Processing & Utilities Layer
    subgraph "Processing & Utilities Layer"
        BIN["utils.binning"]:::processing
        PEA["utils.peaks"]:::processing
        VOL["utils.volcano"]:::processing
    end

    %% Native Backend Layer
    subgraph "Native Backend Layer"
        CPP["C++ MITK Core\n(libMitkXY)"]:::native
        WR["m2PythonWrapper.cpp\n(SWIG/pybind11)"]:::native
        IMZ["imzML Files\n(Input/Output)"]:::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        SITK["SimpleITK"]:::external
        TF["TensorFlow"]:::external
        PT["PyTorch"]:::external
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        SETUP["setup.py"]:::aux
        REQ["requirements.txt"]:::aux
        DOC1["docs/m2aia.rst"]:::aux
        DOC2["docs/m2aia.keras.rst"]:::aux
        DOC3["docs/m2aia.utils.rst"]:::aux
        TESTS["tests/"]:::aux
    end

    %% Data Flow & Relationships
    IMZ -->|read/write| IO
    IO -->|invoke| WR
    WR -->|bindings| CPP
    CPP -->|image arrays| SITK
    IO -->|raw data| BIN
    IO -->|raw data| PEA
    IO -->|raw data| VOL
    BIN -->|processed data| GEN
    PEA -->|processed data| GEN
    VOL -->|processed data| GEN
    DS -->|data model| GEN
    LIB -->|data model| GEN
    GEN -->|batch stream| KG
    GEN -->|batch stream| PG
    KG -->|training loop| TF
    PG -->|training loop| PT
    GEN -->|write continuous centroid| IO

    %% Click Events
    click IO "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/ImageIO.py"
    click DS "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/Dataset.py"
    click LIB "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/Library.py"
    click GEN "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/Generators.py"
    click KG "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/keras/KerasGenerators.py"
    click PG "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/torch/PyTorchGenerators.py"
    click BIN "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/utils/binning.py"
    click PEA "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/utils/peaks.py"
    click VOL "https://github.com/m2aia/pym2aia/blob/main/src/m2aia/utils/volcano.py"
    click SETUP "https://github.com/m2aia/pym2aia/blob/main/setup.py"
    click REQ "https://github.com/m2aia/pym2aia/blob/main/requirements.txt"
    click DOC1 "https://github.com/m2aia/pym2aia/blob/main/docs/m2aia.rst"
    click DOC2 "https://github.com/m2aia/pym2aia/blob/main/docs/m2aia.keras.rst"
    click DOC3 "https://github.com/m2aia/pym2aia/blob/main/docs/m2aia.utils.rst"
    click TESTS "https://github.com/m2aia/pym2aia/tree/main/tests/"

    %% Styles
    classDef python fill:#b2f5ea,stroke:#2c7a7b,color:#1a202c;
    classDef processing fill:#f0fff4,stroke:#38a169,color:#22543d;
    classDef native fill:#bee3f8,stroke:#2b6cb0,color:#2c5282;
    classDef external fill:#fefcbf,stroke:#dd6b20,color:#65350f;
    classDef aux fill:#e2e8f0,stroke:#4a5568,color:#1a202c;
```
