# adibvafa/codontransformer architecture

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

- Interactive diagram: https://gitdiagram.com/adibvafa/codontransformer
- Repository: https://github.com/adibvafa/codontransformer

## Overview

##### Project type and purpose
- This is an open-source Python library and command-line tool (CodonTransformer) for codon optimization. It provides both training (pretrain.py, finetune.py, SLURM scripts) and inference (CodonPrediction, CodonJupyter) pipelines. It integrates a pretrained BigBird transformer model from Hugging Face, processes genetic data, and offers evaluation utilities.

##### File structure
- Top-level scripts and configs:
- pretrain.py, finetune.py (model training)
- Makefile, setup.py, pyproject.toml, requirements.txt (build/test/deploy)
- slurm/*.sh (SLURM job submission for HPC)
- demo/ (sample datasets)
- Core package: `CodonTransformer/` subpackages:
- CodonData (data preprocessing)
- CodonPrediction (model loading & inference)
- CodonEvaluation (metrics calculation)
- CodonUtils (constants, mappings, helpers)
- CodonJupyter (notebook widgets & formatting)
- src/ holds shipped artifacts (tokenizer JSON, organism pickles, Excel template)
- tests/ implements unit tests for each subpackage

##### README for additional insights
- The README outlines use cases: interactive Jupyter/Colab, batch inference template, API usage for predict_dna_sequence, finetuning instructions.
- It highlights dependencies (PyTorch, Transformers, Hugging Face), external data sources (Kazusa, NCBI) and output evaluation metrics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        UI_CLI["Python CLI/API<br/>(pretrain.py, finetune.py)"]:::ui
        UI_JUPYTER["Jupyter Notebook UI<br/>(CodonJupyter)"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        RawData["Raw Data<br/>(demo/sample_dataset.csv or user)"]:::data
        DemoInput["Demo Dataset<br/>(demo/sample_dataset.csv)"]:::data
        TokenizerArtifact["Tokenizer JSON<br/>(src/CodonTransformerTokenizer.json)"]:::data
        OrganismArtifact["Organism Mapping<br/>(src/organism2id.pkl)"]:::data
        ExcelTemplate["Inference Excel Template<br/>(src/CodonTransformer_inference_template.xlsx)"]:::data
        DemoOutput["Demo Predictions<br/>(demo/sample_predictions.csv)"]:::data
    end

    %% Processing Layer
    subgraph "Processing Layer"
        CodonData["CodonData Module<br/>(CodonData.py)"]:::data
        CodonUtils["CodonUtils Module<br/>(CodonUtils.py)"]:::utils
    end

    %% Model Layer
    subgraph "Model Layer"
        Pretrain["Pretrain Script<br/>(pretrain.py)"]:::compute
        Finetune["Finetune Script<br/>(finetune.py)"]:::compute
        BigBird["BigBird Transformer<br/>(Hugging Face)"]:::external
        SLURM_PT["SLURM Orchestrator<br/>(slurm/pretrain.sh)"]:::compute
        SLURM_FT["SLURM Orchestrator<br/>(slurm/finetune.sh)"]:::compute
        ModelHub["Hugging Face Model Hub"]:::external
    end

    %% Inference Layer
    subgraph "Inference Layer"
        CodonPrediction["CodonPrediction Module<br/>(CodonPrediction.py)"]:::compute
    end

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        CodonEvaluation["CodonEvaluation Module<br/>(CodonEvaluation.py)"]:::compute
    end

    %% Tests
    subgraph "Tests"
        TestData["Test CodonData<br/>(tests/test_CodonData.py)"]:::tests
        TestPrediction["Test CodonPrediction<br/>(tests/test_CodonPrediction.py)"]:::tests
        TestUtils["Test CodonUtils<br/>(tests/test_CodonUtils.py)"]:::tests
        TestJupyter["Test Jupyter UI<br/>(tests/test_CodonJupyter.py)"]:::tests
    end

    %% External Services
    subgraph "External Services"
        HFHubAPI["Hugging Face Hub API"]:::external
        NCBI["NCBI/Kazusa Codon API"]:::external
    end

    %% Connections
    RawData --> CodonData
    DemoInput --> CodonData
    OrganismArtifact --> CodonData
    CodonUtils --> CodonData

    CodonData --> Pretrain
    CodonData --> Finetune

    SLURM_PT --> Pretrain
    SLURM_FT --> Finetune

    Pretrain --> BigBird
    Finetune --> BigBird

    BigBird --> ModelHub
    HFHubAPI --> BigBird

    ModelHub --> CodonPrediction
    TokenizerArtifact --> CodonPrediction
    CodonUtils --> CodonPrediction

    UI_CLI --> CodonData
    UI_CLI --> Pretrain
    UI_CLI --> Finetune
    UI_CLI --> CodonPrediction
    UI_JUPYTER --> CodonPrediction

    CodonPrediction --> DemoOutput
    CodonPrediction --> CodonEvaluation
    CodonEvaluation --> UI_JUPYTER
    CodonEvaluation --> UI_CLI

    NCBI --> CodonData
    NCBI --> CodonUtils

    %% Click Events
    click Pretrain "https://github.com/adibvafa/codontransformer/blob/main/pretrain.py"
    click Finetune "https://github.com/adibvafa/codontransformer/blob/main/finetune.py"
    click SLURM_PT "https://github.com/adibvafa/codontransformer/blob/main/slurm/pretrain.sh"
    click SLURM_FT "https://github.com/adibvafa/codontransformer/blob/main/slurm/finetune.sh"
    click CodonData "https://github.com/adibvafa/codontransformer/blob/main/CodonTransformer/CodonData.py"
    click CodonPrediction "https://github.com/adibvafa/codontransformer/blob/main/CodonTransformer/CodonPrediction.py"
    click CodonJupyter "https://github.com/adibvafa/codontransformer/blob/main/CodonTransformer/CodonJupyter.py"
    click CodonEvaluation "https://github.com/adibvafa/codontransformer/blob/main/CodonTransformer/CodonEvaluation.py"
    click CodonUtils "https://github.com/adibvafa/codontransformer/blob/main/CodonTransformer/CodonUtils.py"
    click TokenizerArtifact "https://github.com/adibvafa/codontransformer/blob/main/src/CodonTransformerTokenizer.json"
    click OrganismArtifact "https://github.com/adibvafa/codontransformer/blob/main/src/organism2id.pkl"
    click ExcelTemplate "https://github.com/adibvafa/codontransformer/blob/main/src/CodonTransformer_inference_template.xlsx"
    click DemoInput "https://github.com/adibvafa/codontransformer/blob/main/demo/sample_dataset.csv"
    click DemoOutput "https://github.com/adibvafa/codontransformer/blob/main/demo/sample_predictions.csv"
    click TestData "https://github.com/adibvafa/codontransformer/blob/main/tests/test_CodonData.py"
    click TestPrediction "https://github.com/adibvafa/codontransformer/blob/main/tests/test_CodonPrediction.py"
    click TestUtils "https://github.com/adibvafa/codontransformer/blob/main/tests/test_CodonUtils.py"
    click TestJupyter "https://github.com/adibvafa/codontransformer/blob/main/tests/test_CodonJupyter.py"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#1B4F72,color:#1A5276
    classDef compute fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef ui fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef external fill:#E8DAEF,stroke:#6C3483,color:#512E5F
    classDef utils fill:#FADBD8,stroke:#C0392B,color:#922B21
    classDef tests fill:#F4ECF7,stroke:#7D3C98,color:#512E5F
```
