# bayer-group/mocca architecture

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

- Interactive diagram: https://gitdiagram.com/bayer-group/mocca
- Repository: https://github.com/bayer-group/mocca

## Overview

##### Project type and purpose
- MOCCA2 is an open-source Python library and CLI tool for automatic processing of HPLC chromatograms.
- Purpose: ingest raw chromatogram data (Agilent, Shimadzu, Waters), apply baseline correction, peak picking, deconvolution, clustering, and output results (plots, data objects).

##### File structure
- src/mocca2/… – core Python packages broken into subpackages:
- parsers – raw data file readers
- baseline – baseline-correction algorithms
- peaks – peak-finding and splitting
- deconvolution – deconvolution routines & models
- clustering – component clustering across runs
- classes – data models (Chromatogram, Peak, Component, etc.)
- dataset – dataset loader and settings
- example_data – data downloader+loaders
- serializing – saving/loading processed results
- __main__.py – CLI entrypoint (`python -m mocca2`)
- tests/ – unit tests for each component
- examples/ – sample scripts exercising the API
- docs/ – Sphinx documentation sources
- GitHub workflows – CI, docs deployment, packaging, PyPI publishing

##### README for additional insights
- Describes workflows:
- local API usage & example workflows
- automated testing on push
- docs build & GitHub Pages publication
- example data branch and download command
- PyPI publishing

##### Main components and interactions
a. Core Components
1. CLI / API Layer (src/mocca2/__main__.py)
2. Parsers (raw file → Chromatogram object)
3. Baseline Correction (Chromatogram → corrected Chromatogram)
4. Peak Picking (Chromatogram → Chromatogram+Peak list)
5. Deconvolution (Chromatogram + Peak list → DeconvolvedPeak list)
6. Clustering (multiple Chromatograms → tracked Components)
7. Serialization (persist processed data to disk)
8. Example Data Loader (download & unpack from example-data branch)
9. Data Models (Chromatogram, Peak, Component, Dataset)
b. External Dependencies & Services
- Python scientific stack (numpy, scipy, matplotlib, pandas)
- PyPI (package distribution)
- GitHub Actions (CI, docs, packaging)
- GitHub Pages (documentation hosting)
c. Data Flows & Relationships
- Raw files → Parsers → Chromatogram objects
- Chromatogram → Baseline → Filtered Chromatogram
- Filtered Chromatogram → Peak Picking → Chromatogram+Peaks
- Chromatogram+Peaks → Deconvolution → Chromatogram+DeconvolvedPeaks
- Multiple Chromatograms → Clustering → Component tracking
- Processed objects → Serialization → Re-loadable files
- CLI or Python API orchestrates above steps

##### Architectural patterns and design principles
- Modular subpackages following single responsibility principle
- Data model objects (Chromatogram, Peak) encapsulate state + behavior
- Pipeline design: each processing step returns enriched object
- Extensibility: wrapper modules for new parsers, baseline methods, deconvolution models
- CLI entrypoint vs. library API separation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Processing Pipeline
    subgraph "Core Processing"
        CLI["CLI / API Layer"]:::core
        Parsers["Parsers"]:::core
        Baseline["Baseline Correction"]:::core
        Peaks["Peak Picking"]:::core
        Deconv["Deconvolution"]:::core
        Clustering["Clustering"]:::core
        Serialization["Serialization"]:::core
        ProcessedData["Serialized Data"]:::storage
    end

    %% Data Models
    subgraph "Data Models"
        Chrom["Chromatogram"]:::model
        PeakModel["Peak"]:::model
        DeconvPeak["DeconvolvedPeak"]:::model
        Component["Component"]:::model
        Compound["Compound"]:::model
        Data2D["Data2D"]:::model
    end

    %% Example Data Loader
    subgraph "Example Data"
        ExampleData["Example Data Loader"]:::core
        ExampleRepo["Example Data Repo"]:::storage
    end

    %% Utilities
    subgraph "Utilities"
        Math["math.py"]:::util
        Exceptions["exceptions.py"]:::util
    end

    %% Dataset Loader
    Dataset["Dataset Loader & Settings"]:::core

    %% External Services
    subgraph "External Services"
        PythonStack["Python Stack"]:::external
        PyPI["PyPI"]:::external
        GitHubActions["GitHub Actions"]:::external
        GitHubPages["GitHub Pages"]:::external
    end

    %% Pipeline Connections
    CLI --> Parsers
    Parsers --> Baseline
    Baseline --> Peaks
    Peaks --> Deconv
    Deconv --> Clustering
    Clustering --> Serialization
    Serialization --> ProcessedData

    %% Data Model Flows
    Parsers --> Chrom
    Baseline --> Chrom
    Peaks --> PeakModel
    Deconv --> DeconvPeak
    Clustering --> Component

    %% Example Data Flow
    CLI --> ExampleData
    ExampleData --> ExampleRepo

    %% Dataset Loader Flow
    CLI --> Dataset

    %% Utility Dependencies
    Parsers --> Math
    Baseline --> Math
    Peaks --> Math
    Deconv --> Math
    Clustering --> Math
    Parsers --> Exceptions
    Baseline --> Exceptions

    %% CI/CD & Publication
    GitHubActions --> PyPI
    GitHubActions --> GitHubPages
    CLI --> PythonStack

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef model fill:#E6FFED,stroke:#22863A,stroke-width:1px
    classDef external fill:#FFF5B1,stroke:#D69D00,stroke-width:1px
    classDef util fill:#F0F0F0,stroke:#6A737D,stroke-width:1px
    classDef storage fill:#FBEFEF,stroke:#D73A49,stroke-width:1px

    %% Click Events
    click CLI "https://github.com/bayer-group/mocca/blob/main/src/mocca2/__main__.py"
    click Parsers "https://github.com/bayer-group/mocca/tree/main/src/mocca2/parsers/"
    click Baseline "https://github.com/bayer-group/mocca/tree/main/src/mocca2/baseline/"
    click Peaks "https://github.com/bayer-group/mocca/tree/main/src/mocca2/peaks/"
    click Deconv "https://github.com/bayer-group/mocca/tree/main/src/mocca2/deconvolution/"
    click Clustering "https://github.com/bayer-group/mocca/blob/main/src/mocca2/clustering/cluster_components.py"
    click Serialization "https://github.com/bayer-group/mocca/blob/main/src/mocca2/serializing.py"
    click ExampleData "https://github.com/bayer-group/mocca/tree/main/src/mocca2/example_data/"
    click ExampleRepo "https://github.com/bayer-group/mocca/tree/main/src/mocca2/example_data/data/"
    click Dataset "https://github.com/bayer-group/mocca/tree/main/src/mocca2/dataset/"
    click Math "https://github.com/bayer-group/mocca/blob/main/src/mocca2/math.py"
    click Exceptions "https://github.com/bayer-group/mocca/blob/main/src/mocca2/exceptions.py"
    click DataModels "https://github.com/bayer-group/mocca/tree/main/src/mocca2/classes/"
```
