# idslme/idsl_mint architecture

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

- Interactive diagram: https://gitdiagram.com/idslme/idsl_mint
- Repository: https://github.com/idslme/idsl_mint

## Overview

##### Project type and purpose
- This is a Python-based command-line data-processing and modeling framework (no GUI frontend) for mass-spectrometry interpretation.
- It implements three parallel “pipelines” (MS2FP, MS2SMILES, FP2MS), each driven by transformer models, to translate between MS/MS spectra, molecular fingerprints, and canonical SMILES.
- Configuration and orchestration are YAML-driven via a single CLI entrypoint `MINT_workflow`.

##### File structure
- Top-level:
- `IDSL_MINT_workflow.py` (CLI entrypoint)
- `setup.py`, `environment.yml` (install & environment)
- `YAML/` (six trainer/predictor config files)
- `IDSL_MINT/` (package root)
- Inside `IDSL_MINT/`:
- Three pipeline folders: `MS2FP/`, `MS2SMILES/`, `FP2MS/`
– Each contains: Assembler, DataLoader, Dataset, Model, training_function, yaml_trainer, yaml_predictor, msp_pickler
- `utils/`: reusable data-parsing, fingerprint, plotting, logging, mask-generation modules
- `IDSL_MINT_workflow.py`: inspects the YAML, dispatches to the correct pipeline
- Notice:
- Pattern: “YAML → workflow dispatcher → pipeline module → data loader & assembler → PyTorch Dataset → Transformer Model → training/inference → pickling & logging”
- External config = YAML files; external data = MSP files; external libs = PyTorch, RDKit.

