bakaano.extensions.scenario

Scenario utilities for land-cover change experiments.

class bakaano.extensions.scenario.ScenarioManager(working_dir, study_area, climate_data_source=None)

Bases: object

Create and evaluate standalone vegetation-change scenarios.

The scenario workflow is file-based: each scenario is written under {working_dir}/scenarios/{scenario_name} and contains modified vegetation rasters, a scenario-specific NDVI climatology, runoff outputs, and any downstream streamflow simulations.

Notes

• This class is intentionally independent from the neural-network training and simulation entry points.

• Scenarios modify vegetation inputs only inside a user-supplied polygon.

• NDVI changes use a threshold-based rule tied to VegET’s NDVI > 0.4 breakpoint; this is operationally convenient but still a simplification.

build_draw_map(backend='ipyleaflet')

Return an interactive map with draw controls enabled.

The map is a convenience UI for collecting a polygon. The drawn geometry is not stored globally; pass the returned map object back to create_land_cover_scenario(..., map_obj=...) when you are ready to create the scenario.

create_land_cover_scenario(scenario_name, geometry=None, percent_change=0, change_type='deforestation', map_obj=None, open_map_if_missing=True)

Create a scenario from explicit geometry or from a drawn map polygon.

If geometry is omitted and map_obj is provided, the most recent drawn polygon on that specific map object is used. If no map is supplied and no geometry is provided, open_map_if_missing=True returns a new draw map instead of creating the scenario immediately.

create_tree_cover_scenario(scenario_name, geometry, percent_change, change_type='deforestation')

Create scenario-specific vegetation and NDVI inputs from a polygon.

Parameters:

• scenario_name (str) – Simple directory name used under working_dir/scenarios.

• geometry (GeoDataFrame | dict | str) – Scenario polygon as a GeoDataFrame, GeoJSON-like dict, vector path, or WKT string. Only cells intersecting this geometry are modified.

• percent_change (float) – Scenario intensity between 0 and 100. For tree/herb cover this is interpreted as a proportional change. For NDVI it controls the size of the threshold-crossing shift around NDVI = 0.4.

• change_type ({"deforestation", "reforestation"}) – Direction of change inside the polygon.

Returns:

Scenario metadata including output paths and the NDVI threshold rule.

Return type:

dict

Notes

This method expects baseline products to already exist under working_dir/vcf and working_dir/ndvi.

get_last_drawn_geometry(map_obj)

Extract the most recent drawn geometry from a Leafmap map object.

get_paths(scenario_name)

plot_ndvi_scenario_timeseries(scenario_name, figsize=(10, 4))

Plot baseline vs scenario NDVI seasonal means inside the scenario area.

plot_scenario_change(scenario_name, figsize=(15, 4))

Plot baseline, scenario, and difference rasters for tree cover.

Parameters:

• scenario_name (str) – Name of a previously created scenario.

• figsize (tuple, default (15, 4)) – Matplotlib figure size.

Returns:

(fig, axes) for additional customization.

Return type:

tuple

Notes

The scenario polygon boundary is overlaid when available.

recompute_runoff(scenario_name, sim_start, sim_end, routing_method='mfd', climate_data_source=None, force=False, resume=False)

Recompute routed runoff using the scenario-specific vegetation inputs.

Parameters:

• scenario_name (str) – Name of a previously created scenario.

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

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

• routing_method ({"mfd", "d8", "dinf"}, default "mfd") – Routing method forwarded to VegET.

• climate_data_source (str, optional) – Climate source override. If omitted, the value passed to ScenarioManager(...) is used.

• force (bool, default False) – If True, delete an existing final runoff file before recomputing.

• resume (bool, default False) – Whether VegET should resume from any checkpoint files in the scenario runoff directory.

Returns:

Path to the final wacc_sparse_arrays.pkl file.

Return type:

str

Notes

This method consumes the scenario tree cover, herb cover, and NDVI climatology written by create_tree_cover_scenario.

simulate_grdc_csv_stations(scenario_name, model_path, sim_start, sim_end, grdc_netcdf=None, routing_method='mfd', csv_dir=None, lookup_csv=None, id_col='id', lat_col='latitude', lon_col='longitude', date_col='date', discharge_col='discharge', file_pattern='{id}.csv', area_normalize=True, log_transform=True, recompute_runoff=False, runoff_resume=True)

Simulate streamflow for GRDC or CSV stations for one scenario.

Provide exactly one station source: - grdc_netcdf, or - csv_dir plus lookup_csv.

Returns a dictionary with the scenario output directory and all written station CSV files. Outputs are isolated under the scenario directory and do not overwrite baseline simulation files.

Parameters:

runoff_resume (bool, default True) – Whether scenario runoff recomputation may resume from existing checkpoints when this method needs to trigger VegET.

simulate_streamflow(scenario_name, model_path, sim_start, sim_end, latlist, lonlist, routing_method='mfd', area_normalize=True, log_transform=True, recompute_runoff=False, runoff_resume=True)

Simulate streamflow at user-provided coordinates for one scenario.

Parameters:

• scenario_name (str) – Name of a previously created scenario.

• 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.

• latlist (iterable of float) – Coordinates to simulate. The lists must have equal length.

• lonlist (iterable of float) – Coordinates to simulate. The lists must have equal length.

• routing_method ({"mfd", "d8", "dinf"}, default "mfd") – Routing method used for predictor generation.

• area_normalize (bool, default True) – Whether model outputs are interpreted as area-normalized and converted back to discharge.

• log_transform (bool, default True) – Whether the model was trained with log1p-transformed predictors and targets.

• recompute_runoff (bool, default False) – If True, force scenario runoff recomputation before simulation.

• runoff_resume (bool, default True) – Whether scenario runoff recomputation may resume from existing checkpoints when this method needs to trigger VegET.

Returns:

Output directory and written CSV files.

Return type:

dict

Notes

This method writes CSV outputs under the scenario-specific predicted_streamflow_data directory. It does not infer FloodMapper outlet coordinates automatically; use explicit lat/lon values.

class bakaano.extensions.scenario.ScenarioMetadata(dict=None, /, **kwargs)

Bases: UserDict

Dict-like scenario metadata with cleaner notebook display.