oggm.tasks.mb_calibration_from_scalar_mb

oggm.tasks.mb_calibration_from_scalar_mb(gdir, *, settings_filesuffix='', observations_filesuffix='', overwrite_observations=False, ref_mb=None, ref_mb_unit='kg m-2 yr-1', ref_mb_err=None, ref_mb_period=None, ref_mb_years=None, write_to_gdir=True, overwrite_gdir=False, use_2d_mb=False, calibrate_param1='melt_f', calibrate_param2=None, calibrate_param3=None, melt_f=None, melt_f_min=None, melt_f_max=None, prcp_fac=None, prcp_fac_min=None, prcp_fac_max=None, temp_bias=None, temp_bias_min=None, temp_bias_max=None, mb_model_class=<class 'oggm.core.massbalance.MonthlyTIModel'>, return_mb_model=False, **kwargs: dict)

Determine the mass balance parameters from a scalar mass-balance value.

This calibrates the mass balance parameters using reference MB data over a given period (annual average or cumulative in-situ SMB or geodetic MB). This flexible calibration allows to calibrate three parameters one after another. The first parameter is varied between two chosen values (a range) until the ref MB value is matched. If this fails, the second parameter can be changed, etc.

This can be used for example to apply the “three-step calibration” introduced by Huss & Hock 2015, but you can choose any order of calibration.

This task can be called by other, “higher level” tasks, for example oggm.core.massbalance.mb_calibration_from_geodetic_mb() or oggm.core.massbalance.mb_calibration_from_wgms_mb().

Note that this does not compute the apparent mass balance at the same time - users need to run apparent_mb_from_any_mb after calibration.

Parameters:

gdiroggm.GlacierDirectory

the glacier directory to calibrate

settings_filesuffix: str

You can use a different set of settings by providing a filesuffix. This is useful for sensitivity experiments. Code-wise the settings_filesuffix is set in the @entity-task decorater.

observations_filesuffix: str

You can provide a filesuffix for the mb observations to use. If you provide ref_mb, ref_mb_err, ref_mb_period and/or ref_mb_years, then this values will be stored in the observations file, if ref_mb is not already present. If you want to force to use the provided values and override the current ones, set overwrite_observations to True. Code-wise the observations_filesuffix is set in the @entity-task decorater.

overwrite_observationsbool

If you want to overwrite already existing observation values in the provided observations file set this to True. Default is False.

ref_mbfloat, required

The reference mass balance to match, either provided as an annual average (kg m-2 yr-1) or as a cumulative value (kg m-2) over the provided ref_mb_period. The correct unit must be set in ref_mb_unit. To use available observations, see oggm.core.massbalance.mb_calibration_from_geodetic_mb() or oggm.core.massbalance.mb_calibration_from_wgms_mb().

ref_mb_unitstr, optional

The unit of ref_mb`. Options are: - ‘kg m-2 yr-1’: annual average MB over a full-year ref_mb_period. - ‘kg m-2’: cumulative MB over any ref_mb_period.

ref_mb_errfloat, optional

currently only used for logging - it is not used in the calibration.

ref_mb_periodstr, optional

date format - for example ‘2000-01-01_2010-01-01’. If this is not set, ref_mb_years needs to be set.

ref_mb_yearstuple of length 2 (range) or list of years.

convenience kwarg to override ref_mb_period. If a tuple of length 2 is given, all years between this range (excluding the last one) are used. If a list of years is given, all these will be used (useful for data with gaps)

write_to_gdirbool

whether to write the results of the calibration to the glacier directory. If True (the default), this will be saved as mb_calib.json and be used by the MassBalanceModel class as parameters in subsequent tasks.

overwrite_gdirbool

if mass balance parameters exists, this task won’t overwrite it per default. Set this to True to enforce overwriting (i.e. with consequences for the future workflow).

use_2d_mbbool

Set to True if the mass balance calibration has to be done of the 2D mask of the glacier (for fully distributed runs only).

mb_model_classMassBalanceModel, default MonthlyTIModel

the MassBalanceModel to use for the calibration. Needs to use the same parameters as MonthlyTIModel (the default): melt_f, temp_bias, prcp_fac.

calibrate_param1str

in the three-step calibration, the name of the first parameter to calibrate (one of ‘melt_f’, ‘temp_bias’, ‘prcp_fac’).

calibrate_param2str

in the three-step calibration, the name of the second parameter to calibrate (one of ‘melt_f’, ‘temp_bias’, ‘prcp_fac’). If not set and the algorithm cannot match observations, it will raise an error.

calibrate_param3str

in the three-step calibration, the name of the third parameter to calibrate (one of ‘melt_f’, ‘temp_bias’, ‘prcp_fac’). If not set and the algorithm cannot match observations, it will raise an error.

melt_f: float

the default value to use as melt factor (or the starting value when optimizing MB). Defaults to gdir.settings[‘melt_f’].

melt_f_min: float

the minimum accepted value for the melt factor during optimisation. Defaults to gdir.settings[‘melt_f_min’].

melt_f_max: float

the maximum accepted value for the melt factor during optimisation. Defaults to gdir.settings[‘melt_f_max’].

prcp_fac: float

the default value to use as precipitation scaling factor (or the starting value when optimizing MB). Defaults to the method chosen in params.cfg (winter prcp or global factor).

prcp_fac_min: float

the minimum accepted value for the precipitation scaling factor during optimisation. Defaults to gdir.settings[‘prcp_fac_min’].

prcp_fac_max: float

the maximum accepted value for the precipitation scaling factor during optimisation. Defaults to gdir.settings[‘prcp_fac_max’].

temp_bias: float

the default value to use as temperature bias (or the starting value when optimizing MB). Defaults to 0.

temp_bias_min: float

the minimum accepted value for the temperature bias during optimisation. Defaults to gdir.settings[‘temp_bias_min’].

temp_bias_max: float

the maximum accepted value for the temperature bias during optimisation. Defaults to gdir.settings[‘temp_bias_max’].

return_mb_model: bool

if the finally calibrated mb_model should be returned. Useful for testing mb_models with a memory (e.g. SfcTypeTIModel). Default is False.

kwargs: dict

kwargs to pass to the mb_model_class instance

Notes

Files written to the glacier directory:

mb_calib.json

A dict containing the glacier’s mass balance calibration parameters.