HAB-COM

HAB-COM is a software suite for live tracking HABs and running trajectory predictions with the latest forecasts for High Altitude Balloons (HABs).

Project Status

This suite is under active development.

Working:

• The data collectors (GFS, radiosondes, ADS-B, APRS, SPOT)
• montecarlo_dash — Monte Carlo trajectory dashboard
• wind_vis — GFS wind/forecast visualizer with interactive Skew-T
• tracker — live HAB tracker (APRS/ADS-B)
• tracker_w_prediction — live tracker + single / Monte Carlo forward-trajectory predictor

In progress: the reachability / comparison scripts in beta

Project Layout

Run everything from the repo root as a module (python -m hab.<sub>.<name>) so package imports and the regions/ input path resolve.

hab/
  config.py          # shared data dir + GFS grid / forecast / Monte Carlo defaults
  collectors/        # gfs, radiosondes, adsb, aprs, spot collectors
  utils/             # transform, advection, wind interpolation, forecast backends
  backend/           # Forecast engine, Monte Carlo, ensemble + reachability compute
  frontend/          # Dash dashboards + FastAPI app (static/, templates/)
  verification/      # verify_backends, verify_montecarlo (engine correctness checks)
  scripts/           # standalone analysis CLIs (compare_winds)
data/                # regions/ station CSVs (collector *input*, committed)
outputs/             # generated .html / .png / .csv artifacts (gitignored)

Shared collector outputs. All collector outputs (the SQLite DBs and GFS_DATA/) save to config.DATA_DIR. It defaults to /srv/shared/HAB-COM/data (group-writable by developers) and is overridable with the HAB_DATA_DIR env var (e.g. point at a local copy for development):

To start/stop all dashboards at once with the helper script (each runs in its own detached screen named dash-*, so stop kills only the dashboards):

./dashboards.sh start     # start all four dashboards
./dashboards.sh stop      # kill only the dash-* screens
./dashboards.sh restart   # stop then start
./dashboards.sh status    # list running dashboards

Once running, open (Ctrl/Cmd-click in most terminals):

• wind_vis — http://localhost:8083
• tracker_w_prediction — http://localhost:8084
• tracker — http://localhost:8085
• montecarlo_dash — http://localhost:7005

Installation

Tested on:

• Ubuntu 24.04
• conda 25.11.1
• Python 3.13

conda install -c conda-forge netcdf4 hdf5 libnetcdf --force-reinstall
conda create -n HAB-COM -c conda-forge python=3.13 netcdf4 xarray h5py
conda activate HAB-COM
pip install -r requirements.txt

Supported Forecasts

Currently only GFS from AWS is supported.

Note: GFS uses geopotential height ("HGT", "GH") which we convert to "z" whereas ERA5 uses geopotential (m²/s²) and needs to be divided by the gravitational constant. We also assume geopotential height to be approximately equivalent to altitude (geometric height). At higher altitudes this error increases, but it is good enough for HABs.

Viewing Databases

The collectors generate 4 different sqlite3 databases under the shared data dir (config.DATA_DIR, default /srv/shared/HAB-COM/data):

• radiosondes.sqlite3
• adsb.sqlite3
• aprs.sqlite3
• spot.sqlite3

These can be explored in a web browser with the datasette python package

Usage:

datasette path/to/your_database.db

Script Descriptions

[hab/collectors] Download scripts

• multi-download.sh this will run 5 collector modules in new named screen windows:
  • hab.collectors.gfs_collector Download and processes latest GFS forecast from AWS
  • hab.collectors.radiosondes_collector Download latest radiosonde data from University of Wyoming and save to database. This script requires option flags set. Database is saved to radiosondes.sqlite3 in the shared data dir by default.
  • hab.collectors.adsb_collector downloads latest HAB adsb callsigns by first checking opensky for eligible HBAL callsigns and then using adsb.lol API to download the latest tracking information. Database is saved to adsb.sqlite3 in the shared data dir by default
  • hab.collectors.aprs_collector downloads latest aprs callsigns from pre-defined list to check under TARGETS at the top of the file using python library aprslib. Database is saved to aprs.sqlite3 in the shared data dir by default.
  • hab.collectors.spot_collector downloads latest SPOT tracker messages and saves them to the database. Database is saved to spot.sqlite3 in the shared data dir by default.

Processing scripts

• hab.scripts.compare_winds will compare latest radiosonde sounding to GFS forecast. Follow usage examples. Note, radiosonde and GFS data needs to be downloaded already.

Interactive Dashboards

• hab.frontend.montecarlo_dash runs a Monte Carlo ensemble over the latest forecast and shows predicted trajectories, an altitude profile, and an hourly position-probability heatmap with play/scrub controls.
• hab.frontend.wind_vis opens a GFS visualization (forecast maps, interactive Skew-T, wind rose) of the most recently downloaded and processed GFS forecast.
• hab.frontend.tracker plots live HAB tracks from an APRS/ADS-B sqlite database. Filter by callsign and time range; scroll to zoom the map; box-zoom the altitude plot's time axis to filter and re-center the map to that window.
  • ADS-B HABs can be viewed with the same script by changing the sqlite DB source to the shared adsb.sqlite3 and leaving the table as is.
• hab.frontend.tracker_w_prediction combines the live tracker with the Monte Carlo engine: pick a live HAB and run a single (deterministic) or Monte Carlo forward trajectory seeded from its latest fix, using the same forecast backends as hab.frontend.montecarlo_dash.
  • Start position/altitude/time are taken live from the HAB's latest fix at run time. By default the balloon holds its current altitude (a float-altitude spread can be applied for Monte Carlo runs).
  • The simulation window is automatically clamped to the loaded forecast's coverage.
  • The live historical track overlays the trajectory map and altitude fan, with the latest fix marked.