interpolate

py3dinterpolations.modelling.interpolate

Top-level interpolation function.

interpolate(griddata, model_type, grid_resolution, model_params=None, model_params_grid=None, preprocessing=None, **predict_kwargs)

Interpolate GridData and return the Modeler with results.

Parameters:

Name	Type	Description	Default
griddata	GridData	Source data to interpolate.	required
model_type	ModelType | str	Which model to use (e.g. "ordinary_kriging", "idw").	required
grid_resolution	float | dict[str, float]	Grid resolution. Float for regular, dict for irregular.	required
model_params	dict[str, object] | None	Model constructor parameters.	None
model_params_grid	dict[str, list[object]] | None	Parameter grid for cross-validation search.	None
preprocessing	PreprocessingKwargs | None	Keyword args for Preprocessor (e.g. downsampling_res, normalize_xyz).	None
**predict_kwargs	object	Extra kwargs passed to model.predict().	{}

Returns:

Type	Description
Modeler	Modeler instance with .result populated.

Raises:

Type	Description
ValueError	If neither or both model_params/model_params_grid are given.
NotImplementedError	If parameter search is used for non-kriging models.

Source code in py3dinterpolations/modelling/interpolate.py

def interpolate(
    griddata: GridData,
    model_type: ModelType | str,
    grid_resolution: float | dict[str, float],
    model_params: dict[str, object] | None = None,
    model_params_grid: dict[str, list[object]] | None = None,
    preprocessing: PreprocessingKwargs | None = None,
    **predict_kwargs: object,
) -> Modeler:
    """Interpolate GridData and return the Modeler with results.

    Args:
        griddata: Source data to interpolate.
        model_type: Which model to use (e.g. "ordinary_kriging", "idw").
        grid_resolution: Grid resolution. Float for regular, dict for irregular.
        model_params: Model constructor parameters.
        model_params_grid: Parameter grid for cross-validation search.
        preprocessing: Keyword args for Preprocessor
            (e.g. downsampling_res, normalize_xyz).
        **predict_kwargs: Extra kwargs passed to model.predict().

    Returns:
        Modeler instance with .result populated.

    Raises:
        ValueError: If neither or both model_params/model_params_grid are given.
        NotImplementedError: If parameter search is used for non-kriging models.
    """
    logger.info("Starting interpolation with model=%s", model_type)

    if model_params is None and model_params_grid is None:
        msg = "Either model_params or model_params_grid must be provided"
        raise ValueError(msg)
    if model_params is not None and model_params_grid is not None:
        msg = "Cannot provide both model_params and model_params_grid"
        raise ValueError(msg)

    # Build grid
    grid = create_grid(griddata, grid_resolution)

    # Preprocess if needed
    if preprocessing is not None:
        preprocessor = Preprocessor(griddata, **preprocessing)
        griddata = preprocessor.preprocess()

    # Parameter search via estimator
    if model_params is None:
        model_type_enum = ModelType(model_type)
        if model_type_enum != ModelType.ORDINARY_KRIGING:
            msg = "Parameter search is only supported for ordinary_kriging"
            raise NotImplementedError(msg)

        assert model_params_grid is not None
        est = Estimator(griddata, model_params_grid)
        model_params = dict(est.best_params)
        model_params.pop("method", None)

    # Build and fit model
    model = get_model(model_type, **model_params)
    modeler = Modeler(griddata=griddata, grid=grid, model=model)

    # Predict
    modeler.predict(**predict_kwargs)

    logger.info("Interpolation complete")
    return modeler