Skip to content

Experimental Variography Automatic Fitting🍋

model_fit(variograms, cov, constraints=None, weighting_method=VarioFitWeightingMethod.INVERSE_DISTANCE) 🍋

Fit a variogram model from an experimental semivariogram.

Parameters:

Name Type Description Default
variograms List[DataFrame]

Experimental semivariogram.

required
cov Union[Covariance, CovarianceElem]

Covariance model.

required
constraints List[Dict[str, Union[float, str]]]

Constraints for each model given in cov.

None
weighting_method Optional[VarioFitWeightingMethod]

Method used to compute residual between data and model.

INVERSE_DISTANCE

Note

Constraint parameters are given as a free-form dictionary for simplicity. In future version, strict objects may be considered. Constraint name follows this convention:

{PARAM}_{KIND}_{AXIS}

with {AXIS} being optional based on the type of {PARAM}.

For now, the following are accepted:

  • {PARAM} = [sill, angle, scale]
  • {KIND} = [min, max, fixed, expr]
  • {AXIS} = [0, 1, 2] (when applicable)

Here are examples of valid constraints: sill_max, scale_min_1, angle_fixed_0

Here are examples of invalid constraint: sill_max_2, scale_min, angle_fixed

If a constraint is inconsistent wrt its covariance model, it will be ignored: e.g. Nugget() ↔ {angle_fixed: 30} => will be ignored In addition, {PARAM} boundaries are forced in order to avoid meaningless values:

  • sill: [0, maxcov]
  • scale: [0, maxdist]
  • angle: [0, 360]

{PARAM}_expr are free-form expression as defined by LMFIT Parameters may be used as function of other parameters using expression. For instance, expressions can be used to ensure several structures share the same sill or angles. To use other model parameters as variable, simply follow this convention for naming: {PARAM}_{AXIS}_{MODEL_INDEX} with _{AXIS} being optional based on the type of {PARAM}. {MODEL_INDEX} starts at 0 and corresponds to the index of the structure defined in the covariance model.

For instance:

    >>> model_fit(
            vario_list,
            Nugget() + Spherical(2) + Gaussian(2),
            constraints=[
                {},
                {'sill_expr': 'sill_0', 'scale_max_1': 35},
                {'angle_expr_0': 'angle_0_1',
                    'scale_expr_1': 'scale_1_1 + 3'},
            ]
        )

In this example:

  • the 2 Nugget (structure 0 and 1) will share the same nugget effect (~sill): "sill_expr = sill_0" [sill_expr = sill_{MODEL_INDEX}]
  • the Spherical model (structure 2) and Gaussian model (structure 3) will share the same angle along the first axis (axis=0): "angle_expr_0 = angle_0_2" [angle_expr_{AXIS} = angle_{AXIS}_{MODEL_INDEX}]
  • the range of the Gaussian model along the 2nd axis (axis=1) will be equal to 3 plus the same range as the Spherical model (structure 2) along the 2nd axis (axis=1): "scale_expr_1 = scale_1_2 + 3" [scale_expr_{AXIS} = scale_{AXIS}_{MODEL_INDEX} + 3] Note that it is possible to set contradictory/inconsistent constraints to satisfy, then it will lead to 3 possible outcomes:
  • some constraints will be ignored => if {PARAM}_fixed is used, it will override/not take into account any defined {PARAM}_min, {PARAM}_max and {PARAM}_expr
  • fitting will not converge => results may silently not respect some or all constraints
  • an exception will be raised by lmfit => error message will help debug which constraint is incorrect Therefore it is your responsibility to check the consistency of the constraints among themselves and wrt the results obtained too.

Warning

Important note: the sill of the last structure in the covariance model cannot be fixed (trying to set it to fixed will be ignored). In that case, define the fixed sill first rather than last. For instance:

WRONG: the Gaussian structure will not have a sill of 0.4

>>> model_fit(
        vario_list,
        Nugget() + Spherical(2) + Exponential(2) + Gaussian(2),
        constraints=[
            {'sill_fixed': 0.2},
            {},
            {},
            {'sill_fixed': 0.4}
        ]
    )

CORRECT: the Gaussian structure will have a sill of 0.4

>>> model_fit(
        vario_list,
        Nugget() + Gaussian(2) + Spherical(2) + Exponential(2),
        constraints=[
            {'sill_fixed': 0.2},
            {'sill_fixed': 0.4},
            {},
            {},
        ]
    )

Returns:

Type Description
None

The fitted covariance model

Example

>>> model_fit(
        vario_list,
        Nugget() + Spherical(2) + Gaussian(2),
        constraints=[
            {'sill_fixed': 0.18},
            {'sill_max': 0.1},
            {'scale_max_0': 85, 'scale_max_1': 95},
        ]
    )

Last update: 2023-10-09