hydro_utils

Hydrological and unit-conversion helpers for the forecast pipeline.

Small, mostly stateless functions used throughout data processing and forecasting:

Lake surface areas and other constants are defined inline where used.

src.hydro_utils.seconds_in_month(year, month)[source]

Calculate the number of seconds in a given month of a specific year.

Parameters:

  • (int) (month)

  • (int)

Returns:

int

Return type:

The number of seconds in the specified month.

Raises:

ValueError – If the month is not between 1 and 12.:

src.hydro_utils.calculate_grid_cell_areas(lon, lat)[source]

Calculate the area of each grid cell given latitude and longitude arrays.

Parameters:

  • (array-like) (lat)

  • (array-like)

Returns:

numpy.ndarray

Return type:

A 2D array of grid cell areas in square meters.

Raises:

ValueError – If lat or lon are not 1D arrays.:

src.hydro_utils.calculate_evaporation_rate(temperature_K, latent_heat_flux)[source]

Convert latent heat flux to evaporation rate.

Parameters:

  • temperature_K (float or array) – Air temperature in Kelvin.

  • latent_heat_flux_W_m2 (float or array) – Latent heat flux in W/m².

  • Notes

  • or (No input validation is performed. Negative temperature_K)

  • physically (latent_heat values will produce numerically valid but)

  • inputs. (meaningless results — callers are responsible for sanity-checking)

  • Sub-optimal (a future revision should raise ValueError for inputs)

  • ranges. (outside physical)

Returns:

evaporation_rate_mm_s – Evaporation rate in mm/s.

Return type:

float or array

src.hydro_utils.convert_mm_to_cms(df)[source]

Converts the ‘value [mm]’ in the dataframe to ‘value [cms]’ (cubic meters per second) based on lake surface area and the number of seconds in the month.

Parameters:

(pd.DataFrame) (- df)

Returns:

  • - pd.DataFrame (DataFrame with a new column ‘value [cms]’ representing the value in cubic meters per second.)

  • Notes

  • Recognized lake names are ‘superior’, ‘michigan-huron’, ‘erie’, and

  • ’ontario’. Any other value in the ‘lake’ column silently yields a

  • ’value [cms]’ of 0 (surface area defaults to 0 via dict.get).

  • Sub-optimal (a future revision should raise on unknown lake names)

  • rather than masking the issue with zeros.

src.hydro_utils.load_model(model_name: str, models_info: list)[source]

Load a serialized model by its name.

Parameters:

  • model_name (str) – The short identifier of the model (e.g., “GP”, “RF”).

  • models_info (list of dict) – Each dict must contain: - “model”: the short identifier - “path” : the path to the saved model file

Returns:

The deserialized model object.

Return type:

object

Raises: