Merge pull request #161 from GeoStat-Framework/develop

v1.5.1 release

.gitignore

@@ -121,3 +121,4 @@ pykrige/_version.py
 *.vtr
 examples/meuse_example_data/*
 *.ipynb_checkpoints/*
+examples/output.asc

.travis.yml

@@ -1,3 +1,6 @@
+# do not build pull request from base repo twice (only build PRs of forks)
+if: type != pull_request OR fork = true
+
 language: python
 python: 3.8
 
@@ -11,6 +14,7 @@ env:
     - CIBW_BEFORE_BUILD="pip install numpy==1.17.3 scipy==1.3.2 cython==0.29.14 setuptools"
     - CIBW_TEST_REQUIRES="pytest scikit-learn gstools"
     - CIBW_TEST_COMMAND="pytest -v {project}/tests"
+    - OMP_NUM_THREADS=2
 
 before_install:
   - |

CHANGELOG.md

@@ -2,6 +2,22 @@ Changelog
 =========
 
 
+Version 1.5.1
+-------------
+*August 20, 2020*
+
+**New features**
+
+* update Regression Kriging class to be compatible with all kriging features (#158)
+* added option to enable/disable "exact values" to all kriging routines (#153)
+* added option to use the pseudo-inverse in all kriging routines (#151)
+
+**Changes**
+
+* removed compat-layer for sklearn (#157)
+* updated examples in documentation
+
+
 Version 1.5.0
 -------------
 *April 04, 2020*

README.rst

@@ -12,7 +12,7 @@ PyKrige
 .. image:: https://coveralls.io/repos/github/GeoStat-Framework/PyKrige/badge.svg?branch=master
    :target: https://coveralls.io/github/GeoStat-Framework/PyKrige?branch=master
 .. image:: https://readthedocs.org/projects/pykrige/badge/?version=stable
-   :target: http://pykrige.readthedocs.io/en/latest/?badge=stable
+   :target: http://pykrige.readthedocs.io/en/stable/?badge=stable
    :alt: Documentation Status
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
@@ -26,6 +26,7 @@ PyKrige
 
 Kriging Toolkit for Python.
 
+
 Purpose
 ^^^^^^^
 
@@ -39,7 +40,9 @@ point and all grid points. With the 'functional' drift capability, the user may
 of the spatial coordinates that define the drift(s). The package includes a module that contains functions
 that should be useful in working with ASCII grid files (`*.asc`).
 
-See the documentation at `http://pykrige.readthedocs.io/ <http://pykrige.readthedocs.io/>`_ for more details.
+See the documentation at `http://pykrige.readthedocs.io/ <http://pykrige.readthedocs.io/>`_
+for more details and examples.
+
 
 Installation
 ^^^^^^^^^^^^
@@ -60,193 +63,52 @@ If you use conda, PyKrige can be installed from the `conda-forge` channel with,
     conda install -c conda-forge pykrige
 
 
-Ordinary Kriging Example
-^^^^^^^^^^^^^^^^^^^^^^^^
+Features
+^^^^^^^^
 
-First we will create a 2D dataset together with the associated x, y grids,
+Kriging algorithms
+------------------
 
-.. code:: python
+* ``OrdinaryKriging``: 2D ordinary kriging with estimated mean
+* ``UniversalKriging``: 2D universal kriging providing drift terms
+* ``OrdinaryKriging3D``: 3D ordinary kriging
+* ``UniversalKriging3D``: 3D universal kriging
+* ``RegressionKriging``: An implementation of Regression-Kriging
 
-    import numpy as np
-    import pykrige.kriging_tools as kt
-    from pykrige.ok import OrdinaryKriging
-
-    data = np.array([[0.3, 1.2, 0.47],
-                     [1.9, 0.6, 0.56],
-                     [1.1, 3.2, 0.74],
-                     [3.3, 4.4, 1.47],
-                     [4.7, 3.8, 1.74]])
-
-    gridx = np.arange(0.0, 5.5, 0.5)
-    gridy = np.arange(0.0, 5.5, 0.5)
-
-    # Create the ordinary kriging object. Required inputs are the X-coordinates of
-    # the data points, the Y-coordinates of the data points, and the Z-values of the
-    # data points. If no variogram model is specified, defaults to a linear variogram
-    # model. If no variogram model parameters are specified, then the code automatically
-    # calculates the parameters by fitting the variogram model to the binned
-    # experimental semivariogram. The verbose kwarg controls code talk-back, and
-    # the enable_plotting kwarg controls the display of the semivariogram.
-    OK = OrdinaryKriging(data[:, 0], data[:, 1], data[:, 2], variogram_model='linear',
-                         verbose=False, enable_plotting=False)
-
-    # Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
-    # grid of points, on a masked rectangular grid of points, or with arbitrary points.
-    # (See OrdinaryKriging.__doc__ for more information.)
-    z, ss = OK.execute('grid', gridx, gridy)
-
-    # Writes the kriged grid to an ASCII grid file.
-    kt.write_asc_grid(gridx, gridy, z, filename="output.asc")
-
-
-Universal Kriging Example
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: python
-
-    from pykrige.uk import UniversalKriging
-    import numpy as np
-
-    data = np.array([[0.3, 1.2, 0.47],
-                     [1.9, 0.6, 0.56],
-                     [1.1, 3.2, 0.74],
-                     [3.3, 4.4, 1.47],
-                     [4.7, 3.8, 1.74]])
-
-    gridx = np.arange(0.0, 5.5, 0.5)
-    gridy = np.arange(0.0, 5.5, 0.5)
-
-    # Create the ordinary kriging object. Required inputs are the X-coordinates of
-    # the data points, the Y-coordinates of the data points, and the Z-values of the
-    # data points. Variogram is handled as in the ordinary kriging case.
-    # drift_terms is a list of the drift terms to include; currently supported terms
-    # are 'regional_linear', 'point_log', and 'external_Z'. Refer to
-    # UniversalKriging.__doc__ for more information.
-    UK = UniversalKriging(data[:, 0], data[:, 1], data[:, 2], variogram_model='linear',
-                          drift_terms=['regional_linear'])
-
-    # Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
-    # grid of points, on a masked rectangular grid of points, or with arbitrary points.
-    # (See UniversalKriging.__doc__ for more information.)
-    z, ss = UK.execute('grid', gridx, gridy)
-
-
-Three-Dimensional Kriging Example
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: python
-
-    from pykrige.ok3d import OrdinaryKriging3D
-    from pykrige.uk3d import UniversalKriging3D
-    import numpy as np
-
-    data = np.array([[0.1, 0.1, 0.3, 0.9],
-                                     [0.2, 0.1, 0.4, 0.8],
-                                     [0.1, 0.3, 0.1, 0.9],
-                                     [0.5, 0.4, 0.4, 0.5],
-                                     [0.3, 0.3, 0.2, 0.7]])
-
-    gridx = np.arange(0.0, 0.6, 0.05)
-    gridy = np.arange(0.0, 0.6, 0.01)
-    gridz = np.arange(0.0, 0.6, 0.1)
-
-    # Create the 3D ordinary kriging object and solves for the three-dimension kriged
-    # volume and variance. Refer to OrdinaryKriging3D.__doc__ for more information.
-    ok3d = OrdinaryKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
-                                                     variogram_model='linear')
-    k3d, ss3d = ok3d.execute('grid', gridx, gridy, gridz)
-
-    # Create the 3D universal kriging object and solves for the three-dimension kriged
-    # volume and variance. Refer to UniversalKriging3D.__doc__ for more information.
-    uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
-                                                      variogram_model='linear', drift_terms=['regional_linear'])
-    k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz)
-
-    # To use the generic 'specified' drift term, the user must provide the drift values
-    # at each data point and at every grid point. The following example is equivalent to
-    # using a linear drift in all three spatial dimensions. Refer to
-    # UniversalKriging3D.__doc__ for more information.
-    zg, yg, xg = np.meshgrid(gridz, gridy, gridx, indexing='ij')
-    uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
-                                                      variogram_model='linear', drift_terms=['specified'],
-                                                      specified_drift=[data[:, 0], data[:, 1]])
-    k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz, specified_drift_arrays=[xg, yg, zg])
-
-    # To use the generic 'functional' drift term, the user must provide a callable
-    # function that takes only the spatial dimensions as arguments. The following example
-    # is equivalent to using a linear drift only in the x-direction. Refer to
-    # UniversalKriging3D.__doc__ for more information.
-    func = lambda x, y, z: x
-    uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
-                                                      variogram_model='linear', drift_terms=['functional'],
-                                                      functional_drift=[func])
-    k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz)
-
-    # Note that the use of the 'specified' and 'functional' generic drift capabilities is
-    # essentially identical in the two-dimensional universal kriging class (except for a
-    # difference in the number of spatial coordinates for the passed drift functions).
-    # See UniversalKriging.__doc__ for more information.
-
-
-GSTools covariance models
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can also use `GSTools <https://github.com/GeoStat-Framework/GSTools>`_
-covariance models as input for the ``variogram_model`` in the
-PyKrige routines:
-
-.. code:: python
-
-    import numpy as np
-    from gstools import Gaussian
-    from pykrige.ok import OrdinaryKriging
-    from matplotlib import pyplot as plt
-
-    # conditioning data
-    data = np.array([[0.3, 1.2, 0.47],
-                     [1.9, 0.6, 0.56],
-                     [1.1, 3.2, 0.74],
-                     [3.3, 4.4, 1.47],
-                     [4.7, 3.8, 1.74]])
-    # grid definition for output field
-    gridx = np.arange(0.0, 5.5, 0.1)
-    gridy = np.arange(0.0, 6.5, 0.1)
-    # a GSTools based covariance model
-    cov_model = Gaussian(dim=2, len_scale=1, anis=0.2, angles=-0.5, var=0.5, nugget=0.1)
-    # ordinary kriging with pykrige
-    OK1 = OrdinaryKriging(data[:, 0], data[:, 1], data[:, 2], cov_model)
-    z1, ss1 = OK1.execute('grid', gridx, gridy)
-    plt.imshow(z1, origin="lower")
-    plt.show()
-
-Which gives:
-
-.. image:: https://raw.githubusercontent.com/GeoStat-Framework/GSTools/master/docs/source/pics/20_pykrige.png
-   :width: 400px
-   :align: center
 
-Have a look at the `documentation about the Covariance Model of GSTools <https://geostat-framework.readthedocs.io/projects/gstools/en/latest/tutorial_02_cov.html>`_.
+Wrappers
+--------
+
+* ``rk.Krige``: A scikit-learn wrapper class for Ordinary and Universal Kriging
+
+
+Tools
+-----
+
+* ``kriging_tools.write_asc_grid``: Writes gridded data to ASCII grid file (\*.asc)
+* ``kriging_tools.read_asc_grid``: Reads ASCII grid file (\*.asc)
 
 
 Kriging Parameters Tuning
-^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------
 
 A scikit-learn compatible API for parameter tuning by cross-validation is exposed in
 `sklearn.model_selection.GridSearchCV <http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.GridSearchCV.html>`_.
-See the `Krige CV <http://pykrige.readthedocs.io/en/latest/examples/krige_cv.html#sphx-glr-examples-krige-cv-py>`_
+See the `Krige CV <http://pykrige.readthedocs.io/en/latest/examples/08_krige_cv.html#sphx-glr-examples-08-krige-cv-py>`_
 example for a more practical illustration.
 
 
 Regression Kriging
-^^^^^^^^^^^^^^^^^^
+------------------
 
 `Regression kriging <https://en.wikipedia.org/wiki/Regression-Kriging>`_ can be performed
-with `pykrige.rk.RegressionKriging <http://pykrige.readthedocs.io/en/latest/examples/regression_kriging2d.html>`_.
+with `pykrige.rk.RegressionKriging <http://pykrige.readthedocs.io/en/latest/examples/07_regression_kriging2d.html>`_.
 This class takes as parameters a scikit-learn regression model, and details of either either
 the ``OrdinaryKriging`` or the ``UniversalKriging`` class, and performs a correction steps on the ML regression prediction.
 
 A demonstration of the regression kriging is provided in the
-`corresponding example <http://pykrige.readthedocs.io/en/latest/examples/regression_kriging2d.html#sphx-glr-examples-regression-kriging2d-py>`_.
+`corresponding example <http://pykrige.readthedocs.io/en/latest/examples/07_regression_kriging2d.html#sphx-glr-examples-07-regression-kriging2d-py>`_.
+
 
 License
 ^^^^^^^

examples/00_ordinary.py

@@ -0,0 +1,58 @@
+"""
+Ordinary Kriging Example
+========================
+
+First we will create a 2D dataset together with the associated x, y grids.
+
+"""
+
+import numpy as np
+import pykrige.kriging_tools as kt
+from pykrige.ok import OrdinaryKriging
+import matplotlib.pyplot as plt
+
+
+data = np.array(
+    [
+        [0.3, 1.2, 0.47],
+        [1.9, 0.6, 0.56],
+        [1.1, 3.2, 0.74],
+        [3.3, 4.4, 1.47],
+        [4.7, 3.8, 1.74],
+    ]
+)
+
+gridx = np.arange(0.0, 5.5, 0.5)
+gridy = np.arange(0.0, 5.5, 0.5)
+
+###############################################################################
+# Create the ordinary kriging object. Required inputs are the X-coordinates of
+# the data points, the Y-coordinates of the data points, and the Z-values of the
+# data points. If no variogram model is specified, defaults to a linear variogram
+# model. If no variogram model parameters are specified, then the code automatically
+# calculates the parameters by fitting the variogram model to the binned
+# experimental semivariogram. The verbose kwarg controls code talk-back, and
+# the enable_plotting kwarg controls the display of the semivariogram.
+
+OK = OrdinaryKriging(
+    data[:, 0],
+    data[:, 1],
+    data[:, 2],
+    variogram_model="linear",
+    verbose=False,
+    enable_plotting=False,
+)
+
+###############################################################################
+# Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
+# grid of points, on a masked rectangular grid of points, or with arbitrary points.
+# (See OrdinaryKriging.__doc__ for more information.)
+
+z, ss = OK.execute("grid", gridx, gridy)
+
+###############################################################################
+# Writes the kriged grid to an ASCII grid file and plot it.
+
+kt.write_asc_grid(gridx, gridy, z, filename="output.asc")
+plt.imshow(z)
+plt.show()