# museomics/its-fun-2-map architecture

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

- Interactive diagram: https://gitdiagram.com/museomics/its-fun-2-map
- Repository: https://github.com/museomics/its-fun-2-map

## Overview

its-fun-2-map processes fungal museum-specimen paired reads into taxonomically validated ITS barcode sequences. Its principal workflow is QC, UNITE reference retrieval, read mapping, assembly, multi-round BLAST validation, and ITS extraction; the README says the pipeline can be run sequentially with run_pipeline.sh. Taxonomy retrieval and final summary compilation are additional capabilities. Several links and subsystem details rely on README documentation because their implementations were not sampled; dashed links mark relationships that are documented only at a broad workflow level.

Main entry points: [`run_pipeline.sh`](https://github.com/museomics/its-fun-2-map/blob/main/run_pipeline.sh) (Pipeline runner), [`mapping_module.py`](https://github.com/museomics/its-fun-2-map/blob/main/mapping_module.py) (Read mapping and baiting), [`blast_round1.py`](https://github.com/museomics/its-fun-2-map/blob/main/blast_round1.py) (BLAST round one), [`its_fun_tools.py`](https://github.com/museomics/its-fun-2-map/blob/main/its_fun_tools.py) (Pipeline utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Pipeline workflow"]
  node_runner["Pipeline runner<br/>[run_pipeline.sh]"]
  node_qc["Read quality control<br/>[fastp_module.py]"]
  node_mapping["Read mapping and baiting<br/>[mapping_module.py]"]
  node_assembly["Fallback assembly<br/>[assembly_module.py]"]
end

subgraph group_taxonomy["Taxonomy retrieval"]
  node_reference["UNITE reference retrieval<br/>[UNITEd.py]"]
  node_lineage["NCBI lineage retrieval"]
end

subgraph group_validation["BLAST validation"]
  node_blast1["BLAST round one<br/>[blast_round1.py]"]
  node_blast1parse["Round-one parsing"]
  node_blast2["BLAST round two<br/>[blast_round2.py]"]
  node_blastparse["BLAST result validation"]
end

subgraph group_reporting["Extraction and reporting"]
  node_primer["ITS primer extraction"]
  node_summary["Summary compilation"]
  node_decision["Validation decisions"]
end

subgraph group_shared["Shared utilities"]
  node_tools["Pipeline utilities<br/>[its_fun_tools.py]"]
  node_fastpjson["Fastp metrics parsing<br/>[parse_fastp_json.R]"]
  node_blasttask["BLAST task helper<br/>[its_fun_tools.py]"]
end

node_user(("Researcher"))
node_ncbi["NCBI Entrez"]

node_user -.->|"starts run"| node_runner
node_runner -.->|"runs QC"| node_qc
node_runner -.->|"retrieves references"| node_reference
node_runner -.->|"maps reads"| node_mapping
node_runner -.->|"assembles reads"| node_assembly
node_runner -.->|"starts validation"| node_blast1
node_qc -.->|"provides filtered reads"| node_mapping
node_reference -.->|"provides references"| node_mapping
node_mapping -.->|"provides mapped reads"| node_assembly
node_assembly -.->|"provides contigs"| node_blast1
node_blast1 -.->|"produces BLAST results"| node_blast1parse
node_blast1parse -.->|"supports further validation"| node_blast2
node_blast2 -.->|"produces BLAST results"| node_blastparse
node_blastparse -.->|"validates sequences"| node_primer
node_primer -.->|"provides ITS results"| node_summary
node_summary -.->|"provides summary data"| node_decision
node_lineage -->|"queries lineage"| node_ncbi
node_blast1 -->|"dispatches BLAST"| node_blasttask
node_blast2 -->|"uses utilities"| node_tools
node_blasttask -->|"uses shared helpers"| node_tools
node_blastparse -->|"uses shared helpers"| node_tools
node_mapping -->|"uses shared helpers"| node_tools
node_reference -.->|"queries taxonomy"| node_ncbi

click node_runner "https://github.com/museomics/its-fun-2-map/blob/main/run_pipeline.sh"
click node_qc "https://github.com/museomics/its-fun-2-map/blob/main/fastp_module.py"
click node_reference "https://github.com/museomics/its-fun-2-map/blob/main/UNITEd.py"
click node_lineage "https://github.com/museomics/its-fun-2-map/blob/main/pull_ncbi_lineage.py"
click node_mapping "https://github.com/museomics/its-fun-2-map/blob/main/mapping_module.py"
click node_assembly "https://github.com/museomics/its-fun-2-map/blob/main/assembly_module.py"
click node_blast1 "https://github.com/museomics/its-fun-2-map/blob/main/blast_round1.py"
click node_blast1parse "https://github.com/museomics/its-fun-2-map/blob/main/blast_round1_parser.py"
click node_blast2 "https://github.com/museomics/its-fun-2-map/blob/main/blast_round2.py"
click node_blastparse "https://github.com/museomics/its-fun-2-map/blob/main/blast_output_parser.py"
click node_primer "https://github.com/museomics/its-fun-2-map/blob/main/its_primer_binding.py"
click node_summary "https://github.com/museomics/its-fun-2-map/blob/main/its_a_summary_compiler.py"
click node_decision "https://github.com/museomics/its-fun-2-map/blob/main/its_decision_making.R"
click node_tools "https://github.com/museomics/its-fun-2-map/blob/main/its_fun_tools.py"
click node_fastpjson "https://github.com/museomics/its-fun-2-map/blob/main/parse_fastp_json.R"
click node_blasttask "https://github.com/museomics/its-fun-2-map/blob/main/its_fun_tools.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_runner,node_qc,node_mapping,node_assembly toneBlue
class node_reference,node_lineage toneAmber
class node_blast1,node_blast1parse,node_blast2,node_blastparse toneMint
class node_primer,node_summary,node_decision toneRose
class node_tools,node_fastpjson,node_blasttask,node_user,node_ncbi toneIndigo
```

## Components

### Pipeline workflow

- [Pipeline runner](https://github.com/museomics/its-fun-2-map/blob/main/run_pipeline.sh): `run_pipeline.sh`
- [Read quality control](https://github.com/museomics/its-fun-2-map/blob/main/fastp_module.py): `fastp_module.py`
- [Read mapping and baiting](https://github.com/museomics/its-fun-2-map/blob/main/mapping_module.py): `mapping_module.py`
- [Fallback assembly](https://github.com/museomics/its-fun-2-map/blob/main/assembly_module.py): `assembly_module.py`

### Taxonomy retrieval

- [UNITE reference retrieval](https://github.com/museomics/its-fun-2-map/blob/main/UNITEd.py): `UNITEd.py`
- [NCBI lineage retrieval](https://github.com/museomics/its-fun-2-map/blob/main/pull_ncbi_lineage.py): `pull_ncbi_lineage.py`

### BLAST validation

- [BLAST round one](https://github.com/museomics/its-fun-2-map/blob/main/blast_round1.py): `blast_round1.py`
- [Round-one parsing](https://github.com/museomics/its-fun-2-map/blob/main/blast_round1_parser.py): `blast_round1_parser.py`
- [BLAST round two](https://github.com/museomics/its-fun-2-map/blob/main/blast_round2.py): `blast_round2.py`
- [BLAST result validation](https://github.com/museomics/its-fun-2-map/blob/main/blast_output_parser.py): `blast_output_parser.py`

### Extraction and reporting

- [ITS primer extraction](https://github.com/museomics/its-fun-2-map/blob/main/its_primer_binding.py): `its_primer_binding.py`
- [Summary compilation](https://github.com/museomics/its-fun-2-map/blob/main/its_a_summary_compiler.py): `its_a_summary_compiler.py`
- [Validation decisions](https://github.com/museomics/its-fun-2-map/blob/main/its_decision_making.R): `its_decision_making.R`

### Shared utilities

- [Pipeline utilities](https://github.com/museomics/its-fun-2-map/blob/main/its_fun_tools.py): `its_fun_tools.py`
- [Fastp metrics parsing](https://github.com/museomics/its-fun-2-map/blob/main/parse_fastp_json.R): `parse_fastp_json.R`
- [BLAST task helper](https://github.com/museomics/its-fun-2-map/blob/main/its_fun_tools.py): `its_fun_tools.py`

### Other components

- **Researcher**
- **NCBI Entrez**

## Connections

- Researcher → Pipeline runner: starts run (evidence: `README.md`)
- Pipeline runner → Read quality control: runs QC (evidence: `README.md`)
- Pipeline runner → UNITE reference retrieval: retrieves references (evidence: `README.md`)
- Pipeline runner → Read mapping and baiting: maps reads (evidence: `README.md`)
- Pipeline runner → Fallback assembly: assembles reads (evidence: `README.md`)
- Pipeline runner → BLAST round one: starts validation (evidence: `README.md`)
- Read quality control → Read mapping and baiting: provides filtered reads (evidence: `README.md`)
- UNITE reference retrieval → Read mapping and baiting: provides references (evidence: `README.md`)
- Read mapping and baiting → Fallback assembly: provides mapped reads (evidence: `README.md`)
- Fallback assembly → BLAST round one: provides contigs (evidence: `README.md`)
- BLAST round one → Round-one parsing: produces BLAST results (evidence: `README.md`)
- Round-one parsing → BLAST round two: supports further validation (evidence: `README.md`)
- BLAST round two → BLAST result validation: produces BLAST results (evidence: `README.md`)
- BLAST result validation → ITS primer extraction: validates sequences (evidence: `README.md`)
- ITS primer extraction → Summary compilation: provides ITS results (evidence: `README.md`)
- Summary compilation → Validation decisions: provides summary data (evidence: `README.md`)
- NCBI lineage retrieval → NCBI Entrez: queries lineage (evidence: `pull_ncbi_lineage.py`)
- BLAST round one → BLAST task helper: dispatches BLAST (evidence: `blast_round1.py`)
- BLAST round two → Pipeline utilities: uses utilities (evidence: `blast_round2.py`)
- BLAST task helper → Pipeline utilities: uses shared helpers (evidence: `its_fun_tools.py`)
- BLAST result validation → Pipeline utilities: uses shared helpers (evidence: `blast_output_parser.py`)
- Read mapping and baiting → Pipeline utilities: uses shared helpers (evidence: `mapping_module.py`)
- UNITE reference retrieval → NCBI Entrez: queries taxonomy (evidence: `README.md`)
