matilda.core module

matilda.core.calculate_PDD(ds, prints=True)[source]

Calculates positive degree days (PDD) from a provided time series dataset, along with daily means of temperature and precipitation components (rain and snow).

Parameters:

  • ds (xarray.Dataset or pandas.DataFrame) – Input dataset containing temperature (T2), total precipitation (RRR), and optionally rain and snow variables. For xarray datasets, a glacier mask (MASK) is applied if present.

  • parameter (pandas.Series) – Series of MATILDA parameters (not directly used in this function but required for compatibility).

  • prints (bool, optional) – If True, prints status messages during the calculation. Defaults to True.

Returns:

A dataset containing:

  • temp_mean: Daily mean temperature in °C.

  • RRR: Daily total precipitation in mm.

  • rain: Daily rainfall in mm.

  • snow: Daily snowfall in mm.

  • pdd: Positive degree days (sum of daily mean temperatures above 0°C).

Return type:

xarray.Dataset

matilda.core.calculate_glaciermelt(ds, parameter, prints=True)[source]

Calculates accumulation, snow and ice melt, and runoff rates from glaciers using a Degree Day Model (DDM). This method is inspired by PYPDD (github.com/juseg/pypdd) and includes glacier storage-release dynamics.

Parameters:

  • ds (xarray.Dataset) –

    Input dataset containing daily climate variables:

    • temp_mean: Daily mean temperature in °C.

    • RRR: Total precipitation in mm.

    • snow: Daily snowfall in mm.

    • rain: Daily rainfall in mm.

    • pdd: Positive degree day values (°C·days).

  • parameter (pandas.Series) –

    Series of MATILDA parameters containing:

    • CFMAX_snow: Degree-day factor for snowmelt.

    • CFMAX_ice: Degree-day factor for ice melt.

    • CFR: Refreezing factor for snowmelt.

    • CFR_ice: Refreezing factor for ice melt.

    • AG: Glacier outflow adjustment parameter.

  • prints (bool, optional) – If True, prints status updates during the calculation. Defaults to True.

Returns:

A DataFrame containing daily values for various outputs of the Degree Day Model:

  • DDM_smb: Surface mass balance (mm w.e.).

  • pdd: Positive degree days (°C·days).

  • DDM_temp: Daily mean temperature (°C).

  • DDM_prec: Total precipitation (mm).

  • DDM_rain: Rainfall (mm).

  • DDM_snow: Snowfall (mm).

  • DDM_accumulation_rate: Snow accumulation rate (mm).

  • DDM_ice_melt: Ice melt (mm).

  • DDM_snow_melt: Snow melt (mm).

  • DDM_total_melt: Total melt (mm).

  • DDM_refreezing: Total refreezing (mm).

  • DDM_glacier_reservoir: Water stored in the glacier reservoir (mm).

  • Q_DDM: Actual runoff from the glacier (mm).

Return type:

pandas.DataFrame

References

  • PYPDD (github.com/juseg/pypdd)

  • Stahl, K., Moore, R. D., & McKendry, I. G. (2008). The role of synoptic-scale circulation in the linkage between large-scale ocean-atmosphere indices and winter surface climate in British Columbia, Canada. Water Resources Research, 44(7). https://doi.org/10.1029/2007WR005956

  • Toum, J., et al. (2021). Understanding glacier mass-balance variability using climate teleconnections. The R Journal, 13(1). https://doi.org/10.32614/RJ-2021-059

Notes

This implementation uses a storage-release scheme for glacier outflow that adjusts based on snow depth and drainage system conditions.

matilda.core.create_lookup_table(glacier_profile, parameter)[source]

Generates a lookup table of glacier area and water equivalent changes from the initial state (100% glacier coverage) to an ice-free state (0% coverage) using the deltaH scaling approach. This method is based on the routines outlined in Seibert et al. (2018) and Huss et al. (2010).

Parameters:

  • glacier_profile (pandas.DataFrame) –

    DataFrame containing the glacier’s initial state, including:

    • Area: Area of each elevation band (in km²).

    • WE: Initial water equivalent of each elevation band (in mm w.e.).

    • Elevation: Elevation of each band (in meters).

  • parameter (pandas.Series) –

    Series of MATILDA parameters, including:

    • area_glac: Total glacier area (in km²).

Returns:

Lookup table showing scaled glacier area for each elevation band over 101 mass states (from 100% to 0% in 1% steps). Each column corresponds to an elevation band (EleZone), and each row represents a scaled mass state.

Return type:

pandas.DataFrame

References

  • Huss, M., Jouvet, G., Farinotti, D., & Bauder, A. (2010). Future high-mountain hydrology: a new parameterization of glacier retreat. *Hydrology and Earth System Sciences, 14*(5), 815–829. https://doi.org/10.5194/hess-14-815-2010

  • Seibert, J., Vis, M. J. P., Kohn, I., Weiler, M., & Stahl, K. (2018). Technical note: Representing glacier geometry changes in a semi-distributed hydrological model. *Hydrology and Earth System Sciences, 22*(4), 2211–2224. https://doi.org/10.5194/hess-22-2211-2018

Notes

  1. The deltaH parameterization involves a scaling factor (fs) based on the total glacier mass change and the normalized elevation profile of the glacier.

  2. Three different parameter sets (a, b, c, y) are applied based on glacier size as outlined in Huss et al. (2010).

  3. Elevation bands with negative water equivalent are excluded iteratively during the scaling process.

matilda.core.create_statistics(output_MATILDA)[source]

Generates descriptive statistics for a given MATILDA output DataFrame.

Parameters:

output_MATILDA (pandas.DataFrame) – Input DataFrame containing MATILDA model output variables.

Returns:

A DataFrame containing descriptive statistics (e.g., mean, standard deviation, min, max) for each column in output_MATILDA, along with the sum of all columns appended as an additional row.

Return type:

pandas.DataFrame

Notes

  1. The sum row is labeled as “sum” and included at the bottom of the statistics DataFrame.

  2. All values are rounded to three decimal places for consistency.

matilda.core.glacier_area_change(output_DDM, lookup_table, glacier_profile, parameter)[source]

Calculates the new glacier area for each hydrological year and scales glacier variables using the deltaH scaling approach. This is the second part of the glacier scaling routine, based on Seibert et al. (2018) and Huss et al. (2010).

Parameters:

  • output_DDM (pandas.DataFrame) – Degree Day Model (DDM) output containing surface mass balance (DDM_smb) and other glacier-related variables.

  • lookup_table (pandas.DataFrame) – Lookup table created in part 1 of the scaling routine, mapping glacier area changes to mass loss percentages.

  • glacier_profile (pandas.DataFrame) –

    DataFrame containing glacier initial states:

    • Area: Area of each elevation band (in km²).

    • WE: Initial water equivalent of each elevation band (in mm w.e.).

  • parameter (pandas.Series) –

    Series of MATILDA parameters, including:

    • area_glac: Total glacier area (in km²).

    • area_cat: Catchment area (in km²).

    • hydro_year: Starting month of the hydrological year (1–12).

Returns:

  • output_DDM (pandas.DataFrame): Updated DDM output with scaled glacier variables for each hydrological year.

  • glacier_change_area (pandas.DataFrame): Time series of annual glacier area changes and cumulative scaled SMB.

Return type:

tuple

