# merck/deepbgc architecture

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

- Interactive diagram: https://gitdiagram.com/merck/deepbgc
- Repository: https://github.com/merck/deepbgc

## Overview

DeepBGC is a command-line genome-mining tool that annotates sequences, detects biosynthetic gene clusters (BGCs), classifies predicted clusters, and writes reports. The main path runs through the pipeline command: sequence input is annotated with proteins and Pfam domains, scored by a detector, classified, and exported in several formats. Separate documented workflows prepare training data and train custom models; download and info commands support model and database setup. Some links for unsampled command and classifier behavior rely on the README and SOURCE INDEX rather than inspected implementation details.

Main entry points: [`deepbgc/command/pipeline.py`](https://github.com/merck/deepbgc/blob/master/deepbgc/command/pipeline.py) (Pipeline command), [`deepbgc/models/wrapper.py`](https://github.com/merck/deepbgc/blob/master/deepbgc/models/wrapper.py) (Sequence model wrapper), [`deepbgc/main.py`](https://github.com/merck/deepbgc/blob/master/deepbgc/main.py) (Command router), [`deepbgc/pipeline/annotator.py`](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/annotator.py) (Record annotator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli_entry["Command router<br/>[main.py]"]
  node_pipeline_cmd["Pipeline command<br/>[pipeline.py]"]
  node_prepare_cmd["Prepare command<br/>[prepare.py]"]
  node_train_cmd["Train command<br/>[train.py]"]
  node_download_cmd["Download command<br/>[download.py]"]
  node_info_cmd["Info command<br/>[info.py]"]
end

subgraph group_annotation["Sequence annotation"]
  node_annotator["Record annotator<br/>[annotator.py]"]
  node_prodigal["Protein prediction<br/>[protein.py]"]
  node_pfam_scan["Pfam scanning<br/>[pfam.py]"]
end

subgraph group_prediction["BGC prediction"]
  node_detector["BGC detector<br/>[detector.py]"]
  node_classifier["Cluster classifier<br/>[classifier.py]"]
end

subgraph group_models["Model runtime"]
  node_model_wrapper["Sequence model wrapper<br/>[wrapper.py]"]
  node_rnn["RNN detector<br/>[rnn.py]"]
  node_hmm["HMM detector<br/>[hmm.py]"]
  node_random_forest["Random forest<br/>[random_forest.py]"]
  node_features["Feature transforms<br/>[features.py]"]
  node_data_store[("Downloaded models and Pfam<br/>[data.py]")]
end

subgraph group_reporting["Reports and outputs"]
  node_writers["Output writers<br/>[writer.py]"]
  node_genbank["GenBank output<br/>[genbank.py]"]
  node_cluster_tsv["Cluster TSV<br/>[cluster_tsv.py]"]
  node_pfam_tsv["Pfam TSV<br/>[pfam_tsv.py]"]
  node_antismash_json["antiSMASH JSON<br/>[antismash_json.py]"]
  node_eval_plots["Evaluation plots"]
end

node_user(("Researcher"))
node_sequence["Genome sequence"]
node_hmmer["HMMER"]
node_prodigal_service["Prodigal"]
node_result["Output directory"]
node_antismash["antiSMASH viewer"]

node_user -->|"runs command"| node_cli_entry
node_sequence -->|"provides input"| node_pipeline_cmd
node_cli_entry -->|"dispatches to"| node_pipeline_cmd
node_cli_entry -->|"dispatches to"| node_prepare_cmd
node_cli_entry -->|"dispatches to"| node_train_cmd
node_cli_entry -->|"dispatches to"| node_download_cmd
node_cli_entry -->|"dispatches to"| node_info_cmd
node_pipeline_cmd -->|"runs annotation"| node_annotator
node_annotator -->|"runs if needed"| node_prodigal
node_annotator -->|"runs if needed"| node_pfam_scan
node_prodigal -->|"predicts proteins"| node_prodigal_service
node_pfam_scan -->|"scans domains"| node_hmmer
node_pipeline_cmd -->|"runs detection"| node_detector
node_pipeline_cmd -->|"runs classification"| node_classifier
node_detector -->|"predicts with"| node_model_wrapper
node_classifier -->|"classifies with"| node_model_wrapper
node_model_wrapper -->|"transforms samples"| node_features
node_model_wrapper -->|"loads model"| node_rnn
node_model_wrapper -->|"loads model"| node_hmm
node_model_wrapper -.->|"loads model"| node_random_forest
node_detector -->|"resolves model"| node_data_store
node_download_cmd -->|"downloads assets"| node_data_store
node_info_cmd -->|"reports assets"| node_data_store
node_prepare_cmd -->|"prepares sequences"| node_annotator
node_train_cmd -->|"trains models"| node_model_wrapper
node_pipeline_cmd -->|"writes records"| node_genbank
node_pipeline_cmd -->|"writes annotations"| node_antismash_json
node_pipeline_cmd -->|"writes clusters"| node_cluster_tsv
node_pipeline_cmd -->|"writes domains"| node_pfam_tsv
node_pipeline_cmd -->|"writes evaluation"| node_eval_plots
node_genbank -->|"uses writer base"| node_writers
node_cluster_tsv -->|"uses writer base"| node_writers
node_pfam_tsv -->|"uses writer base"| node_writers
node_antismash_json -->|"uses writer base"| node_writers
node_pipeline_cmd -->|"creates reports"| node_result
node_antismash_json -->|"uploads annotations"| node_antismash

click node_cli_entry "https://github.com/merck/deepbgc/blob/master/deepbgc/main.py"
click node_pipeline_cmd "https://github.com/merck/deepbgc/blob/master/deepbgc/command/pipeline.py"
click node_prepare_cmd "https://github.com/merck/deepbgc/blob/master/deepbgc/command/prepare.py"
click node_train_cmd "https://github.com/merck/deepbgc/blob/master/deepbgc/command/train.py"
click node_download_cmd "https://github.com/merck/deepbgc/blob/master/deepbgc/command/download.py"
click node_info_cmd "https://github.com/merck/deepbgc/blob/master/deepbgc/command/info.py"
click node_annotator "https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/annotator.py"
click node_prodigal "https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/protein.py"
click node_pfam_scan "https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/pfam.py"
click node_detector "https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/detector.py"
click node_classifier "https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/classifier.py"
click node_model_wrapper "https://github.com/merck/deepbgc/blob/master/deepbgc/models/wrapper.py"
click node_rnn "https://github.com/merck/deepbgc/blob/master/deepbgc/models/rnn.py"
click node_hmm "https://github.com/merck/deepbgc/blob/master/deepbgc/models/hmm.py"
click node_random_forest "https://github.com/merck/deepbgc/blob/master/deepbgc/models/random_forest.py"
click node_features "https://github.com/merck/deepbgc/blob/master/deepbgc/features.py"
click node_data_store "https://github.com/merck/deepbgc/blob/master/deepbgc/data.py"
click node_writers "https://github.com/merck/deepbgc/blob/master/deepbgc/output/writer.py"
click node_genbank "https://github.com/merck/deepbgc/blob/master/deepbgc/output/genbank.py"
click node_cluster_tsv "https://github.com/merck/deepbgc/blob/master/deepbgc/output/cluster_tsv.py"
click node_pfam_tsv "https://github.com/merck/deepbgc/blob/master/deepbgc/output/pfam_tsv.py"
click node_antismash_json "https://github.com/merck/deepbgc/blob/master/deepbgc/output/antismash_json.py"
click node_eval_plots "https://github.com/merck/deepbgc/tree/master/deepbgc/output/evaluation"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_pipeline_cmd,node_prepare_cmd,node_train_cmd,node_download_cmd,node_info_cmd,node_antismash toneBlue
class node_annotator,node_prodigal,node_pfam_scan toneAmber
class node_detector,node_classifier toneMint
class node_model_wrapper,node_rnn,node_hmm,node_random_forest,node_features,node_data_store toneRose
class node_writers,node_genbank,node_cluster_tsv,node_pfam_tsv,node_antismash_json,node_eval_plots,node_user,node_sequence,node_hmmer,node_prodigal_service,node_result toneIndigo
```

## Components

### CLI workflows

- [Command router](https://github.com/merck/deepbgc/blob/master/deepbgc/main.py): `deepbgc/main.py`
- [Pipeline command](https://github.com/merck/deepbgc/blob/master/deepbgc/command/pipeline.py): `deepbgc/command/pipeline.py`
- [Prepare command](https://github.com/merck/deepbgc/blob/master/deepbgc/command/prepare.py): `deepbgc/command/prepare.py`
- [Train command](https://github.com/merck/deepbgc/blob/master/deepbgc/command/train.py): `deepbgc/command/train.py`
- [Download command](https://github.com/merck/deepbgc/blob/master/deepbgc/command/download.py): `deepbgc/command/download.py`
- [Info command](https://github.com/merck/deepbgc/blob/master/deepbgc/command/info.py): `deepbgc/command/info.py`

### Sequence annotation

- [Record annotator](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/annotator.py): `deepbgc/pipeline/annotator.py`
- [Protein prediction](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/protein.py): `deepbgc/pipeline/protein.py`
- [Pfam scanning](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/pfam.py): `deepbgc/pipeline/pfam.py`

### BGC prediction

- [BGC detector](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/detector.py): `deepbgc/pipeline/detector.py`
- [Cluster classifier](https://github.com/merck/deepbgc/blob/master/deepbgc/pipeline/classifier.py): `deepbgc/pipeline/classifier.py`

### Model runtime

- [Sequence model wrapper](https://github.com/merck/deepbgc/blob/master/deepbgc/models/wrapper.py): `deepbgc/models/wrapper.py`
- [RNN detector](https://github.com/merck/deepbgc/blob/master/deepbgc/models/rnn.py): `deepbgc/models/rnn.py`
- [HMM detector](https://github.com/merck/deepbgc/blob/master/deepbgc/models/hmm.py): `deepbgc/models/hmm.py`
- [Random forest](https://github.com/merck/deepbgc/blob/master/deepbgc/models/random_forest.py): `deepbgc/models/random_forest.py`
- [Feature transforms](https://github.com/merck/deepbgc/blob/master/deepbgc/features.py): `deepbgc/features.py`
- [Downloaded models and Pfam](https://github.com/merck/deepbgc/blob/master/deepbgc/data.py): `deepbgc/data.py`

### Reports and outputs

- [Output writers](https://github.com/merck/deepbgc/blob/master/deepbgc/output/writer.py): `deepbgc/output/writer.py`
- [GenBank output](https://github.com/merck/deepbgc/blob/master/deepbgc/output/genbank.py): `deepbgc/output/genbank.py`
- [Cluster TSV](https://github.com/merck/deepbgc/blob/master/deepbgc/output/cluster_tsv.py): `deepbgc/output/cluster_tsv.py`
- [Pfam TSV](https://github.com/merck/deepbgc/blob/master/deepbgc/output/pfam_tsv.py): `deepbgc/output/pfam_tsv.py`
- [antiSMASH JSON](https://github.com/merck/deepbgc/blob/master/deepbgc/output/antismash_json.py): `deepbgc/output/antismash_json.py`
- [Evaluation plots](https://github.com/merck/deepbgc/tree/master/deepbgc/output/evaluation): `deepbgc/output/evaluation`

### Other components

- **Researcher**
- **Genome sequence**
- **HMMER**
- **Prodigal**
- **Output directory**
- **antiSMASH viewer**

## Connections

- Researcher → Command router: runs command (evidence: `deepbgc/main.py`)
- Genome sequence → Pipeline command: provides input (evidence: `deepbgc/command/pipeline.py`)
- Command router → Pipeline command: dispatches to (evidence: `deepbgc/main.py`)
- Command router → Prepare command: dispatches to (evidence: `deepbgc/main.py`)
- Command router → Train command: dispatches to (evidence: `deepbgc/main.py`)
- Command router → Download command: dispatches to (evidence: `deepbgc/main.py`)
- Command router → Info command: dispatches to (evidence: `deepbgc/main.py`)
- Pipeline command → Record annotator: runs annotation (evidence: `deepbgc/command/pipeline.py`)
- Record annotator → Protein prediction: runs if needed (evidence: `deepbgc/pipeline/annotator.py`)
- Record annotator → Pfam scanning: runs if needed (evidence: `deepbgc/pipeline/annotator.py`)
- Protein prediction → Prodigal: predicts proteins (evidence: `README.md`)
- Pfam scanning → HMMER: scans domains (evidence: `deepbgc/pipeline/pfam.py`)
- Pipeline command → BGC detector: runs detection (evidence: `deepbgc/command/pipeline.py`)
- Pipeline command → Cluster classifier: runs classification (evidence: `deepbgc/command/pipeline.py`)
- BGC detector → Sequence model wrapper: predicts with (evidence: `deepbgc/pipeline/detector.py`)
- Cluster classifier → Sequence model wrapper: classifies with (evidence: `deepbgc/pipeline/classifier.py`)
- Sequence model wrapper → Feature transforms: transforms samples (evidence: `deepbgc/models/wrapper.py`)
- Sequence model wrapper → RNN detector: loads model (evidence: `deepbgc/models/wrapper.py`)
- Sequence model wrapper → HMM detector: loads model (evidence: `deepbgc/models/wrapper.py`)
- Sequence model wrapper → Random forest: loads model
- BGC detector → Downloaded models and Pfam: resolves model (evidence: `deepbgc/pipeline/detector.py`)
- Download command → Downloaded models and Pfam: downloads assets (evidence: `deepbgc/command/download.py`)
- Info command → Downloaded models and Pfam: reports assets (evidence: `deepbgc/command/info.py`)
- Prepare command → Record annotator: prepares sequences (evidence: `deepbgc/command/prepare.py`)
- Train command → Sequence model wrapper: trains models (evidence: `deepbgc/command/train.py`)
- Pipeline command → GenBank output: writes records (evidence: `deepbgc/command/pipeline.py`)
- Pipeline command → antiSMASH JSON: writes annotations (evidence: `deepbgc/command/pipeline.py`)
- Pipeline command → Cluster TSV: writes clusters (evidence: `deepbgc/command/pipeline.py`)
- Pipeline command → Pfam TSV: writes domains (evidence: `deepbgc/command/pipeline.py`)
- Pipeline command → Evaluation plots: writes evaluation (evidence: `deepbgc/command/pipeline.py`)
- GenBank output → Output writers: uses writer base (evidence: `deepbgc/output/genbank.py`)
- Cluster TSV → Output writers: uses writer base (evidence: `deepbgc/output/cluster_tsv.py`)
- Pfam TSV → Output writers: uses writer base (evidence: `deepbgc/output/pfam_tsv.py`)
- antiSMASH JSON → Output writers: uses writer base (evidence: `deepbgc/output/antismash_json.py`)
- Pipeline command → Output directory: creates reports (evidence: `deepbgc/command/pipeline.py`)
- antiSMASH JSON → antiSMASH viewer: uploads annotations (evidence: `README.md`)