The GLOBEC Kriging Software Package - EasyKrig2.0, January 10, 2000

Copyright (c) 2000, property of Dezhang Chu and Woods Hole Oceanographic Institution. All Rights Reserved.

The kriging software described in this document was developed by Dezhang Chu with funding from the National Science Foundation through the U.S. GLOBEC Georges Bank Project's Program Service and Data Management Office. It was inspired by a MATLAB toolbox developed by Yves Gratton and Caroline Lafleur (INRS-Océanologie, Rimouski, Qc, Canada), and Jeff Runge (Institut Maurice-Lamontagne). This software may be reproduced for noncommercial purposes only.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. Contact Dr. Chu at dchu@whoi.edu with enhancements or suggestions for changes.

For a Czech translation of the documentation for the Version 2.1 of the program, click here (Translation by Barbora Lebedová).
For a Romanian translation of the documentation for Version 2.1 of the program, click here. (Translation by Paula-Maria Niculescu).

Table of Contents:
1. Introduction
1.1 General Information
1.1.1 Operating systems
1.1.2 Brief descriptions
1.2 Getting started
1.2.1 Down-load the program
1.2.2 Quick start
2. Data Processing Stages
2.1 Data preparation
2.2 Semi-variogram
2.3 Kriging
2.4 Visualization
2.5 Saving results
3. Examples
4. References
1. Introduction
1.1 General Information
1.1.1 Operating systems

The software was originally developed under Matlab 5.2 on a PC and intended to be computer and/or operating system platform independent. The program has been tested on varies machines and performs fine. The following table shows the tested machines/OS:

* Windows98 needs to get the patch from Mathworks to fix graphical user interface (GUI) related bugs, see instructions from Mathworks web site: http://www.mathworks.com/support/solutions/v5/20744.shtml

1.1.2 Brief description

The program uses a graphical user interface (GUI) to simplify the operation. It requires Matlab 5.2 or higher with or without optimization toolbox (see section 2.2) and consists of five components, or processing stages: (1) data preparation, (2) variogram computation, (3) kriging, (4) visualization and (5) saving results. It allows the user to process anisotropic data, select a list of variogram models, and a choice of kriging methods, which are also common features of the other existing software packages. One of the major advantages of this program package is that the program minimizes the users' requirements to "guess" the initial parameters and automatically generates the required default parameters. In addition, because it uses a GUI, the modifications from the initial parameter settings can be easily performed. Another feature of this program package is that it has a built-in on-line help library that allows the user to understand the use of parameter and operation buttons by just a simple click.

Although this software package lacks some abilities such as 3D- and Co-kriging, it does provide a convenient tool for geostatistical applications and should also help scientists from other fields.

1.2 Getting Started

1.2.1 Down-load the program

You can

• download the compressed file from GLOBEC web site;
ftp://globec.whoi.edu/pub/software/kriging/easy_krig/V2.0/
Windows 95/98/NT: easy_krig2.zip
LINUX: easy_krig2.zip
UNIX(LINUX): easy_krig2.tar.Z
Macintosh: easy_krig2.sea.hqx**

and then run

unzip for Windows (95/98/NT), and Linux
uncompress + untar for UNIX-based machine (including Linux)
unstuff for Macintosh (or equivalent software)

to uncompress the file. After uncompressing the file, you are ready to start and run the program.

or

• obtain the original uncompressed files (and sub-directories) directly:
  ftp://globec.whoi.edu/pub/software/kriging/easy_krig/V2.0/easy_krig2.0/

  (using binary mode for UNIX, automatic for Macintosh)

  ** requires Stuffit Expander software to unstuff the compressed file. If you don't have it, you can get it free from the Internet: http://www.aladdinsys.com/downloads/index.html

1.2.2 Quick start

Start MATLAB and go to the designated easy_krig2.0 home directory. Just type 'startkrig' in the MATLAB command window, a window will pop up. This window is the base window, called the Navigator window. The menu bar in this window contains many options you can choose. Now you are ready to move on.

Note: You can add the kriging home directory and run the program from other directories. However, you have to make sure that there are no functions of your own having the same name as those used for easy_krig2.0. Since the program will allow you to load and save files using a file browser, it is recommended that you run the program under the easy_krig2.0 home directory.

The program provides many on-line help buttons; the use of almost all of the selectable functions and parameters can be found by clicking on these help buttons (small buttons each with a question mark '?' on it). It is quite self-explanatory and easy to use.

2. Data Processing Stages

