============================================================================ WeathGen 2.6.1 A Stochastic Weather Generator for Climate Change Studies PROGRAM DOCUMENTATION AND USER'S MANUAL D. Gyalistras E-mail: gyalistras@env.ethz.ch URL: http://www.climate-impacts.ch Last updated 03-Feb-2005. ============================================================================ 1. INTRODUCTION 2. AVAILABILITY 3. INSTALLATION 4. DESCRIPTION 5. USAGE 6. IMPLEMENTATION 7. TROUBLESHOOTING 8. REFERENCES ============================================================================ 1. INTRODUCTION ============================================================================ 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 studies: - 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. ============================================================================ 2. AVAILABILITY ============================================================================ 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 ============================================================================ 3. INSTALLATION ============================================================================ ---------------------------------------------------------------------------- 3.1 MACINTOSH VERSION ---------------------------------------------------------------------------- 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. ---------------------------------------------------------------------------- 3.2 SUN VERSION ---------------------------------------------------------------------------- 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 Note: ---- 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 type: tar vfx WeathGen261.tar WG261/file_or_directory_name ---------------------------------------------------------------------------- 3.3 GENERATING THE REFERENCE OUTPUT ---------------------------------------------------------------------------- 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 self-explanatory. 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 WeathGen 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 "TEST_REF_OUT_1" to "TEST_REF_OUT_3". Note: ---- 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.*". ============================================================================ 4. DESCRIPTION ============================================================================ 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. ---------------------------------------------------------------------------- 4.1 STATISTICAL ANALYSES ---------------------------------------------------------------------------- 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 include: - 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. ---------------------------------------------------------------------------- 4.2 DERIVATION OF SIMULATION INPUTS AND PARAMETER ESTIMATION ---------------------------------------------------------------------------- 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. ---------------------------------------------------------------------------- 4.3 STOCHASTIC SIMULATION OF WEATHER VARIABLES ---------------------------------------------------------------------------- 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. ---------------------------------------------------------------------------- 4.4 AUXILIARY TASKS ---------------------------------------------------------------------------- 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". ---------------------------------------------------------------------------- 5.1 INPUT/OUTPUT ---------------------------------------------------------------------------- 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. ---------------------------------------------------------------------------- 5.2 THE PROGRAM CONTROL FILE ---------------------------------------------------------------------------- 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 | GenerateDData. 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 "WG.CTRL.ClcRefOutput" 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. ---------------------------------------------------------------------------- 5.3 WEATHGEN TASKS ---------------------------------------------------------------------------- Below follows a short description of the individual tasks performed by WeathGen. Each task is introduced by its keyword as used in the control file. GLOBAL_SETTINGS 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 calculated. CHECK_H_DATA 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. Note: ---- 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. ANALYZE_H_DATA Performs various, variable-specific statistical analyses on hourly weather data. FIT_D_CYCLE_SPECS 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. Note: ---- This task currently uses a brute-force identification algorithm and may thus take some hours of computing time, even on a powerful workstation. ANALYZE_H_RESIDS 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. FIT_D_CYCLE_REG_PARS 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. FIT_H_SIMUL_PARS Determines all parameters needed (in addition to the DCS and DCR) to simulate hourly weather sequences based on daily input variables. EXTRACT_D_DATA 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. GENERATE_H_DATA Simulates hourly weather variables, given daily weather variables and corresponding parameters as inputs. FIT_D_REGS Estimates parameters of linear regressions between daily weather variables from two different data sets. The regressions are fitted separately for each calendar month as follows: Temperature: Temper = a*xTemper + b (Applied separately for daily mean/min/max Temperatures) 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. APPLY_D_REGS Applies linear regressions as determined by means of FIT_D_REGS to predict daily variables from independent data. ANALYZE_D_DATA Performs various, variable-specific statistical analyses on daily weather variables. FIT_D_SIMUL_PARS Determines all parameters needed to simulate daily weather sequences from monthly input variables. EXTRACT_M_DATA Extracts monthy weather variables from daily data files. These variables can be used as input for the simulation of daily weather variables. GENERATE_D_DATA Simulates daily weather variables, given monthy weather variables and corresponding parameters as inputs. ---------------------------------------------------------------------------- 5.4 SYNTAX OF HOURLY INPUT FILE ---------------------------------------------------------------------------- Syntax: 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. stationID, frstYearNr, lastYearNr, frstMonthNr, lastMonthNr, yearNr, monthNr, dayNr, hourNr = INTEGER. value = REAL. ch = CHARACTER. Units: 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. Time: 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 author. Note: ---- (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. ============================================================================ 6. IMPLEMENTATION ============================================================================ 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). ============================================================================ 7. TROUBLESHOOTING ============================================================================ 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 data. Known bugs ---------- (list to be completed) ============================================================================ 8. REFERENCES ============================================================================ 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.