# zhong-yy/volpick architecture

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

- Interactive diagram: https://gitdiagram.com/zhong-yy/volpick
- Repository: https://github.com/zhong-yy/volpick

## Overview

Volpick is a research workflow for assembling volcano-seismic waveform data, formatting it as SeisBench datasets, training phase pickers, and evaluating their picks. Its user-facing result is phase-pick predictions; it also provides the VCSEIS benchmark and pretrained models usable through SeisBench. The map preserves distinct acquisition, dataset preparation, training, and evaluation stages. Some subsystem links are based on README descriptions because their source was not sampled; uncertain implementation details are omitted.

Main entry points: [`volpick/model/train.py`](https://github.com/zhong-yy/volpick/blob/main/volpick/model/train.py) (Training interface), [`volpick/data/convert.py`](https://github.com/zhong-yy/volpick/blob/main/volpick/data/convert.py) (SeisBench conversion), [`volpick/data/data.py`](https://github.com/zhong-yy/volpick/blob/main/volpick/data/data.py) (Catalog and waveform clients), [`volpick/model/eval_taks0.py`](https://github.com/zhong-yy/volpick/blob/main/volpick/model/eval_taks0.py) (Task 0 evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Data acquisition"]
  node_download_scripts["Regional download scripts<br/>[download_alaska.py]"]
  node_data_clients["Catalog and waveform clients<br/>[data.py]"]
  node_raw_waveforms[("Downloaded waveforms")]
end

subgraph group_preparation["Dataset preparation"]
  node_channel_check["Waveform channel checks"]
  node_dataset_combine["Dataset combining"]
  node_dataset_converter["SeisBench conversion<br/>[convert.py]"]
  node_data_utils["Signal utilities<br/>[utils.py]"]
  node_vcseis[("VCSEIS dataset")]
end

subgraph group_learning["Picker training"]
  node_training_interface["Training interface<br/>[train.py]"]
  node_picker_models["Picker architectures<br/>[models.py]"]
  node_augmentations["Training augmentations<br/>[augmentations.py]"]
  node_ema["EMA training support<br/>[ema.py]"]
  node_trained_weights[("Trained picker weights")]
end

subgraph group_evaluation["Evaluation and use"]
  node_target_generation["Evaluation target generation"]
  node_task0_eval["Task 0 evaluation<br/>[eval_taks0.py]"]
  node_task123_eval["Tasks 1–3 evaluation<br/>[eval_taks123.py]"]
  node_model_utils["Model utilities<br/>[utils.py]"]
end

node_researcher(("Researcher"))
node_regional_sources(("Regional catalogs and waveforms"))
node_seisbench["SeisBench model API"]
node_phase_picks["Phase-pick results"]

node_researcher -->|"runs acquisition"| node_download_scripts
node_download_scripts -->|"calls dataset clients"| node_data_clients
node_data_clients -->|"requests data"| node_regional_sources
node_data_clients -->|"saves waveforms"| node_raw_waveforms
node_researcher -->|"checks waveforms"| node_channel_check
node_channel_check -->|"reads waveforms"| node_raw_waveforms
node_researcher -->|"converts data"| node_dataset_converter
node_dataset_converter -->|"reads waveforms"| node_raw_waveforms
node_dataset_converter -->|"uses signal utilities"| node_data_utils
node_dataset_converter -->|"writes SeisBench format"| node_vcseis
node_dataset_combine -->|"combines datasets"| node_vcseis
node_researcher -->|"starts training"| node_training_interface
node_training_interface -->|"loads training data"| node_vcseis
node_training_interface -->|"trains picker"| node_picker_models
node_training_interface -->|"uses augmentation"| node_augmentations
node_training_interface -->|"uses EMA support"| node_ema
node_training_interface -->|"saves weights"| node_trained_weights
node_researcher -->|"prepares evaluation"| node_target_generation
node_target_generation -->|"reads dataset metadata"| node_vcseis
node_researcher -->|"runs evaluation"| node_task0_eval
node_researcher -->|"runs evaluation"| node_task123_eval
node_task0_eval -->|"reads waveforms and metadata"| node_vcseis
node_task123_eval -->|"reads waveforms and metadata"| node_vcseis
node_task0_eval -->|"uses model utilities"| node_model_utils
node_task123_eval -->|"uses model utilities"| node_model_utils
node_trained_weights -.->|"loads pretrained model"| node_seisbench
node_researcher -->|"classifies waveform"| node_seisbench
node_seisbench -->|"returns picks"| node_phase_picks

click node_download_scripts "https://github.com/zhong-yy/volpick/blob/main/data_proc/download_alaska.py"
click node_data_clients "https://github.com/zhong-yy/volpick/blob/main/volpick/data/data.py"
click node_channel_check "https://github.com/zhong-yy/volpick/blob/main/data_proc/check_V_channels.py"
click node_dataset_combine "https://github.com/zhong-yy/volpick/blob/main/data_proc/combine_datasets.py"
click node_dataset_converter "https://github.com/zhong-yy/volpick/blob/main/volpick/data/convert.py"
click node_data_utils "https://github.com/zhong-yy/volpick/blob/main/volpick/data/utils.py"
click node_training_interface "https://github.com/zhong-yy/volpick/blob/main/volpick/model/train.py"
click node_picker_models "https://github.com/zhong-yy/volpick/blob/main/volpick/model/models.py"
click node_augmentations "https://github.com/zhong-yy/volpick/blob/main/volpick/model/augmentations.py"
click node_ema "https://github.com/zhong-yy/volpick/blob/main/volpick/model/ema.py"
click node_target_generation "https://github.com/zhong-yy/volpick/blob/main/volpick/model/generate_eval_targets.py"
click node_task0_eval "https://github.com/zhong-yy/volpick/blob/main/volpick/model/eval_taks0.py"
click node_task123_eval "https://github.com/zhong-yy/volpick/blob/main/volpick/model/eval_taks123.py"
click node_model_utils "https://github.com/zhong-yy/volpick/blob/main/volpick/model/utils.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_download_scripts,node_data_clients,node_raw_waveforms toneBlue
class node_channel_check,node_dataset_combine,node_dataset_converter,node_data_utils,node_vcseis toneAmber
class node_training_interface,node_picker_models,node_augmentations,node_ema,node_trained_weights,node_seisbench toneMint
class node_target_generation,node_task0_eval,node_task123_eval,node_model_utils toneRose
class node_researcher,node_regional_sources,node_phase_picks toneIndigo
```

## Components

### Data acquisition

- [Regional download scripts](https://github.com/zhong-yy/volpick/blob/main/data_proc/download_alaska.py): `data_proc/download_alaska.py`
- [Catalog and waveform clients](https://github.com/zhong-yy/volpick/blob/main/volpick/data/data.py): `volpick/data/data.py`
- **Downloaded waveforms**

### Dataset preparation

- [Waveform channel checks](https://github.com/zhong-yy/volpick/blob/main/data_proc/check_V_channels.py): `data_proc/check_V_channels.py`
- [Dataset combining](https://github.com/zhong-yy/volpick/blob/main/data_proc/combine_datasets.py): `data_proc/combine_datasets.py`
- [SeisBench conversion](https://github.com/zhong-yy/volpick/blob/main/volpick/data/convert.py): `volpick/data/convert.py`
- [Signal utilities](https://github.com/zhong-yy/volpick/blob/main/volpick/data/utils.py): `volpick/data/utils.py`
- **VCSEIS dataset**

### Picker training

- [Training interface](https://github.com/zhong-yy/volpick/blob/main/volpick/model/train.py): `volpick/model/train.py`
- [Picker architectures](https://github.com/zhong-yy/volpick/blob/main/volpick/model/models.py): `volpick/model/models.py`
- [Training augmentations](https://github.com/zhong-yy/volpick/blob/main/volpick/model/augmentations.py): `volpick/model/augmentations.py`
- [EMA training support](https://github.com/zhong-yy/volpick/blob/main/volpick/model/ema.py): `volpick/model/ema.py`
- **Trained picker weights**

### Evaluation and use

- [Evaluation target generation](https://github.com/zhong-yy/volpick/blob/main/volpick/model/generate_eval_targets.py): `volpick/model/generate_eval_targets.py`
- [Task 0 evaluation](https://github.com/zhong-yy/volpick/blob/main/volpick/model/eval_taks0.py): `volpick/model/eval_taks0.py`
- [Tasks 1–3 evaluation](https://github.com/zhong-yy/volpick/blob/main/volpick/model/eval_taks123.py): `volpick/model/eval_taks123.py`
- [Model utilities](https://github.com/zhong-yy/volpick/blob/main/volpick/model/utils.py): `volpick/model/utils.py`

### Other components

- **Researcher**
- **Regional catalogs and waveforms**
- **SeisBench model API**
- **Phase-pick results**

## Connections

- Researcher → Regional download scripts: runs acquisition
- Regional download scripts → Catalog and waveform clients: calls dataset clients
- Catalog and waveform clients → Regional catalogs and waveforms: requests data
- Catalog and waveform clients → Downloaded waveforms: saves waveforms
- Researcher → Waveform channel checks: checks waveforms
- Waveform channel checks → Downloaded waveforms: reads waveforms
- Researcher → SeisBench conversion: converts data
- SeisBench conversion → Downloaded waveforms: reads waveforms
- SeisBench conversion → Signal utilities: uses signal utilities
- SeisBench conversion → VCSEIS dataset: writes SeisBench format
- Dataset combining → VCSEIS dataset: combines datasets
- Researcher → Training interface: starts training
- Training interface → VCSEIS dataset: loads training data
- Training interface → Picker architectures: trains picker
- Training interface → Training augmentations: uses augmentation
- Training interface → EMA training support: uses EMA support
- Training interface → Trained picker weights: saves weights
- Researcher → Evaluation target generation: prepares evaluation
- Evaluation target generation → VCSEIS dataset: reads dataset metadata
- Researcher → Task 0 evaluation: runs evaluation
- Researcher → Tasks 1–3 evaluation: runs evaluation
- Task 0 evaluation → VCSEIS dataset: reads waveforms and metadata
- Tasks 1–3 evaluation → VCSEIS dataset: reads waveforms and metadata
- Task 0 evaluation → Model utilities: uses model utilities
- Tasks 1–3 evaluation → Model utilities: uses model utilities
- Trained picker weights → SeisBench model API: loads pretrained model
- Researcher → SeisBench model API: classifies waveform
- SeisBench model API → Phase-pick results: returns picks