There are several data processing stages (tasks) that are selectable from the menu bar on the top of the main Navigator window. By selecting or clicking on any of the tasks, a window corresponding to the task will pop up. On each task window, small buttons marked with a question mark '?' provide the on-line help. By clicking on the button, a small window will pop up and provide the information about the use of the parameter or operation button. On any window, clicking on the 'Navigator' button, or selecting 'Navigator' from the menu bar and then 'Open' from the pull down sub menu will activate the navigator window.

2.1 Data preparation

Selecting 'Load Data' from the menu bar of any window and then 'Open' from the sub-menu leads to the data preparation window. Click on the 'Load' button to load the raw data file. The format of the data file should be a 3-column ASCII file. User(s) can provide their own m-file to load the data. This function allows the user to generate the input data directly from the raw data instead of generating an ASCII file. The required format for the input and output parameters can be found by clicking on the small square button marked with a '?' mark next to the 'Browse' button associated with the 'External Program' option. One can set the other parameters before loading the file. After the file is loaded, if the user wants to change the other settings, such as data filter, click on 'Apply' after the parameters have been set. The difference between 'Load' and 'Apply' is that the later will not re-load the data file. To change the 'xlabel' or 'ylabel' after having loaded the data, one needs to re-load the data.

2.2 Semi-variogram

Selecting 'Variogram' from the menu bar and then 'Open' from the sub-menu leads to a popup variogram window. First, click on the 'Compute' button to generate a data-based semi-variogram (or correlogram). Then, seek a model-based semi-variogram (or correlogram) to fit the computed variogram. The relation between the semi-variogram g(h) and the correlogram C(h) is:

C(h) = 1 - g(h),

where h is the lag distance. An appropriate variogram (correlogram) model can be selected depending on the shape of the variogram (correlogram) computed from the data. The explanations of the parameters associated with the model can be found using the on-line help button ('?' button). Click on the 'Apply' button, the program will compute the model-based variogram/correlogram using the current settings. The parameter settings can be changed either by changing the slider position or by entering the number directly into the text edit window. If using the slider, the theoretical curve will change automatically, while if entering the number into the text edit window, the user needs to click on the 'Apply' button to re-compute the curve.

If the optimization toolbox (recommended) is installed, the user can use the Least-Squares fit function to fit the data by clicking on the 'LSQ fit' button. If the optimization toolbox isn't installed, the program will automatically disable the Least-Square fit function.

Note that since the LSQ fit has a certain range for each parameter, different initial settings (parameters) will produce different results.

In some cases when the data are anisotropic, an anisotropic variogram (correlogram) model can be activated. By clicking on 'enable 2D-variogram' button, the corresponding settings are enabled. If you don't know or not sure of the orientation and aspect ratio of the anisotropic feature of the data, you can use the default settings first and then adjust to obtain satisfactory results.

2.3 Kriging

Selecting 'Kriging' from the menu bar and then 'Open' from the sub-menu opens the kriging window. The parameters of the variogram (or correlogram) needed in the kriging operation are automatically passed from variogram window to kriging window, but can be changed from the kriging window. Click on the 'Refresh' button to obtained the most recent semi-variogram parameters and click on the 'Krig' button to start the kriging. There are two passes of kriging; the first one is used in producing the kriging map and the second one is used to perform a cross validation of the kriging model.

2.4 Visualization (Display)

Choosing 'Display' from the menu bar and then 'Open' from the sub-menu leads to the visualization window. There are three figures in this window: kriging map (upper left), kriging-variance map (upper right) and cross-validation (lower left). The first two maps are commonly used in the kriging literature while the last one is a unique approach of this program.

Click on the 'Show Plot' button to display the current kriging results and on 'Load' to load previously saved results (.mat file). You can also load the file by selecting 'File' from the menu bar and selecting 'Load Data'.

If the data have been transformed in the data preparation window, you can choose either transformed (default) or un-transformed results.

By choosing the single plot option, a window containing only the selected figure will pop up.

2.5 Saving results

Selecting 'File' from the menu bar and then choosing 'Save Data' to save the output as a .mat file with a user-defined filename and at the user selected location. The program saves the parameters and data structures (para and data) in the file. For information on the structures, the user needs to Select 'File' from the menu bar and then 'Variable Structure' to obtain explanations for all variables (note that many variables are not important to users).

3. Examples

There are some sample data files included in the package. All files are in ASCII format which is required by the program. In the following two examples, the designated krig directory is assumed to be 'easy_krig2.0'.

