The GLOBEC Kriging Software Package

The GLOBEC Kriging Software Package - EasyKrig2.1, May 1, 2000

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 Romanian translation of this document (program Version 2.1), 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 various machines and performs fine. [The current version of easyKrig software is not compatible with Matlab 6. A version that is compatible will be available soon. 10/23/03] The following table shows the tested machines/OS:

Computer OS

----------------------------------------------------------------------------------------------

PC-compatible Windows 95/NT, Windows 98*

PC Linux (Red Hat 5.2)

SUN UNIX (Solaris)

SGI UNIX (Irix)

Macintosh OS 8.6

----------------------------------------------------------------------------------------------

* Windows98 needs to get the patch from Mathworks to fix the graphical user interface (GUI) related bugs, see instructions from Mathworks web site:

http://www.mathworks.com/

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

(a) download the compressed file from GLOBEC web site;

ftp://globec.whoi.ed/pub/software/kriging/easy_krig/V2.1/

Windows 95/98/NT: easy_krig21.zip

LINUX: easy_krig21.zip

UNIX(LINUX): easy_krig21.tar.Z

Macintosh: easy_krig21mac.zip**

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.

(b) obtain the original uncompressed files (and sub-directories) directly:

ftp://globec.whoi.edu/pub/software/kriging/easy_krig/V2.1/easy_krig2.1/

(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.1 home directory (for Macintosh users, you may need to increase your allocated memory to at least 48MB). 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.1. 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.1 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 (disabled by default) 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 latter will not re-load the data file. For example, 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 γ(h) and the correlogram C(h) is:

C(h) = 1 - γ(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 and 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 are 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.1'.

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.1. 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.

(a) Select 'LATITUDE' from listbox of DataFile Col. 1 (default).

(b) Select 'LONGITUDE' from listbox of DataFile Col. 2 (default).

(d) 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.

(a) Click on the 'Compute' button to compute the semi-variogram (correlogram). This plots the semi-variogram (correlogram) as discrete open circles.

(b) 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 resultant semi-variogram 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 within the 'Model Parameters' frame.

(c) 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.

(d) 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.

(a) 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).

(b) 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 specifying the 'Color' and 'Fontsize' allows the user to display the observed values or the difference between the observed values and those from kriging.

(c) Type 1.0 in the 'Display Threshold' text window and click on the 'Show Plot' button. There are blank regions on the kriging map, where the normalized kriging variance (normalized by the variance) exceeds specified 'Display Threshold' 1.0. Change this number to another value to see how the kriging map changes. The maximum 'Display Threshold' is defined as 'Relative Error' in the kriging window (default value is 1.5).

(d) 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.

(e) 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.

(a) Select 'output' directory and any name you like (the default filename is cal83sal.mat) and click on the 'Save' button.

(b) 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.

(8) Select 'Navigator' from the menu bar and then 'Open' from the sub-menu to bring up the navigator window.

(a) Select 'About' from the menu bar and then 'Variable Structure' from the sub-menu to open the data structure description file.

(b) Follow the instruction and try to load and plot the output variables yourself.

Example 2: A Vertical Section of Salinity Data

(1) Start MATLAB; in the MATLAB command window, change directory to the home directory of EasyKrig2.1. 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.

(a) Select 'X' from listbox of DataFile Col. 1.

(b) Select 'Depth' from listbox of DataFile Col. 2.

(d) 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.

(e) Select 'y-axis reverse' to reverse the y axis.

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

(a) Click on the 'Compute' button to compute the semi-variogram (correlogram). This plots the semi-variogram (correlogram) as discrete open circles.

(b) 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.

(c) 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.

(a) Simply click on the 'Krig' button to start kriging by accepting the default settings.

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

(a) 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).

(b) Select 'y-axis reverse' to reverse the y axis.

(c) 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.

(d) 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.

(a) Select 'enable 2D-variogram' to enable 2D variogram that allows 2D anisotropy.

(b) Click on the 'computing' button within the 'enable 2-D variogram' box to compute and display the 2D variogram (image).

(c) 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 'Aspect 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.

(d) Click on the 'Compute' button on the right again to re-compute the 1D semi-variogram from the data using the automatically saved anisotropic parameters obtained in (c). This step is necessary to obtain the correct semi-variogram.

(e) Adjust display control by clicking on the two sliders ('Lag' and 'Value') below the graphic window.

(f) Select variogram model 'General exponential-Bessel' (model 13).

(g) 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.

(h) 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.

(a) Click on 'Show Plot' to refresh the maps.

(b) 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.

(a) Select 'output' directory and any name you like (the default filename is cal83sal.mat) and click on the 'Save' button.

Example 3: Batch Process of Potential Density at Different Depth

(1) Start MATLAB; in the MATLAB command window, change directory to the home directory of EasyKrig. 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.

(a) Select 'LATITUDE' from listbox of DataFile Col. 1 (default).

(b) Select 'LONGITUDE' from listbox of DataFile Col. 2 (default).

(d) Click on the file broswer, change directory to extern_program and select 'remove_nan.m', and then click 'open' enabling the program to access the program (If this external program is not chosen, the locations where the data values are NaN's will be displayed on the map). This program provides an example to write your own routine to obtain the required data format for EasyKirg from an arbitrary data file.

(e) Leave other parameters unchanged.

(f) Click on the 'Load' button to bring up a file browser window, select 'data/pdensity' directory, and then select 'layer12.dat' file in the directory to load the selected file into memory.

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

(a) Click on the 'Compute' button to compute the semi-variogram (correlogram). This plots the semi variogram (correlogram) as discrete open circles.

(b) 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 within the 'Model Parameters' frame.

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

(a) Set coordinates as:

minimum horizontal to -22

maximum horizontal to -12

horizontal resolution to 0.4

minimum vertical to -25

maximum vertical to -20

vertical resolution to 0.2

(b) Select 'Batch Processing' (radio button) to enable the batch processing.

(c) Click on the 'Browse' button next to the 'Load Filename-list file' to initiate the file browser. Change the directory to 'data' and select 'batch_file.dat' to load the filename-list file in which a list of data file names is specified.

(d) Click on the 'Browse' button next to the 'Save batch log file' to initiate the file browser. Change the directory to 'output', or wherever you want. Type a file name for the log file, where the input/output information is saved.

(e) Click on the 'Batch Krig' button to start batch kriging. The output files will be saved in the same directory as the batch process log file.

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

(a) Click on the 'Show Plot' button to display the kriging results from the last data set: 'layer14'.

(b) Check the output for the other layers. To check the processing results, you need to load the output files. Click on the 'Load' button and then change the directory where your log file is saved. Load one of the output files ('layer10.dat'-'layer14.dat') and display it by click on the 'Show Plot' button.

(c) If you are not satisfied with the kriging results, you can go back to the 'Variogram' window and/or 'Kriging' window to change the the involved parameters, and re-kriging until you are satisfied. For example, by setting nugget=0.05, sill=1.16, length=.253, power=1.5, and hole scl=0 in the variogram window and performing kriging again, you will obtain a better result, i.e., the resultant Q1 and Q2 will fall within the acceptable regions.

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.