Read Me

README file for the application of the expanded downscaling (EDS) method.


1. Sources and Installation

EDS runs on linux using the octave programming environemnt. EDS sources and
documentation can be obtained using the command `svn' (i.e. subversion) from the
following url:

svn co https://xds.svn.sourceforge.net/svnroot/xds

This creates a directory 'xds' and in it all relevant source files (extension
".m") and one configuration file ("xds.cfg") whose settings need to be adjusted
for the application (area) in question. Everything before and after the
simulation is beneath this directory node.

octave is an open source matlab clone (~95% compatible) that is part of any
major linux distribution. EDS requires at least version 3.4, which can be
obtained from www.octave.org. Various octave packages are required, as listed
under 6.



2. Configuration and Invocation

It is invoked by running

[var=...] octave [options] xds.m [config file]

where config file has the same format as and defaults to the provided 'xds.cfg'.
The main entries of this file are described in detail below.

The script 'xds.m' simply executes the four scripts

init.m:	   Initialization

ptr.m:	   Reading and processing of atmospheric (analyses/GCM) predictor fields

pdd.m:	   Reading and processing of the local predictand (station) variables.

cal.m:	   Calibration of the EDS matrix, mainly depending on the number of
	   retained atmospheric EOFs.

out.m:	   Downscaling of the atmospheric fields and output.



3. Data

All data are placed in a subdirectory whose name defaults to 'data' (and which
can be set using the variable 'TOP'), and are organized as follows. For a
particular project (area, watershed), 'oakbay' by way of example,

#########  xds.cfg  ###########
PRJ = "oakbay" ;
#########  xds.cfg  ###########

and a directory 'data/oakbay' is to be created.

3a. Local data

The local station data are put into several files V1.csv, V2.csv,... The names
Vi,... are defined in the metafile 'data/oakbay/meta.txt', whose format is as
follows:

id,var,varname,lon,lat,alt,undef
1018616,P,precip,-123.517,48.5167,191,-9999
1017101,P,precip,-123.05,48.7833,24,-9999
1018616,Tx,max temperature,-123.517,48.5167,191,-9999
1017101,Tx,max temperature,-123.05,48.7833,24,-9999
1018616,Tn,min temperature,-123.517,48.5167,191,-9999
1017101,Tn,min temperature,-123.05,48.7833,24,-9999
...

Note that from the entry 'varname' the specific normalization procedure is
chosen.

Accordingly, an input file Tx.csv is expected that should have the following
format:

Y,M,D,1018620,1017230
1997,6,28,0,9.6
1997,6,29,17,15.8
1997,6,30,0,1.6

3b. Atmospheric data

The atmospheric predictor fields must be contained in a path like this:

data/some/path/to/gcm, for example

data/ecmwf .............. analyses           = PAR.ana
data/gcm1/sresa2/run2 ... future simulation  = PAR.sim{1}
data/gcm1/20c3m/run1 .... present simulation = PAR.sim{2}
...

The corresponding files are the strings defined in PAR.ana for the analyses and
in the two-element cell PAR.sim for the simulations (simulation and reference
climate). They are netcdf files with variable names AVAR (analyses) and SVAR
(simulations) specified in 'xds.cfg'. Because the GCM fields are projected onto
the corresponding analysis variables, the corresponding variable names (e.g. 't'
and 'temp') of analysis and GCM fields must correspond exactly to one another,
such as

#########  xds.cfg  ###########
AVAR = {"temp_700" "temp_850" "hus_700" "hus_850" "div_700" "div_850" "pr"} ;
SVAR = {"t_700" "t_850" "q_700" "q_850" "sd_700" "sd_850" "precip"} ;
#########  xds.cfg  ###########

PAR.sim{2} refers to a GCM simulation for the reference climate (present),
relative to which anomalies are taken; it defaults to PAR.sim{1} if only one
element is given. It is important to run this simulation first (e.g. using
PAR.sim = "data/gcm1/20c3m/run1")



4. Configuration

EDS is calibrated using analysis fields and station data. For example, to select
for the predictor fields a latitude-longitude rectangle between 0 and 25E and
40N and 50N, and using the ecmwf analyses for calibration in the baseline period
1991 and 2000, the following entry is needed.

#########  xds.cfg  ###########
PAR.lon = [0 25] ; PAR.lat = [40 50] ;
PAR.ana = "ncep" ;
PAR.cper = [1961 1 1; 1990 12 31] ;
#########  xds.cfg  ###########

The calibration performance statistics of EDS grows steadily with the numberof
retained atmospheric EOFs, neof. To obtain the best possible value of neof, one
that verifies on independent data, we do an additional split of the calibration
period and systematically check EDS performance relative to neof, using the RE
statistic of simulated (areal) mean variables. A typical splitting is defined in
'xds.cfg' via

#########  xds.cfg  ###########
PAR.edscal = [1961 1 1; 1975 12 31] ;
PAR.edsval = [1976 1 1; 1990 12 31] ;
#########  xds.cfg  ###########


As EDS is an anomaly model, for each simulation a baseline period and a
corresponding baseline simulation needs to be specified. For example, the
anomalies of 'gcm1/sresa2/run2' are to be downscaled relative to the climate of
'gcm1/20c3m/run2', using the baseline period of 1961 to 1990. This setting would
be obtained from the 'xds.cfg' entries

#########  xds.cfg  ###########
PAR.sim = {"gcm1/sresa2/run2", "gcm1/20c3m/run2"} ;
PAR.cper = [1989 1 1; 2000 12 31] ;
#########  xds.cfg  ###########


5. Output

After executing the script 'xds.m' (or e.g. simply 'out.m') the downscaled data
are put in the directory

data/oakbay/ptr/gcm1/sresa2/run2/pdd

in the files P.csv, V1.csv, V2.csv,...



6. Octave packages

The following packages are required to run xds.m:

general
miscellaneous
nan
octcdf
optim
statistics
time

If not installed already (see `pkg list' in octave) a package "foo" can be
install using the command

pkg install -forge foo