SequentialSimul {HyetosMinute} | R Documentation |
This function enables the generation of synthetic rainfall series via the Bartlett-Lewis rectangular pulse model without performing any disaggregation.
SequentialSimul(Length=1000,BLpar=list(lambda,phi,kappa,alpha,v,mx,sxmx), CellIntensityProp=list(Weibull=FALSE,iota=NA), TimeScale=1,Statistics=list(print=TRUE,plot=TRUE), ImportHistData=list(imp=FALSE,file="histdata.txt",ImpDataTimeScale=1, FileContent=c("WetDays","AllDays"),DailyValues=TRUE,DaysPerSeason=31,na.values="NA"), ExportSynthData=list(exp=FALSE,file="SynthData.txt", FileContent=c("WetDays","AllDays"),DaysPerSeason=31),PlotTs=FALSE,RandSeed=NULL)
Length |
A positive integer that specifies the length of time series. For argument |
BLpar |
List of parameters of the Bartlett-Lewis model. See |
CellIntensityProp |
List of arguments that specifies the distribution of cell intensity. See |
TimeScale |
A positive number that specifies the time scale of the time series. Please make sure that for the argument |
Statistics |
A list of logical variables (TRUE/FALSE) indicating whether the matrix of the historical, synthetic and theoretical statistics of rainfall should be printed or plotted. If |
ImportHistData |
A list of parameters that specifies the import of historical rainfall depths from an input file. See |
ExportSynthData |
A list of parameters specifying the export of synthetic rainfall depths to an output file. See |
PlotTs |
A logical variable (TRUE/FALSE) indicating whether the synthetic time series should be plotted. Default is |
RandSeed |
An integer value for the random number generator. If it equals to NULL, then a random seed is not inserted. |
The function SequentialSimul
enables the generation of synthetic rainfall time series via the Bartlett-Lewis rectangular pulse model with the given parameters, without performing any disaggregation. This function is appropriate for testing (e.g., by comparing simulated, theoretical and historical (if available) statistics) the model performance including the appropriateness of the Bartlett-Lewis model and its parameters. The statistics and the simulated time series can be either printed or displayed graphically. Additionally, the simulated time series can be exported to an output file.
Bartlett-Lewis model description
Argument BLpar
is a list that specifies the Bartlett-Lewis rectangular pulse model parameters. The general assumptions of the Bartlett-Lewis rectangular pulse model (Rodriguez-Iturbe et al., 1987, 1988) are:
Storm origins t_i occur following a Poisson process with rate λ (argument lambda
).
Cell origins t_{ij} occur following a Poisson process with rate β.
Cell arrivals terminate after a time v_i exponentially distributed with parameter γ.
Each cell has a duration w_{ij} exponentially distributed with parameter η.
Each cell has a uniform intensity X_{ij} with a specified distribution.
In the original version of the model (Bartlett-Lewis Rectangular Pulse Model), the parameters associated with cells are assumed constant among different storms.
In the modified version (random parameter Bartlett-Lewis model), the parameter η is randomly varied from storm to storm according to a gamma distribution with shape parameter α (argument alpha
) and scale parameter ν (argument v
). Subsequently, parameters β and γ also vary so that the ratios κ=β/η (argument kappa
) and φ=γ/η (argument phi
) are constant.
HyetosMinute package implements also the Random Parameter Bartlett-Lewis Rectangular Pulse Model with dependent intensity-duration (Kaczmarska et al., 2014) that allows μ_x to vary in proportion to the cell duration parameter, η, so as the ratio ι=μ_x/η (argument iota
) is kept constant.
The distribution of the cell intensity X_{ij} is typically assumed exponential with mean μ_x. Alternatively, it can be assumed two-parameter gamma distribution with mean μ_x and standard deviation σ_x. The package also supports Weibull distribution for cell intensity with mean μ_x and shape parameter.
Thus, in its most simplified version the model uses five parameters, namely λ, β, γ, η and μ_x (or equivalently λ, κ, φ, η and μ_x) and in its most enriched version seven parameters, namely λ, κ, φ, α, ν, μ_x, σ_x.
Normally, one parameter set corresponds to one month but it can be also correspond to a season of e.g. three months or even the whole year.
HyetosMinute package supports both the original and the random model version with exponential, gamma or Weibull intensities. By default, the random model is assumed. To implement the original model version with constant parameter η, set argument alpha
greater than 100 and insert the value of parameter η in argument v
.
To implement the random model with with dependent intensity-duration, set the value of ratio ι=μ_x/η in argument iota
.
To implement exponential or gamma distribution for cell intensity then set argument Weibull
in CellIntensityProp
list as FALSE.
To implement the exponential distribution set mean μ_x in argument mx
and the ratio μ_x/σ_x (argument sxmx
) equals to 1. If the argument sxmx
is not equal to 1 then the gamma distribution is assumed with a specific ratio sxmx
.
To implement Weibull distribution, then set argument weibTF
equal to TRUE. In this case, the intensity follows the Weibull distribution with mean μ_x (argument mx
) and shape parameter (put in argument sxmx
).
In the case of random model with with dependent intensity-duration and exponential distribution, set the value of ratio ι=μ_x/η in argument iota
, argument mx
as NA and argument sxmx
equals to 1. To implement gamma distribution, set argument mx
as NA and specify the ratio μ_x/σ_x (argument sxmx
). To implement Weibull distribution set argument mx
as NA and specify the shape parameter in argument sxmx
.
Please make sure that for parameters μ_x and σ_x the length units are millimeters (mm) and for parameters λ, ν, μ_x and σ_x the time units are days (d).
Read data from file
Argument ImportHistData
is a list of parameters specifying the features of input file if original data is to be read from a file. This file must have a specific format (see examples
).
A logical variable (TRUE/FALSE) that indicates if rainfall depths are to be read from an input file. If imp=TRUE
, original data is imported from a file. Default is imp=FALSE
.
A character string that specifies the name of the file or connection of the rainfall data. The input files are text files with the ".txt" extension (e.g. file="histdata.txt"
).
The time scale of rainfall data to be imported. It defaults to 1 that means that hourly rainfall data is imported. For sub-hourly time scales, use subdivisions of hour. For instance 1/60 for 1 minute data, 1/30 for 2 minute data, 1/6 for 10 minute data etc.
A character string indicating if dry days (with zero rainfall depths) are also contained in the input file. If FileContent=c("WetDays")
the input file contains only the rainfall depths of wet days. If FileContent=c("AllDays")
the input file contains the rainfall depths of wet and dry days. Default is DailyValues=c("WetDays")
.
A logical variable (TRUE/FALSE) that specifies if the daily rainfall depths are contained in the input file. If DailyValues=FALSE
, the imported rainfall depths are aggregated into daily scale. Default is DailyValues=TRUE
.
A positive integer, typically 30 or 31, that specifies the number of days of the month or season of the input data. Default is DaysPerSeason=31
.
A character vector of strings which are to be interpreted as NA
values. Default is na.values="NA"
.
The input file must not contain any header lines or the Bartlett-Lewis model parameters.
In the input file, each row contains the data of a single day. The three first columns of the input file determine the dates of the data. The first column corresponds to the "Day", the second column corresponds to the "Month" and the third column corresponds to the "Year". The fourth column contains "the daily values (mm)", if available (DailyValues=TRUE
). The rest columns contain the rainfall depths.
The "Year" field in the input file does not necessarily correspond to a real year. Thus, the sequence of years could be 1, 2, ..., or 49, 50, ..., instead of 1949, 1950, ... .
The "Day" and "Month" fields in the input file do not necessarily correspond to a real month. A "Month" can well be a season containing e.g. three months or even the whole year. In the latter case the number of days of month should be set to 366 and the "Day" field should be the Julian number of the date.
Write synthetic data to file
Argument ExportSynthData
is a list of parameters that specifies the features of output file if synthetic data is to be exported to a text file. The output file has similar structure as the input file, without any header line.
A logical variable (TRUE/FALSE) that indicates whether synthetic rainfall depths is to be written to an output file. If exp=TRUE
, synthetic data is exported to a text file. Default is exp=FALSE
.
A character string that specifies the name of the file or connection to which the rainfall data are to be exported. The output files are text files with the ".txt" extension (e.g. file="SynthData.txt"
).
A character string indicating if dry days (with zero rainfall depths) will be also written in the output file. If FileContent=c("WetDays")
the output file will contain only the rainfall depths of wet days. If FileContent=c("AllDays")
the output file will contain the rainfall depths of wet and dry days. Default is DailyValues=c("WetDays")
.
A positive integer, typically 30 or 31, that specifies the number of days of the month or season of the output data. Default is DaysPerSeason=31
.
Argument Statistics
is a list of logical variables (TRUE/FALSE) that indicates whether the matrix of the main historical (if applicable), synthetic and theoretical statistics is to be printed or plotted. The statistics are computed and printed if print=TRUE
. Additionally, if plot=TRUE
bar plots and auto-correlation function plots are produced on screen devices in order to compare the historical (if applicable), synthetic and theoretical statistics.
The examples below and the used parameters are indicative. Subsequently, new parameters for the Bartlett-Lewis model should be estimated for other data-sets.
A list with the following components:
Time series |
Vector of synthetic rainfall depths. |
Statistics |
Matrix of the main synthetic as well as theoretical statistical characteristics, and optionally historical statistics if available ( |
The statistics are plotted on screen devices if plot
is TRUE
. See Details
for further information.
The generated rainfall depths are exported to a text file (i.e., ".txt" format), if exp
is TRUE
. See Details
for further information.
The synthetic time series is plotted on screen device, if PlotTs
is TRUE
. It is worth noting that for sub-hourly time scales this process is time-consuming.
Kossieris Panagiotis pkossier@central.ntua.gr
For the Bartlett-Lewis rectangular pulse model the user is referenced to:
Rodriguez-Iturbe I., D. R. Cox, and V. Isham, Some models for rainfall based on stochastic point processes, Proc. R. Soc. Lond., A 410, 269-288, 1987.
Rodriguez-Iturbe I., D. R. Cox, and V. Isham, A point process model for rainfall: Further developments, Proc. R. Soc. Lond., A 417, 283-298, 1988.
Onof, C. and H. S. Wheater, Modelling of British rainfall using a Random Parameter Bartlett-Lewis Rectangular Pulse Model, Journal of Hydrology, 149, 67-95, 1993.
Onof, C. and H. S. Wheater, Improvements to the modelling of British rainfall using a Modified Random Parameter Bartlett-Lewis Rectangular Pulse Model, Journal of Hydrology, 157, 177-195, 1994.
Onof, C., Chandler, R.E., Kakou, A., Northrop, P., Wheater, H.S., Isham, V., 2000. Rainfall modelling using Poisson-cluster processes: a review of developments. Stoch. Environ. Res. Risk Assess. 14, 384?411. doi:10.1007/s004770000043
Kaczmarska, J., Isham, V., Onof, C., 2014. Point process models for fine-resolution rainfall. Hydrol. Sci. J. 140806131733005. doi:10.1080/02626667.2014.925558
# Example 1: Generate hourly rainfall series # for 100 days, using the original # Bartlett-Lewis model (without historical data imported) # Hourly data are exported to "SynthBLRPM.txt" file ex1 <- SequentialSimul(Length=100,BLpar=list(lambda=0.19104,phi=0.06620544,kappa=0.3529412, alpha=150,v=40.8,mx=71.6544,sxmx=1),CellIntensityProp=list(Weibull=FALSE,iota=NA), TimeScale=1,ExportSynthData=list(exp=TRUE,FileContent=c("AllDays"),DaysPerSeason=31, file="SynthBLRPM.txt"),ImportHistData=list(imp=FALSE,file="data.txt", ImpDataTimeScale=1,na.values="NA",FileContent=c("WetDays"),DaysPerSeason=31,DailyValues=TRUE), PlotTs=FALSE,Statistics=list(print=TRUE,plot=FALSE),RandSeed=5) # Example 2: Generate hourly rainfall series # for 100 days, using the random parameter # Bartlett-Lewis model # Hourly data is imported from "HistHourlyData.txt" file # Hourly data is exported to "SynthRPBLM.txt" file # To load the data set "HistHourlyData" use data(HistHourlyData) # To export the daily and hourly rainfall depths of # "HistHourlyData" data in the chosen working directory use write.table(HistHourlyData,file="HistHourlyData.txt",sep="\t", quote=FALSE,row.names=FALSE,col.names=FALSE) # To generate synthetic rainfall series using the random parameter Bartlett-Lewis model # (compared them to historical data) use ex2 <- SequentialSimul(Length=100,BLpar=list(lambda=0.9396,phi=0.0568,kappa=1.05819, alpha=2.69519,v=0.006283,mx=24.33408,sxmx=1),CellIntensityProp=list(Weibull=FALSE, iota=NA),TimeScale=1,ExportSynthData=list(exp=TRUE,FileContent=c("AllDays"),DaysPerSeason=31, file="SynthRPBLM.txt"),ImportHistData=list(imp=TRUE,file="HistHourlyData.txt", ImpDataTimeScale=1,na.values="NA",FileContent=c("AllDays"),DaysPerSeason=31,DailyValues=TRUE), PlotTs=FALSE,Statistics=list(print=TRUE,plot=FALSE),RandSeed=5 ) # Example 3: Generate 100 daily rainfall depths, # with the random parameter Bartlett-Lewis model, # with cell intensities from Gama distribution # Hourly data is imported from "HistHourlyData2.txt" file # The daily data is produced via aggregation of the hourly # Daily data is exported to "SynthRPBLGM.txt" file # To load the data set "HistHourlyData2" use data(HistHourlyData2) # To export the daily and hourly rainfall depths of # "HistHourlyData2" data in the chosen working directory use write.table(HistHourlyData2,file="HistHourlyData2.txt",sep="\t", quote=FALSE,row.names=FALSE,col.names=FALSE) # To generate synthetic rainfall series using the random parameter Bartlett-Lewis gamma model # (compared them to historical data) use ex3 <- SequentialSimul(Length=100,BLpar=list(lambda=0.4596792,phi=0.0394698, kappa=0.1479426,alpha=3.9529358,v=0.0141872,mx=158.1091152,sxmx=55.6506624/158.1091152), CellIntensityProp=list(Weibull=FALSE,iota=NA),TimeScale=24,ExportSynthData=list(exp=TRUE, FileContent=c("AllDays"),DaysPerSeason=30,file="SynthRPBLGM.txt"), ImportHistData=list(imp=TRUE,file="HistHourlyData2.txt", ImpDataTimeScale=1,na.values="NA",FileContent=c("AllDays"), DaysPerSeason=30,DailyValues=TRUE),PlotTs=FALSE, Statistics=list(print=TRUE,plot=FALSE),RandSeed=5) # Example 4: Generate 10-min rainfall depths # for 100 days, with the random parameter # Bartlett-Lewis model, with dependent intensity-duration # 10-min data is exported to "SynthRPBLMD.txt" file ex4 <- SequentialSimul(Length=100,BLpar=list(lambda=0.528,phi=0.042,kappa=0.996, alpha=2.075,v=0.01724338,mx=NA,sxmx=1), CellIntensityProp=list(Weibull=FALSE,iota=0.164), TimeScale=1/6,ExportSynthData=list(exp=TRUE,FileContent=c("AllDays"), DaysPerSeason=31,file="SynthRPBLMD.txt"),ImportHistData=list(imp=FALSE, file="data.txt",ImpDataTimeScale=6,na.values="NA",FileContent=c("WetDays"), DaysPerSeason=31,DailyValues=TRUE),PlotTs=FALSE,Statistics=list(print=TRUE,plot=FALSE),RandSeed=5)