##### Key README insights
- Three core use-cases:
a. MS/MS → molecular fingerprints (MS2FP)
b. MS/MS → SMILES (MS2SMILES)
c. Fingerprints/SMILES → MS/MS (FP2MS)
- Single CLI command: `MINT_workflow --yaml /path/to/xxx.yaml`
- Device-agnostic (CPU/GPU) via PyTorch; MSP parsing tolerant of different headers; YAML files define hyperparameters, file paths, beam search, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "CLI & Config Layer"
    CLI["MINT_workflow"]:::cli
    YAML["YAML Config Files"]:::config
  end

  CLI -->|"reads config"| YAML
  CLI -->|"invokes"| OCI
  YAML -->|"drives"| CLI

  OCI["Config Loader & Dispatcher"]:::orchestration

  subgraph "Pipeline Modules"
    direction TB

    subgraph "MS2FP Pipeline" 
      MS2FP_DL["DataLoader"]:::pipeline
      MS2FP_ASM["Assembler"]:::pipeline
      MS2FP_DS["Dataset"]:::pipeline
      MS2FP_MDL["Transformer Model"]:::pipeline
      MS2FP_TRN["TrainingFunction"]:::pipeline
      MS2FP_PRD["Predictor"]:::pipeline
      MS2FP_PKL["MSP Pickler"]:::io
    end

    subgraph "MS2SMILES Pipeline"
      MS2SM_DL["DataLoader"]:::pipeline
      MS2SM_ASM["Assembler"]:::pipeline
      MS2SM_DS["Dataset"]:::pipeline
      MS2SM_MDL["Transformer Model"]:::pipeline
      MS2SM_TRN["TrainingFunction"]:::pipeline
      MS2SM_PRD["Predictor"]:::pipeline
      MS2SM_PKL["MSP Pickler"]:::io
    end

    subgraph "FP2MS Pipeline"
      FP2MS_DL["DataLoader"]:::pipeline
      FP2MS_ASM["Assembler"]:::pipeline
      FP2MS_DS["Dataset"]:::pipeline
      FP2MS_MDL["Transformer Model"]:::pipeline
      FP2MS_TRN["TrainingFunction"]:::pipeline
      FP2MS_PRD["Predictor"]:::pipeline
      FP2MS_PKL["MSP Pickler"]:::io
    end

  end

  OCI --> MS2FP_DL
  OCI --> MS2SM_DL
  OCI --> FP2MS_DL

  MS2FP_DL -->|"raw .msp"| MS2FP_ASM
  MS2FP_ASM -->|"tokens & features"| MS2FP_DS
  MS2FP_DS -->|"batches"| MS2FP_TRN
  MS2FP_TRN -->|"updates model"| MS2FP_MDL
  MS2FP_MDL -->|"predictions"| MS2FP_PRD
  MS2FP_PRD -->|"results"| MS2FP_PKL

  MS2SM_DL -->|"raw .msp"| MS2SM_ASM
  MS2SM_ASM -->|"tokens & features"| MS2SM_DS
  MS2SM_DS -->|"batches"| MS2SM_TRN
  MS2SM_TRN -->|"updates model"| MS2SM_MDL
  MS2SM_MDL -->|"predictions"| MS2SM_PRD
  MS2SM_PRD -->|"results"| MS2SM_PKL

  FP2MS_DL -->|"fingerprints/SMILES"| FP2MS_ASM
  FP2MS_ASM -->|"tokens & features"| FP2MS_DS
  FP2MS_DS -->|"batches"| FP2MS_TRN
  FP2MS_TRN -->|"updates model"| FP2MS_MDL
  FP2MS_MDL -->|"predictions"| FP2MS_PRD
  FP2MS_PRD -->|"results"| FP2MS_PKL

  subgraph "Utilities" 
    LOG["MINT_logRecorder"]:::utils
    FPR["MINT_fingerprint_descriptor"]:::utils
    TAN["MINT_tanimoto_coefficient"]:::utils
    SMU["SMILES_utils"]:::utils
    MSK["get_future_masks"]:::utils
    MFU["msp_file_utils"]:::utils
    PLO["plot_loss_curves"]:::utils
    ENT["spectral_entropy_utils"]:::utils
    AGG["MINT_aggregate"]:::utils
  end

  MFU -.-> MS2FP_DL
  MSK -.-> MS2FP_ASM
  LOG -.-> MS2FP_TRN
  PLO -.-> MS2FP_TRN
  ENT -.-> MS2FP_TRN
  FPR -.-> FP2MS_ASM
  SMU -.-> MS2SM_ASM
  TAN -.-> FP2MS_TRN
  AGG -.-> FP2MS_PRD

  subgraph "External Dependencies & Data"
    MSP[".msp Files"]:::io
    TORCH["PyTorch"]:::external
    RDK["RDKit"]:::external
    OUT["Outputs: weights, pickle, logs, plots"]:::io
  end

  MSP --> MS2FP_DL
  TORCH -.-> MS2FP_MDL
  RDK -.-> FP2MS_DL
  MS2FP_PKL --> OUT

  click CLI "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/IDSL_MINT_workflow.py"
  click OCI "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/IDSL_MINT_workflow.py"

  click MS2FP_DL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_DataLoader.py"
  click MS2FP_ASM "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_Assembler.py"
  click MS2FP_DS "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_Dataset.py"
  click MS2FP_MDL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_Model.py"
  click MS2FP_TRN "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_training_function.py"
  click MS2FP_PRD "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_yaml_predictor.py"
  click MS2FP_PKL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2FP/MS2FP_msp_pickler.py"

  click MS2SM_DL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_DataLoader.py"
  click MS2SM_ASM "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_Assembler.py"
  click MS2SM_DS "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_Dataset.py"
  click MS2SM_MDL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_Model.py"
  click MS2SM_TRN "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_training_function.py"
  click MS2SM_PRD "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_yaml_predictor.py"
  click MS2SM_PKL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/MS2SMILES/MS2SMILES_msp_pickler.py"

  click FP2MS_DL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_DataLoader.py"
  click FP2MS_ASM "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_Assembler.py"
  click FP2MS_DS "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_Dataset.py"
  click FP2MS_MDL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_Model.py"
  click FP2MS_TRN "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_training_function.py"
  click FP2MS_PRD "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_yaml_predictor.py"
  click FP2MS_PKL "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/FP2MS/FP2MS_msp_pickler.py"

  click LOG "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/MINT_logRecorder.py"
  click FPR "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/MINT_fingerprint_descriptor.py"
  click TAN "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/MINT_tanimoto_coefficient.py"
  click SMU "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/SMILES_utils.py"
  click MSK "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/get_future_masks.py"
  click MFU "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/msp_file_utils.py"
  click PLO "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/plot_loss_curves.py"
  click ENT "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/spectral_entropy_utils.py"
  click AGG "https://github.com/idslme/idsl_mint/blob/main/IDSL_MINT/utils/MINT_aggregate.py"

  classDef cli fill:#FADBD8,stroke:#C0392B,color:#000
  classDef config fill:#FCF3CF,stroke:#B7950B,color:#000
  classDef orchestration fill:#F9E79F,stroke:#B9770E,color:#000
  classDef pipeline fill:#AED6F1,stroke:#2E86C1,color:#000
  classDef utils fill:#D5D8DC,stroke:#7B7D7D,color:#000
  classDef io fill:#ABEBC6,stroke:#27AE60,color:#000
  classDef external fill:#F5B041,stroke:#CA6F1E,color:#000
```
