idw | centroid_poisson_kriging docs examples

Author: SimonMolinsky

CHANGELOG.rst

@@ -43,7 +43,7 @@ Changes - from version >= 1.x
 * [docs] corrected broken links to `CONTRIBUTING.md` file in readme and docs
 * [setup] links to documentation have been added to `pyproject.toml`
 * [docs] docstring examples - all user-facing API endpoints has examples in docstrings, using new input types (values | geometries)
-* [docs] updated docstrings (examples) in: `PointSupportDistance`, `core.block_filter`, `pipelines.interpolate`, `pyinterpolate.distance.block.calc_block_to_block_distance`, `validate_kriging`, `metrics` module functions, 
+* [docs] updated docstrings (examples) in: `PointSupportDistance`, `core.block_filter`, `pipelines.interpolate`, `pyinterpolate.distance.block.calc_block_to_block_distance`, `validate_kriging`, `metrics` module functions, `inverse_distance_weighting`, `centroid_poisson_kriging`,
 
 2025-10-11
 ----------

src/pyinterpolate/idw/idw.py

@@ -72,6 +72,27 @@ def inverse_distance_weighting(unknown_location: ArrayLike,
     ValueError
         Less than 2 neighbours or more than the number of ``known_points``
         neighbours are given in the ``number_of_neighbours`` parameter.
+
+    Examples
+    --------
+    >>> unknown_pos = (10, 10)
+    >>> locs = np.array([
+    ...     [11, 1, 1],
+    ...     [23, 2, 2],
+    ...     [33, 3, 3],
+    ...     [14, 44, 4],
+    ...     [13, 10, 9],
+    ...     [12, 55, 35],
+    ...     [11, 9, 7]
+    ... ])
+    >>> pred = inverse_distance_weighting(
+    ...     unknown_locations=unknown_pos,
+    ...     known_values=locs[:, -1],
+    ...     known_geometries=locs[:, :-1],
+    ...     no_neighbors=2
+    ... )
+    >>> print(pred)
+    7.286311587314138
     """
 
     # Check power parameter

src/pyinterpolate/kriging/block/centroid_based_poisson_kriging.py

@@ -73,6 +73,71 @@ def centroid_poisson_kriging(semivariogram_model: TheoreticalVariogram,
     ------
     ValueError
         Raised when prediction or prediction error are negative.
+
+    Examples
+    --------
+    >>> import os
+    >>> import geopandas as gpd
+    >>> from pyinterpolate import (
+    ...     centroid_poisson_kriging,
+    ...     Blocks,
+    ...     ExperimentalVariogram,
+    ...     PointSupport,
+    ...     TheoreticalVariogram
+    ... )
+    >>>
+    >>>
+    >>> FILENAME = 'cancer_data.gpkg'
+    >>> LAYER_NAME = 'areas'
+    >>> DS = gpd.read_file(FILENAME, layer=LAYER_NAME)
+    >>> AREA_VALUES = 'rate'
+    >>> AREA_INDEX = 'FIPS'
+    >>> AREA_GEOMETRY = 'geometry'
+    >>> PS_LAYER_NAME = 'points'
+    >>> PS_VALUES = 'POP10'
+    >>> PS_GEOMETRY = 'geometry'
+    >>> PS = gpd.read_file(FILENAME, layer=PS_LAYER_NAME)
+    >>>
+    >>> CANCER_DATA = {
+    ...    'ds': DS,
+    ...    'index_column_name': AREA_INDEX,
+    ...    'value_column_name': AREA_VALUES,
+    ...    'geometry_column_name': AREA_GEOMETRY
+    ... }
+    >>> POINT_SUPPORT_DATA = {
+    ...     'ps': PS,
+    ...     'value_column_name': PS_VALUES,
+    ...     'geometry_column_name': PS_GEOMETRY
+    ... }
+    >>> BLOCKS = Blocks(**CANCER_DATA)
+    >>> indexes = BLOCKS.block_indexes
+    >>>
+    >>> PS = PointSupport(
+    ...     points=POINT_SUPPORT_DATA['ps'],
+    ...     ps_blocks=BLOCKS,
+    ...     points_value_column=POINT_SUPPORT_DATA['value_column_name'],
+    ...     points_geometry_column=POINT_SUPPORT_DATA['geometry_column_name']
+    ... )
+    >>>
+    >>> EXPERIMENTAL = ExperimentalVariogram(
+    ...     ds=BLOCKS.representative_points_array(),
+    ...     step_size=40000,
+    ...     max_range=300001
+    ... )
+    >>>
+    >>> THEO = TheoreticalVariogram()
+    >>> THEO.autofit(
+    ...     experimental_variogram=EXPERIMENTAL,
+    ...     sill=150
+    ... )
+    >>> centroid_pk = centroid_poisson_kriging(
+    ...     semivariogram_model=THEO,
+    ...     point_support=PS,
+    ...     unknown_block_index=34017,
+    ...     number_of_neighbors=8
+    ... )
+    >>> print(centroid_pk)
+    {'block_id': 34017, 'zhat': 134.13113195517153, 'sig': 11.795520367595483}
     """
     # Kriging data
     kriging_data = select_centroid_poisson_kriging_data(

tests/test_kriging/test_centroid_pk.py

@@ -66,6 +66,7 @@ def test_cpk():
         unknown_block_index=indexes[-1],
         number_of_neighbors=8
     )
+    print(cpk)
     assert isinstance(cpk, dict)
     assert cpk['block_id'] == indexes[-1]
     assert cpk['zhat'] > 0