Example 1: An Aerial Image of Zooplankton Abundance Data

1. Start MATLAB; in the MATLAB command window, change directory to the home directory of EasyKrig2.0. Type 'startkrig' to launch the program.
2. Adjust the window size and position and select 'Save Window Position' option from the menu bar and then 'Save Position' from the sub-menu. Click on the 'Instruction' button to load this document into the MATLAB Editor.
3. Select 'Load Data' from the menu bar and then 'Open' from the sub-menu to bring up the data preparation window.
4. Select 'LATITUDE' from listbox of DataFile Col. 1 (default).
5. Select 'LONGITUDE' from listbox of DataFile Col. 2 (default).
6. Leave other parameters unchanged.
7. Click on the 'Load' button to bring up a file browser window, select 'data' directory, and then select 'zooplankton.dat' file in the 'data' directory to load the selected file into memory.

(4) Select 'Variogram' from the menu bar and then 'Open' from the sub-menu to bring up the variogram window.

1. Click on the 'Compute' button to compute the semi-variogram (correlogram). This plots the semi-variogram (correlogram) as discrete open circles.
2. Select 'General exponential-Bessel' (default) from the variogram model listbox on the upper right. Click on the 'LSQ Fit' button. If you don't have optimization toolbox, click on the 'Apply' button, a theoretical model-based semi-variogram will be superimposed on the original data-based semi-variogram. The parameters from the least-square fit (if you have optimization toolbox) or from the default settings (if you don't have optimization toolbox) are shown in the text edit windows.
3. Clicking on the sliders associated with the variogram parameters, the theoretical curves will change accordingly to reflect the parameter changes. The parameters also can be changed by entering the values directly into the text edit windows and clicking on the 'Apply' button.
4. Type 0 in the 'nugget' text edit window, 1.0 in the 'sill' text edit window, 0.14 in the 'length' text edit window, 1.5 in the 'power' window, and 0 in the 'hole scl' (hole scale) text edit window. Then, click on the 'Apply' button. A revised theoretical curve of the model-based semi-variogram will be plotted.

(5) Select 'Kriging' from the menu bar and then 'Open' from the sub-menu to bring up the kriging window.

(a) Simply click on the 'Krig' button to start kriging by accepting the default settings. A status window pops up and displays the processing progress. When the kriging is done, click on the 'Quit' button to close the status window.

(6) Select 'Display' from the menu bar and then 'Open' from the sub-menu to bring up the visualization window.

1. Simply click on the 'Show Plot' button to display the kriging results. Note that the station positions on the kriging map are color-coded to reflect the level of the agreement of the kriged results with the original data. The cross-validation figure (lower left) uses the double-kriging method (default).
2. Click on 'Track Line' from the menu bar and then select between 'Color', 'Black/White' and 'None' to observe the color change of the locations of the original data. Selecting 'Value' or 'Error', and specify the 'Color' and 'Fontsize' allows the user to display the observed values or the difference between the observed values and those from kriging.
3. Select 'Q1' from the cross-validation list box and wait until the computation is done. A vertical red line at about 0.07 in between the two black lines at about 0.5 and -0.5 indicates the model parameters are good based on Q1 criterion.
4. Select 'Q2' from the cross-validation list box results in another plot. A vertical red line is located within the accept region at about 0.78, which means the model parameters are likely 'good'.

(7) Select 'File' from the menu bar and then select 'Save Data' to bring up the file browser window.

1. Select 'output' directory and any name you like (the default filename is cal83sal.mat) and click on the 'Save' button.
2. Click on 'Quit' from the menu bar and then 'Quit Easykrig' from the sub-menu to quit the program. Restart the program again by typing 'startkrig' in the MATLAB command window. Click on the 'Display' button and then 'Open' from the sub-menu to bring up the visualization window, and click on the 'Load' button to load the output file that has just been saved by using the file browser.
3. Click on the 'Show Plot' button to display the kriging results, which should be the same as before.

Example 2: A Vertical Section of Salinity Data

