# ecampbell50/ptolemaea architecture

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

- Interactive diagram: https://gitdiagram.com/ecampbell50/ptolemaea
- Repository: https://github.com/ecampbell50/ptolemaea

## Overview

Ptolemaea is a genome-scale bacterial antiviral-defence annotation and reconciliation pipeline. Users provide genome FASTAs; the documented run predicts proteins, invokes PADLOC and DefenseFinder, performs bidirectional BLAST against the Bacillus cereus defence set, then produces per-genome consensus profiles. Optional curation resolves MAPPING/CONFLICT patterns before final tables and heatmaps. The README documents runtime orchestration and tool stages, but those source scripts were not excerpted, so only documented links are shown. The sampled post-processing code supports the curation, aggregation, and plotting relationships.

Main entry points: [`scripts/create_defence_profile_direct.py`](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_defence_profile_direct.py) (Consensus profiles), [`singularity_scripts/Ptolemaea_singularity.sh`](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh) (Pipeline runner), [`scripts/create_final_defence_matrix.py`](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_final_defence_matrix.py) (Apply resolutions), [`genomes`](https://github.com/ecampbell50/ptolemaea/tree/main/genomes) (Genome FASTAs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Annotation run"]
  node_genomes["Genome FASTAs"]
  node_runner["Pipeline runner"]
  node_gene_call["Gene calling"]
  node_padloc["PADLOC detection"]
  node_defensefinder["DefenseFinder detection"]
  node_blast["Bidirectional BLAST"]
  node_reference[("B. cereus reference")]
  node_consensus["Consensus profiles"]
  node_tool_key["Nomenclature key<br/>[MASTER_ToolKey.tsv]"]
end

subgraph group_curate["Consensus curation"]
  node_pattern_extract["Unresolved patterns"]
  node_resolutions["Curated resolutions"]
  node_finalize["Apply resolutions"]
end

subgraph group_results["Results and plots"]
  node_tables["Final data tables"]
  node_heatmap["Defence heatmap"]
end

node_user(("Genome analyst"))
node_curator(("Manual curator"))

node_user -->|"provides"| node_genomes
node_genomes -->|"supplies genomes"| node_runner
node_runner -->|"runs"| node_gene_call
node_runner -->|"runs"| node_padloc
node_runner -->|"runs"| node_defensefinder
node_runner -->|"runs"| node_blast
node_blast -->|"searches"| node_reference
node_runner -->|"produces profiles"| node_consensus
node_padloc -->|"provides detections"| node_consensus
node_defensefinder -->|"provides detections"| node_consensus
node_blast -->|"provides votes"| node_consensus
node_tool_key -->|"maps names"| node_consensus
node_consensus -->|"reads profiles"| node_pattern_extract
node_pattern_extract -->|"presents patterns"| node_curator
node_curator -->|"decides labels"| node_resolutions
node_consensus -->|"loads profiles"| node_finalize
node_resolutions -->|"applies decisions"| node_finalize
node_finalize -->|"writes tables"| node_tables
node_tables -->|"plots matrix"| node_heatmap
node_consensus -->|"plots profiles"| node_heatmap

click node_genomes "https://github.com/ecampbell50/ptolemaea/tree/main/genomes"
click node_runner "https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh"
click node_gene_call "https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh"
click node_padloc "https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh"
click node_defensefinder "https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh"
click node_blast "https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh"
click node_reference "https://github.com/ecampbell50/ptolemaea/blob/main/databases/bcereus_db/Bcereus_DefenceProts_17Sep25.faa"
click node_consensus "https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_defence_profile_direct.py"
click node_tool_key "https://github.com/ecampbell50/ptolemaea/blob/main/databases/MASTER_ToolKey.tsv"
click node_pattern_extract "https://github.com/ecampbell50/ptolemaea/blob/main/scripts/extract_unresolved_patterns.py"
click node_finalize "https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_final_defence_matrix.py"
click node_tables "https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_final_defence_matrix.py"
click node_heatmap "https://github.com/ecampbell50/ptolemaea/blob/main/scripts/plot_defence_heatmap.py"

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_genomes,node_runner,node_gene_call,node_padloc,node_defensefinder,node_blast,node_reference,node_consensus,node_tool_key toneBlue
class node_pattern_extract,node_resolutions,node_finalize toneAmber
class node_tables,node_heatmap toneMint
class node_user,node_curator toneIndigo
```

## Components

### Annotation run

- [Genome FASTAs](https://github.com/ecampbell50/ptolemaea/tree/main/genomes): `genomes`
- [Pipeline runner](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh): `singularity_scripts/Ptolemaea_singularity.sh`
- [Gene calling](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh): `singularity_scripts/Ptolemaea_singularity.sh`
- [PADLOC detection](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh): `singularity_scripts/Ptolemaea_singularity.sh`
- [DefenseFinder detection](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh): `singularity_scripts/Ptolemaea_singularity.sh`
- [Bidirectional BLAST](https://github.com/ecampbell50/ptolemaea/blob/main/singularity_scripts/Ptolemaea_singularity.sh): `singularity_scripts/Ptolemaea_singularity.sh`
- [B. cereus reference](https://github.com/ecampbell50/ptolemaea/blob/main/databases/bcereus_db/Bcereus_DefenceProts_17Sep25.faa): `databases/bcereus_db/Bcereus_DefenceProts_17Sep25.faa`
- [Consensus profiles](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_defence_profile_direct.py): `scripts/create_defence_profile_direct.py`
- [Nomenclature key](https://github.com/ecampbell50/ptolemaea/blob/main/databases/MASTER_ToolKey.tsv): `databases/MASTER_ToolKey.tsv`

### Consensus curation

- [Unresolved patterns](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/extract_unresolved_patterns.py): `scripts/extract_unresolved_patterns.py`
- **Curated resolutions**
- [Apply resolutions](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_final_defence_matrix.py): `scripts/create_final_defence_matrix.py`

### Results and plots

- [Final data tables](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/create_final_defence_matrix.py): `scripts/create_final_defence_matrix.py`
- [Defence heatmap](https://github.com/ecampbell50/ptolemaea/blob/main/scripts/plot_defence_heatmap.py): `scripts/plot_defence_heatmap.py`

### Other components

- **Genome analyst**
- **Manual curator**

## Connections

- Genome analyst → Genome FASTAs: provides (evidence: `README.md`)
- Genome FASTAs → Pipeline runner: supplies genomes (evidence: `README.md`)
- Pipeline runner → Gene calling: runs (evidence: `README.md`)
- Pipeline runner → PADLOC detection: runs (evidence: `README.md`)
- Pipeline runner → DefenseFinder detection: runs (evidence: `README.md`)
- Pipeline runner → Bidirectional BLAST: runs (evidence: `README.md`)
- Bidirectional BLAST → B. cereus reference: searches (evidence: `README.md`)
- Pipeline runner → Consensus profiles: produces profiles (evidence: `README.md`)
- PADLOC detection → Consensus profiles: provides detections (evidence: `README.md`)
- DefenseFinder detection → Consensus profiles: provides detections (evidence: `README.md`)
- Bidirectional BLAST → Consensus profiles: provides votes (evidence: `README.md`)
- Nomenclature key → Consensus profiles: maps names (evidence: `README.md`)
- Consensus profiles → Unresolved patterns: reads profiles (evidence: `scripts/extract_unresolved_patterns.py`)
- Unresolved patterns → Manual curator: presents patterns (evidence: `README.md`)
- Manual curator → Curated resolutions: decides labels (evidence: `README.md`)
- Consensus profiles → Apply resolutions: loads profiles (evidence: `scripts/create_final_defence_matrix.py`)
- Curated resolutions → Apply resolutions: applies decisions (evidence: `scripts/create_final_defence_matrix.py`)
- Apply resolutions → Final data tables: writes tables (evidence: `scripts/create_final_defence_matrix.py`)
- Final data tables → Defence heatmap: plots matrix (evidence: `scripts/plot_defence_heatmap.py`)
- Consensus profiles → Defence heatmap: plots profiles (evidence: `scripts/plot_defence_heatmap.py`)
