# rnajena/bertax architecture

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

- Interactive diagram: https://gitdiagram.com/rnajena/bertax
- Repository: https://github.com/rnajena/bertax

## Overview

##### Project Type and Purpose
- BERTax is a Python‐based command‐line tool and library for taxonomic classification of DNA sequences using a deep neural network (BERT) model.
- The project can be run locally (pip/conda install) or inside a Docker container, with optional GPU acceleration.

##### File Structure Analysis
- Top-level:
- Dockerfile, .github workflows: container build and CI/CD.
- setup.py, conda.recipe: packaging and distribution.
- confusion_matrices: static PDF outputs, example results.
- Source code: “bertax/” package
- bertax.py: main CLI and inference logic.
- utils.py: data handling, sequence splitting, encoding.
- resources/: model file(s) and related assets.
- No frontend/backend split. It’s a standalone CLI/library with core engine and visualization module.

##### README Insights
- Describes usage, parameters, installation options (Docker, conda, pip).
- Highlights external dependencies: keras-bert, torch, transformers, bertviz.
- Mentions model download (HDF5) into resources.
- Notes GPU support via NVIDIA toolkit.

##### Main Components
a. User Interfaces
- CLI “bertax”: takes FASTA input, prints or writes predictions.
b. Core Modules
- Sequence Parser & Splitter (utils.py): reads FASTA, splits long sequences.
- Encoder: tokenizes and encodes DNA k-mers for BERT input.
- Model Loader (resources): loads pretrained .h5 model via keras-bert.
- Inference Engine (bertax.py): runs model.predict on batches (CPU/GPU).
- Postprocessor & Aggregator: averages chunk predictions, formats output.
c. Outputs
- Console or file‐based tabular output.
- Optional JSON confidences (--conf_matrix_file).
- HTML visualizations via bertviz.
- Static confusion matrices folder (for reference).
d. Packaging & Deployment
- Docker image: builds environment, installs package, sets entrypoint.
- Conda recipe: for channel distribution.
- setup.py: pip installation.

##### Component Interactions and Data Flow
1. User invokes CLI command with sequence file.
2. Sequence Parser reads sequences → Sequence Splitter produces chunks.
3. Encoder transforms chunks into input tensors.
4. Model Loader loads weights → Inference Engine runs forward pass.
5. Postprocessor aggregates predictions → Output Writer sends to console/file.

##### Architectural Patterns and Design Principles
- Modular separation: parsing, encoding, inference, postprocessing.
- Single‐responsibility principle: each Python module handles one concern.
- Pluggable backend: can swap in custom models (--custom_model_file).
- Containerization: infrastructure as code, reproducibility.

##### Technologies and Frameworks
- Python 3.x
- keras-bert, TensorFlow/Keras backend
- torch, transformers, bertviz (visualization)
- Biopython or custom FASTA parsing in utils
- Docker, Conda for environment management

- Parameters (batch_size, sequence_split options).
- External dependencies (keras-bert, bertviz) as supporting libraries.
- Conditional path for visualization vs. classification.
- Resources directory as the source of model assets.
- Packaging layers: source code, Dockerfile, conda.recipe, setup.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        CLI_bertax("bertax CLI"):::entry
        CLI_visualize("bertax-visualize CLI"):::entry
    end

    subgraph "Core Modules"
        ParserSplitter["Sequence Parser & Splitter\n(utils.py)"]:::module
        Encoder["Encoder\n(utils.py)"]:::module
        ModelLoader["Model Loader\n(resources)"]:::module
        ResourcesReadme["Model Resources README\n(README.txt)"]:::artifact
        Inference["Inference Engine\n(bertax.py)"]:::module
        Postprocessor["Postprocessor & Aggregator\n(utils.py / bertax.py)"]:::module
    end

    subgraph "Outputs"
        Console["Console / File Output"]:::io
        JSON["JSON Confidences"]:::io
        HTML["HTML Visualization"]:::io
        ConfMatrices["Static Confusion Matrices\n(confusion_matrices/)"]:::artifact
    end

    subgraph "Packaging & CI"
        DockerfileNode["Dockerfile"]:::artifact
        CondaNode["Conda Recipe\n(meta.yaml)"]:::artifact
        Setup["setup.py"]:::artifact
        CI_publish["Publish Conda CI"]:::external
        CI_push["Push Docker CI"]:::external
        DockerRegistry("Docker Registry"):::cloud
        CondaChannel("Conda Channel"):::cloud
    end

    subgraph "External Libraries"
        KerasBert("keras-bert"):::external
        Torch("torch"):::external
        Transformers("transformers"):::external
        BertViz("bertviz"):::external
        BioPython("Biopython"):::external
    end

    CLI_bertax --> ParserSplitter
    CLI_visualize --> ParserSplitter

    ParserSplitter --> Encoder
    ParserSplitter --> BioPython

    Encoder --> ModelLoader
    ModelLoader --> ResourcesReadme
    ModelLoader --> Inference

    Inference --> KerasBert
    Inference --> Torch
    Inference --> Transformers
    Inference --> Postprocessor

    Postprocessor --> Console
    Postprocessor --> JSON

    CLI_visualize --> BertViz
    BertViz --> HTML

    ConfMatrices

    Setup --> DockerfileNode
    Setup --> CondaNode
    DockerfileNode --> DockerRegistry
    CondaNode --> CondaChannel
    CI_publish --> CondaNode
    CI_push --> DockerfileNode

    classDef entry fill:#cfe2f3,stroke:#333;
    classDef module fill:#d9ead3,stroke:#333;
    classDef io fill:#9ec5fe,stroke:#333;
    classDef artifact fill:#f9cb9c,stroke:#333;
    classDef external fill:#fff2cc,stroke:#333;
    classDef cloud fill:#d9d2e9,stroke:#333;

    click CLI_bertax "https://github.com/rnajena/bertax/blob/master/bertax/bertax.py"
    click CLI_visualize "https://github.com/rnajena/bertax/blob/master/bertax/visualize.py"
    click ParserSplitter "https://github.com/rnajena/bertax/blob/master/bertax/utils.py"
    click Encoder "https://github.com/rnajena/bertax/blob/master/bertax/utils.py"
    click ModelLoader "https://github.com/rnajena/bertax/tree/master/bertax/resources/"
    click ResourcesReadme "https://github.com/rnajena/bertax/blob/master/bertax/resources/README.txt"
    click Inference "https://github.com/rnajena/bertax/blob/master/bertax/bertax.py"
    click Postprocessor "https://github.com/rnajena/bertax/blob/master/bertax/utils.py"
    click ConfMatrices "https://github.com/rnajena/bertax/tree/master/confusion_matrices/"
    click DockerfileNode "https://github.com/rnajena/bertax/tree/master/Dockerfile"
    click CondaNode "https://github.com/rnajena/bertax/blob/master/conda.recipe/meta.yaml"
    click Setup "https://github.com/rnajena/bertax/blob/master/setup.py"
    click CI_publish "https://github.com/rnajena/bertax/blob/master/.github/workflows/publish-conda.yml"
    click CI_push "https://github.com/rnajena/bertax/blob/master/.github/workflows/push_docker.yml"
```
