WeathGen 2.6.1

         A Stochastic Weather Generator for Climate Change Studies


                                D. Gyalistras

                       E-mail: gyalistras@env.ethz.ch
                       URL: http://www.climate-impacts.ch

                           Last updated 03-Feb-2005.

   5.  USAGE 



 WeathGen is a flexible, user-friendly computer program that analyzes 
 weather data from one location and uses the results of the analyses to 
 simulate for this location an arbitrary number of weather sequences with  
 a daily or hourly time step.

 In contrast to most existing local weather generators (e.g., Richardson 
 1981; Wilks 1992) WeathGen does not only depend on a series of long-term 
 climate parameters, but it is driven by time series of monthly (or daily) 
 weather variables.  These driving inputs are used together with location- 
 specific climate parameters to generate an arbitrary number of realiza- 
 tions of possible daily (or hourly) weather courses for the respective 
 months (or days).
 WeathGen has been specifically designed for use in climate change impact 
   - WeathGen allows to simulate weather sequences for individual months, 
     such that it can be used to test in as far an impact model can be 
     driven only with monthly rather than daily (or hourly) weather inputs;
   - A large number of input variables and parameters can be easily adjusted
     in order to generate weather sequences with new statistical properties as 
     specified in a given climate change scenario;
   - WeathGen can be easily run in a batch mode according to directives 
     found in a simple control file, and is thus particularly suitable for 
     comprehensive sensitivity analyses with impact models.
 WeathGen runs on Macintosh personal computers and on Sun workstations.

 If you are interested to obtain WeathGen, please contact
   Dr. Dimitrios Gyalistras                     
   Climatology and Meteorology               
   Institute of Geography, Univ. of Berne    
   Hallerstr. 12, 3012 Berne/SWITZERLAND     

   Phone:  +41 (0)31 631 88 80
   Fax:    +41 (0)31 631 85 11
   E-mail: gyalistras@giub.unibe.ch
   URL:    www.giub.unibe.ch/~gyalistr

 Hard- and software requirements:
     * at least 2 MB of free RAM
     * at least 13 MB of free disk space
     * Mathematical co-processor present
     * MacOS >= 6.0 

 The WeathGen release for Macintosh personal computers is packed in a 
 single file named "WeathGenXY.sea", where "XY" stands for the program 
 version, and "sea" for self extracting application.
 In order to install WeathGen just double-click the "sea" file.  The 
 application will first ask you for a target folder, and then it will 
 uncompress and unpack its content.
 Hard- and software requirements:
     * at least 4 MB of free RAM
     * at least 13 MB of free disk space
     * WeathGen has been developed under SunOS2 (v4.1.4).  
       It has not been tested under the Solaris-OS.

 The WeathGen release for Sun workstations is packed in a single file named 
 "WeathGen261.tar", where "261" stands for the program version (2.6.1), and
 "tar" for the "tar" UNIX archiving utility.
 Installation of the release requires the following two steps:

 (1)  Extract the entire release from the archive file by typing
          tar   vfx   WeathGen261.tar   WG261
 (2) Uncompress various compressed (extension ".Z") files by typing
          uncompress  WG261/*/*.Z
   You can view the contents of the tar-file by typing:
          tar   vft    WeathGen261.tar
   In order to extract an individual file or sub-directory from the release
          tar   vfx   WeathGen261.tar   WG261/file_or_directory_name


 The WeathGen release comes with extensive reference output that exemplifies
 all supported tasks.  The files containing the reference output are 
 located in the sub-directories "TEST_REF_OUT_1" to "TEST_REF_OUT_3".
 The reference output has been generated according to program directives 
 specified in the file "WG.CTRL.ClcRefOutput".  The input data files which 
 are neded to generate the reference output (and which are referenced in 
 "WG.CTRL.ClcRefOutput") are located in the sub-directory "TEST_IN".

 The contents of the various reference input and output files should be 
 In order to reproduce the reference output proceed as follows: 
     (1)  Change to the directory WG261:
     (2)  Copy the file "WG.CTRL.ClcRefOutput" to "WG.CTRL";
     (3)  Run WeathGen. 

     These three steps can be accomplished with the following UNIX commands:
     cd WG261
     cp WG.CTRL.ClcRefOutput WG.CTRL

 The program will write a series of result files to the directories "TST_1" 
 to "TST_3".  The test output will require additional ca. 8 MB of disk 
 space.  Its calculation will take ca. 25 min. on a Sun-SPARC 4m workstation,
 and ca. 5 min on a Sun-ULTRA 1E/167 workstation.
 If everything went all right, the newly generated output files should have 
 exactly the same names and contents as the files in the directories 

   Do not bother about a file named "RASS.NYI", which may be produced when 
   WeathGen is run.
   On a Sun the two sets of files can be easily compared using the 
   following sequence of standard UNIX-commands:

      diff  -s  TEST_REF_OUT_1  TST_1  >  diff.out.1
      diff  -s  TEST_REF_OUT_2  TST_2  >  diff.out.2
      diff  -s  TEST_REF_OUT_3  TST_3  >  diff.out.3
   The results of the comparisons can be found in the files "diff.out.*". 


 WeathGen (v2.4) processes hourly to monthly weather data related to:
   1.  Temperature       (T)  
   2.  Precipitation     (P)  
   3.  Global Radiation  (GR) 
   4.  Vapour Pressure   (VP)  
   5.  Wind Speed        (WS).
 The program always requires (and produces) data for all five above vari- 
 ables.  In order to determine the parameters needed for weather simulation 
 typically a few years of daily and/or hourly data will be sufficient.
 In order to help reducing the input requirements, WeathGen supports 
 interpolation between daily data sets, as well as the estimation of global 
 radiation from daily measurements of the sunshine duration (see below).
 A description of the mathematical model implemented in WeathGen, of  
 the procedures used for parameter estimation, and of the properties of 
 WeathGen can be found in Gyalistras et al. (1997) and Gyalistras & 
 Fischlin (1999).
 Below follows a summary of the main tasks performed by WeathGen.
 WeathGen performs various statistical analyses on hourly and daily weather 
 data.  The results of the analyses are stratified by hour, by month, by 
 the occurrence or absence of precipitation, and/or by year.  The analyses 
   - standard statistics (mean, standard deviation, median, 
     skewness, extrema, 90%-quantiles, histograms);

   - detection and fitting of functions to describe the long-term  
     average daily cycles of T, GR, VP, and WS;

   - gamma distribution parameters for P and WS;
   - transition probabilities for changes between dry and wet hours
     or days; 

   - lag-zero and lag-one covariance matrices of hourly and daily
     T, GR, VP, and WS variables.  

 WeathGen supports the preparation of all input variables required for 
 simulation, i.e. it allows to extract
   - daily weather variables from hourly data;

   - monthly weather variables from daily data.
 Further, WeathGen estimates for each calendar month and writes to file the 
 simulation parameters needed to simulate hourly weather variables, i.e. the
   - lag-zero and lag-one covariance matrices of hourly mean T, GR, VP,  
     and WS;

   - long-term transition probabilities between hours with and without P;
   - long-term gamma distribution parameters of hourly P;

   - long-term standard deviations of hourly mean T, GR, VP, and WS   
     stratified by P-status (wet/dry hours);

   - parameters that specify the general shape of the daily cycles of  
     hourly mean T, GR, VP, and WS;

   - parameters to predict the daily cycles of hourly mean T, GR, VP, and 
     WS as a function of these variables' daily mean, minima and maxima;

 Finally, WeathGen determines for each calendar month all parameters needed 
 to simulate daily weather variables, i.e. the
   - lag-zero and lag-one covariance matrices of daily variables related to
     T, GR, VP, and WS;

   - information on the long-term distributions of these variables (normal,
     or positively or negatively skewed log-normal);

   - parameters to predict the transition probabilities between dry and 
     wet days as a function of the monthly probability for a wet day;

   - parameters to predict the distribution parameters of daily P as a func- 
     tion of the monthly total P and the monthly probability of a wet day; 

   - parameters to predict the monthly dry- and wet-day means and variances of 
     daily T, GR, VP, and WS variables as a function of the variables' means
     and variances for all days in a month.

 WeathGen can be used to make the transition from monthly to daily, or 
 from daily to hourly weather.
 The transition from monthly to daily weather requires as input 22 
 variables with a monthly time step, plus a series of time-invariant 
 parameters (see previous section).  As output are obtained an arbitrary 
 number of realizations for 11 daily weather variables.
 The 22 input variables are:  (1) probability for a wet day,  (2) monthly 
 total P,  (3-22) monthly means and within-month standard deviations of 
 daily mean GR, and of daily mean, minimum and maximum T, P, and WS.  
 The 11 daily output variables are: daily total P, daily mean GR, and daily 
 mean, minimum and maximum T, VP, and WS.
 For the transition from daily to hourly weather WeathGen requires as input 
 11 daily variables, plus a series of time-invariant parameters (see above).
 As output it produces an arbitrary number of realizations for 5 hourly
 weather variables.
 The 11 daily input variables correspond to the outputs from the simulation 
 of daily weather.  The 5 hourly outputs are:  hourly total P, and hourly  
 mean T, GR, VP, and WS.

 Consistency checks:
   WeathGen checks the range and mututal consistency of hourly weather data
   and replaces inconsistent and/or missing values based on measurements 
   from adjacent hours.
 Interpolation between daily data sets:
   WeathGen determines and applies linear regressions to estimate daily 
   total P, daily mean GR, and daily mean, minimum and maximum T, VP, and 
   WS from independent measurements (as e.g. available from a neighbouring 
   climate station).

 5.  USAGE

 WeathGen can only be run in a batch mode, i.e., once the program has been 
 started, no further interaction with the user is required or possible.  
 All tasks to be executed by WeathGen are specified in textual form in a 
 so-called "control file" which must have the name "WG.CTRL".  The control 
 file must be located in the same directory as WeathGen.

 Accordingly, the usage of WeathGen consists of the following two steps: 
 (1) Preparation  of the control file and all further input files; 
 (2) Execution of the program.
 On a Macintosh WeathGen is started by double-clicking it's icon.  On a Sun 
 type "WeathGen", followed by a carriage return.
 The program can be halted on a Macintosh by means of a software- or a 
 hardware-interrupt (see your computer's reference manual for how to do 
 this).  On a Sun, program execution is halted by pressing simultaneously 
 the keys "control" and "C".

 WeathGen reads all required inputs from text (ASCII) files.  It writes 
 outputs to a terminal window (Mac), respectively to the standard output 
 (Sun), and to a series of text (ASCII) files.
 WeathGen keeps the user always informed about the task and the calcula- 
 tions currently performed by writing brief messages to the terminal/ 
 standard output.  Messages which report reading of an input file are 
 always introduced by a "-", messages which report the writing of an output 
 file by a "+" at the beginning of a new line.
 If an error occurs, WeathGen stops, and a concise error message is written 
 to the standard ouput. 
 All files generated by WeathGen can be viewed from within a standard text 
 editor.  All rows and columns in outputs from statistical analyses, and 
 all outputed variables and simulation parameters are described in the 
 respective files by means of corresponding keywords and/or identifiers.  
 Data and keywords are separated by means of tabulators, such that the file
 contents can easily be transferred to a table calculator, or to other 
 data analysis programs.
 Note that all simulated weather ouptputs can be directly fed again into, 
 respectively re-analyzed with WeathGen.
 The syntax of the control file and of the hourly input (data) files are 
 explained below.  The syntax and contents of all other input and output 
 files should be self-explanatory.  (See also the reference input and output 
 files).  Some general rules apply:
   - Input data must always be characterized by the appropriate keywords or 
     identifiers in column headers or at the beginning of a row.

   - Input files may contain an arbitrary number of comments.  A comment  
     starts with "(*" and stops with "*)".  All commented data within an
     input file are skipped.  Nested comments are possible.


 The syntax of the control file is as follows:
     ControlFile =   GlobalSettings {Task} ["STOP"].
     Task        =   GlobalSettings     |
                     CheckHData         |
                     AnalyzeHData       |
                     FitDCycleSpecs     |
                     AnalyzeHResids     |
                     FitDCycRegPars     |
                     FitHSimulPars      |
                     ExtractDData       |
                     GenerateHData      |
                     FitDRegs           |
                     ApplyDRegs         |
                     AnalyzeDData       |
                     FitDSimulPars      |
                     ExtractMData       |
 Each task consists of a task identifier (e.g., "GLOBAL_SETTINGS"), which 
 is followed by the actual program directives, typically a series of input 
 and output file names.  
 The tasks and their identifiers are presented in the next section.  For 
 the exact syntax of all tasks see the control file named
 which is used to produce the reference output. 
 WeathGen executes all tasks sequentially in the order they occur in the 
 control file.  Unless an error occurs, the program stops at the first 
 occurrence of the keyword STOP, or when the end of the control file is 
 reached, whatever occurs first.  Note that besides the "STOP" command you 
 can also use comments [i.e.  "(* ...  *)"] to quickly adapt a given 
 control file.
 Names of input files must always be specified.  However, for output files 
 "" (empty string) may also be used.  In this case, no respective output 
 files will be written.  This can enhance the performance of WeathGen, 
 since in some cases computationally expensive analyses will be skipped.


 Below follows a short description of the individual tasks performed by
 WeathGen.  Each task is introduced by its keyword as used in the control 
     Defines the values of a series of basic parameters which are used in 
     all subsequent calculations with WeathGen.  The parameter values 
     remain valid until a new GlobalSettings task occurs.  Note that the 
     ranges of years and months which are specified in this task only 
     specify which output shall be written to file, not how it is to be 
     Checks the consistency and plausibility of values contained in a 
     hourly input data file, and attempts to interpolate inplausible or 
     missing values from adjacent time points.  The checks are performed to 
     all data found in the input file.  
     A hourly value is considered inconsistent if:
     Temperature:       (val<>misVal) AND
                        ( (val<-45.0) OR     (*  [deg.C]   *)
                          (val>+45.0) OR    
                        ((prev1<>misVal) AND (ABS(val-prev1)>12.0)) OR
                        ((prev2<>misVal) AND (ABS(val-prev2)>24.0)) )
     Precipitation:     (val<>misVal) AND
                        ( (val<0.0 )  OR    
                          (val>60.0) )       (*  [mm]  *)

     Global radiation:  (val<>misVal)  AND
                        ( (val<-20.0 ) OR    (*  [Wh/m^2]  *)
                          (val>1400.0) OR  
                        ((prev1<>misVal) AND (ABS(val-prev1)>900.0)) OR
                        ((prev2<>misVal) AND (ABS(val-prev2)>900.0)) )
     Vapour pressure:   (val<>misVal) AND
                        ( (val<0.006) OR     (*  [kPa] *)
                          (val>12.3 ) OR   
                        ((prev1<>misVal) AND (ABS(val-prev1)>6.0)) OR  
                        ((prev2<>misVal) AND (ABS(val-prev2)>6.0)) )
                        0.006 = saturation VP at -50 [deg.C]
                        12.3  = saturation VP at +50 [deg.C]
                        6.0   = ca. change of saturation VP  
                                from 5 to 30 [deg.C]
     Wind speed:        (val<>misVal) AND
                        ( (val<0.0 )  OR
                          (val>42.0))        (* [m/s] *)

                        42 = ca. 150 [km/h]
     where "val"     = hourly value, 
           "misVal"  = missing value (-99.999), 
           "prev1/2" = value before one/two hours.
       This task can also be used to simply extract data from a 
       large hourly data file.  The years and months to be extracted 
       must be specified in a preceeding GlobalSettings task.

     Performs various, variable-specific statistical analyses on hourly 
     weather data.
     Determines for each calendar month approporiate functions to describe  
     the long-term mean daily cycles of hourly T, GR, VP, and WS, the so- 
     called "daily cycle specifications" (DCS).
     The following functions are tested (Below "f1-f2" means that two 
     different functions are used to describe the daily cycle of a 
     variable; "f1" accounts for the "falling", and "f2 for the "rising" 
     limb of the daily cycle.  For instance, "Exp-Sinus" means that the 
     "falling" limb is described by an exponential function, whereas the 
     "rising" limb is described by (a part of) a sine function.  The 
     timepoint within the day at which the switch between f1 and f2 occurs 
     is one of the parameters that are determined by this task):
     Temperature:       (1)  Sinus-Sinus, 
                        (2)  Exp-Exp, 
                        (3)  Exp-Sinus.
     Global radiation:  A*exp(-k/sin(hs)) + mu,  where  
                        hs = solar altitude angle; 
                        k  = hourly clearness index GlobRad/Ho, i.e.  
                             ratio of actual to maximum possible radiation
     Vapour pressure:   (1)  Constant, 
                        (2)  Sinus-Sinus, 
                        (3)  Exp-Exp, 
                        (4)  Exp-Sinus, 
                        (5)  k*(x-k1)^2*(x-k2)^2+mu.
     Wind speed:        Same as Vapour pressure.    

       This task currently uses a brute-force identification algorithm  
       and may thus take some hours of computing time, even on a powerful 
    Analyzes statistically the residuals of T, GR, VP, and WS from their 
    long-term mean daily cycles as determined by means of FIT_D_CYCLE_SPECS.
     Determines the so-called "daily cycle regression parameters" (DCR).  
     These parameters are used to predict the parameters of a hourly 
     variable's daily cycle (e.g., the amplitude of a sine) from the
     variable's daily mean, minimum and/or maximum values.

     Determines all parameters needed (in addition to the DCS and DCR) to  
     simulate hourly weather sequences based on daily input variables.
     Extracts daily weather variables from a hourly data file.  The 
     extracted variables can be used as input for the simulation of hourly 
     weather variables, or to determine the parameters needed for the 
     simulation of daily weather variables.
     Simulates hourly weather variables, given daily weather variables and 
     corresponding parameters as inputs.
     Estimates parameters of linear regressions between daily weather  
     variables from two different data sets.
     The regressions are fitted separately for each calendar month as 

     Temperature:       Temper = a*xTemper + b
                        (Applied separately for daily mean/min/max 
     Precipitation:     Psum = ( a*Sqrt(xPSum) + b )^2
     Global radiation:  GlobRad = ( a*AbsSunsh/So + b )*Ho,  where
                        AbsSunsh = daily actual sunshine duration;
                        So       = daily theoretical sunshine duration; 
                        Ho       = extraterrestrial radiation;
                        (Angstrom-type regression).
     Vapour pressure:   Same as Precipitation, but applied separately 
                        for the daily mean/minima/maxima.
     Wind speed:        Same as Vapour pressure.    
     Applies linear regressions as determined by means of FIT_D_REGS to 
     predict daily variables from independent data.
     Performs various, variable-specific statistical analyses on daily 
     weather variables.
     Determines all parameters needed to simulate daily weather sequences 
     from monthly input variables.
     Extracts monthy weather variables from daily data files.  These 
     variables can be used as input for the simulation of daily weather

     Simulates daily weather variables, given monthy weather variables and 
     corresponding parameters as inputs.

     InputFile     =  {ch}  "#"  "A"|"K"|"N"  {ch}  "."  stationID  {ch} 
                      "PERIOD"  frstYearNr   lastYearNr
                      "MONTHS"  frstMonthNr  lastMonthNr
                      "TIME_STEP = HOUR"
                      "YEAR"  "MONTH  "DAY"  "HOUR" 
                      "Temper"   "Precip"   "GlobRad"  "VapPress"  "WindSpeed"
                      DataEntry {DataEntry}. 

     DataEntry     =  yearNr monthNr dayNr hourNr 
                      value  value  value  value  value.
     yearNr, monthNr, 
     dayNr, hourNr = INTEGER. 
     value         = REAL.
     ch            = CHARACTER. 

     Temperature must be provided in [degC], Precipitation in [mm], 
     Global radiation in [Wh/m^2], Vapour pressure in [kPa = 10 mbar], 
     and Wind speed in [m/s]. 

 Missing values:
     Missing values are denoted throughout all WeathGen input/output
     files as -99.999.

     Hour numbers refer to solar time.  The first hour of a day (hourNr=1) 
     is from 00.00 to 01.00, the last hour (hourNr=24) from 23.00 to 24.00.  
     Time 12.00 corresponds to solar noon.  (Note that hourly values for 
     global radiation should be plotted against the middle of an hour 
     (i.e., hourNr+0.5), and not the index of the hour (= hourNr).
 Files with the above syntax are for instance produced by the program "GetENAD",  
 which extracts  hourly data files from the "ENAD" data base of the Swiss 
 Meteorological Institute.  The program "GetENAD" can be obtained from the 
 (1) WeathGen always analyzes/outputs data for February using 28 days. 
 Data for Feb. 29th (leap year) can occur in the input data files, but 
 will be discarded.  
 (2) Daily precipitation totals are determined by summing up all hourly 
 totals from solar time tpDMeasStart ("timepoint of start of daily 
 measurements") of the current day until solar time tpDMeasStart of the 
 next day.  The parameter tpDMeasStart is not only used to extract daily 
 precipitation values from hourly data (EXTRACT_D_DATA), but also when 
 generating hourly values from daily data (GENERATE_H_DATA).  The value  
 of tpDMeasStart is normally specified in the GLOBAL_SETTINGS.  For the 
 generation of hourly values, however, if a corresponding entry can be 
 found in the DCS input file, this value is used instead.
 (3) For the syntax of all other files, in particular the expected names 
 for the various daily variables, see the reference outputs, respectively 
 the corresponding input files.

 WeathGen was implemented in Modula-2 using the MacMETH Modula-2 Language 
 System on Macintosh computers (Wirth et al., 1992; Version 3.2.2), and
 EPC Modula-2 (Anonymous, 1994; Version 2.0.8) on SUN workstations.  
 WeathGen was based upon a batch-orientated version of the "Dialog Machine",
 as implemented in the "RASS" software (RASS = "RAmses Simulation Server"; 
 RAMSES = "Research Aids for the Modelling and Simulation of Environmental 
 Systems").  For more information on the Dialog Machine and RASS/RAMSES see 
 Fischlin & Schaufelberger (1987) and Thoeny et al. (1994).

   Problem                               Possible remedy
   -------                               ---------------
   An input file can not been found. ->  Check the file name and path 
                                         specified in the control file.
   The stochastic generation of 
   daily or hourly data stops
   with an error.                    ->  Specify new "seeds" for the 
                                         random number generator in the
                                         control file  and try again.
                                     ->  Fit daily/hourly simulation 
                                         parameters using more years of 

   Known bugs                                 
   (list to be completed) 

 Anonymous, 1994.  "EPC Modula-2. User's reference manual".  Edinburgh 
     Portable Compilers Ltd., Edinburgh, UK.

 Fischlin, A. & Schaufelberger, W., 1987.  "Arbeitsplatzrechner im 
     technisch-naturwissenschaftlichen Hochschulunterricht".  Bulletin 
     SEV/VSE, 78 (January): p15-21.

 Gyalistras, D., Fischlin, A. & Riedo, M. (1997). "Herleitung stündlicher 
     Wetterszenarien unter zukünftigen Klimabedingungen". In: Fuhrer,
     J. (ed.),  Klimaänderung und Grünland - eine Modellstudie über die
     Auswirkungen zukünftiger Klimaveränderungen auf das Dauergrünland in 
     der Schweiz. vdf, Hochschulverlag AG an der ETH Zürich, pp. 207-276.
 Gyalistras, D. & Fischlin, A. (1999).  "Towards a general method to 
     construct regional climatic scenarios for model-based impacts
     assessments".  Petermanns geogr. Mittlg. 143(4): 251-264. 
 Richardson, C.W., 1981.  "Stochastic simulation of daily precipitation, 
     temperature, and solar radiation".  Water Resour. Res. 17: 182-190.
 Thoeny, J., Fischlin, A. & Gyalistras, D., 1994.  "RASS: towards bridging 
     the gap between interactive and off-line simulations".  In: Halin, J., 
     Karplus, W., Rimane, R. (eds.): CISS - First Joint Conference of 
     International Simulation Societies Proceedings (August 22-25, 1994, 
     ETH Zuerich).  Society for Computer Simulation International, San 
     Diego, p99-103.
 Wilks, D.S., 1992.  "Adapting stochastic weather generation algorithms  
    for climate change studies".  Clim.  Change 22: 67-84.

 Wirth, N., Gutknecht, J., Heiz, W., Schaer, H., Seiler, H., Vetterli, C. 
    & Fischlin, A., 1992.  "MacMETH. A fast Modula-2 Language System for 
    the Apple Macintosh.  User Manual".  4th.  completely revised ed., 
    Departement fuer Informatik, ETH Zuerich, Switzerland.


This page is maintained by Dimitrios Gyalistras. Last updated 03-Feb-2005.