Package 'WACS'

Synthetic climate series of a french town between 1995 and 2012.

Description

year : Year

Details

month : Month

day : Day

ETPP : Evaporation and sweating (mm)

RG : Radiance (Joules/cm²)

rain : Height of precipitation (mm)

tmin : Minimum temperature (degré Celsius)

tmax : Maximum temperature (degré Celsius)

V : Wind speed (meters per second)

---

WACS: Multivariate Weather-state Approach Conditionally Skew-normal Generator

Description

WACS is a multivariate weather generator for daily climate variables based on weather-states that uses a Markov chain for modeling the succession of weather states. Conditionally to the weather states, the multivariate variables are modeled using the family of Complete Skew-Normal distributions. Parameters are estimated on measured series. Must include a 'Rain' variable and can accept as many other variables as desired.

WACS functions

• WACSdata: Builds a data structure compatible with WACS functions

• WACSestim: Estimation of the parameters of a WACS model

• WACSsimul: Performs simulations based on estimated parameters of the WACS model

• WACSvalid: Performs validations of WACS simulations

• WACScompare: Performs comparisons between two WACS data structures, or between two WACS simulation series

• WACSplot: Plots validation figures from WACSvalid and from WACScompare

• WACSplotdensity: Plots fitted bivariate densities of residuals

Authors

Denis Allard, Ronan Trépos

Reference

• Flecher C., Naveau P., Allard D., Brisson N.(2010) A stochastic weather generator for skewed data. Water Resource Research, 46, W07519

• WACSgen: model, methods and algorithms (2015). Allard D., Biostatistiques et Processus Spatiaux, INRA, Avignon, France. Available at denis.biosp.org

• Flecher, C., Naveau, Ph. and Allard, D. (2009) Estimating the Closed Skew-Normal distributions parameters using weighted moments", Statistics and Probability Letters, 79, 1977-1984.

Examples

## Not run:  
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries, from="1995-01-01", to="2012-12-31")
  ThisPar  = WACSestim(ThisData)
  ThisSim  = WACSsimul(ThisPar, from="1995-01-01", to="2012-12-31")
  ThisVal  = WACSvalid(what="Sim",wacsdata = ThisData, wacspar = ThisPar, 
                       wacssimul = ThisSim,varname="tmin")
  WACSplot(ThisVal,file="ThisFile.pdf")

## End(Not run)

---

Performs comparisons between two WACS data structures, or between two WACS simulation series

Description

The comparison is based on different types of statistics computed on WACSdata1 and WACSdata2, or WACSsim1 and WACSsim2

Usage

WACScompare(
  what = what,
  wacs1 = wacs1,
  wacspar = wacspar,
  wacs2 = wacs2,
  varname = varname,
  varname2 = NULL,
  base = 0,
  above = T,
  months = 1:12
)

Arguments

what	Type of validation. Possible choices are: ="Sim" Compares a simulation run to data ="Rain" qq-plots of rainfall, per season ="MeanSd" Compares monthly mean and standard deviations ="BiVar" Compares bivariate correlations ="CorTemp" Compares temporal correlations ="SumBase" Compares sums above a threshold ="Persistence" Compares persistence of a variable above (or below) a threshold
wacs1	Either WACS data obtained when calling WACSdata, or WACS simulations obtained when calling WACSsimul.
wacspar	WACS parameters estimated when calling WACSestim on wacs1
wacs2	Either WACS data obtained when calling WACSdata, or WACS simulations obtained when calling WACSsimul. Must be of the same class as wacs1
varname	Variable on which the validation is performed
varname2	Second variable on which validation is performed (only needed if what=BiVar)
base	Threshold used for "SumBase" and "Persistence"
above	Boolean value used for "Persistence": TRUE if data is considered above threshold; FALSE otherwise
months	Months to which the analysis should be restricted (only for "SumBase" and "Persistence")

Value

A list containing all information needed for plots; contains also the type of validation, as a class

Note

wacs1 and wacs2 must be of the same WACS class. We must either have

class(wacs1)=class(wacs2)=class(WACSdata),

or class(wacs1)=class(wacs2)=class(WACSsimul).

If what="sim", data and simulations are displayed as a function of the day of the year, from 1 to 365. Smoothed versions daily average and daily envelopes (defined by average +/- 2. standard deviations) are also displayed.

If what="rain", qq-plots and superimposition of histograms and models of rain are produced for each season.

If what="MeanSd", boxplots of monthly means and monthly standard deviations are compared. The median value of the monthly mean, resp. monthly standard deviation, of the data are displayed on top of the boxplots computed on the simulations.