1. Start MATLAB; in the MATLAB command window, change directory to the home directory of EasyKrig2.0. Type 'startkrig' to launch the program.
2. Select 'Load Data' from the menu bar and then 'Open' from the sub-menu to bring up the data preparation window.
3. Select 'X' from listbox of DataFile Col. 1.
4. Select 'Depth' from listbox of DataFile Col. 2.
5. Leave other parameters unchanged.
6. Click on the 'Load' button to bring up a file browser window, select 'data' directory, and then select 'salinity.dat' file in the 'data' directory to load the selected file into memory.
7. Select 'Variogram' from the menu bar and then 'Open' from the sub-menu to bring up the variogram window.
8. Click on the 'Compute' button to compute the semi-variogram (correlogram). This plots the semi-variogram (correlogram) as discrete open circles.
9. Select 'Linear' from the variogram model listbox on the upper right. Click on the 'LSQ Fit' button [If you don't have optimization toolbox, go to step (c).] A theoretical model-based semi-variogram (a straight line in this case) will be superimposed on the original data-based semi-variogram.
10. Type 0 in the 'nugget' parameter edit window, and type 1.7 in the 'sill' parameter edit window, and then click on the 'Apply' button. A revised theoretical curve of the model-based semi-variogram will be plotted.

(4) Select 'Kriging' from the menu bar and then 'Open' from the sub-menu to bring up the kriging window.

(5) Select 'Display' from the menu bar and then 'Open' from the sub-menu to bring up the visualization window.

1. Simply click on the 'Show Plot' button to display the kriging results. Note that the ship track on kriging map is color-coded to reflect the level of the agreement of the kriged results with the original data. The cross-validation figure (lower left) uses the double-kriging method (default).
2. Select 'Q1' from the cross-validation list box and wait until the computation is done. A vertical red line in between the two black lines at about 0.1 and -0.1 indicates the model parameters are good based on Q1 criterion.
3. Select 'Q2' from the cross-validation list box results in another plot. A vertical red line is located beyond the accept region at about 0.22, which means the model parameters are likely not 'good' and further modifications to the parameters are needed.

(6) Select 'Variogram' from the menu bar and then 'Open' from the sub-menu to bring back the variogram window.

1. Select 'enable 2D-variogram' to enable 2D variogram that allows 2D anisotropy.
2. Click on the 'computing' button to compute and display the 2D variogram (image).
3. Since the variogram image shows an elongated pattern having an aspect ratio about 1:4 and an orientation angle about 5 degree, we enter 0.25 in the ratio edit window and 5 in the angle edit window, and then click on the 'computing' button again. A recomputed 2-D semi-variogram shows basically an isotropic pattern.
4. Click on the 'Compute' button on the right again to re-compute the 1D semi-variogram from the data using the auotmatically saved anisotropic parameters obtained in (c).
5. Select variogram model 'General exponential-Bessel' (model 13).
6. Enter 0.6 in the range edit window and click on the 'LSQ fit' button. If you don't have optimization toolbox, set 'sill' to 0.46, 'length' to 0.34, 'power' to 1.76 and 'hole scl' to 0.
7. Change 'nugget' to about 0.0165 by entering the number in the edit window and then click on 'Apply'. Adjust display scale by clicking on the two sliders below the 1-D semi-variogram graphic window, lag for horizontal scale and value for vertical scale.

(7) Select 'Kriging' from the menu bar and then 'Open' from the sub-menu to bring back the kriging window and click on the 'Krig' button to re-compute the kriging map.

(8) Select 'Display' from the menu bar to bring back the visualization window.

1. Click on 'Show Plot' to refresh the maps.
2. As in (5), select 'Q1' and 'Q2' again, we find that both Q1 and Q2 are now within the acceptable regions. Note that by using an anisotropic model, some improvements can be achieved, but the kriging map itself doesn't change much.

(9) Select 'File' from the menu bar and then select 'Save Data' to bring up the file browser window.

1. Select 'output' directory and any name you like (the default filename is cal83sal.mat) and click on the 'Save' button.
2. Click on 'Quit' from the menu bar and then 'Quit Easykrig' from the sub-menu to quit the program. Restart the program again by typing 'startkrig' in the MATLAB command window. Click on the 'Display' button and then 'Open' from the sub-menu to bring up the visualization window, and click on the 'Load' button to load the output file that has just been saved by using the file browser.
3. Click on the 'Show Plot' button to display the kriging results, which should be the same as before.

4. References.

Deutsch, C. V and A. G. Journel, 1992. GSLIB: Geostatistical Software Library and User's Guide. Oxford University Press, Oxford, 340 p.

Journel, A.G. & C.J. Huijbregts, 1992. Mining Geostatistics. Academic Press, New York, 600 p.

Kitanidi, P.K. 1997. Introduction to Geostatistics. Applications in hydrogeology. Cambridge University Press. 249 p.

Marcotte, D. 1991. Cokriging with MATLAB. Computers & Geosciences. 17(9):1265-1280.