Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC simplify the readme #91

Merged
merged 7 commits into from Apr 21, 2018
Merged

DOC simplify the readme #91

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
45b55f4
Improve the readme
rth Mar 28, 2018
545f4db
More changes of the README
rth Mar 28, 2018
b065140
Address review comments
rth Apr 19, 2018
3e32a50
Use stable documentation links for the release
rth Apr 19, 2018
01a6971
Update long description
rth Apr 21, 2018
a0eb8e1
Fix Appveyor
rth Apr 21, 2018
9a9f347
Update appveyor
rth Apr 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
154 changes: 47 additions & 107 deletions README.rst
View file
Open in desktop
Expand Up @@ -21,28 +21,36 @@ Kriging Toolkit for Python



The code supports two- and three- dimensional ordinary and universal kriging. Standard variogram models (linear, power, spherical, gaussian, exponential) are built in, but custom variogram models can also be used with the code. The kriging methods are separated into four classes. Examples of their uses are shown below. The two-dimensional universal kriging code currently supports regional-linear, point-logarithmic, and external drift terms, while the three-dimensional universal kriging code supports a regional-linear drift term in all three spatial dimensions. Both universal kriging classes also support generic 'specified' and 'functional' drift capabilities. With the 'specified' drift capability, the user may manually specify the values of the drift(s) at each data point and all grid points. With the 'functional' drift capability, the user may provide callable function(s) 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`).
The code supports 2D and 3D ordinary and universal kriging. Standard variogram models (linear, power, spherical, gaussian, exponential) are built in, but custom variogram models can also be used. The 2D universal kriging code currently supports regional-linear, point-logarithmic, and external drift terms, while the 3D universal kriging code supports a regional-linear drift term in all three spatial dimensions. Both universal kriging classes also support generic 'specified' and 'functional' drift capabilities. With the 'specified' drift capability, the user may manually specify the values of the drift(s) at each data point and all grid points. With the 'functional' drift capability, the user may provide callable function(s) 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`).

PyKrige is on PyPi, so installation is as simple as typing the following into a command line.
See the `documentation <http://pykrige.readthedocs.io/en/latest/>`_ for more details.

Installation
^^^^^^^^^^^^

PyKrige requires Python 2.7 or 3.5+ as well as numpy, scipy and matplotlib. It can be installed from PyPi with,

.. code:: bash

pip install pykrige

To update PyKrige from PyPi, type the following into a command line.
scikit-learn is an optional dependency needed for parameter tuning and regression kriging.


If you use conda, PyKrige can be installed from the `conda-forge` channel with,

.. code:: bash

pip install --upgrade pykrige
Copy link
Contributor Author

@rth rth Mar 28, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pip prior to mid 2017 by default has an eager upgrade strategy pypa/pip@375ed4d that can break things in the existing packages pypa/pip#304 so I'd rather not put this in the readme.

conda install -c conda-forge pykrige

PyKrige uses the BSD 3-Clause License.

Ordinary Kriging Example
^^^^^^^^^^^^^^^^^^^^^^^^

First we will create a 2D dataset together with the associated x, y grids,

.. code:: python

from pykrige.ok import OrdinaryKriging
import numpy as np
import pykrige.kriging_tools as kt

Expand All @@ -54,126 +62,58 @@ Ordinary Kriging Example

gridx = np.arange(0.0, 5.5, 0.5)
gridy = np.arange(0.0, 5.5, 0.5)



Then we create the ordinary kriging object. The 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 verbosity, and
the ``enable_plotting`` kwarg controls the display of the semivariogram.


# 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.
.. code:: python

from pykrige.ok import OrdinaryKriging

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.)
Next, we will create the kriged grid and the variance grid. Kriging on a rectangular
grid of points, on a masked rectangular grid of points, or with arbitrary points is allowed,

.. code:: python

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
^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, we write the kriged grid to an ASCII grid file,

.. code:: python

from pykrige.uk import UniversalKriging
import numpy as np
kt.write_asc_grid(gridx, gridy, z, filename="output.asc")

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)
Other examples can be found in the `example gallery <http://pykrige.readthedocs.io/en/latest/examples/index.html>`_.

# 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
Parameter Tuning
^^^^^^^^^^^^^^^^

from pykrige.ok3d import OrdinaryKriging3D
from pykrige.uk3d import UniversalKriging3D
import numpy as np
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>`_ example for a more practical illustration.

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.


Kriging Parameters Tuning
^^^^^^^^^^^^^^^^^^^^^^^^^

PyKrige also exposes a scikit learn compatible API, which can be used to perform parameter tuning including the krige algorithm using `sklearn.model_selection.GridSearchCV <http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.GridSearchCV.html>`_. Once `scikit-learn` is installed, you can run the corresponding example with
`python path/to/examples/krige_cv.py`

In it's current form, the `pykrige.rk.Krige` class can be used to optimise all the common parameters of `OrdinaryKriging` and `UniversalKriging` classes.
In it's current form, the `pykrige.rk.Krige <http://pykrige.readthedocs.io/en/latest/generated/pykrige.rk.Krige.html#pykrige.rk.Krige>`_ class can be used to optimise all the common parameters of ``OrdinaryKriging`` and ``UniversalKriging``.


Regression Kriging
^^^^^^^^^^^^^^^^^^

PyKrige exposes a class `pykrige.rk.RegressionKriging` that can be used to perform `regression kriging <https://en.wikipedia.org/wiki/Regression-Kriging>`_. This class takes as parameters a `scikit-learn` regression model, and details of either the Ordinary/UniversalKriging class, and performs a correction steps on the ML regression prediction.
`Regression kriging <https://en.wikipedia.org/wiki/Regression-Kriging>`_ can be performed with `pykrige.rk.RegressionKriging <http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.GridSearchCV.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 `examples.regression_kriging.py`. Once again, `scikit-learn` is required to use this functionality.
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>`_.

License
^^^^^^^

PyKrige uses the BSD 3-Clause License.