If what="BiVar", boxplots of monthly correlations coefficients between varname and varname2 are compared. The median value of the correlation coefficient computed on the data is displayed on top of the boxplots computed on the simulations.

If what="CorTemp", boxplots of monthly 1-day auto correlation are compared. The median value of the auto-correlation coefficient computed on the data is displayed on top of the boxplots computed on the simulations.

If what="SumBase", boxplots of the sum of the variable varname above a given threshold, base, is computed during the months provided in the variable months.

If what="Persistence", histograms of consecutive days of the variable varname above (or below) a given threshold, base, are compared. If above=TRUE, consecutive days above the threshold are computed, whereas days below the threshold are computed if above=FALSE. Months can be selected with the variable months.

Examples

## Not run: 
  ## Simple example
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries,from="1995-01-01", to="2005-12-31")
  ThisPar  = WACSestim(ThisData)
  ThatData = WACSdata(ClimateSeries,from="2002-01-01", to="2012-12-31")
  Comp = WACScompare(what="Sim", wacs1=ThisData, wacspar=ThisPar,
                     wacs2=ThatData, varname="tmin")
  WACSplot(Comp)
  Comp = WACScompare(what="MeanSd",wacs1=ThisData, wacspar=ThisPar,
                     wacs2=ThatData, varname="RG")
  WACSplot(Comp)
  Comp = WACScompare(what="SumBase", wacs1=ThisData, wacspar=ThisPar,
                     wacs2=ThatData, varname="tmoy", base=5, months=2:5)
  WACSplot(Comp)
  Comp = WACScompare(what="Persistence",wacs1=ThisData, wacspar=ThisPar,
                     wacs2=ThatData, varname="tmin", base=0, above=FALSE)
  WACSplot(Comp)

## End(Not run)

---

Format data for WACS

Description

WACSdata Builds a data structure compatible with WACS functions

Usage

WACSdata(
  data,
  mapping = NULL,
  bounds = NULL,
  from = NULL,
  to = NULL,
  skip = NULL,
  Trange = FALSE,
  seasons = c("03-01", "06-01", "09-01", "12-01")
)

Arguments

data	A dataframe containing series of values for each variable
mapping	The names of special variables: year, month, day, rain, tmin and tmax. Eg. list(RR = "rain", Tmin = "tmin") [optional; default is NULL]
bounds	A list of lists indicating the bounds for some variables eg. list(rain=list(min=0, max=7)) [optional; default is NULL] If not provided is set automatically according to data
from	Date at which the estimation should begin [optional; default is NULL]
to	Date at which the estimation should stop [optional; default is NULL]
skip	Vector of column names to skip[optional; default is NULL]
Trange	Boolean value. When Trange=TRUE, the couple (tmin, trange=tmax-tmin) is modeled. When Trange=FALSE, he couple (tmin, tmax) is modeled. Default is Trange=FALSE
seasons	Vector of string of format 'mm-dd', gives the dates of change of seasons (default: is c("03-01", "06-01", "09-01","12-01"))

Value

A data frame structure, which will be used to call WACSestim, the function that estimates the parameters of the statistical model.

Note

bounds can be provided as a list, as shown above. If bounds=NULL, bounds are computed from the data. Some variables will have minimal values set automatically to 0 (trange,V,RG,ETPP) and maximal values to 100 (ETPP). Other minimum (resp. maximum) values are computed by adding (resp. subtracting) to the maximum (resp. minimum value) its difference to the 10th largest (resp. lowest) value.

from and to must be provided with format 'yyyy-mm-dd' (e.g. '2012-01-30').

There can be as many seasons as desired, with unequal length. There can also be one single season, in which case a single date is entered.

Default is seasons = c("03-01","06-01","09-01","12-01").

Author(s)

D. Allard, BioSP, Ronan Trépos MIA-T, INRA

Examples

## Not run: 
  ## Simple example
  ThisData = WACSdata(ClimateSeries,from="1995-01-01",to="2012-12-31",
                      Trange=F,seasons=c("03-01","06-01","09-01","12-01"))
 
## End(Not run)

---

Estimation of the parameters of a WACS model

Description

Estimation of the parameters of a WACS model

Usage

WACSestim(
  wacsdata,
  spar = 0.7,
  trend.norm = "L2",
  rain.model = "Gamma",
  method = "MLE",
  Vsel = NULL,
  Nclusters = NULL,
  clustering = "soft",
  plot.it = FALSE,
  DIR = "./"
)