References

  • Huss, M., Jouvet, G., Farinotti, D., & Bauder, A. (2010). Future high-mountain hydrology: a new parameterization of glacier retreat. *Hydrology and Earth System Sciences, 14*(5), 815–829. https://doi.org/10.5194/hess-14-815-2010

  • Seibert, J., Vis, M. J. P., Kohn, I., Weiler, M., & Stahl, K. (2018). Technical note: Representing glacier geometry changes in a semi-distributed hydrological model. *Hydrology and Earth System Sciences, 22*(4), 2211–2224. https://doi.org/10.5194/hess-22-2211-2018

Notes

  1. The glacier area change is calculated annually based on the cumulative surface mass balance (SMB).

  2. SMB is scaled to the current glacier area to reflect its dynamic changes.

  3. If the cumulative SMB indicates a mass loss beyond 99% of the initial mass, the glacier area is set to zero.

  4. Variables in output_DDM are updated to reflect the new glacierized area fraction each year.

matilda.core.hbv_simulation(input_df_catchment, parameter, glacier_area=None)[source]

Simulates runoff from a catchment using the HBV model. Calculates key hydrological processes, including snowmelt, evaporation, soil moisture, and groundwater flow, based on input climate data and parameters.

The Python code is adapted from the LHMP hydrological modeling playground (github.com/hydrogo/LHMP, Ayzel Georgy. (2016). doi:10.5281/zenodo.59501). Evapotranspiration values are calculated using the method outlined in Oudin et al. (2005) if not provided in the input data.

Parameters:

  • input_df_catchment (pandas.DataFrame) –

    Input climate dataset with daily resolution, including:

    • T2: Temperature (°C).

    • RRR: Total precipitation (mm).

    • rain: Rainfall (mm).

    • snow: Snowfall (mm).

    • PE (optional): Potential evapotranspiration (mm).

  • parameter (pandas.Series) –

    Series of HBV model parameters, including:

    • CFMAX_snow: Degree-day factor for snowmelt.

    • CFR: Refreezing factor for snowmelt.

    • TT_snow: Threshold temperature for snowmelt.

    • CWH: Water holding capacity of snowpack.

    • FC: Field capacity of the soil.

    • LP: Soil moisture threshold for potential evapotranspiration.

    • BETA: Shape parameter for soil moisture recharge.

    • PERC: Percolation rate from upper to lower groundwater box.

    • K0, K1, K2: Recession coefficients for runoff components.

    • UZL: Threshold for upper groundwater runoff.

    • CET: Correction factor for evapotranspiration.

    • MAXBAS: Parameter for hydrograph smoothing.

    • area_cat: Total catchment area (km²).

    • area_glac: Glacierized area within the catchment (km²).

    • lat: Latitude of the catchment for radiation calculations.

    • sim_start, sim_end: Simulation period (YYYY-MM-DD).

    • set_up_start, set_up_end: Setup period (YYYY-MM-DD).

  • glacier_area (pandas.DataFrame, optional) – Time series of annual glacier areas for dynamically scaling snow and rain fractions. Defaults to None.

Returns:

A DataFrame containing simulated hydrological variables and runoff, including:

  • HBV_temp: Input temperature (°C).

  • HBV_prec: Input precipitation (mm).

  • HBV_rain: Rainfall off-glacier (mm).

  • HBV_snow: Snowfall off-glacier (mm).

  • HBV_pe: Potential evapotranspiration (mm).

  • HBV_snowpack: Snowpack water equivalent (mm).

  • HBV_soil_moisture: Soil moisture content (mm).

  • HBV_AET: Actual evapotranspiration (mm).

  • HBV_refreezing: Refreezing within the snowpack (mm).

  • HBV_upper_gw: Water in the upper groundwater box (mm).

  • HBV_lower_gw: Water in the lower groundwater box (mm).

  • HBV_melt_off_glacier: Meltwater runoff from snow and refreezing off-glacier (mm).

  • Q_HBV: Simulated catchment runoff (mm).

Return type:

pandas.DataFrame

References

  • Ayzel, G. (2016). LHMP: Lumped hydrological modeling playground. Zenodo. https://doi.org/10.5281/zenodo.59501

  • Oudin, L., Hervé, A., Perrin, C., Michel, C., Andréassian, V., Anctil, F., & Loumagne, C. (2005). Which potential evapotranspiration input for a lumped rainfall–runoff model?: Part 2—Towards a simple and efficient potential evapotranspiration model for rainfall–runoff modelling. *Journal of Hydrology, 303*(1), 290–306. https://doi.org/10.1016/j.jhydrol.2004.08.026

Notes

  1. Calculates potential evapotranspiration using Oudin et al. (2005) if not provided.

  2. Simulates snowmelt, soil moisture recharge, evaporation, and groundwater flow iteratively over the setup and simulation periods.

  3. Supports optional scaling of snow and rain fractions based on dynamically changing glacier areas.

matilda.core.input_scaling(df_preproc, parameter)[source]

Scales input climate data to mean elevations for glacierized and non-glacierized areas, separates precipitation into phases (rain and snow), and applies the snowfall correction factor.

Parameters:

  • df_preproc (pandas.DataFrame) – Preprocessed input dataset containing temperature (T2) in degrees Celsius and precipitation (RRR) in mm.

  • parameter (pandas.Series) –

    Series of MATILDA parameters, including:

    • ele_glac: Mean elevation of the glacierized area (in meters).

    • ele_non_glac: Mean elevation of the non-glacierized area (in meters).

    • ele_dat: Reference elevation of the input data (in meters).

    • lr_temp: Temperature lapse rate (°C/m).

    • lr_prec: Precipitation lapse rate (mm/m).

    • pfilter: Threshold for filtering small precipitation values (mm).

    • SFCF: Snowfall correction factor.

Returns:

  • input_df_glacier: Scaled dataset for the glacierized area, including separated rain and snow fractions.

  • input_df_catchment: Scaled dataset for the non-glacierized catchment, including separated rain and snow fractions.

Return type:

tuple of pandas.DataFrame

matilda.core.matilda_parameter(input_df, set_up_start=None, set_up_end=None, sim_start=None, sim_end=None, freq='D', lat=None, area_cat=None, area_glac=None, ele_dat=None, ele_glac=None, ele_cat=None, warn=False, **matilda_param)[source]

Initialize parameters for the MATILDA simulation.

This function processes user-defined and default parameters for the MATILDA model, validates parameter ranges, calculates derived parameters, and prepares the final parameter set for the simulation.

Parameters:

input_dfpandas.DataFrame

Input data containing meteorological and optional discharge data.

set_up_startstr or None, optional

Start date for the model setup period (default: inferred from input data).

set_up_endstr or None, optional

End date for the model setup period (default: one year after set_up_start).

sim_startstr or None, optional

Start date for the simulation period (default: inferred from input data).

sim_endstr or None, optional

End date for the simulation period (default: inferred from input data).

freqstr, optional

Resampling frequency for output data. Options: ‘D’ (daily), ‘W’ (weekly), ‘M’ (monthly), ‘Y’ (yearly). Default is ‘D’.

latfloat, required

Latitude of the study area in degrees, required for potential evapotranspiration calculations.

area_catfloat, required

Total catchment area in square kilometers.

area_glacfloat or None, optional

Glacierized area within the catchment in square kilometers (default: 0).

ele_datfloat or None, optional

