Configuration

Settings are loaded from a YAML file. If you omit --settings, Coldcast loads the bundled defaults from the package:

src/coldcast/data/default_settings.yaml (installed as coldcast.data).

Global keys

Typical top-level keys include:

  • output_dir — download destination.

  • max_num_threads — concurrency for HTTP downloads.

  • log_file, log_xml_file, xml_log — logging.

  • run_info_file, run_info_netcdf — FEWS run info overrides (see Run-info overrides).

  • fews_name_space — XML namespace for FEWS run info XML.

  • bounding_box — optional default geographic extent:

    • Preferred: mapping lon_min, lon_max, lat_min, lat_max (west/east/south/north latitude bounds).

    • CDS-style: sequence [North, West, South, East] (degrees), same order as CDS area.

    Sources that honor it merge per key with a more specific block—under ECMWF, the ERA5 and ERA5_LAND product keys accept bounding_box or bbox (legacy top-level ERA5 / ERA5_LAND blocks still merge the same way); DYNAMICAL_CATALOG model bbox; ECCC_PRECIP_GRID fews_netcdf.clip_bbox when clip_to_bbox is true—so product keys override the global default for those keys only.

  • Shared YAML anchors — The bundled defaults repeat identical sub-mappings (for example NOMADS bbox and shared clip regions) using YAML aliases; that is layout-only and does not change runtime behavior.

Per-source blocks

Each data source has a YAML block named after the source key (e.g. NOAA_HRRR, ECCC_API). Inside that block:

  • Templates — url_template and filename_template are Python str.format-style templates. Context variables are built in code per source.

  • Models — Multi-model sources (ECCC_NWP, ECCC_PRECIP_GRID, ECMWF, DYNAMICAL_CATALOG) nest configuration under product/model keys; default_model selects the default when --model is omitted (for ECMWF this can be a forecast model or ERA5 / ERA5_LAND).

  • HREPA FEWS NetCDF — Under ECCC_PRECIP_GRID keys HREPA, HREPA_PCT25, and HREPA_PCT75, optional fews_netcdf enables post-processing after download (clip via clip_to_bbox / clip_bbox, merged with top-level bounding_box; CF metadata touch-ups, optional variable rename). ECMWF forecast product YAML may list clip_to_bbox / clip_bbox, but those keys are not applied to ECMWF GRIB2 downloads in code—only the HREPA FEWS NetCDF path uses clipping today.

  • Dynamical catalog FEWS NetCDF — DYNAMICAL_CATALOG opens dynamical.org xarray/Zarr forecast datasets, selects init_time from FEWS runinfo time0 minus delay_hours, clips using the merge of top-level bounding_box and each model’s bbox, and writes one CF NetCDF. Ensemble datasets keep all members in a single file using the CF realization dimension.

  • Sequences — forecast_hours and members may be a list or a dict with start / end / step (expanded at runtime).

Bundled CSV assets

Station lists for ECCC_API and SNOTEL ship under coldcast.data. Relative paths in YAML are resolved relative to the settings file directory when you pass a custom --settings path, or relative to the package data directory when using defaults.

NOAA Grib Filter

NOAA_HRRR, NOAA_GFS, and NOAA_GEFS build NOMADS Grib Filter URLs using url_base, filter_script, native NOMADS bbox fields (leftlon, rightlon, toplat, bottomlat), variables, cycles, and forecast hours defined in YAML. There is no conversion from top-level bounding_box to NOMADS parameters; use source bbox as in the bundled defaults.