Arguments

wacsdata	Data, as returned by WACSdata
spar	Smoothing parameter for estimating annual cycle
trend.norm	Type of norm used in for computing central tendency and variation. Must be "L1" or "L2".
rain.model	Model for precipitation. Must be "Gamma" or "None"
method	"MLE" or "MOM". Estimation method for the rain model.
Vsel	Variables (other than rain) on which clustering is performed when Vsel=NULL, all variables are considered.
Nclusters	Number of clusters to consider. When Nclusters = NULL, absolute best clustering is sought for wet and dry weather states in each season (up to 4).
clustering	Indicates whether "hard" or "soft" clustering is considered.
plot.it	Boolean indicating whether plots are produced
DIR	Directory in which placing plot

Value

A list containing all parameters; see the user guide for details.

Note

Larger values of spar produce smoother estimates. Smaller values produce less smooth estimates. spar=0.7 is a good compromise

Soft clustering means that days have probabilities to belong to each weather state. With hard clustering, this probability is set to 1 to the most likely weather state and 0 to all others. Density parameter estimates are more robust with clustering="soft". Clustering is done by means of the mclust package with modelNames="VVV"

Examples

## Not run: 

 ## For an estimation with default setting 
 ThisPar  = WACSestim(ThisData)

 ## For an estimation with max. 2 dry and wet weather types per season, 
 ## and production of plots
 ThisPar  = WACSestim(ThisData, Nclusters = 1:2, plot.it = TRUE) 

 ## For an estimation with exactly 2 dry and wet weather states per season, 
 ## clustering on variables 3 and 5 only and no production of plots
 ThisPar  = WACSestim(ThisData, Nclusters = 2, Vsel = c(3,5)) 
 
## End(Not run)

---

Produces validation and/or WACS comparison plots

Description

For plotting validation figures from outputs generated when calling WACSvalid or WACScompare. Figures are either displayed or printed in a file

Usage

WACSplot(wacsvalid, file = NULL)

Arguments

wacsvalid	Output, as obtained when calling WACSvalid or WACScompare
file	File in which to write the figure. Default is NULL. If file=NULL, no file is produced; the figure is only produced in the graphical interface

Value

No return. A Figure is either displayed or printed in a file.

Examples

## Not run: 
  ## Simple example
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries)
  ThisPar  = WACSestim(ThisData)
  ThisSim  = WACSsimul(ThisPar, from="1995-01-01", to="2012-12-31")
  ThisVal  = WACSvalid(what="Sim",wacsdata = ThisData, wacspar = ThisPar, 
                       wacssimul = ThisSim,varname="tmin")
  WACSplot(ThisVal,file="ThisFile.pdf")

## End(Not run)

---

For plotting fitted bivariate densities of residuals

Description

For plotting fitted bivariate densities of residuals

Usage

WACSplotdensity(
  wacsdata = NULL,
  wacspar = NULL,
  season,
  dimens = c(1, 2),
  dry = T,
  DIR = "./"
)

Arguments

wacsdata	WACS data obtained when calling WACSdata on original climate series
wacspar	WACS parameters estimated when calling WACSestim
season	season to be considered (a scalar)
dimens	a vector of length 1 or 2 indicating the marginals to be plotted
dry	indicates whether dry weather states (if dry=TRUE) or wet weather states (if dry=FALSE) must be considered
DIR	Directory in which saving the Figures

Note

If length(dimens)=1, the bivariate density of the variable at days (d,d+1) is plotted. If length(dimens)=2, the same-day bivariate density of the pair of variables is plotted.

Examples

## Not run: 
  ## Simple example
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries)
  ThisPar  = WACSestim(ThisData)
  WACSplotdensity(ThisData,ThisPar,season=2,dimens=c(2,3),dry=TRUE) 

## End(Not run)

---

Function that reads a file of format Agroclim

Description

Function that reads a file of format Agroclim

Usage

WACSreadAgroclim(filename)

Arguments

filename

path to the filemane to read

Value

A list of 2 objects:

• dataThe table data

• mappingThe names of special var: year, month, day rain, tmin and tmax

Examples

## Not run: 
  # using an agroclim format file
  WACSdata(WACSreadAgroclim("myfile.csv"))

## End(Not run)

---

Performs simulations based on estimated parameters of the WACS model

Description

Performs simulations based on estimated parameters of the WACS model

Usage

WACSsimul(wacspar, from, to, first.day = NULL, REJECT = FALSE)

Arguments

