This is the documentation for the area identification algorithm presented in
"A network-based method for the study of climate teleconnections". 

-----------------------------------------------------------------------------
The code is provided in java at was developed using NetBeans IDE 7.0.

---------------------------------------------------------------------------------------------------
Folders

src : Source .java files (documentation of the routines available in each .java file).
dist: Contains an executable .jar file.
mylib: see external libraries.
matlabScripts: Matlab scripts to produce the correlation file given a grid of detrended anomalies (also included).

-----------------------------------------------------------------------------
Example usage: java -Xmx#g -jar locationOfCorrelations.txt dimX dimY significance mode

locationOfCorrelations.txt: can be either a file having a path to the correlation files or the
correlation matrix. 

dimX : number of latitudes (e.g. a data set with a 2 latitudinal resolution will have 90 latitudes)

dimY : number of longitudes (e.g. a data set with a 2 longitudinal resolution will have 180 longitudes)

significance : The significance will determine the threshold tau of an area. The threshold tau is defined as
the average of all correlations significant for a given level alpha. Thus a significance value of 0.01 will
perdorm a t-test using that level

mode : 0 if the input are correlation files | 1 if the input is the correlation matrix

-----------------------------------------------------------------------------
Using as an input correlation files:

Correlation files have information about the pair wise correlations from a given
cell A to all other cells in a grid. The file id should correspond to a cells id 
(see a note on grid cells). In case that a correlation between two cells does not exist
(for example in the case that a grid cell has a land mask) then the correlation should be 
set > 1.0. 

Thus a correlation file for grid cell A (were A is a number, the id of the grid cell) will
have MxN lines (M by N being the dimensions of the input data set).

Producing correlation files: 

Locate the two Matlab scripts "exportCorrelations2.m" and "computeCorrelationsFromSST2.m" in the matlabScripts folder. 
Load the detrended anomaly file (hadsst_1979_2005_win_noTre.mat, located again in the matlabScripts folder)
using Matlab and execute the command exportCorrelations2(hadsst7905_winter_notrend); 

You should see the correlation files being generated at Matlab's directory. 

Identifying areas:

Cut and paste the correlation files in a new folder (let as assume that the folders name
is "hadlsst"). Create a .txt file, such as the one provided ("_correlFileLoc.txt") with the
location of the correlation files.

execute the java program as

java -Xmx#g -jar AreaIdentification.jar _correlFileLoc.txt 90 144 0.001 0

-----------------------------------------------------------------------------
Using as an input correlation a correlation matrix

An alternative to the correlation files is the usage of a correlation matrix.
A correlation matrix is just an adjacency matrix (an M*N by M*N array) showing
correlations from cell i to the rest (M*N-1) cells in the grid. Diagonal elements
must be values greater than 1 (correlation between a cell and it self should not
be counted as valid). Again in case that a correlation between two grid cells 
does not exist it should be a value greater than 1.

Given a correlation matrix (say correl_matrix.txt) execute the java program as

java -Xmx#g AreaIdentification.jar correl_matrix.txt 90 144 0.001 1

-----------------------------------------------------------------------------
External libraries

We use the java distribution functions (http://statdistlib.sourceforge.net/).
The latter is also included in the mylib folder.

-----------------------------------------------------------------------------
A note on the ids of grid cells:

It is obvious that each grid cell has a unique id. Given a M by N grid each cell will have an id according to
the following rule

1	2	...	...	N
N+1	N+2	...	...	2N
...	...	...	...	...
...	...	...	...	...
...	...	...	...	...
...	...	...	...	...
(M-1)N+1...	...	..,	MN