meshflow.utility.forcing_prep.prepare_mesh_forcing

meshflow.utility.forcing_prep.prepare_mesh_forcing(path, variables, units, hru_dim=None, unit_registry=None, to_units=None, aggregate=False, local_attrs=None, global_attrs=None)[source]

Prepare a MESH forcing file by merging, converting, and annotating data.

Parameters:

  • path (str) – Path to input forcing files.

  • variables (Sequence[str]) – Sequence of variable names to include in the output file.

  • units (dict of str) – Dictionary mapping variable names to their units.

  • hru_dim (str, optional) – Name of the HRU dimension to use in the output dataset.

  • unit_registry (pint.UnitRegistry, optional) – Pint unit registry for unit conversion. Default is None.

  • to_units (dict of str, optional) – Dictionary mapping variable names to target units for conversion.

  • aggregate (bool, default False) – If True, merge multiple input files into one using CDO. If False, assumes input files are already in the correct format and reads them directly. This is useful for MESH, which only reads one file. If aggregate is False, the input files are assumed to be already in the correct chunk format and are read directly. If aggregate is True, CDO is used to merge the files. Note that CDO is a binary dependency and must be installed separately.

  • local_attrs (dict of dict, optional) –

    Dictionary of local attributes for each forcing variable. The keys are variable names and the values are dictionaries of attributes to assign to each variable.

    Example:
    {‘air_temperature’: {‘long_name’: ‘Air Temperature’,

    ’units’: ‘K’}}

  • global_attrs (dict of str, optional) – Dictionary of global attributes for the output dataset. The keys are attribute names and the values are their descriptions.

Returns:

Merged and converted dataset containing forcing variables.

Return type:

xarray.Dataset

Raises:

  • TypeError – If variables is not a sequence of string values.

  • ValueError – If units for variables are not provided, or if any variable in units cannot be found in the dataset.

Notes

  • Merges all input forcing files into a single NetCDF file, as MESH only reads one file. CDO is used for merging, but the function returns an xarray.Dataset.

  • The variables sequence should include: ‘air_pressure’, ‘specific_humidity’, ‘air_temperature’, ‘wind_speed’, ‘precipitation’, ‘shortwave_radiation’, ‘longwave_radiation’.

  • The units and to_units dictionaries must contain the same keys as variables.

  • The merge functionality may be expanded in future versions.