# linudz/caastools architecture

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

- Interactive diagram: https://gitdiagram.com/linudz/caastools
- Repository: https://github.com/linudz/caastools

## Overview

CAAStools is a command-line bioinformatics suite for discovering and validating convergent amino-acid substitutions (CAAS) in orthologous-protein alignments. The principal workflow compares foreground and background species at alignment positions, filters candidate patterns, calculates empirical p-values, and writes discovery results. Separate resampling modes generate virtual phenotype groups; bootstrap analysis evaluates CAAS across those resamplings. The README documents these capabilities, while the sampled source shows discovery, alignment processing, statistics, and bootstrap internals. The launcher and some resampling dispatch details were not sampled, so their internal wiring is kept limited.

Main entry points: [`modules/init_bootstrap.py`](https://github.com/linudz/caastools/blob/main/modules/init_bootstrap.py) (Resampling), [`modules/boot.py`](https://github.com/linudz/caastools/blob/main/modules/boot.py) (Bootstrap), [`modules/disco.py`](https://github.com/linudz/caastools/blob/main/modules/disco.py) (Discovery), [`ct`](https://github.com/linudz/caastools/blob/main/ct) (ct CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["CAAS Discovery"]
  node_discovery_tool["Discovery<br/>[disco.py]"]
  node_phenotypes["Phenotype Config<br/>[pindex.py]"]
end

subgraph group_resampling["Trait Resampling"]
  node_resampling_tool["Resampling<br/>[init_bootstrap.py]"]
  node_tree["Phylogenetic Tree"]
  node_trait_values["Trait Values"]
  node_r_integration["RERconverge"]
  node_permulations["BM Permulations<br/>[permulations.r]"]
end

subgraph group_bootstrap["Bootstrap Validation"]
  node_bootstrap_tool["Bootstrap<br/>[boot.py]"]
  node_bootstrap_traits["Resampled Traits<br/>[init_bootstrap.py]"]
end

subgraph group_shared["Alignment And Statistics"]
  node_alignment_slicer["Alignment Slicer<br/>[runslice.py]"]
  node_alignment_import["Alignment Import<br/>[alimport.py]"]
  node_position_analysis["Position Analysis<br/>[caas_id.py]"]
  node_pattern_statistics["Pattern And P-values<br/>[hyper.py]"]
end

node_user(("Researcher"))
node_cli["ct CLI"]
node_results["CAAS Results"]

node_user -->|"runs tool"| node_cli
node_cli -->|"dispatches"| node_discovery_tool
node_cli -->|"dispatches"| node_resampling_tool
node_cli -->|"dispatches"| node_bootstrap_tool
node_discovery_tool -->|"loads config"| node_phenotypes
node_discovery_tool -->|"receives slices"| node_alignment_slicer
node_alignment_slicer -->|"imports alignment"| node_alignment_import
node_discovery_tool -->|"processes positions"| node_position_analysis
node_position_analysis -->|"calculates p-values"| node_pattern_statistics
node_discovery_tool -->|"writes candidates"| node_results
node_user -->|"provides inputs"| node_resampling_tool
node_resampling_tool -->|"reads tree"| node_tree
node_resampling_tool -->|"reads values"| node_trait_values
node_resampling_tool -.->|"uses BM mode"| node_r_integration
node_r_integration -.->|"runs script"| node_permulations
node_resampling_tool -->|"writes groups"| node_bootstrap_traits
node_user -->|"requests validation"| node_bootstrap_tool
node_bootstrap_tool -->|"reads groups"| node_bootstrap_traits
node_bootstrap_tool -->|"receives slices"| node_alignment_slicer
node_bootstrap_tool -->|"processes positions"| node_position_analysis
node_bootstrap_tool -->|"writes bootstrap results"| node_results

click node_cli "https://github.com/linudz/caastools/blob/main/ct"
click node_discovery_tool "https://github.com/linudz/caastools/blob/main/modules/disco.py"
click node_phenotypes "https://github.com/linudz/caastools/blob/main/modules/pindex.py"
click node_resampling_tool "https://github.com/linudz/caastools/blob/main/modules/init_bootstrap.py"
click node_permulations "https://github.com/linudz/caastools/blob/main/scripts/permulations.r"
click node_bootstrap_tool "https://github.com/linudz/caastools/blob/main/modules/boot.py"
click node_bootstrap_traits "https://github.com/linudz/caastools/blob/main/modules/init_bootstrap.py"
click node_alignment_slicer "https://github.com/linudz/caastools/blob/main/modules/runslice.py"
click node_alignment_import "https://github.com/linudz/caastools/blob/main/modules/alimport.py"
click node_position_analysis "https://github.com/linudz/caastools/blob/main/modules/caas_id.py"
click node_pattern_statistics "https://github.com/linudz/caastools/blob/main/modules/hyper.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_discovery_tool,node_phenotypes toneBlue
class node_resampling_tool,node_tree,node_trait_values,node_r_integration,node_permulations toneAmber
class node_bootstrap_tool,node_bootstrap_traits toneMint
class node_alignment_slicer,node_alignment_import,node_position_analysis,node_pattern_statistics toneRose
class node_user,node_results toneIndigo
class node_cli toneTeal
```

## Components

### CAAS Discovery

- [Discovery](https://github.com/linudz/caastools/blob/main/modules/disco.py): `modules/disco.py`
- [Phenotype Config](https://github.com/linudz/caastools/blob/main/modules/pindex.py): `modules/pindex.py`

### Trait Resampling

- [Resampling](https://github.com/linudz/caastools/blob/main/modules/init_bootstrap.py): `modules/init_bootstrap.py`
- **Phylogenetic Tree**
- **Trait Values**
- **RERconverge**
- [BM Permulations](https://github.com/linudz/caastools/blob/main/scripts/permulations.r): `scripts/permulations.r`

### Bootstrap Validation

- [Bootstrap](https://github.com/linudz/caastools/blob/main/modules/boot.py): `modules/boot.py`
- [Resampled Traits](https://github.com/linudz/caastools/blob/main/modules/init_bootstrap.py): `modules/init_bootstrap.py`

### Alignment And Statistics

- [Alignment Slicer](https://github.com/linudz/caastools/blob/main/modules/runslice.py): `modules/runslice.py`
- [Alignment Import](https://github.com/linudz/caastools/blob/main/modules/alimport.py): `modules/alimport.py`
- [Position Analysis](https://github.com/linudz/caastools/blob/main/modules/caas_id.py): `modules/caas_id.py`
- [Pattern And P-values](https://github.com/linudz/caastools/blob/main/modules/hyper.py): `modules/hyper.py`

### Other components

- **Researcher**
- [ct CLI](https://github.com/linudz/caastools/blob/main/ct): `ct`
- **CAAS Results**

## Connections

- Researcher → ct CLI: runs tool
- ct CLI → Discovery: dispatches
- ct CLI → Resampling: dispatches
- ct CLI → Bootstrap: dispatches
- Discovery → Phenotype Config: loads config
- Discovery → Alignment Slicer: receives slices
- Alignment Slicer → Alignment Import: imports alignment
- Discovery → Position Analysis: processes positions
- Position Analysis → Pattern And P-values: calculates p-values
- Discovery → CAAS Results: writes candidates
- Researcher → Resampling: provides inputs
- Resampling → Phylogenetic Tree: reads tree
- Resampling → Trait Values: reads values
- Resampling → RERconverge: uses BM mode
- RERconverge → BM Permulations: runs script
- Resampling → Resampled Traits: writes groups
- Researcher → Bootstrap: requests validation
- Bootstrap → Resampled Traits: reads groups
- Bootstrap → Alignment Slicer: receives slices
- Bootstrap → Position Analysis: processes positions
- Bootstrap → CAAS Results: writes bootstrap results