Reference elevation for input meteorological data (default: None).

ele_glacfloat or None, optional

Mean elevation of the glacierized area (default: None).

ele_catfloat or None, optional

Mean elevation of the entire catchment (default: None).

warnbool, optional

Whether to display warnings for potential configuration issues (default: False).

**matilda_paramdict, optional

Additional model parameters, passed as key-value pairs. If a parameter is not provided, default values from the parameter JSON file are used.

Returns:

pandas.Series

A series containing all configured parameters for the MATILDA simulation.

Raises:

ValueError

If required parameters (lat or area_cat) are not provided or if parameter values are outside acceptable bounds.

Notes:

  • Derived parameters such as TT_rain (threshold temperature for rain) and CFMAX_ice (melt factor for ice) are computed automatically.

  • Reference elevations (ele_cat, ele_glac) are used to scale meteorological input data.

  • The parameter set is validated against predefined bounds from a JSON configuration file.

  • Default values are stored in the parameters.json file.

matilda.core.matilda_plots(output_MATILDA, parameter, plot_type='print')[source]

Generates visualizations for MATILDA simulation results, including meteorological inputs, runoff outputs, and HBV reservoir variables. Supports multiple plotting styles (static, interactive, and combined).

Parameters:

  • output_MATILDA (list) –

    MATILDA simulation output containing the following elements:

    • Compact output (pandas.DataFrame): Key simulation variables (e.g., runoff, precipitation, temperature).

    • Full simulation results (pandas.DataFrame).

    • Model efficiency metric (e.g., Kling-Gupta Efficiency coefficient).

    • Statistics (pandas.DataFrame).

    • Glacier lookup table (if applicable).

    • Glacier change data (if applicable).

  • parameter (pandas.Series) –

    Series of MATILDA parameters, including:

    • freq: Frequency for resampling (e.g., “D” for daily, “M” for monthly, “Y” for yearly).

    • freq_long: Long-form frequency description (e.g., “Daily”, “Monthly”).

    • sim_start: Start date of the simulation period (YYYY-MM-DD).

    • sim_end: End date of the simulation period (YYYY-MM-DD).

  • plot_type (str, optional) –

    Specifies the type of plots to generate:

    • ”print”: Static plots using Matplotlib.

    • ”interactive”: Interactive plots using Plotly.

    • ”all”: Both static and interactive plots.

    Defaults to “print”.

Returns:

The updated output_MATILDA list with added visualizations. The plots are appended as follows:

  • Static Matplotlib plots: [fig1, fig2, fig3] for meteorological inputs, runoff, and HBV reservoirs, respectively.

  • Interactive Plotly plots: [fig1, fig2] for full results and annual mean results, respectively.

Return type:

list

Notes

  1. Static Plots:

    • Plots meteorological inputs (temperature, precipitation, evaporation).

    • Visualizes runoff contributions and comparisons with observed data (if available).

    • Displays HBV reservoir outputs (soil moisture, snowpack, groundwater).

  2. Interactive Plots:

    • Provides detailed and zoomable visualizations for meteorological inputs, runoff, and contributions using Plotly.

    • Includes annotations for model efficiency metrics like KGE.

  3. Data is resampled to the specified frequency (freq) for consistent visualization across time steps.

  4. Observed runoff data (observed_runoff) is included if available in the input.

Warning

  • Ensure that output_MATILDA contains valid simulation results before calling this function.

  • Interactive plots require Plotly; ensure it is installed for “interactive” or “all” options.

  • Large datasets may cause performance issues with interactive plotting.

matilda.core.matilda_preproc(input_df, parameter, obs=None)[source]

Processes and prepares input climate data and optional observation data for MATILDA simulations. Includes format transformations, unit conversions, and application of precipitation correction factors.

Parameters:

  • input_df (pandas.DataFrame or xarray.Dataset) – Input dataset containing climate variables such as temperature (T2) in Celsius or Kelvin and precipitation (RRR) in mm.

  • parameter (pandas.Series) – Series of MATILDA parameters, including setup and simulation periods, precipitation correction factor, and additional configuration details.

  • obs (pandas.DataFrame or None, optional) – Observation data for discharge, with columns ‘Date’ and ‘Qobs’ in m³/s. If provided, it will be resampled, converted to mm/day, and optionally filtered by season of interest (if specified). Defaults to None.

Returns:

  • pandas.DataFrame – Preprocessed input dataset with climate variables adjusted for the specified simulation period, including temperature conversion and precipitation correction.

  • tuple of pandas.DataFrame, optional – If obs is provided, returns a tuple of the preprocessed input dataset and the preprocessed observation dataset, with discharge values converted to mm/day and resampled to the simulation period.

matilda.core.matilda_save_output(output_MATILDA, parameter, output_path, plot_type='print')[source]

Saves MATILDA simulation outputs, statistics, parameters, glacier area changes, and plots to the local disk.

Parameters:

  • output_MATILDA (list) –

    List containing the outputs from the MATILDA simulation. Includes:

    • Full model output (pandas.DataFrame).

    • Model statistics (pandas.DataFrame).

    • Model parameters (pandas.Series).

    • Glacier area data (optional, pandas.DataFrame).

    • Plots (Matplotlib or Plotly objects, depending on the plot type).

  • parameter (pandas.Series) –

    Series containing the simulation parameters, including:

    • sim_start: Start date of the simulation period (YYYY-MM-DD).

    • sim_end: End date of the simulation period (YYYY-MM-DD).

  • output_path (str) – Directory path where the output files will be saved. A subfolder with the simulation date and time will be created.

  • plot_type (str, optional) –

    Specifies the type of plots to save:

    • ”print”: Saves Matplotlib plots as PNG files.

    • ”interactive”: Saves Plotly plots as HTML files.

    • ”all”: Saves both Matplotlib and Plotly plots in their respective formats.

    Defaults to “print”.

Returns:

Saves the outputs and plots to the specified directory.

Return type:

None

Notes

  1. A subdirectory is created under output_path with a timestamped name for organizing the outputs.

  2. The outputs saved include:

    • Full simulation results as CSV (model_output_<date_range>.csv).

    • Statistics as CSV (model_stats_<date_range>.csv).

    • Parameters as CSV (model_parameter.csv).

    • Glacier area changes as CSV (glacier_area_<date_range>.csv) if applicable.

  3. Plots are saved in the specified format (PNG or HTML).

  4. The function automatically handles the appending of date ranges and timestamps to filenames.

Warning

  • Ensure the specified output_path exists and has write permissions.

  • When using “interactive” or “all”, ensure Plotly is installed for saving HTML plots.

Examples

Save MATILDA outputs and plots (Matplotlib only): >>> matilda_save_output(output_MATILDA, parameter, “/path/to/output”, plot_type=”print”)

Save MATILDA outputs and interactive plots (Plotly): >>> matilda_save_output(output_MATILDA, parameter, “/path/to/output”, plot_type=”interactive”)

Save MATILDA outputs with both static and interactive plots: >>> matilda_save_output(output_MATILDA, parameter, “/path/to/output”, plot_type=”all”)

matilda.core.matilda_simulation(input_df, obs=None, glacier_profile=None, output=None, warn=False, set_up_start=None, set_up_end=None, sim_start=None, sim_end=None, freq='D', lat=None, area_cat=None, area_glac=None, ele_dat=None, ele_glac=None, ele_cat=None, plots=True, plot_type='print', science_plot=True, elev_rescaling=False, drop_surplus=False, **matilda_param)[source]

