A modern, integrated Horizontal-to-Vertical Spectral Ratio (HVSR) analysis suite for seismic site characterization — featuring project-based workflows, multi-station batch processing, bedrock depth mapping, HVSR inversion, and publication-quality visualization.
Author: Mersad Fathizadeh — Ph.D. Candidate, University of Arkansas
📧 mersadf@uark.edu · GitHub: @mersadfathizadeh1995
HVSR Pro provides a complete pipeline for HVSR analysis of ambient vibration (microtremor) recordings. From raw seismic data import through spectral ratio computation to bedrock depth estimation and Google Earth export — everything is accessible through an interactive GUI, command-line interface, or Python API.
| Module | Description |
|---|---|
| Standard Analysis | Single-station HVSR with interactive windowing, multi-algorithm rejection, and azimuthal processing |
| Batch Processing | Multi-station automated analysis with configurable sensor routing and time-window assignment |
| Bedrock Mapping | Spatial interpolation of bedrock depth from HVSR peak frequencies, with KMZ export to Google Earth |
| HV Strip | Progressive time-frequency analysis with multiple processing engines and a figure studio |
| HVSR Invert | Forward-model inversion of HVSR curves to recover subsurface velocity structure |
| Project Manager | Unified project workflow connecting all modules with persistent state |
Create and manage analysis projects. Define stations, assign sensors, and navigate between modules — all state is saved and restored automatically.
Load seismic data in multiple formats, configure processing settings, and compute HVSR interactively. Supports real-time window rejection, azimuthal processing, and layer-based visualization.
📈 Analysis Output Figures (click to expand)
HVSR Pro generates a comprehensive set of publication-quality figures for each analysis:
Three-component waveform display
Window spectrogram with time-frequency content
Pre- and post-rejection HVSR comparison
Raw vs. adjusted HVSR curves
Final HVSR curve with peak identification
Statistical summary — mean/median, variability, and quality metrics
Export dialog (left) and layer management panel (right)
Process multiple stations at once with automatic sensor routing, per-station time-window configuration, and comprehensive statistics. Results are saved to the project and can be reloaded at any time.
Per-station statistics: H/V curve with uncertainty, mean vs. median comparison, variability, and summary
Compute bedrock depth from HVSR peak frequencies and Vs profiles. Perform spatial interpolation (IDW, Kriging, RBF), generate surface and bedrock contours, and export everything to Google Earth as KMZ.
Station registry with coordinates, Vs average, f0, depth, and bedrock elevation
Interpolation configuration panel
Contour layers and station markers exported to Google Earth
2D cross-section and interactive 3D subsurface model
Time-frequency progressive HVSR analysis with multiple processing engines, side-by-side engine comparison, and a dedicated figure studio for creating custom visualizations.
Progressive analysis (left) and multi-engine comparison (right)
Figure Studio — customize and export publication-ready plots
Forward-model inversion of HVSR curves to estimate subsurface shear-wave velocity profiles. Define layer bounds, run the inversion, and visualize the recovered Vs structure.
Layer bound generation (left) and inversion progress (right)
- Python 3.8 or newer
- pip (included with Python)
git clone --recurse-submodules https://github.com/mersadfathizadeh1995/HV_Pro.git
cd HV_Pro/HV_Analyze_Pro# Windows
python -m venv .venv
.venv\Scripts\activate
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtOr install the package in editable mode:
pip install -e .Core Dependencies
| Package | Purpose |
|---|---|
| NumPy | Array operations and numerical computation |
| SciPy | Signal processing, spectral analysis |
| Matplotlib | Plotting and visualization |
| Pandas | Tabular data handling |
| ObsPy | Seismic data I/O (MiniSEED, SAC, etc.) |
| PyQt5 | GUI framework |
| PyQtWebEngine | Interactive map display |
| Folium | Leaflet-based station maps |
| Plotly | Interactive 3D visualizations |
| pyproj | Coordinate system transformations |
| scikit-learn | ML-based window rejection |
| PyYAML | Settings persistence |
Optional — 3D Bedrock Mapping
| Package | Purpose |
|---|---|
| PyKrige | Kriging interpolation |
| Shapely | Boundary geometry operations |
| PyVista | 3D mesh visualization and export |
| Pillow | Contour image generation |
# GUI launcher
python launch_gui.py
# Project Manager (project-based workflow)
python -m hvsr_pro.packages.project_manager.main
# CLI
python -m hvsr_pro.cli --helppython launch_gui.py- Load Data — Import seismic recordings (MiniSEED, SAC, GCF, TXT, and more)
- Configure — Adjust window length, overlap, smoothing, and rejection settings
- Process — Compute HVSR spectral ratios
- Reject — Toggle individual windows on/off interactively
- Analyze — View mean HVSR, peak frequency, amplitude, and quality metrics
- Export — Save results, plots, and full session files
# Process a single file
python -m hvsr_pro.cli process data.txt --output results/
# Batch process a directory
python -m hvsr_pro.cli batch input_dir/ --output results/
# Show help
python -m hvsr_pro.cli --helpfrom hvsr_pro import HVSRDataHandler, HVSRProcessor, HVSRAnalysis
# Quick analysis
analysis = HVSRAnalysis()
results = analysis.run("data.txt", output_dir="results/")
print(f"Peak frequency: {results.peak_frequency:.2f} Hz")
# Step-by-step
handler = HVSRDataHandler()
data = handler.load_data("data.txt")
processor = HVSRProcessor()
results = processor.process(data)HV_Pro/
└── HV_Analyze_Pro/
├── launch_gui.py # GUI launcher
├── setup.py # Package setup
├── requirements.txt # Dependencies
│
└── hvsr_pro/ # Main package
├── core/ # Data structures & handling
├── processing/ # HVSR computation engine
│ ├── hvsr/ # Spectral ratio algorithms
│ ├── windows/ # Window management
│ ├── rejection/ # Multi-algorithm rejection
│ ├── smoothing/ # Konno-Ohmachi, Parzen, etc.
│ └── azimuthal/ # Directional HVSR
├── visualization/ # Matplotlib plotting tools
├── gui/ # PyQt5 application
│ ├── main_window.py # Main window
│ ├── tabs/ # Analysis tab widgets
│ ├── panels/ # Side panels
│ ├── docks/ # Dockable widgets
│ ├── dialogs/ # Dialog windows
│ └── workers/ # Background threads
├── loaders/ # Format-specific readers
├── config/ # Settings & session persistence
├── cli/ # Command-line interface
├── api/ # Programmatic API
│
└── packages/ # Integrated sub-packages
├── project_manager/ # Project workflow manager
├── batch_processing/ # Multi-station batch analysis
├── bedrock_mapping/ # Bedrock depth mapping (submodule)
├── hvstrip-progressive/ # HV strip analysis (submodule)
└── invert_hvsr/ # HVSR inversion (submodule)
HVSR Pro follows a layered, modular architecture:
| Layer | Location | Role |
|---|---|---|
| Core | core/ |
Data structures, unified data handler, caching |
| Processing | processing/ |
Windowing, rejection, smoothing, HVSR computation |
| Visualization | visualization/ |
Matplotlib-based plotting engine |
| Loaders | loaders/ |
Format-specific readers (MiniSEED, SAC, GCF, TXT, ...) |
| Config | config/ |
Settings management, validation, session persistence |
| GUI | gui/ |
PyQt5 application with tabs, docks, and background workers |
| CLI / API | cli/, api/ |
Non-GUI access to the full pipeline |
| Packages | packages/ |
Self-contained modules (batch, bedrock, invert, HV strip) connected via the project manager |
| Format | Extension | Description |
|---|---|---|
| MiniSEED | .mseed, .miniseed |
Standard seismological format (via ObsPy) |
| SAC | .sac |
Seismic Analysis Code format |
| GCF | .gcf |
Guralp Compressed Format |
| ASCII/TXT | .txt, .dat |
Column-based time series |
| SAF | .saf |
Seismic Analysis Format |
| PEER | .at2, .peer |
PEER ground motion database |
| MiniShark | various | MiniShark portable recorder |
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m "Add my feature") - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
This work was developed under the guidance of Dr. Clinton Wood at the University of Arkansas. Parts of the azimuthal analysis workflow and certain data-input format handling drew inspiration from hvsrpy.
If you use HVSR Pro in your research, please cite:
Rahimi, M., Wood, C., Fathizadeh, M., & Rahimi, S. (2025). A Multi-method Geophysical Approach for Complex Shallow Landslide Characterization. Annals of Geophysics, 68(3), NS336. https://doi.org/10.4401/ag-9203
Copyright (C) 2025 Mersad Fathizadeh
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.
See the LICENSE file for details.