# paoli-lab/igua-df architecture

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

- Interactive diagram: https://gitdiagram.com/paoli-lab/igua-df
- Repository: https://github.com/paoli-lab/igua-df

## Overview

IGUA assigns genomic and metagenomic gene clusters to gene-cluster families (GCFs). The user supplies cluster data through the CLI; dataset adapters extract cluster and protein sequences, then the pipeline performs fragment mapping, nucleotide deduplication, and protein-composition clustering before writing GCF assignments and optional representative-protein and composition outputs. The README documents the three-stage method and outputs; sampled source shows CLI dataset construction and pipeline dependencies. Some stage-to-stage details are documented rather than fully visible in the excerpts.

Main entry points: [`src/igua/pipeline.py`](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py) (Analysis pipeline), [`src/igua/cli/__init__.py`](https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/__init__.py) (CLI), [`src/igua/cli/inputs.py`](https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/inputs.py) (Input adapters), [`src/igua/dataset/defensefinder.py`](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/defensefinder.py) (DefenseFinder reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and inputs"]
  node_cli["CLI<br/>[__init__.py]"]
  node_input_adapters["Input adapters<br/>[inputs.py]"]
end

subgraph group_datasets["Dataset adapters"]
  node_genbank["GenBank reader<br/>[genbank.py]"]
  node_antismash["antiSMASH reader<br/>[antismash.py]"]
  node_defensefinder["DefenseFinder reader<br/>[defensefinder.py]"]
  node_fasta_gff["FASTA/GFF reader<br/>[fasta_gff.py]"]
  node_dataset_list["Dataset collection<br/>[list.py]"]
  node_dataset_base["Dataset interface<br/>[base.py]"]
end

subgraph group_analysis["GCF analysis"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_fragment_mapping["Fragment mapping<br/>[pipeline.py]"]
  node_nucleotide_dedup["Nucleotide deduplication<br/>[pipeline.py]"]
  node_protein_clusters["Protein clustering<br/>[mmseqs.py]"]
  node_composition["Composition matrix<br/>[pipeline.py]"]
  node_gcf_clustering["GCF clustering<br/>[clustering.py]"]
end

subgraph group_outputs["Results"]
  node_results["GCF assignments<br/>[pipeline.py]"]
  node_protein_fasta["Representative proteins<br/>[pipeline.py]"]
  node_composition_output["Composition output<br/>[pipeline.py]"]
end

node_user(("Researcher"))
node_mmseqs["MMseqs2"]

node_user -->|"provides inputs"| node_cli
node_cli -->|"parses inputs"| node_input_adapters
node_input_adapters -->|"creates dataset"| node_genbank
node_input_adapters -->|"creates dataset"| node_antismash
node_input_adapters -->|"creates dataset"| node_defensefinder
node_defensefinder -->|"extends"| node_fasta_gff
node_cli -->|"combines datasets"| node_dataset_list
node_input_adapters -->|"returns datasets"| node_dataset_base
node_pipeline -->|"extracts sequences"| node_dataset_base
node_cli -->|"runs"| node_pipeline
node_pipeline -->|"performs"| node_fragment_mapping
node_pipeline -->|"performs"| node_nucleotide_dedup
node_pipeline -->|"performs"| node_protein_clusters
node_pipeline -->|"invokes"| node_mmseqs
node_pipeline -->|"builds"| node_composition
node_pipeline -->|"delegates clustering"| node_gcf_clustering
node_pipeline -->|"produces assignments"| node_results
node_pipeline -->|"optionally writes"| node_protein_fasta
node_pipeline -->|"optionally writes"| node_composition_output
node_cli -->|"writes TSV"| node_results

click node_cli "https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/__init__.py"
click node_input_adapters "https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/inputs.py"
click node_genbank "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/genbank.py"
click node_antismash "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/antismash.py"
click node_defensefinder "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/defensefinder.py"
click node_fasta_gff "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/fasta_gff.py"
click node_dataset_list "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/list.py"
click node_dataset_base "https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/base.py"
click node_pipeline "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_fragment_mapping "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_nucleotide_dedup "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_protein_clusters "https://github.com/paoli-lab/igua-df/blob/main/src/igua/mmseqs.py"
click node_composition "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_gcf_clustering "https://github.com/paoli-lab/igua-df/blob/main/src/igua/clustering.py"
click node_results "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_protein_fasta "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py"
click node_composition_output "https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.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_cli,node_input_adapters toneBlue
class node_genbank,node_antismash,node_defensefinder,node_fasta_gff,node_dataset_list,node_dataset_base toneAmber
class node_pipeline,node_fragment_mapping,node_nucleotide_dedup,node_protein_clusters,node_composition,node_gcf_clustering toneMint
class node_results,node_protein_fasta,node_composition_output toneRose
class node_user,node_mmseqs toneIndigo
```

## Components

### CLI and inputs

- [CLI](https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/__init__.py): `src/igua/cli/__init__.py`
- [Input adapters](https://github.com/paoli-lab/igua-df/blob/main/src/igua/cli/inputs.py): `src/igua/cli/inputs.py`

### Dataset adapters

- [GenBank reader](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/genbank.py): `src/igua/dataset/genbank.py`
- [antiSMASH reader](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/antismash.py): `src/igua/dataset/antismash.py`
- [DefenseFinder reader](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/defensefinder.py): `src/igua/dataset/defensefinder.py`
- [FASTA/GFF reader](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/fasta_gff.py): `src/igua/dataset/fasta_gff.py`
- [Dataset collection](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/list.py): `src/igua/dataset/list.py`
- [Dataset interface](https://github.com/paoli-lab/igua-df/blob/main/src/igua/dataset/base.py): `src/igua/dataset/base.py`

### GCF analysis

- [Analysis pipeline](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [Fragment mapping](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [Nucleotide deduplication](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [Protein clustering](https://github.com/paoli-lab/igua-df/blob/main/src/igua/mmseqs.py): `src/igua/mmseqs.py`
- [Composition matrix](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [GCF clustering](https://github.com/paoli-lab/igua-df/blob/main/src/igua/clustering.py): `src/igua/clustering.py`

### Results

- [GCF assignments](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [Representative proteins](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`
- [Composition output](https://github.com/paoli-lab/igua-df/blob/main/src/igua/pipeline.py): `src/igua/pipeline.py`

### Other components

- **Researcher**
- **MMseqs2**

## Connections

- Researcher → CLI: provides inputs (evidence: `README.md`)
- CLI → Input adapters: parses inputs (evidence: `src/igua/cli/__init__.py`)
- Input adapters → GenBank reader: creates dataset (evidence: `src/igua/cli/inputs.py`)
- Input adapters → antiSMASH reader: creates dataset (evidence: `src/igua/cli/inputs.py`)
- Input adapters → DefenseFinder reader: creates dataset (evidence: `src/igua/cli/inputs.py`)
- DefenseFinder reader → FASTA/GFF reader: extends (evidence: `src/igua/dataset/defensefinder.py`)
- CLI → Dataset collection: combines datasets (evidence: `src/igua/cli/__init__.py`)
- Input adapters → Dataset interface: returns datasets (evidence: `src/igua/cli/inputs.py`)
- Analysis pipeline → Dataset interface: extracts sequences (evidence: `src/igua/pipeline.py`)
- CLI → Analysis pipeline: runs (evidence: `src/igua/cli/__init__.py`)
- Analysis pipeline → Fragment mapping: performs (evidence: `README.md`)
- Analysis pipeline → Nucleotide deduplication: performs (evidence: `README.md`)
- Analysis pipeline → Protein clustering: performs (evidence: `README.md`)
- Analysis pipeline → MMseqs2: invokes (evidence: `src/igua/pipeline.py`)
- Analysis pipeline → Composition matrix: builds (evidence: `README.md`)
- Analysis pipeline → GCF clustering: delegates clustering (evidence: `src/igua/pipeline.py`)
- Analysis pipeline → GCF assignments: produces assignments (evidence: `README.md`)
- Analysis pipeline → Representative proteins: optionally writes (evidence: `README.md`)
- Analysis pipeline → Composition output: optionally writes (evidence: `README.md`)
- CLI → GCF assignments: writes TSV (evidence: `src/igua/cli/__init__.py`)