Run the complete MATILDA simulation framework, including preprocessing, simulation, and optional output saving.

This function integrates data preprocessing, hydrological and glacial simulations, and optional output handling using the MATILDA framework. It can perform simulations with default or user-defined parameters, handle optional glacier rescaling, and generate visualizations and model statistics.

Parameters:

  • input_df (pandas.DataFrame) – Input meteorological data for the simulation. Must include timestamp and relevant fields (e.g., temperature, precipitation).

  • obs (pandas.DataFrame, optional) – Observed runoff data for model calibration or comparison. If provided, it will be included in outputs.

  • glacier_profile (pandas.DataFrame, optional) – Glacier profile data for elevation-based glacier rescaling routines. If not provided, glacier rescaling is disabled.

  • output (str, optional) – Directory path to save outputs (CSV files, statistics, plots). If not specified, outputs are not saved.

  • warn (bool, optional) – Whether to show warnings during execution. Default is False.

  • set_up_start (str, optional) – Start date for the model spin-up period (YYYY-MM-DD). Default is None.

  • set_up_end (str, optional) – End date for the model spin-up period (YYYY-MM-DD). Default is None.

  • sim_start (str, optional) – Start date for the simulation period (YYYY-MM-DD). Default is None.

  • sim_end (str, optional) – End date for the simulation period (YYYY-MM-DD). Default is None.

  • freq (str, optional) – Simulation time step frequency (“D” for daily, “M” for monthly). Default is “D”.

  • lat (float, optional) – Latitude of the catchment area for potential evapotranspiration calculation. Required for HBV simulations.

  • area_cat (float, optional) – Total catchment area in km². Required for runoff scaling.

  • area_glac (float, optional) – Glacierized area of the catchment in km². Default is None.

  • ele_dat (float, optional) – Elevation of the meteorological station used for input data in meters. Default is None.

  • ele_glac (float, optional) – Average elevation of the glacierized area in meters. Default is None.

  • ele_cat (float, optional) – Average elevation of the entire catchment in meters. Default is None.

  • plots (bool, optional) – Whether to generate plots. Default is True.

  • plot_type (str, optional) – Type of plots to generate. Options are “print”, “interactive”, or “all”. Default is “print”.

  • science_plot (bool, optional) – Whether to apply a scientific plot style using scienceplot`package. Default is `True.

  • elev_rescaling (bool, optional) – Whether to perform annual elevation rescaling for glaciers. Default is False.

  • drop_surplus (bool, optional) – Whether to drop surplus glacial mass balance during simulation. Default is False.

  • **matilda_param (dict, optional) – Additional model parameters passed as key-value pairs. These override the default parameter values.

Returns:

A list containing:

  • Compact MATILDA output (pandas.DataFrame).

  • Full MATILDA output (pandas.DataFrame).

  • Efficiency coefficient (str or float).

  • Model statistics (pandas.DataFrame).

  • Glacier lookup table (optional, str or pandas.DataFrame).

  • Glacier changes (optional, str or pandas.DataFrame).

Return type:

list

Notes

  1. Outputs are saved to disk if output is specified.

  2. Observed runoff data, if provided, is included in the efficiency calculations and final outputs.

  3. Plots can be suppressed by setting plots=False.

  4. If science_plot=True, plots are styled with a scientific layout using the science and no-latex options.

matilda.core.matilda_submodules(df_preproc, parameter, obs=None, glacier_profile=None, elev_rescaling=False, drop_surplus=False)[source]

Executes the main MATILDA simulation, which integrates data preprocessing, Degree Day Model (DDM), HBV hydrological model, and optional glacier elevation rescaling to produce comprehensive runoff and hydrological outputs.

Parameters:

  • df_preproc (pandas.DataFrame) – Preprocessed input dataset containing climate variables such as temperature, precipitation, snow, and rain.

  • parameter (pandas.Series) –

    Series of MATILDA parameters including:

    • Simulation settings (sim_start, sim_end, set_up_start, set_up_end, freq, freq_long).

    • Glacier parameters (area_glac, area_cat, ele_glac, ele_cat, warn).

    • HBV and DDM model parameters.

  • obs (pandas.DataFrame, optional) – Observed runoff data for model evaluation. Defaults to None.

  • glacier_profile (pandas.DataFrame, optional) – Initial glacier profile with columns such as Area, WE (water equivalent), and Elevation. Required if elev_rescaling=True.

  • elev_rescaling (bool, optional) – If True, enables glacier elevation rescaling based on the deltaH scaling routine. Defaults to False.

  • drop_surplus (bool, optional) – If True, drops runs where the cumulative surface mass balance (SMB) is positive. Defaults to False.

Returns:

A list containing the following elements:

  • output_MATILDA_compact (pandas.DataFrame): Compact output with key variables for quick assessment.

  • output_MATILDA (pandas.DataFrame): Full simulation results including all variables.

  • kge (str or float): Kling-Gupta Efficiency coefficient for model performance evaluation.

  • stats (pandas.DataFrame): Statistical summary of the simulation results.

  • lookup_table (str or pandas.DataFrame): Lookup table for glacier area changes (if applicable).

  • glacier_change (str or pandas.DataFrame): Time series of glacier changes (if applicable).

Return type:

list

Notes

  1. If elev_rescaling=True and glacier_profile is provided, glacier elevation and area are dynamically updated annually.

  2. When glacier elevation scaling is turned off, average glacier elevation is treated as constant, which may introduce biases for longer simulations.

  3. Observed runoff (obs) is required for model efficiency metrics such as KGE, NSE, RMSE, and MARE.

  4. The function calculates and outputs both compact and detailed results for downstream analyses.

Warning

  • If no glacier profile is provided while elev_rescaling=True, an error is raised.

  • Glacier melt calculations are skipped if the glacier area is zero (area_glac = 0).

  • Model efficiency metrics are not calculated if observed data (obs) is not provided.

matilda.core.melt_rates(snow, pdd, parameter)[source]

Computes melt rates from snow precipitation and positive degree day (PDD) sums. Snow melt is calculated using the CFMAX_snow parameter, and excess energy after snow melt contributes to ice melt, calculated using the CFMAX_ice parameter.

This function is adapted from pypdd.py, line 331. Original source is referenced at the beginning of the script.

Parameters:

  • snow (array_like) – Snow precipitation rate (mm/day).

  • pdd (array_like) – Positive degree day values (°C·days).

  • parameter (pandas.Series) –

    Series of MATILDA parameters containing:

    • CFMAX_snow: Degree-day factor for snowmelt.

    • CFMAX_ice: Degree-day factor for ice melt.

Returns:

  • snow_melt: Effective snow melt rates (mm/day), limited by the available snow.

  • ice_melt: Ice melt rates (mm/day), proportional to excess PDD energy beyond snow melt.

Return type:

tuple of array_like

matilda.core.phase_separation(df_preproc, parameter)[source]

Separates precipitation into liquid and solid fractions based on temperature thresholds using a linear transition.

Parameters:

  • df_preproc (pandas.DataFrame) – Preprocessed input dataset containing temperature (T2) in degrees Celsius and precipitation (RRR) in mm.

  • parameter (pandas.Series) – Series of MATILDA parameters, including TT_snow (threshold temperature for snow), TT_rain (threshold temperature for rain), and other configuration details.

