BMM-within

Research code and manuscript material for fine-scale 3D/4D reconstruction of bird migration from weather radar.

The project is organized around manuscript evidence blocks:

• 01_radar_observation_model/: radar beam geometry, sparse forward operator, and Section 2 appendix.
• 02_preprocessing/: reference layers, beam blockage, refraction, and cleaning diagnostics.
• 03_simulator_fit/: selected scans, cleaned case-study data, covariance fits, VP models, and transforms.
• 04_static_synthetic/: static synthetic single-radar reconstruction benchmark.
• 05_advection_synthetic/: moving synthetic single-radar reconstruction benchmark.
• 06_mosaic_synthetic/: simple synthetic multi-radar, multi-time mosaic reconstruction benchmark.
• 07_realistic_synthetic/: realistic synthetic multi-radar, multi-time mosaic reconstruction benchmark.
• 07_single_radar_reconstruction/: real-data single-radar inverse remapping examples.
• 08_advection_speed/: real-data advection constraints and speed-field workflows.
• 09_cape_may_reconstruction/: real-data Cape May multi-radar reconstruction.
• 10_mosaic_reconstruction/: real-data multi-radar mosaic reconstruction.
• 11_flux_analysis/: take-off, landing, entering, and leaving flux outputs.

Shared code lives in functions/. Large raw, reference, derived, and cache data live in data/. Manuscript text and submission material live in manuscript/.

Synthetic data products are split by ownership:

• data/derived/simulator/: shared fitted simulator inputs produced by 03_simulator_fit/
• 04_static_synthetic/data/, 05_advection_synthetic/data/, 06_mosaic_synthetic/data/, 07_realistic_synthetic/data/: generated cases and inversions for each analysis
• data/derived/legacy/: older generated products kept for reference but not used by the active scripts

Run active MATLAB scripts from their folder or section-by-section after calling:

project_root = setup_paths();

Shared MATLAB Contracts

The current first-party reconstruction pipeline uses these shared names consistently:

• radar_scans: cleaned radar scans returned by read_rd(...)
• elevation_kernels: precomputed elevation-specific forward kernels returned by load_F_elev(...)
• grid: Cartesian analysis grid returned by create_grid(...)
• F: sparse forward operator returned by construct_F(...)
• obs_matrix: sparse observation matrix saved in data/derived/simulator/scans_data.mat
• info.obs_grid_size: observation reshape size used with reshape(full(obs_matrix(:, i_t)), info.obs_grid_size)
• info.obs_block_offset: observation block offsets inside the stacked sparse system

Key function signatures:

[elevation_kernels, radar_scans] = load_F_elev(filepath, radar_scans);
grid = create_grid(elevation_kernels, radar_scans, ...);
[F, obs_matrix, info] = construct_F(radar_scans, elevation_kernels, grid);
density_field = compute_scan(F, obs_matrix(:, i_t), grid, ...);
[obs_values, nonzero_obs_idx, azimuth_deg, elevation_deg, range_m, beam_height_m] = ...
    format_data(obs_matrix(:, i_t), elevation_kernels, info);

Derived Data Note

Some saved .mat products are generated artifacts, not stable interfaces.

• After changing the shared forward-model code, regenerate data/derived/simulator/scans_data.mat and related downstream products.
• data/derived/F_elev/*.mat kernels now use the variable name elevation_kernel.
• Older derived files that only store the legacy variable dfe are considered stale and should be regenerated or updated before rerunning the workflows.