BMM-4D: bird-migration reconstruction in space and time from weather radars

Version 1 (v1.0.0, v1.0.1) is the method of the paper (tag paper-v1) as a MATLAB package. Version 2 changes the production defaults: radar data to density, observation errors, prior and wind field, terrain following, the web map and cluster runs. The paper path is kept and checked against paper-v1 by the regression test. Every change between versions is listed in MIGRATION.md. To cite, use CITATION.cff ("Cite this repository" on GitHub).

Code for reconstructing animated 3D bird-density fields from a network of NEXRAD radars: radar processing, forward model, density prior, advection-regularized inversion, and the operational pipeline built on them.

This repository was split from the paper repository BMM-within on 24 October 2026. The paper keeps its own frozen copy of the code; tag paper-v1 marks the code state behind the submitted manuscript figures (paper commit e52a81b). Changes made here reach the paper only when they are ported on purpose and the affected workflows rerun.

Layout

Path	Content
toolbox/	The package, in the bmm4d namespace (toolbox/+bmm4d/): radar reading and cleaning (bmm4d.radar), beam kernels and forward operator (bmm4d.forward), grid and masks (bmm4d.grid), priors (bmm4d.prior), advection (bmm4d.advect), solvers (bmm4d.solve), plotting (bmm4d.plot), helpers (bmm4d.util). Calls are written in full, e.g. bmm4d.radar.read_rd(...); a script can import bmm4d.radar.* to use short names.
examples/	Running a case: run_case.m calls the stages (bmm4d.config, get_volumes, clean_volumes, static_clutter, build_observations, invert, export_maps, export_webmap); case_settings.m holds the test cases. See examples/README.md.
synthetic/	Synthetic truths, advection and observations for tests and studies; not part of the package.
studies/	Research beside the package: gate density near the radar (gate_density), rain and cleaning methods (cleaning_study), the Midwest sandbox (sandbox), beam-blockage maps (beam_blockage) and kernel generation (kernels).
tests/	Unit tests of the shared code, and paperRegressionTest (tag Regression): today's code against outputs of tag paper-v1 on three Key West volumes. Its reference is local (data/regression/), built by tests/regression/make_regression_reference.m.
hpc/	Runs on the Vogelwarte HPC cluster from a frozen snapshot of the working tree (submit.sh, bmm4d_submit.m); see hpc/README.md.
webmap/	The viewer of inversion results: bmm4d.export_webmap exports a run, python3 webmap/serve.py lists every run on the laptop and the cluster share and shows it on a zoomable, animated map; see webmap/README.md.

Setup

Copy local_settings.example.json to local_settings.json (not tracked) and set the folders of this machine, then:

project_root = setup_paths();

setup_paths installs the bmm4d package (toolbox/) in place for the MATLAB session, so edits apply at once, and adds the external code, whose folders come from local_settings.json (absolute, or relative to the repository root; defaults under external/, which is not tracked):

Setting	Code	Needed for
wsrlib_dir	wsrlib: NEXRAD reading (rsl2mat), VVP, MatConvNet for MistNet. On Apple Silicon, MatConvNet must be built without finite-math assumptions (master of Rafnuss/wsrlib from commit 482e6a8, part of darkecology/wsrlib#3); mistnet_polar_radar stops otherwise.	Required; setup_paths stops with an error without it
regtools_dir	Hansen's Regularization Tools (cgsvd, tikhonov, L-curve corner)	compute_vp and compute_scan
fast_gaussian_simulation_dir	FastGaussianSimulation	Synthetic Gaussian truth fields (synthetic/)

MathWorks toolboxes used: Optimization, Mapping, Image Processing, Statistics and Machine Learning, Curve Fitting, Parallel Computing.

Package and build

toolbox/ is a MATLAB package (R2024b or later; toolbox/resources/mpackage.json, version 2.0.0). The manifest stays on schema 1.0.0 so that R2024b and R2025 can read it; recent MATLAB releases may rewrite it to a newer schema, which older releases reject. Without setup_paths, install it with mpminstall("toolbox"), or as an add-on from the toolbox file of buildtool package. The external code above still has to be on the path.

buildtool              % check (Code Analyzer, fails on errors) and test (unit tests)
buildtool regression   % paper-v1 regression test (local data, ~1 min)
buildtool package      % release/BMM-4D_<version>.mltbx

Data

Code reads data through bmm4d.util.data_path(...), from the data folder: data_dir in local_settings.json, or data/ in the repository root. Only reference/radar.csv (radar sites, 8 KB) is tracked.

Path in the data folder	Content	Source
reference/radar.csv	Radar sites (tracked)	Copied from the paper repository
reference/DEM/, onwater/, scan_pattern_new.mat	Terrain, land–water mask, scan patterns	Copied from the paper repository
reference/beam_blockage/	Terrain-horizon maps	studies/beam_blockage/beam_blockage_script.m
derived/F_elev/150km/	Beam elevation kernels	Copied; studies/kernels/generate_F_elev.m rebuilds them
raw_scans/nexrad/	Older raw volumes	Symbolic link to the paper repository's folder (read only)
regression/	Reference of the paper-v1 regression test	tests/regression/make_regression_reference.m

More folders are set in local_settings.json:

• nexrad_raw_dir: where raw volumes are downloaded and searched first (bmm4d.radar.nexrad_raw_dir()).
• nexrad_shared_dir (optional): a raw archive load_rd also searches but never writes to, skipped when not mounted. On the laptop, the cluster's raw folder (/Volumes/UNIT_Vogelzug/weather_radar_us/nexrad_level2).
• local_data_dir: large generated products such as volume caches, cases and inversions (bmm4d.util.local_data_dir()).
• cluster_products_dir (optional, read by webmap/serve.py only): the cluster's local_data_dir as mounted here (/Volumes/UNIT_Vogelzug/BMM-4D/products), so the web map lists cluster runs.

Cluster runs and their settings: hpc/README.md.

License

GPL-3.0 (LICENSE), as wsrlib, on which BMM-4D depends. The package manifest has no license field; the toolbox file ships the license as toolbox/license.txt.