Returns:

  • rain: Liquid precipitation fraction (in mm).

  • snow: Solid precipitation fraction (in mm).

Return type:

tuple of pandas.Series

matilda.core.updated_glacier_melt(data, lookup_table, glacier_profile, parameter, drop_surplus=False)[source]

Calculates the new glacier area for each hydrological year and scales glacier variables using the deltaH scaling approach. This is the second part of the glacier scaling routine, based on Seibert et al. (2018) and Huss et al. (2010).

Parameters:

  • output_DDM (pandas.DataFrame) – Degree Day Model (DDM) output containing surface mass balance (DDM_smb) and other glacier-related variables.

  • lookup_table (pandas.DataFrame) – Lookup table created in part 1 of the scaling routine, mapping glacier area changes to mass loss percentages.

  • glacier_profile (pandas.DataFrame) –

    DataFrame containing glacier initial states:

    • Area: Area of each elevation band (in km²).

    • WE: Initial water equivalent of each elevation band (in mm w.e.).

  • parameter (pandas.Series) –

    Series of MATILDA parameters, including:

    • area_glac: Total glacier area (in km²).

    • area_cat: Catchment area (in km²).

    • hydro_year: Starting month of the hydrological year (1–12).

Returns:

  • output_DDM (pandas.DataFrame): Updated DDM output with scaled glacier variables for each hydrological year.

  • glacier_change_area (pandas.DataFrame): Time series of annual glacier area changes and cumulative scaled SMB.

Return type:

tuple

References

  • Huss, M., Jouvet, G., Farinotti, D., & Bauder, A. (2010). Future high-mountain hydrology: a new parameterization of glacier retreat. *Hydrology and Earth System Sciences, 14*(5), 815–829. https://doi.org/10.5194/hess-14-815-2010

  • Seibert, J., Vis, M. J. P., Kohn, I., Weiler, M., & Stahl, K. (2018). Technical note: Representing glacier geometry changes in a semi-distributed hydrological model. *Hydrology and Earth System Sciences, 22*(4), 2211–2224. https://doi.org/10.5194/hess-22-2211-2018

Notes

  1. The glacier area change is calculated annually based on the cumulative surface mass balance (SMB).

  2. SMB is scaled to the current glacier area to reflect its dynamic changes.

  3. If the cumulative SMB indicates a mass loss beyond 99% of the initial mass, the glacier area is set to zero.

  4. Variables in output_DDM are updated to reflect the new glacierized area fraction each year.

matilda.mspot module

class matilda.mspot_glacier.HiddenPrints[source]

Bases: object

Suppress prints during multiple iterations or noisy function calls.

This utility class redirects standard output to /dev/null, effectively silencing any print statements during its usage. It can be used as a context manager to suppress output temporarily.

Example

with HiddenPrints():

# Any print statements here will be suppressed noisy_function()

__enter__()[source]

Redirects standard output to /dev/null.

__exit__(exc_type, exc_val, exc_tb)[source]

Restores the original standard output.

matilda.mspot_glacier.analyze_results(sampling_data, obs, algorithm, obj_dir='maximize', fig_path=None, dbname='mspot_results', glacier_only=False, target_mb=None)[source]

Analyze the results of SPOTPY sampling for model calibration of the MATILDA model.

This function processes sampling results from SPOTPY to identify the best parameter set, evaluate performance, and optionally generate visualizations of the results.

Parameters:

  • sampling_data (str or SPOTPY result object) – The file path to a SPOTPY results CSV file or a SPOTPY result object.

  • obs (str or pandas.DataFrame) – The file path to observed data (in CSV format with ‘Date’ column) or a DataFrame containing observed data.

  • algorithm (str) – The SPOTPY algorithm used for sampling (e.g., ‘abc’, ‘dream’, ‘sceua’).

  • obj_dir (str, optional) – Direction of the objective function optimization, either ‘maximize’ or ‘minimize’. Default is ‘maximize’.

  • fig_path (str, optional) – Path to save generated plots. If None, plots are not saved.

  • dbname (str, optional) – Name for saving the database and plots. Default is ‘mspot_results’.

  • glacier_only (bool, optional) – If True, optimizes only for glacier-specific metrics (e.g., mass balance). Default is False.

  • target_mb (float, optional) – Target mean annual mass balance for melt model calibration. If None, this metric is not considered. Default is None.

Returns:

A dictionary containing: - ‘best_param’: dict

Best parameter set identified during sampling.

  • ’best_index’: int

    Index of the best run in the SPOTPY results.

  • ’best_model_run’: array

    Model output corresponding to the best parameter set.

  • ’best_objf’: float

    Value of the objective function for the best parameter set.

  • ’best_simulation’: pandas.Series (if glacier_only is False and target_mb is None)

    Simulated time series corresponding to the best parameter set.

  • ’sampling_plot’: matplotlib.Figure (if applicable)

    Iteration vs. objective function plot.

  • ’best_run_plot’: matplotlib.Figure (if applicable)

    Best simulation vs. observed data plot.

  • ’par_uncertain_plot’: matplotlib.Figure (if applicable)

    Parameter uncertainty plot.

Return type:

dict

Notes

  • The objective function can be maximized (e.g., Kling-Gupta Efficiency) or minimized (e.g., Mean Absolute Error) based on the algorithm and obj_dir setting.

  • For glacier-specific calibration, only glacier mass balance data is considered.

References

matilda.mspot_glacier.annual(year, data)[source]

Extract the annual period for a given year from a record of the World Glacier Monitoring service (WGMS).

This function filters the input dataset for the specified year and returns a slice object representing the annual period based on the BEGIN_PERIOD and END_PERIOD columns.

Parameters:

  • year (int) – The year for which the annual period is to be extracted.

  • data (pandas.DataFrame) – The input dataset containing at least the following columns: - BEGIN_PERIOD: The start of the annual period. - END_PERIOD: The end of the annual period. - Index representing years.

Returns:

A slice object representing the annual period for the specified year.

Return type:

slice

Notes

The function assumes that the dataset is indexed by years and contains the BEGIN_PERIOD and END_PERIOD columns with appropriate datetime or timestamp values.

References

  • WGMS (2024): Fluctuations of Glaciers Database. World Glacier Monitoring Service, Zurich, Switzerland.

https://doi.org/10.5904/wgms-fog-2024-01

matilda.mspot_glacier.dict2bounds(p_dict, drop=None)[source]

Convert a parameter dictionary to a bounds dictionary to be passed to spot_setup().

This function takes a dictionary of parameters and converts it into a dictionary containing both lower (_lo) and upper (_up) bounds for each parameter. Optionally, specific parameters can be excluded from the resulting dictionary.

Parameters:

  • p_dict (dict) – A dictionary containing parameter names as keys and their initial values as values.

  • drop (list, optional) – A list of parameter names to exclude from the resulting bounds dictionary.

Returns:

A dictionary containing both lower (_lo) and upper (_up) bounds for the remaining parameters in p_dict.

Return type:

dict

matilda.mspot_glacier.get_par_bounds(path, threshold=10, percentage=True, drop=None)[source]

Generate parameter bounds from SPOTPY sampling results.

