# acenglish/truvari architecture

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

- Interactive diagram: https://gitdiagram.com/acenglish/truvari
- Repository: https://github.com/acenglish/truvari

## Overview

Truvari is a command-line toolkit for structural-variant VCF comparison, benchmarking, merging, harmonization, and annotation. Its main workflow takes base and comparison VCFs through benchmarking to performance results; users can then refine benchmark results with phab. Other documented commands provide independent analysis branches. The graph preserves these capabilities and the shared variant-processing layer. Command implementations are represented by their documented modules; source excerpts were partial, so uncertain internal call wiring is omitted.

Main entry points: [`truvari/__main__.py`](https://github.com/acenglish/truvari/blob/develop/truvari/__main__.py) (Command dispatcher), [`truvari/variant_file.py`](https://github.com/acenglish/truvari/blob/develop/truvari/variant_file.py) (VCF access), [`truvari/phab.py`](https://github.com/acenglish/truvari/blob/develop/truvari/phab.py) (Harmonize variants), [`truvari/comparisons.py`](https://github.com/acenglish/truvari/blob/develop/truvari/comparisons.py) (Benchmark VCFs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command workflows"]
  node_cli["Command dispatcher<br/>[__main__.py]"]
end

subgraph group_benchmark["Comparison and benchmarking"]
  node_bench["Benchmark VCFs<br/>[comparisons.py]"]
  node_match["Match variants<br/>[matching.py]"]
  node_metrics["Benchmark results<br/>[comparisons.py]"]
end

subgraph group_variant["Variant processing"]
  node_params["Variant parameters<br/>[variant_params.py]"]
  node_records["Variant records<br/>[variant_record.py]"]
  node_vcf["VCF access<br/>[variant_file.py]"]
  node_utils["Variant utilities<br/>[utils.py]"]
end

subgraph group_harmonize["Merging and harmonization"]
  node_collapse["Collapse variants<br/>[collapse.py]"]
  node_refine["Refine results<br/>[refine.py]"]
  node_phab["Harmonize variants<br/>[phab.py]"]
  node_ga4gh["Consolidate results<br/>[make_ga4gh.py]"]
end

subgraph group_analysis["Annotation and analysis"]
  node_anno["Annotate VCF<br/>[anno.py]"]
  node_annotation_modules["Annotation methods"]
  node_consistency["Consistency report<br/>[consistency.py]"]
  node_vcf2df["VCF to DataFrame<br/>[vcf2df.py]"]
  node_segment["Segment variants<br/>[segmentation.py]"]
  node_stratify["Region counts<br/>[stratify.py]"]
  node_divide["Shard VCF<br/>[divide.py]"]
  node_msatovcf["MSA to VCF<br/>[msatovcf.py]"]
end

node_user(("User"))
node_input_vcfs["Input VCFs"]
node_reference["Reference FASTA"]
node_output_vcf["Output VCF"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_bench
node_cli -->|"dispatches"| node_collapse
node_cli -->|"dispatches"| node_refine
node_cli -->|"dispatches"| node_phab
node_cli -->|"dispatches"| node_ga4gh
node_cli -->|"dispatches"| node_anno
node_cli -->|"dispatches"| node_consistency
node_cli -->|"dispatches"| node_vcf2df
node_cli -->|"dispatches"| node_segment
node_cli -->|"dispatches"| node_stratify
node_cli -->|"dispatches"| node_divide
node_input_vcfs -->|"read VCFs"| node_vcf
node_bench -->|"reads variants"| node_vcf
node_bench -->|"matches variants"| node_match
node_bench -->|"writes metrics"| node_metrics
node_match -->|"compares records"| node_records
node_vcf -->|"yields records"| node_records
node_params -->|"configures"| node_records
node_reference -->|"builds haplotypes"| node_phab
node_phab -->|"reads variants"| node_input_vcfs
node_refine -->|"uses harmonization"| node_phab
node_refine -->|"refines results"| node_metrics
node_collapse -->|"reads variants"| node_vcf
node_collapse -->|"checks matches"| node_match
node_collapse -->|"writes collapsed calls"| node_output_vcf
node_phab -->|"writes harmonized calls"| node_output_vcf
node_anno -->|"applies annotations"| node_annotation_modules
node_anno -->|"reads variants"| node_vcf
node_annotation_modules -->|"uses reference"| node_reference
node_anno -->|"writes annotated calls"| node_output_vcf
node_consistency -->|"reads VCFs"| node_vcf
node_vcf2df -->|"reads variants"| node_vcf
node_segment -->|"reads variants"| node_vcf
node_stratify -->|"counts regions"| node_vcf
node_divide -->|"reads variants"| node_vcf
node_ga4gh -->|"consolidates results"| node_metrics
node_msatovcf -->|"writes VCF"| node_output_vcf

click node_cli "https://github.com/acenglish/truvari/blob/develop/truvari/__main__.py"
click node_bench "https://github.com/acenglish/truvari/blob/develop/truvari/comparisons.py"
click node_match "https://github.com/acenglish/truvari/blob/develop/truvari/matching.py"
click node_metrics "https://github.com/acenglish/truvari/blob/develop/truvari/comparisons.py"
click node_params "https://github.com/acenglish/truvari/blob/develop/truvari/variant_params.py"
click node_records "https://github.com/acenglish/truvari/blob/develop/truvari/variant_record.py"
click node_vcf "https://github.com/acenglish/truvari/blob/develop/truvari/variant_file.py"
click node_utils "https://github.com/acenglish/truvari/blob/develop/truvari/utils.py"
click node_collapse "https://github.com/acenglish/truvari/blob/develop/truvari/collapse.py"
click node_refine "https://github.com/acenglish/truvari/blob/develop/truvari/refine.py"
click node_phab "https://github.com/acenglish/truvari/blob/develop/truvari/phab.py"
click node_ga4gh "https://github.com/acenglish/truvari/blob/develop/truvari/make_ga4gh.py"
click node_anno "https://github.com/acenglish/truvari/blob/develop/truvari/anno.py"
click node_annotation_modules "https://github.com/acenglish/truvari/tree/develop/truvari/annotations"
click node_consistency "https://github.com/acenglish/truvari/blob/develop/truvari/consistency.py"
click node_vcf2df "https://github.com/acenglish/truvari/blob/develop/truvari/vcf2df.py"
click node_segment "https://github.com/acenglish/truvari/blob/develop/truvari/segmentation.py"
click node_stratify "https://github.com/acenglish/truvari/blob/develop/truvari/stratify.py"
click node_divide "https://github.com/acenglish/truvari/blob/develop/truvari/divide.py"
click node_msatovcf "https://github.com/acenglish/truvari/blob/develop/truvari/msatovcf.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_user toneBlue
class node_bench,node_match,node_metrics toneAmber
class node_params,node_records,node_vcf,node_utils toneMint
class node_collapse,node_refine,node_phab,node_ga4gh toneRose
class node_anno,node_annotation_modules,node_consistency,node_vcf2df,node_segment,node_stratify,node_divide,node_msatovcf,node_input_vcfs,node_reference,node_output_vcf toneIndigo
```

## Components

### Command workflows

- [Command dispatcher](https://github.com/acenglish/truvari/blob/develop/truvari/__main__.py): `truvari/__main__.py`

### Comparison and benchmarking

- [Benchmark VCFs](https://github.com/acenglish/truvari/blob/develop/truvari/comparisons.py): `truvari/comparisons.py`
- [Match variants](https://github.com/acenglish/truvari/blob/develop/truvari/matching.py): `truvari/matching.py`
- [Benchmark results](https://github.com/acenglish/truvari/blob/develop/truvari/comparisons.py): `truvari/comparisons.py`

### Variant processing

- [Variant parameters](https://github.com/acenglish/truvari/blob/develop/truvari/variant_params.py): `truvari/variant_params.py`
- [Variant records](https://github.com/acenglish/truvari/blob/develop/truvari/variant_record.py): `truvari/variant_record.py`
- [VCF access](https://github.com/acenglish/truvari/blob/develop/truvari/variant_file.py): `truvari/variant_file.py`
- [Variant utilities](https://github.com/acenglish/truvari/blob/develop/truvari/utils.py): `truvari/utils.py`

### Merging and harmonization

- [Collapse variants](https://github.com/acenglish/truvari/blob/develop/truvari/collapse.py): `truvari/collapse.py`
- [Refine results](https://github.com/acenglish/truvari/blob/develop/truvari/refine.py): `truvari/refine.py`
- [Harmonize variants](https://github.com/acenglish/truvari/blob/develop/truvari/phab.py): `truvari/phab.py`
- [Consolidate results](https://github.com/acenglish/truvari/blob/develop/truvari/make_ga4gh.py): `truvari/make_ga4gh.py`

### Annotation and analysis

- [Annotate VCF](https://github.com/acenglish/truvari/blob/develop/truvari/anno.py): `truvari/anno.py`
- [Annotation methods](https://github.com/acenglish/truvari/tree/develop/truvari/annotations): `truvari/annotations`
- [Consistency report](https://github.com/acenglish/truvari/blob/develop/truvari/consistency.py): `truvari/consistency.py`
- [VCF to DataFrame](https://github.com/acenglish/truvari/blob/develop/truvari/vcf2df.py): `truvari/vcf2df.py`
- [Segment variants](https://github.com/acenglish/truvari/blob/develop/truvari/segmentation.py): `truvari/segmentation.py`
- [Region counts](https://github.com/acenglish/truvari/blob/develop/truvari/stratify.py): `truvari/stratify.py`
- [Shard VCF](https://github.com/acenglish/truvari/blob/develop/truvari/divide.py): `truvari/divide.py`
- [MSA to VCF](https://github.com/acenglish/truvari/blob/develop/truvari/msatovcf.py): `truvari/msatovcf.py`

### Other components

- **User**
- **Input VCFs**
- **Reference FASTA**
- **Output VCF**

## Connections

- User → Command dispatcher: runs commands
- Command dispatcher → Benchmark VCFs: dispatches
- Command dispatcher → Collapse variants: dispatches
- Command dispatcher → Refine results: dispatches
- Command dispatcher → Harmonize variants: dispatches
- Command dispatcher → Consolidate results: dispatches
- Command dispatcher → Annotate VCF: dispatches
- Command dispatcher → Consistency report: dispatches
- Command dispatcher → VCF to DataFrame: dispatches
- Command dispatcher → Segment variants: dispatches
- Command dispatcher → Region counts: dispatches
- Command dispatcher → Shard VCF: dispatches
- Input VCFs → VCF access: read VCFs
- Benchmark VCFs → VCF access: reads variants
- Benchmark VCFs → Match variants: matches variants
- Benchmark VCFs → Benchmark results: writes metrics
- Match variants → Variant records: compares records
- VCF access → Variant records: yields records
- Variant parameters → Variant records: configures
- Reference FASTA → Harmonize variants: builds haplotypes
- Harmonize variants → Input VCFs: reads variants
- Refine results → Harmonize variants: uses harmonization
- Refine results → Benchmark results: refines results
- Collapse variants → VCF access: reads variants
- Collapse variants → Match variants: checks matches
- Collapse variants → Output VCF: writes collapsed calls
- Harmonize variants → Output VCF: writes harmonized calls
- Annotate VCF → Annotation methods: applies annotations
- Annotate VCF → VCF access: reads variants
- Annotation methods → Reference FASTA: uses reference
- Annotate VCF → Output VCF: writes annotated calls
- Consistency report → VCF access: reads VCFs
- VCF to DataFrame → VCF access: reads variants
- Segment variants → VCF access: reads variants
- Region counts → VCF access: counts regions
- Shard VCF → VCF access: reads variants
- Consolidate results → Benchmark results: consolidates results
- MSA to VCF → Output VCF: writes VCF