# colinstephen/dual_tree_hvg architecture

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

- Interactive diagram: https://gitdiagram.com/colinstephen/dual_tree_hvg
- Repository: https://github.com/colinstephen/dual_tree_hvg

## Overview

This repository implements horizontal visibility graph (HVG) construction and benchmarks its dual-tree method against binary-search-tree and divide-and-conquer approaches. The main workflow configures algorithms and time-series sources, generates benchmark inputs, times construction, and records results; separate experiments measure chunked graph construction and merging on fractional Brownian, finance, and EEG data. The source excerpts show algorithm internals and several benchmark paths; some benchmark modules are represented from the README and file tree, so their internal wiring is not inferred.

Main entry points: [`experiment1.py`](https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment1.py) (Experiment one), [`run_experiment.py`](https://github.com/colinstephen/dual_tree_hvg/blob/master/run_experiment.py) (Experiment runner), [`experiment2.py`](https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment2.py) (Experiment two), [`merge_experiment3.py`](https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment3.py) (FBM merge benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_algorithms["HVG algorithms"]
  node_dual_tree["Dual-tree HVG<br/>[dt_hvg.py]"]
  node_bst["BST HVG<br/>[bst_hvg.py]"]
  node_divide_conquer["Divide-conquer HVG<br/>[dc_hvg.py]"]
end

subgraph group_series["Time-series sources"]
  node_stream_generators["Series generators<br/>[streams.py]"]
  node_datasets["Finance and EEG data"]
end

subgraph group_benchmarks["Benchmark workflows"]
  node_benchmark_runner["Experiment runner<br/>[run_experiment.py]"]
  node_benchmark_utils["Benchmark utilities"]
  node_experiment_one["Experiment one<br/>[experiment1.py]"]
  node_experiment_two["Experiment two<br/>[experiment2.py]"]
  node_fbm_merge["FBM merge benchmark"]
  node_finance_merge["Finance merge benchmark"]
  node_eeg_merge["EEG merge benchmark"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_benchmark_runner
node_benchmark_runner -->|"times"| node_dual_tree
node_benchmark_runner -->|"times"| node_bst
node_benchmark_runner -->|"times"| node_divide_conquer
node_benchmark_runner -->|"generates inputs"| node_stream_generators
node_researcher -->|"runs"| node_experiment_one
node_experiment_one -->|"uses"| node_benchmark_utils
node_experiment_one -->|"selects sources"| node_stream_generators
node_experiment_one -->|"benchmarks"| node_dual_tree
node_experiment_one -->|"benchmarks"| node_bst
node_experiment_one -->|"benchmarks"| node_divide_conquer
node_researcher -->|"runs"| node_experiment_two
node_experiment_two -->|"uses"| node_benchmark_utils
node_experiment_two -->|"selects sources"| node_stream_generators
node_experiment_two -->|"benchmarks"| node_dual_tree
node_experiment_two -->|"benchmarks"| node_bst
node_researcher -->|"runs"| node_fbm_merge
node_fbm_merge -->|"generates FBM"| node_stream_generators
node_fbm_merge -->|"builds and merges"| node_dual_tree
node_fbm_merge -->|"builds and merges"| node_bst
node_researcher -.->|"runs"| node_finance_merge
node_finance_merge -->|"reads finance data"| node_datasets
node_researcher -.->|"runs"| node_eeg_merge
node_eeg_merge -->|"reads EEG data"| node_datasets

click node_dual_tree "https://github.com/colinstephen/dual_tree_hvg/blob/master/dt_hvg.py"
click node_bst "https://github.com/colinstephen/dual_tree_hvg/blob/master/bst_hvg.py"
click node_divide_conquer "https://github.com/colinstephen/dual_tree_hvg/blob/master/dc_hvg.py"
click node_stream_generators "https://github.com/colinstephen/dual_tree_hvg/blob/master/streams.py"
click node_benchmark_runner "https://github.com/colinstephen/dual_tree_hvg/blob/master/run_experiment.py"
click node_benchmark_utils "https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment_utils.py"
click node_experiment_one "https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment1.py"
click node_experiment_two "https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment2.py"
click node_fbm_merge "https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment3.py"
click node_finance_merge "https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment.py"
click node_eeg_merge "https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment2.py"
click node_datasets "https://github.com/colinstephen/dual_tree_hvg/tree/master/data"

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_dual_tree,node_bst,node_divide_conquer toneBlue
class node_stream_generators,node_datasets toneAmber
class node_benchmark_runner,node_benchmark_utils,node_experiment_one,node_experiment_two,node_fbm_merge,node_finance_merge,node_eeg_merge toneMint
class node_researcher toneIndigo
```

## Components

### HVG algorithms

- [Dual-tree HVG](https://github.com/colinstephen/dual_tree_hvg/blob/master/dt_hvg.py): `dt_hvg.py`
- [BST HVG](https://github.com/colinstephen/dual_tree_hvg/blob/master/bst_hvg.py): `bst_hvg.py`
- [Divide-conquer HVG](https://github.com/colinstephen/dual_tree_hvg/blob/master/dc_hvg.py): `dc_hvg.py`

### Time-series sources

- [Series generators](https://github.com/colinstephen/dual_tree_hvg/blob/master/streams.py): `streams.py`
- [Finance and EEG data](https://github.com/colinstephen/dual_tree_hvg/tree/master/data): `data`

### Benchmark workflows

- [Experiment runner](https://github.com/colinstephen/dual_tree_hvg/blob/master/run_experiment.py): `run_experiment.py`
- [Benchmark utilities](https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment_utils.py): `experiment_utils.py`
- [Experiment one](https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment1.py): `experiment1.py`
- [Experiment two](https://github.com/colinstephen/dual_tree_hvg/blob/master/experiment2.py): `experiment2.py`
- [FBM merge benchmark](https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment3.py): `merge_experiment3.py`
- [Finance merge benchmark](https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment.py): `merge_experiment.py`
- [EEG merge benchmark](https://github.com/colinstephen/dual_tree_hvg/blob/master/merge_experiment2.py): `merge_experiment2.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment runner: runs (evidence: `run_experiment.py`)
- Experiment runner → Dual-tree HVG: times (evidence: `run_experiment.py`)
- Experiment runner → BST HVG: times (evidence: `run_experiment.py`)
- Experiment runner → Divide-conquer HVG: times (evidence: `run_experiment.py`)
- Experiment runner → Series generators: generates inputs (evidence: `run_experiment.py`)
- Researcher → Experiment one: runs (evidence: `experiment1.py`)
- Experiment one → Benchmark utilities: uses (evidence: `experiment1.py`)
- Experiment one → Series generators: selects sources (evidence: `experiment1.py`)
- Experiment one → Dual-tree HVG: benchmarks (evidence: `experiment1.py`)
- Experiment one → BST HVG: benchmarks (evidence: `experiment1.py`)
- Experiment one → Divide-conquer HVG: benchmarks (evidence: `experiment1.py`)
- Researcher → Experiment two: runs (evidence: `experiment2.py`)
- Experiment two → Benchmark utilities: uses (evidence: `experiment2.py`)
- Experiment two → Series generators: selects sources (evidence: `experiment2.py`)
- Experiment two → Dual-tree HVG: benchmarks (evidence: `experiment2.py`)
- Experiment two → BST HVG: benchmarks (evidence: `experiment2.py`)
- Researcher → FBM merge benchmark: runs (evidence: `merge_experiment3.py`)
- FBM merge benchmark → Series generators: generates FBM (evidence: `merge_experiment3.py`)
- FBM merge benchmark → Dual-tree HVG: builds and merges (evidence: `merge_experiment3.py`)
- FBM merge benchmark → BST HVG: builds and merges (evidence: `merge_experiment3.py`)
- Researcher → Finance merge benchmark: runs
- Finance merge benchmark → Finance and EEG data: reads finance data (evidence: `merge_experiment.py`)
- Researcher → EEG merge benchmark: runs
- EEG merge benchmark → Finance and EEG data: reads EEG data (evidence: `merge_experiment2.py`)