This function extracts the minimum and maximum values of model parameters from the best-performing runs in SPOTPY sampling results. The best-performing runs are determined based on a likelihood threshold or percentage.

Parameters:

  • path (str) – File path to the SPOTPY sampling results (e.g., ‘results.csv’).

  • threshold (float, optional) – The threshold for selecting the best-performing runs: - If percentage is True, threshold represents the percentage of the top-performing runs to consider. - If percentage is False, threshold represents the numerical threshold for the objective function. Default is 10.

  • percentage (bool, optional) – Determines whether to interpret threshold as a percentage (True) or a numerical threshold (False). Default is True.

  • drop (list of str, optional) – A list of parameter names to exclude from the resulting bounds. Default is None.

Returns:

A dictionary containing the lower (_lo) and upper (_up) bounds for each parameter, derived from the best-performing runs.

Return type:

dict

Notes

  • The function loads SPOTPY sampling results and identifies the best-performing runs using the specified threshold and criteria.

  • Parameters specified in the drop list are excluded from the output bounds.

  • The resulting dictionary contains keys in the format <parameter_name>_lo and <parameter_name>_up.

References

matilda.mspot_glacier.load_parameters(path, algorithm, obj_dir='maximize', glacier_only=False)[source]

Load the best parameter set from SPOTPY sampling results.

This function retrieves the best parameter set from a SPOTPY sampling results file, based on the specified algorithm and objective function direction.

Parameters:

  • path (str) – File path to the SPOTPY sampling results (e.g., ‘results.csv’).

  • algorithm (str) – SPOTPY algorithm used for sampling (e.g., ‘lhs’, ‘mcmc’, ‘dream’).

  • obj_dir (str, optional) – Direction of the objective function optimization (‘maximize’ or ‘minimize’). Default is ‘maximize’.

  • glacier_only (bool, optional) – If True, processes only glacier-specific sampling results (default is False).

Returns:

A dictionary containing the best parameter set identified from the sampling results.

Return type:

dict

Notes

  • This function uses the analyze_results function to extract the best parameters.

  • It assumes that the corresponding observation file is named <path_without_extension>_observations.csv.

  • Depending on the number of samples loading of the sampling file might be slow.

References

matilda.mspot_glacier.loglike_kge(qsim, qobs)[source]

Calculate a pseudo log-likelihood function using the Kling-Gupta Efficiency (KGE) and a gamma distribution.

This function computes a log-likelihood value based on the KGE between simulated and observed flow values, and models the exceedance deviation (ED) using a gamma distribution.

Parameters:

  • qsim (array_like) – Array of simulated flow values.

  • qobs (array_like) – Array of observed flow values.

Returns:

The calculated value of the log-likelihood function.

Return type:

float

Notes

The log-likelihood function is based on the Kling-Gupta Efficiency (KGE) following Liu et al. (2022). The exceedance deviation (ED) is derived from the KGE as ED = 1 - KGE. The gamma probability density function (PDF) is then used to model the likelihood, with shape parameter a=0.5 and scale parameter scale=1.

References

  • Liu, Y., Fernández-Ortega, J., Mudarra, M., and Hartmann, A. (2022). “Pitfalls and a feasible solution for using KGE as an informal likelihood function in MCMC methods: DREAM(ZS) as an example.” HESS, 26(20).

  • Kling, H., Gupta, H., & Yilmaz, K. K. (2012). “Model selection criteria for rainfall-runoff models: Representation of variability in Bayesian Model Averaging.” Water Resources Research, 48(6), W06306.

  • hydroeval: https://github.com/ThibHlln/hydroeval

  • scipy.stats.gamma: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gamma.html

matilda.mspot_glacier.psample(df, obs, rep=10, output=None, dbname='matilda_par_smpl', dbformat=None, obj_func=None, opt_iter=False, fig_path=None, set_up_start=None, set_up_end=None, sim_start=None, sim_end=None, freq='D', lat=None, area_cat=None, area_glac=None, ele_dat=None, ele_glac=None, ele_cat=None, glacier_profile=None, interf=4, freqst=2, parallel=False, cores=2, save_sim=True, elev_rescaling=True, glacier_only=False, obs_type='annual', target_mb=None, target_swe=None, swe_scaling=None, algorithm='lhs', obj_dir='maximize', fix_param=None, fix_val=None, demcz_args: dict = None, **kwargs)[source]

Run parameter sampling for the MATILDA model using SPOTPY.

This function sets up a SPOTPY sampling routine for parameter optimization or sensitivity analysis. It supports parallel and serial computation, custom objective functions, and a variety of SPOTPY algorithms.

Parameters:

  • df (pandas.DataFrame) – Input data for the MATILDA model.

  • obs (pandas.DataFrame or str) – Observed data as a DataFrame or a file path to a CSV file containing observations.

  • rep (int, optional) – Number of sampling repetitions (default is 10).

  • output (str, optional) – Path to save the output files (default is None).

  • dbname (str, optional) – Name of the database for saving results (default is ‘matilda_par_smpl’).

  • dbformat (str, optional) – Format for the SPOTPY database (e.g., ‘csv’, ‘sql’). Default is None (no database saved).

  • obj_func (callable, optional) – Custom objective function for parameter optimization. If None, defaults are used.

  • opt_iter (bool, optional) – If True, samples the optimum number of iterations based on the setup (default is False).

  • fig_path (str, optional) – Path to save generated plots (default is None).

  • set_up_start (str, optional) – Start and end dates for the model setup period (e.g., ‘2000-01-01’).

  • set_up_end (str, optional) – Start and end dates for the model setup period (e.g., ‘2000-01-01’).

  • sim_start (str, optional) – Start and end dates for the simulation period.

  • sim_end (str, optional) – Start and end dates for the simulation period.

  • freq (str, optional) – Temporal resolution of the input data (default is ‘D’).

  • lat (float, optional) – Latitude of the study area (used for potential evapotranspiration calculations).

  • area_cat (float, optional) – Total catchment area in km².

  • area_glac (float, optional) – Glacierized area in km².

  • ele_dat (float, optional) – Elevations (mean, glacier, and catchment).

  • ele_glac (float, optional) – Elevations (mean, glacier, and catchment).

  • ele_cat (float, optional) – Elevations (mean, glacier, and catchment).

  • glacier_profile (pandas.DataFrame, optional) – Glacier profile data for rescaling and optimization routines.

  • interf (int, optional) – Inference factor for SPOTPY (default is 4).

  • freqst (int, optional) – Frequency step for SPOTPY (default is 2).

  • parallel (bool, optional) – If True, runs sampling in parallel using MPI (default is False).

  • cores (int, optional) – Number of cores to use for parallel sampling (default is 2).

  • save_sim (bool, optional) – Whether to save simulation results in the database (default is True).

  • elev_rescaling (bool, optional) – If True, applies elevation-based rescaling for glacier simulations (default is True).

  • glacier_only (bool, optional) – If True, runs sampling specifically for glacier-related parameters (default is False).

  • obs_type (str, optional) – Type of observed data for glacier calibration (‘annual’, ‘winter’, or ‘summer’). Default is ‘annual’.

  • target_mb (float, optional) – Target mass balance for glacier calibration (default is None).

  • target_swe (float, optional) – Target snow water equivalent for calibration (default is None).

  • swe_scaling (float, optional) – Scaling factor for snow water equivalent (default is None).

  • algorithm (str, optional) – SPOTPY algorithm to use (e.g., ‘lhs’, ‘mcmc’, ‘dream’). Default is ‘lhs’.

  • obj_dir (str, optional) – Direction of the objective function optimization (‘maximize’ or ‘minimize’). Default is ‘maximize’.

  • fix_param (list of str, optional) – List of parameters to fix during sampling (default is None).

  • fix_val (dict, optional) – Dictionary of fixed parameter values (default is None).

  • demcz_args (dict, optional) – Additional arguments for the DEMCz algorithm (default is None).

  • kwargs (dict, optional) – Additional parameters for the MATILDA model.