wacspar	Parameters of the WACS model estimated with WACSestim
from	Starting date of the simulation (format: "yyyy-mm-dd")
to	Ending date of the simulation (format: "yyyy-mm-dd")
first.day	Conditioning values for first day (optional)
REJECT	Boolean indicating whether a rejection technique is used to guarantee variables within bounds. Default is FALSE. In this case, values outside bounds are forced to the bounds.

Value

A list containing the simulation results

Note

Variables are simulated sequentially: day d is simulated conditionally on the values at day (d-1). If REJECT=TRUE, a rejection technique is used to force simulated variables within the bounds. If REJECT=FALSE, variables that could have been simulated outside the bounds are forced to the limits. The rejection technique tends to produce biases. REJECT=FALSE is thus recommended

Examples

## Not run: 
  ## Simple example
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries)
  ThisPar  = WACSestim(ThisData)
  ThisSim  = WACSsimul(ThisPar, from="1995-01-01", to="2012-12-31")

## End(Not run)

---

Performs validations of WACS simulations

Description

The validation is based on different types of statistics computed on WACS data, WACS parameters and WACS simulations.

Usage

WACSvalid(
  what = "Sim",
  wacsdata = NULL,
  wacspar = NULL,
  wacssimul = NULL,
  varname = NULL,
  varname2 = NULL,
  base = 0,
  above = TRUE,
  months = 1:12
)

Arguments

what	Type of validation. Possible choices are: ="Sim" Compares a simulation run to data ="Rain" qq-plots of rainfall, per season ="MeanSd" Compares monthly mean and standard deviations ="BiVar" Compares monthly variate correlations ="CorTemp" Compares monthly temporal correlations ="SumBase" Compares sums above a threshold ="Persistence" Compares persistence of a variable above (or below) a threshold
wacsdata	WACS data obtained when calling WACSdata
wacspar	WACS parameters estimated when calling WACSestim
wacssimul	WACS simulation obtained when calling WACSsimul
varname	Variable on which the validation is performed
varname2	Second variable on which validation is performed (only needed if what=BiVar)
base	Threshold used for "SumBase" and "Persistence"
above	Boolean value used for "Persistence": TRUE if data is considered above threshold; FALSE otherwise
months	Months to which the analysis should be restricted (only for "SumBase" and "Persistence")

Value

A list containing all information needed for plots; contains also the type of validation, as a class

Note

If what=sim, data and simulations are displayed as a function of the day of the year, from 1 to 365. Smoothed versions of daily average and daily envelopes (defined by average +/- 2. standard deviations) are also displayed.

If what=rain, qq-plots and superimposition of histograms and models of rain are produced for each season.

If what=MeanSd, boxplots of monthly means and monthly standard deviations are compared. The median value of the monthly mean, resp. monthly standard deviation, of the data are displayed on top of the boxplots computed on the simulations.

#' If what=BiVar, boxplots of monthly correlations coefficients between varname and varname2 are compared. The median value of the correlation coefficient computed on the data is displayed on top of the boxplots computed on the simulations.

If what=CorTemp, boxplots of monthly 1-day auto correlation are compared. The median value of the auto-correlation coefficient computed on the data is displayed on top of the boxplots computed on the simulations.

If what=SumBase, boxplots of the sum of the variable varname above a given threshold, base, is computed during the months provided in the variable months.

If what=Persistence, histograms of consecutive days of the variable varname above (or below) a given threshold, base, are compared. If above=TRUE, consecutive days above the threshold are computed, whereas days below the threshold are computed if above=FALSE. Months can be selected with the variable months.

Examples

## Not run: 
  ## Simple example
  data(ClimateSeries)
  ThisData = WACSdata(ClimateSeries)
  ThisPar  = WACSestim(ThisData)
  ThisSim  = WACSsimul(ThisPar, from="1995-01-01", to="2012-12-31")
  Val1 = WACSvalid(what="Sim",wacsdata = ThisData, 
                   wacspar = ThisPar, wacssimul = ThisSim, varname="tmin")
  Val2 = WACSvalid(what="MeanSd",wacsdata = ThisData, 
                   wacssimul = ThisSim, varname="RG")
  Val3 = WACSvalid(what="SumBase", wacsdata = ThisData,  
                   wacssimul = ThisSim, varname="tmoy", base=5, month=2:5)
  Val4 = WACSvalid(what="Persistence",wacsdata = ThisData,  
                   wacssimul = ThisSim, varname="tmin", base=0, above=FALSE)

## End(Not run)

---