bakaano.extensions.flood_mapper

Flood mapping utilities built on routed terrain analysis.

Role: Build reach-scale rating curves and map inundation depth without RichDEM.

class bakaano.extensions.flood_mapper.FloodMapper(working_dir, study_area, climate_data_source=None, dem_path=None, routing_method='mfd', mannings_n=0.05, water_levels=None, stream_threshold_ratio=0.1, max_hand_m=100.0, max_stage_height_m=50.0)

Bases: object

Build flood rating curves and inundation maps for a Bakaano project.

The class reuses the existing Bakaano project layout under working_dir and stores flood outputs under {working_dir}/flood.

Notes

This implementation is designed for rapid reach-scale flood mapping rather than full hydraulic modelling. It uses HAND, simplified Manning-based hydraulics, and empirical flood-frequency analysis, so outputs should be treated as screening-level products unless locally validated.

compute_rating_curves(overwrite=False, min_subbasin_cells=10)

describe_hand_subbasin(subbasin_id)

Return descriptive HAND statistics for one subbasin.

extract_annual_peaks(streamflow_data, start_date=None)

Extract annual maximum discharge from a daily streamflow series.

Accepts a DataFrame, Series, or array-like input. When the input lacks a datetime index, start_date is required so that annual aggregation can be constructed correctly.

flood_frequency_analysis(annual_peaks, return_period)

Estimate a return-period discharge from annual peaks using Gumbel EV1.

Parameters:

• annual_peaks (pandas.DataFrame) – Annual maxima with an annual_peaks column.

• return_period (float) – Return period in years. Must be greater than 1.

Returns:

Estimated discharge threshold in m3/s.

Return type:

float

Notes

Uses the Gumbel Extreme Value Type-I (EV1) distribution fitted by the Method of Moments (Chow 1964). This is the conventional approach for annual-maximum flood frequency analysis (Bulletin 17C / WMO guidelines) and replaces the previous quadratic polynomial fit in log-return-period space, which could produce negative or non-monotonic estimates for short records (< ~10 years) and had no physical basis.

The Gumbel frequency factor KT for return period T is:

KT = -sqrt(6)/pi * (ln(ln(T/(T-1))) + 0.5772)

so the estimate is:

QT = mean(Q) + KT * std(Q, ddof=1)

For very short records (< 5 years) the estimate is unreliable; a warning is emitted. For a return period beyond the sample, extrapolation is flagged in metadata but not blocked.

get_skip_summary()

Return the last recorded subbasin skip summary.

get_stage_height(discharge, k, h0, m, discharge_min=None, discharge_max=None)

Predict stage height from discharge with bounded extrapolation.

load_rating_curves(path=None)

Load previously computed rating curves from disk.

Parameters:

path (str or Path, optional) – Pickle path. Defaults to working_dir/flood/rating_curves.pkl.

map_inundated_areas(return_period, model_path=None, sim_start=None, sim_end=None, predicted_streamflows=None, runoff_output_dir=None, output_path=None, override_area_normalize=None, override_log_transform=None, **scaling_options)

Map inundation depth for a specified return period.

Parameters:

• return_period (float) – Return period in years.

• model_path (str, optional) – Trained Bakaano model used to simulate outlet hydrographs.

• sim_start (str, optional) – Simulation window used when model_path is supplied.

• sim_end (str, optional) – Simulation window used when model_path is supplied.

• predicted_streamflows (dict, optional) – Precomputed streamflow series keyed by subbasin id. When provided, these are used instead of running Bakaano simulation.

• runoff_output_dir (str, optional) – Routed runoff directory override, useful for scenario workflows.

• output_path (str or Path, optional) – Custom output GeoTIFF path.

• override_area_normalize (bool, optional) – Explicitly override model sidecar scaling settings when simulating outlet hydrographs. Leave as None to use the trained model configuration.

• override_log_transform (bool, optional) – Explicitly override model sidecar scaling settings when simulating outlet hydrographs. Leave as None to use the trained model configuration.

Returns:

Inundation depth array, flood metadata, output path, and skipped subbasins summary.

Return type:

dict

Notes

Provide either:

• predicted_streamflows keyed by subbasin id, or

• model_path with sim_start and sim_end so FloodMapper can simulate outlet hydrographs itself.

The output raster is a screening-level inundation product based on HAND and rating curves, not a full 2D hydraulic simulation. Model scaling options are loaded from the trained model sidecar config when model_path is used. Use override_area_normalize or override_log_transform only when intentionally overriding that saved config.

plot_hand_subbasin(subbasin_id, figsize=(12, 5))

Plot HAND values for one subbasin as a map plus a histogram.

plot_inundation_map(result=None, output_path=None, figsize=(10, 8), cmap='Blues', overlay_study_area=True)

Plot the inundation depth raster with an optional study-area boundary.

plot_rating_curve(subbasin_id, num_curve_points=200, figsize=(12, 5))

Plot sampled stage-discharge points and a map for one subbasin.

plot_stage_levels(subbasin_id=None, figsize=(10, 5))

Plot stage-height levels for one subbasin or summarize them across all subbasins.

simulate_streamflow_at_outlets(model_path, sim_start, sim_end, runoff_output_dir=None, override_area_normalize=None, override_log_transform=None, **scaling_options)

Simulate Bakaano streamflow at the rating-curve outlet coordinates.

Parameters:

• model_path (str) – Trained Bakaano model checkpoint.

• sim_start (str) – Simulation window in YYYY-MM-DD format.

• sim_end (str) – Simulation window in YYYY-MM-DD format.

• runoff_output_dir (str, optional) – Override for routed runoff inputs. This is useful when coupling FloodMapper to scenario-specific runoff outputs.

• override_area_normalize (bool, optional) – Explicitly override model sidecar scaling settings. Leave as None to use the trained model configuration.

• override_log_transform (bool, optional) – Explicitly override model sidecar scaling settings. Leave as None to use the trained model configuration.

Returns:

Mapping of subbasin id to a daily streamflow DataFrame.

Return type:

dict

Notes

Rating curves must already exist, either in memory or on disk. The streamflow series start one year after sim_start because Bakaano’s predictor windows require a 365-day lead-in period. Model scaling options are loaded from the trained model sidecar config when available. Use override_area_normalize or override_log_transform only when intentionally overriding that saved config.

view_inundation_map_interactive(result=None, output_path=None, overlay_study_area=True, opacity=0.6, cmap='Blues')

Open an interactive ipyleaflet map with inundation over satellite imagery.