Returns:

Results of the sampling, including: - ‘best_param’: dict

Best parameter set identified during sampling.

  • ’best_index’: int

    Index of the best run in the SPOTPY results.

  • ’best_model_run’: array

    Model output corresponding to the best parameter set.

  • ’best_objf’: float

    Value of the objective function for the best parameter set.

  • ’best_simulation’: pandas.Series (if applicable)

    Simulated time series corresponding to the best parameter set.

  • ’sampling_plot’: matplotlib.Figure (if applicable)

    Iteration vs. objective function plot.

  • ’best_run_plot’: matplotlib.Figure (if applicable)

    Best simulation vs. observed data plot.

  • ’par_uncertain_plot’: matplotlib.Figure (if applicable)

    Parameter uncertainty plot.

Return type:

dict

Notes

  • This function uses the SPOTPY library for parameter sampling and optimization.

  • Parallel computation is supported for specific algorithms (‘mc’, ‘lhs’, ‘fast’, ‘rope’, ‘sceua’, ‘demcz’).

References

matilda.mspot_glacier.scaled_ndd(data, elev, lr)[source]

Calculate scaled negative degree days (NDD) based on temperature lapse rate and elevation adjustments.

This function adjusts the input temperature data for elevation differences using a given lapse rate, then calculates the negative degree days by setting all positive or zero temperatures to zero and marking negative temperatures as 1.

Parameters:

  • data (array_like) – Array or series of temperature values (in °C).

  • elev (float) – Elevation difference (in meters) used for scaling the temperature values.

  • lr (float) – Temperature lapse rate (in °C/m) used for scaling.

Returns:

ndd – Scaled negative degree days (NDD), where negative temperatures are marked as 1 and others as 0.

Return type:

array_like

Notes

Negative degree days are used in some hydrological and glaciological models to track periods with freezing conditions. This function adjusts the temperature for elevation differences before computing NDD.

Examples

>>> data = np.array([2, -1, 3, -2, 5])
>>> elev = 500  # meters
>>> lr = -0.006  # °C/m
>>> scaled_ndd(data, elev, lr)
array([0, 1, 0, 1, 0])
matilda.mspot_glacier.scaled_pdd(data, elev, lr)[source]

Calculate scaled positive degree days (PDD) based on temperature lapse rate and elevation adjustments.

This function adjusts the input temperature data for elevation differences using a given lapse rate, then calculates the positive degree days by setting all negative or zero temperatures to zero.

Parameters:

  • data (array_like) – Array or series of temperature values (in °C).

  • elev (float) – Elevation difference (in meters) used for scaling the temperature values.

  • lr (float) – Temperature lapse rate (in °C/m) used for scaling.

Returns:

pdd – Scaled positive degree days (PDD), where negative values are replaced with zero.

Return type:

array_like

Notes

Positive degree days are commonly used in snow and ice melt models to estimate melt based on temperature inputs. This function adjusts the temperature for elevation differences before computing PDD.

Examples

>>> data = np.array([2, -1, 3, -2, 5])
>>> elev = 500  # meters
>>> lr = -0.006  # °C/m
>>> scaled_pdd(data, elev, lr)
array([5, 0, 6, 0, 8])
matilda.mspot_glacier.spot_setup(set_up_start=None, set_up_end=None, sim_start=None, sim_end=None, freq='D', lat=None, area_cat=None, area_glac=None, ele_dat=None, ele_glac=None, ele_cat=None, glacier_profile=None, elev_rescaling=True, target_mb=None, target_swe=None, swe_scaling=None, fix_param=None, fix_val=None, obj_func=None, lr_temp_lo=-0.0065, lr_temp_up=-0.0055, lr_prec_lo=0, lr_prec_up=0.002, BETA_lo=1, BETA_up=6, CET_lo=0, CET_up=0.3, FC_lo=50, FC_up=500, K0_lo=0.01, K0_up=0.4, K1_lo=0.01, K1_up=0.4, K2_lo=0.001, K2_up=0.15, LP_lo=0.3, LP_up=1, MAXBAS_lo=2, MAXBAS_up=7, PERC_lo=0, PERC_up=3, UZL_lo=0, UZL_up=500, PCORR_lo=0.5, PCORR_up=2, TT_snow_lo=-1.5, TT_snow_up=1.5, TT_diff_lo=0.5, TT_diff_up=2.5, CFMAX_snow_lo=0.5, CFMAX_snow_up=10, CFMAX_rel_lo=1.2, CFMAX_rel_up=2, SFCF_lo=0.4, SFCF_up=1, CWH_lo=0, CWH_up=0.2, AG_lo=0, AG_up=1, CFR_lo=0.05, CFR_up=0.25, interf=4, freqst=2)[source]

Spotpy-based setup for parameter optimization and calibration of the MATILDA model.

This class provides the framework to optimize the parameters of the MATILDA model using SPOTPY, a statistical parameter optimization tool. It enables flexible parameter setup, handles fixed parameters, and evaluates simulation results against observed data (e.g., streamflow, snow water equivalent, surface mass balance).

Parameters:

  • inputs (General)

  • set_up_start (-) – Start and end dates of the setup period.

  • set_up_end (str) – Start and end dates of the setup period.

  • sim_start (-) – Start and end dates of the simulation period.

  • sim_end (str) – Start and end dates of the simulation period.

  • freq (-) – Frequency of the data, default is daily (“D”).

  • lat (-) – Latitude of the catchment for extraterrestrial radiation calculation.

  • area_cat (-) – Catchment and glacierized areas in km².

  • area_glac (float) – Catchment and glacierized areas in km².

  • ele_dat (-) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • ele_glac (float) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • ele_cat (float) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • glacier_profile (-) – Glacier profile for scaling and elevation rescaling.

  • elev_rescaling (-) – Flag for enabling elevation rescaling, default is True.

  • target_mb (-) – Target surface mass balance (MB) or snow water equivalent (SWE) for calibration.

  • target_swe (float, optional) – Target surface mass balance (MB) or snow water equivalent (SWE) for calibration.

  • swe_scaling (-) – Scaling factor for snow water equivalent. Used to account for the mismatch in resolution of the SWE calibration data and the glacier mask used for MATILDA.

  • calibration (Parameter bounds for)

  • (e.g. (- Fix parameter bounds)

  • lr_temp_lo

  • rates). (lr_temp_up for lapse)

  • fix_param (-) – List of parameters to fix during calibration.

  • fix_val (-) – Fixed parameter values (if applicable).

  • settings (SPOTPY)

  • interf (-) – Inference factor for parameter iterations, default is 4.

  • freqst (-) – Frequency step for sensitivity analysis, default is 2.

matilda.mspot_glacier.simulation(x, param_names, fix_param, fix_val, swe_scaling)

