Skip to content

Update example configs for zero-configuration out-of-the-box routing #177

@taddyb

Description

@taddyb

Context

After #173, #174, and #176, all the pieces are in place for a zero-download routing experience. The example configs need to be updated to reflect the new data layout:

  • Adjacency zarr (with flowpath attrs): in-repo
  • Trained weights: in-repo (already there)
  • KAN attributes: S3 (Lynker) / Zenodo (MERIT)
  • Lateral inflows: S3 (lazy-loaded via xarray/icechunk)
  • Observations: S3
  • GeoPackage: not required

Proposal

Update example configs so that ddr route --config-name example works immediately after git clone + uv sync:

Lynker example config

mode: routing
geodataset: lynker_hydrofabric
device: cpu  # CPU by default for broadest compatibility

data_sources:
  attributes: s3://mhpi-spatial/hydrofabric_v2.2_attributes/
  conus_adjacency: ./../../data/hydrofabric_v2.2_conus_adjacency.zarr  # in-repo
  statistics: ./../../data/statistics
  streamflow: s3://mhpi-spatial/hydrofabric_v2.2_dhbv_retrospective
  # geospatial_fabric_gpkg omitted — not needed for routing
  # observations omitted — not needed for routing mode

experiment:
  checkpoint: ./ddr-v0.5.2.lynker_hydrofabric_trained_weights.pt
  batch_size: 7
  start_time: 1995/10/01
  end_time: 1995/10/10
  warmup: 3

Key changes

  • Remove geospatial_fabric_gpkg (no longer required)
  • Set device: cpu for out-of-the-box compatibility
  • Keep S3 paths for attributes/streamflow/observations (lazy-loaded, no pre-download)
  • Keep short time range for quick example (10 days)
  • Add inline comments explaining each field

Config templates

Also update config/templates/ routing templates with the same pattern, plus clear comments explaining what each field does and what values are valid.

Files to modify

  • examples/merit/example_config.yaml
  • examples/lynker_hydrofabric/example_config.yaml
  • config/templates/merit_routing.yaml
  • config/templates/lynker_routing.yaml
  • config/templates/merit_training.yaml (comment out gpkg, note it's optional)
  • config/templates/lynker_training.yaml (same)

Acceptance criteria

  • ddr route --config-name example works from a fresh clone with only uv sync
  • No placeholder paths like /path/to/ remain in example configs
  • Every config field has an inline comment
  • Routing templates don't require gpkg
  • Training templates note gpkg is optional

Depends on

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions