# mgriot/chemtools architecture

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

- Interactive diagram: https://gitdiagram.com/mgriot/chemtools
- Repository: https://github.com/mgriot/chemtools

## Overview

##### Project type and purpose
- chemtools is an open-source Python library for chemometric analyses.
- It provides a high-level API to perform data preprocessing, exploratory data analysis, regression modeling, clustering, classification, dimensionality reduction, and advanced plotting.

##### File structure
- Top-level directories/files:
– chemtools/ – the core package, divided into subpackages:
· base – abstract base classes/models
· preprocessing – data-cleaning and scaling routines
· exploration – PCA, MCA, canonical correlation
· clustering – hierarchical clustering
· classification – PCA-based classification
· dimensional_reduction – PCA, factor analysis, etc.
· regression – linear regression and diagnostic bands
· plots – unified plotting engine, backends (Matplotlib, Plotly), themes, subfolders by domain
– data/ – sample Excel files
– doc/ – user documentation and markdown guides
– Test/ – pytest-based tests mirroring each module
– CI configs (.github/workflows), environment.yml, requirements.txt
- Architectural cues: clear modular separation, layered design, test coverage aligned with modules.

##### Extract README insights
- Stacks on pandas, numpy, scikit-learn, statsmodels, Matplotlib, Plotly.
- Emphasizes unified plotting system with theme support.
- Highlights user-friendly interface for chemometric workflows.

a. Main components
– Data Input Layer: Excel/CSV readers, user data
– Preprocessing Module
– Analysis Modules:
· Exploration (PCA, MCA, GCCA)
· Dimensional Reduction (Extended PCA, Factor Analysis)
· Clustering (Hierarchical)
· Classification (PCA-based)
· Regression (Linear regression + diagnostics)
– Plotting Engine:
· Core Plotter API
· Backend drivers (Matplotlib, Plotly)
· Themes and presets
– External Dependencies: pandas, numpy, scikit-learn, statsmodels, Matplotlib, Plotly
b. Relationships and interactions
– Data flows from Data Input → Preprocessing → Analysis Modules → Plotting Engine → Output (figures, diagnostics)
– Each Analysis Module can tap Utility Services for helper functions
– Plotting Engine depends on Analysis Module outputs and Utility Services
– External Dependencies underpin Preprocessing, Analysis, and Plotting layers
c. Architectural patterns and principles
– Layered architecture: separation of concerns between data I/O, core computations, and visualization
– Modular plugin-style: each analysis type is a self-contained subpackage that can be extended
– Single unified plotting interface hides backend complexity
d. Key technologies and frameworks
– Python 3.x, pandas, numpy for data handling
– scikit-learn and statsmodels for statistical/machine learning
– Matplotlib and Plotly for plotting backends
– pytest for testing, GitHub Actions for CI