Executes the MATILDA simulation with sampled parameters and fixed parameters (if specified).

matilda.mspot_glacier.evaluation()

Prepares the observed data (e.g., streamflow, SWE) for comparison with simulation results.

matilda.mspot_glacier.objectivefunction(simulation, evaluation, params=None)

Defines the objective function for model evaluation using the Kling-Gupta Efficiency (KGE) or user-defined metrics.

Returns:

spot_setup_class – Configured SPOTPY setup class for MATILDA parameter optimization and calibration.

Return type:

class

References

matilda.mspot_glacier.spot_setup_glacier(set_up_start=None, set_up_end=None, sim_start=None, sim_end=None, freq='D', lat=None, area_cat=None, area_glac=None, ele_dat=None, ele_glac=None, glacier_profile=None, obs_type='annual', obj_func=None, lr_temp_lo=-0.0065, lr_temp_up=-0.0055, lr_prec_lo=0, lr_prec_up=0.002, PCORR_lo=0.5, PCORR_up=2, TT_snow_lo=-1.5, TT_snow_up=1.5, TT_diff_lo=0.5, TT_diff_up=2.5, CFMAX_snow_lo=0.5, CFMAX_snow_up=10, CFMAX_rel_lo=1.2, CFMAX_rel_up=2, SFCF_lo=0.4, SFCF_up=1, CFR_lo=0.05, CFR_up=0.25, interf=4, freqst=2)[source]

Spotpy-based setup for parameter optimization and calibration of the MATILDA model for a (sub-)catchment entirely covered by glaciers.

This class provides the framework to optimize the parameters of the MATILDA model using SPOTPY, a statistical parameter optimization tool. It enables flexible parameter setup, handles fixed parameters, and evaluates simulation results against observed data (e.g., streamflow, snow water equivalent, surface mass balance). It supports annual, winter, and summer mass balance optimization based on observed data.

Parameters:

  • inputs (General)

  • set_up_start (-) – Start and end dates of the setup period.

  • set_up_end (str) – Start and end dates of the setup period.

  • sim_start (-) – Start and end dates of the simulation period.

  • sim_end (str) – Start and end dates of the simulation period.

  • freq (-) – Frequency of the data, default is daily (“D”).

  • lat (-) – Latitude of the catchment for extraterrestrial radiation calculation.

  • area_cat (-) – Catchment and glacierized areas in km².

  • area_glac (float) – Catchment and glacierized areas in km².

  • ele_dat (-) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • ele_glac (float) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • ele_cat (float) – Mean elevations (m a.s.l.) of the data, glacier, and catchment.

  • glacier_profile (-) – Glacier profile used for elevation rescaling and look-up table generation.

  • obs_type (-) – Type of observed mass balance data: “annual”, “winter”, or “summer”. Default is “annual”.

  • obj_func (-) – Custom objective function to compare simulation and observation. If None, the Mean Absolute Error (MAE) is used.

  • calibration (Parameter bounds for)

  • lr_temp_lo (-) – Bounds for temperature lapse rate (°C/m).

  • lr_temp_up (float) – Bounds for temperature lapse rate (°C/m).

  • lr_prec_lo (-) – Bounds for precipitation correction factor.

  • lr_prec_up (float) – Bounds for precipitation correction factor.

  • PCORR_lo (-) – Bounds for precipitation correction factor.

  • PCORR_up (float) – Bounds for precipitation correction factor.

  • TT_snow_lo (-) – Bounds for snow temperature threshold (°C).

  • TT_snow_up (float) – Bounds for snow temperature threshold (°C).

  • TT_diff_lo (-) – Bounds for the difference between rain and snow temperature thresholds (°C).

  • TT_diff_up (float) – Bounds for the difference between rain and snow temperature thresholds (°C).

  • CFMAX_snow_lo (-) – Bounds for the degree-day factor for snow melt (mm/°C/day).

  • CFMAX_snow_up (float) – Bounds for the degree-day factor for snow melt (mm/°C/day).

  • CFMAX_rel_lo (-) – Bounds for the degree-day factor for relative snow and ice melt.

  • CFMAX_rel_up (float) – Bounds for the degree-day factor for relative snow and ice melt.

  • SFCF_lo (-) – Bounds for snow correction factor.

  • SFCF_up (float) – Bounds for snow correction factor.

  • CFR_lo (-) – Bounds for the refreezing factor.

  • CFR_up (float) – Bounds for the refreezing factor.

  • settings (SPOTPY)

  • interf (-) – Inference factor for parameter iterations, default is 4.

  • freqst (-) – Frequency step for sensitivity analysis, default is 2.

matilda.mspot_glacier.simulation(x)

Executes the glacier mass balance simulation using the degree-day model (DDM).

matilda.mspot_glacier.evaluation()

Prepares observed mass balance data (annual, winter, or summer) for comparison.

matilda.mspot_glacier.objectivefunction(simulation, evaluation, params=None)

Defines the objective function to calculate the error between simulated and observed mass balance values.

Returns:

spot_setup_class – Configured SPOTPY setup class for glacier mass balance parameter optimization.

Return type:

class

References

matilda.mspot_glacier.summer(year, data)[source]

Extract the summer period for a given year from a record of the World Glacier Monitoring service (WGMS).

This function filters the input dataset for the specified year and returns a slice object representing the summer period based on the END_WINTER and END_PERIOD columns.

Parameters:

  • year (int) – The year for which the summer period is to be extracted.

  • data (pandas.DataFrame) – The input dataset containing at least the following columns: - END_WINTER: The end of the winter period. - END_PERIOD: The end of the summer period. - Index representing years.

Returns:

A slice object representing the summer period for the specified year.

Return type:

slice

Notes

The function assumes that the dataset is indexed by years and contains the END_WINTER and END_PERIOD columns with appropriate datetime or timestamp values.

References

  • WGMS (2024): Fluctuations of Glaciers Database. World Glacier Monitoring Service, Zurich, Switzerland.

https://doi.org/10.5904/wgms-fog-2024-01

matilda.mspot_glacier.winter(year, data)[source]

Extract the winter period for a given year from a record of the World Glacier Monitoring service (WGMS).

This function filters the input dataset for the specified year and returns a slice object representing the winter period based on the BEGIN_PERIOD and END_WINTER columns.

Parameters:

  • year (int) – The year for which the winter period is to be extracted.

  • data (pandas.DataFrame) – The input dataset containing at least the following columns: - BEGIN_PERIOD: The start of the winter period. - END_WINTER: The end of the winter period. - Index representing years.

Returns:

A slice object representing the winter period for the specified year.

Return type:

slice

Notes

The function assumes that the dataset is indexed by years and contains the BEGIN_PERIOD and END_WINTER columns with appropriate datetime or timestamp values.

References

  • WGMS (2024): Fluctuations of Glaciers Database. World Glacier Monitoring Service, Zurich, Switzerland.

https://doi.org/10.5904/wgms-fog-2024-01

matilda.mspot_glacier.yesno(question)[source]

Prompt the user with a yes/no question and return the response.

This function repeatedly prompts the user with the given question until a valid response (‘y’ or ‘n’) is entered.

Parameters:

question (str) – The yes/no question to present to the user.

Returns:

Returns True if the user responds with ‘y’, and False if the user responds with ‘n’.

Return type:

bool