Weather Data API

The permeabledt.download_HRRR_historical_forecast module exposes a single helper class for working with HRRR accumulated precipitation data via the herbie-data client. Install the optional extras with:

pip install "permeabledt[weather]"

HRRRAccumulatedPrecipitationDownloader

Constructor

HRRRAccumulatedPrecipitationDownloader(lat, lon, timezone='US/Central')

Initialise the downloader with the location of interest.

• lat, lon (float): Coordinates in decimal degrees.

• timezone (str): Local timezone identifier used when converting timestamps (defaults to US/Central).

Exploration helper

explore_precipitation_variables(sample_date=None, product='subh')

Inspect the GRIB inventory for accumulated-precipitation variables for a given run. Prints matches for the requested date (defaults to 28 April 2024 06:00 UTC) and product ('subh' or 'sfc').

Download accumulated forecasts

download_date_range(start_date, end_date, forecast_hours=6)

Loop over model runs between the supplied start and end dates (inclusive) and collect accumulated precipitation data. For each run the helper attempts to download the subhourly product and falls back to the surface product if necessary.

• Accepts either strings or datetime objects for start_date/end_date.

• Returns a list of pandas DataFrames (one per successful model run) with columns including forecast_time, precipitation_mm, model_run, and forecast_time_local (converted to the configured timezone).

Persist downloads

save_to_csv(forecast_dataframes, output_dir='hrrr_accumulated')

Write the list of DataFrames returned by download_date_range to individual CSV files. Filenames follow the pattern hrrr_accumulated_YYYYMMDD_HHMM_UTC.csv based on the model run time.

Visual comparison

plot_comparison(comp, metrics, output_dir='hrrr_comparison', cumulative=False)

Create a matplotlib plot comparing observed rainfall (comp['obs']) with the forecasted series (comp['fcst']). The metrics dictionary should contain the MAE, RMSE, and bias values used for annotation. When cumulative=True, the helper plots cumulative sums; otherwise it shows 15-minute increments. Figures are saved under output_dir.

Forecast vs observation analysis

compare_with_observed(forecast_dir, observed, cumulative=False, plot=False, output_dir='plots_output')

Load previously saved forecast CSVs from forecast_dir, align them with an observed rainfall DataFrame (date / rain columns), and compute performance statistics. Optionally calls plot_comparison when plot=True.

Returns a tuple (metrics_list, all_comp_df) where metrics_list contains the per-run MAE/RMSE/bias dictionaries and all_comp_df concatenates the per-forecast comparison tables.