##### Final recommendations
- Provide a zoomed­in inset for the Plotting Engine showing Matplotlib vs. Plotly backends, theme system
- Iterate with stakeholders to ensure each component’s responsibility is clearly captured

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input Layer
    DataInput["Data Input Layer"]:::data
    click DataInput "https://github.com/mgriot/chemtools/tree/main/data/"

    %% Preprocessing Module
    Preprocessing["Preprocessing Module"]:::core
    click Preprocessing "https://github.com/mgriot/chemtools/tree/main/chemtools/preprocessing/"

    %% Base Models
    BaseModels["Base Models"]:::core
    click BaseModels "https://github.com/mgriot/chemtools/blob/main/chemtools/base/base_models.py"

    %% Utility Services
    UtilityServices["Utility Services"]:::utility
    click UtilityServices "https://github.com/mgriot/chemtools/tree/main/chemtools/utility/"

    %% Analysis Modules
    subgraph "Analysis Modules"
        Exploration["Exploration Module"]:::core
        click Exploration "https://github.com/mgriot/chemtools/tree/main/chemtools/exploration/"
        DimReduction["Dimensional Reduction Module"]:::core
        click DimReduction "https://github.com/mgriot/chemtools/tree/main/chemtools/dimensional_reduction/"
        Clustering["Clustering Module"]:::core
        click Clustering "https://github.com/mgriot/chemtools/blob/main/chemtools/clustering/HierarchicalClustering.py"
        Classification["Classification Module"]:::core
        click Classification "https://github.com/mgriot/chemtools/blob/main/chemtools/classification/PrincipalComponentClassificationAnalysis.py"
        subgraph RegressionGroup["Regression Module"]
            RegressionLR["LinearRegression"]:::core
            click RegressionLR "https://github.com/mgriot/chemtools/blob/main/chemtools/regression/LinearRegression.py"
            RegressionCB["Confidence Band"]:::core
            click RegressionCB "https://github.com/mgriot/chemtools/blob/main/chemtools/regression/confidence_band.py"
            RegressionPB["Prediction Band"]:::core
            click RegressionPB "https://github.com/mgriot/chemtools/blob/main/chemtools/regression/prediction_band.py"
        end
    end

    %% Plotting Engine
    subgraph "Plotting Engine"
        Plotter["Core Plotter API"]:::plotting
        click Plotter "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/Plotter.py"
        subgraph "Backends & Themes"
            PlotDendo["Dendrogram Plot"]:::plotting
            click PlotDendo "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/clustering/plot_dendogram.py"
            DimRedPlot["Dimensional Reduction Plot"]:::plotting
            click DimRedPlot "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/dimensional_reduction/dimensional_reduction_plot.py"
            PCAPlots["PCA Plots"]:::plotting
            click PCAPlots "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/exploration/pca_plots.py"
            MCAPlots["MCA Plots"]:::plotting
            click MCAPlots "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/exploration/mca_plots.py"
            RegPlots["Regression Plots"]:::plotting
            click RegPlots "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/regression/regression_plots.py"
            PlotUtils["Plot Utilities"]:::plotting
            click PlotUtils "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/utils.py"
            Violin["Violin Plot"]:::plotting
            click Violin "https://github.com/mgriot/chemtools/blob/main/chemtools/plots/violin.py"
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Pandas["pandas"]:::external
        Numpy["numpy"]:::external
        SKLearn["scikit-learn"]:::external
        Statsmodels["statsmodels"]:::external
        Matplotlib["Matplotlib"]:::external
        Plotly["Plotly"]:::external
    end

    %% Flow
    DataInput -->|"DataFrame"| Preprocessing
    Preprocessing -->|"Cleaned Data"| Exploration
    Preprocessing -->|"Cleaned Data"| DimReduction
    Preprocessing -->|"Cleaned Data"| Clustering
    Preprocessing -->|"Cleaned Data"| Classification
    Preprocessing -->|"Cleaned Data"| RegressionLR

    Exploration -->|"Model Object"| Plotter
    DimReduction -->|"Model Object"| Plotter
    Clustering -->|"Model Object"| Plotter
    Classification -->|"Model Object"| Plotter
    RegressionLR -->|"Model Object"| Plotter
    RegressionCB -->|"Diagnostic Model"| Plotter
    RegressionPB -->|"Diagnostic Model"| Plotter

    Plotter -->|"Figure"| Output["Output Figures/Diagnostics"]:::data

    %% Supporting relationships
    UtilityServices -.-> Exploration
    UtilityServices -.-> DimReduction
    UtilityServices -.-> Clustering
    UtilityServices -.-> Classification
    UtilityServices -.-> RegressionLR
    UtilityServices -.-> RegressionCB
    UtilityServices -.-> RegressionPB
    UtilityServices -.-> Plotter

    Pandas -.-> Preprocessing
    Numpy -.-> Preprocessing
    SKLearn -.-> Exploration
    SKLearn -.-> DimReduction
    SKLearn -.-> Clustering
    SKLearn -.-> Classification
    Statsmodels -.-> RegressionLR
    Statsmodels -.-> RegressionCB
    Statsmodels -.-> RegressionPB
    Matplotlib -.-> Plotter
    Plotly -.-> Plotter

    %% Styles
    classDef data fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef core fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef plotting fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef utility fill:#E0E0E0,stroke:#424242,color:#424242;
    classDef external fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A;
```
