DisagSimul.test {HyetosMinute} | R Documentation |
This function enables the disaggregation of daily rainfall series into hourly or sub-hourly rainfall depths. The initial daily sequence either is generated using the Bartlett-Lewis rainfall model or is read from a file. This function is appropriate for testing the entire model performance including the appropriateness of the Bartlett-Lewis model and its parameters and the disaggregation model, by comparing original and disaggregated rainfall depths statistics.
DisagSimul.test(Length=1000,TimeScale=1,BLpar=list(lambda,phi,kappa,alpha,v,mx,sxmx), CellIntensityProp=list(Weibull=FALSE,iota=NA), RepetOpt=list(DistAllowed=0.1,FacLevel1Rep=20,MinLevel1Rep=50,TotalRepAllowed=5000), NumOfSequences=10,Statistics=list(print=TRUE,plot=TRUE), ImportHistData=list(imp=FALSE,file="histdata.txt",ImpDataTimeScale=1, FileContent=c("WetDays","AllDays"),DaysPerSeason=31,DailyValues=TRUE,na.values="NA", ImpDataTimeScale=1),ExportSynthData=list(exp=FALSE,file="SynthData.txt", FileContent=c("WetDays","AllDays"),DaysPerSeason=31),PlotHyetographs=FALSE,RandSeed=NULL)
Length |
A positive integer that specifies the length of synthetic time series of rainfall depth which is generated through the Bartlett-Lewis model, in the case that historic data is not imported from an external file. |
TimeScale |
A positive number that specifies the time scale at which the daily values are to be disaggregated. Please make sure that for the argument |
BLpar |
List of the Bartlett-Lewis model parameters. See |
CellIntensityProp |
List of arguments that specifies the distribution of cell intensity. See |
RepetOpt |
List of parameters that specifies the disaggregation algorithm behavior. See |
NumOfSequences |
A positive integer that specifies the number of wet days sequences to be disaggregated. To disaggregate all clusters of wet days set a large number (e.g., 1000). Default is |
Statistics |
List of logical variables (TRUE/FALSE) that indicate whether the main statistical characteristics of historical and disaggregated data should be printed or plotted. If |
ImportHistData |
List of parameters that specifies the import of historical rainfall depths from an external file. See |
ExportSynthData |
List of parameters that specifies the export of disaggregated rainfall depths to an output file. See |
PlotHyetographs |
A logical variable (TRUE/FALSE) indicating whether original and synthetic hyetographs should be plotted. See |
RandSeed |
An integer value for the random number generator. If it is equal to NULL, then a random seed is not inserted. |
The function DisagSimul.test
enables the disaggregation of daily rainfall into hourly or sub-hourly rainfall. It uses the Bartlett-Lewis rainfall model as a background stochastic model for rainfall generation.Then, it uses repetitions to derive a synthetic rainfall series that resembles the given series at the daily scale and, then, an appropriate adjusting procedure, namely the proportion adjusting procedure, to make the generated series fully consistent with the given daily series. For more detailed information on the disaggregation scheme, see the list of references
.
If an input file of rainfall depths is not available (imp=FALSE
), an initial sequence of storms is generated using the Bartlett-Lewis model with the given parameters and then via aggregation the daily series is obtained. The daily sequence serves then as an "original" series, which is disaggregated, thus producing another synthetic lower-level series. The length of synthetic time series of rainfall depth which is generated through the Bartlett-Lewis model is specifying by Length
argument. If an input file of rainfall depths is available (imp=TRUE
), the daily sequence is imported from this file rather than generated.
The main statistical characteristics of the original and synthetic data can be either printed or displayed graphically. Additionally, the disaggregated rainfall depths and the synthetic hyetograph of each cluster of wet days 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).
Disaggregation scheme options
Argument RepetOpt
is a list of parameters that specifies any changes to the default values of disaggregation repetition scheme.
The scheme incorporates four levels of repetition. The number of Level 1 repetitions is determined by multiplying the FacLevel1Rep
by the number of attempts to establish an appropriate sequence of wet days (Level 0 repetitions, which is not given by the user but rather is determined by the program). In this manner, the more the number of required Level 0 repetitions is, the more the number of Level 1 repetitions, and the less the number of Level 2 repetitions, will be. This results in a faster algorithm. The number of allowed Level 1 repetitions cannot be set lower than MinLevel1Rep
. The total number of Level 1 and Level 2 repetitions cannot exceed the TotalRepAllowed
.
In the case that the model is not able to establish an appropriate sequence of wet days (Level 0 repetitions) after a large number of repetitions (10*TotalRepAllowed
), then NA values are returned. NA values are also returned in the case that the system is not able to obtain cell intensities with the desired properties (Level 1 repetitions). The wet days that were not disaggregated successfully are excluded from the statistical analysis.
A positive number that specifies the distance used to judge whether synthetic daily depths resemble the real ones. Default is DistAllowed=0.1
.
A positive number that specifies the factor for Level 1 repetitions. Default is FacLevel1Rep=20
.
A positive integer that specifies the minimum number of Level 1 repetitions. Default is FacLevel1Rep=50
.
A positive integer that specifies the total repetitions. Default is TotalRepAllowed=5000
.
Argument Statistics
is a list of logical variables (TRUE/FALSE) that indicates whether the main statistical characteristics of synthetic data are 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.
Read historical data from file
Argument ImportHistData
is a list of parameters specifying the features of input file that contains the original rainfall depths to be disaggregated. The input file must have a specific format (see examples
).
A logical variable (TRUE/FALSE) that indicates if original rainfall depths should be imported from an input file. If imp=TRUE
, the original data is imported from a file. Default is imp=FALSE
.
A character string that specifies the name of the file or connection where the rainfall data are located. 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. To import 1 minute rainfall depths, set 1/60, 1/30 for 2 minutes data, 1/6 for 10 minutes data etc.
A character string indicating if dry days (with zero rainfall depths) are also included 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 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 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 character vector of strings which are to be interpreted as NA
values. Default is na.values="NA"
.
In the case that the time scale of input data (ImpDataTimeScale
argument) is greater than the time scale of disaggregation (TimeScale
argument), then the system ignores the input data and generates a new "original" series via Bartlett-Lewis model.
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 in an input file determine the dates of the original 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 data of rainfall depth.
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.
Export 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. The output file always contains the synthetic rainfall depths listed in increasing order of date.
A logical variable (TRUE/FALSE) that indicates whether synthetic rainfall depths should be written to an output file. If exp=TRUE
, synthetic data are exported to a text file. Default is exp=FALSE
.
A character string that specifies the name of the file or connection where the rainfall data is to be exported. The output files are text files with the ".txt" extension (e.g. file="SynthData.txt"
).
A character string indicating whether dry days 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 PlotHyetographs
is a logical variable (TRUE/FALSE) indicating whether original and synthetic hyetographs is to be plotted. If PlotHyetographs=TRUE
, hyetographs of the clusters of wet days are exported as PDF files, in the chosen working directory. The name of each pdf file corresponds to the starting date of disaggregated cluster.
The examples below and the used parameters are indicative. Subsequently, new parameters for the Bartlett-Lewis model should be estimated for other datasets.
A list with the following components:
Disaggregated rainfall depths |
A list of matrices that contains the disaggregated rainfall depths of each cluster of wet days. |
Statistics |
List of matrices of the the main statistical characteristics of the historical and synthetic data (all data values, wet days values and wet hours values). The statistics are printed if |
If plot
is TRUE
, the statistics are plotted on screen device .
If exp
is TRUE
, the disaggregated rainfall depths are exported to a text file. See Details
for further information.
If PlotHyetographs
is TRUE
, the historical and synthetic hyetograph of each cluster of wet days are plotted, . See Details
for further information.
Kossieris Panagiotis pkossier@central.ntua.gr
The methodology of HyetosMinute and details of its application are described in:
Panagiotis Kossieris, Christos Makropoulos, Christian Onof, Demetris Koutsoyiannis, A rainfall disaggregation scheme for sub-hourly time scales: Coupling a Bartlett-Lewis based model with adjusting procedures, Journal of Hydrology, Available online 11 July 2016, ISSN 0022-1694, http://dx.doi.org/10.1016/j.jhydrol.2016.07.015.
http://www.sciencedirect.com/science/article/pii/S0022169416304450 or
Koutsoyiannis, D., and C. Onof, Rainfall disaggregation using adjusting procedures on a Poisson cluster model, Journal of Hydrology, 246, 109-122, 2001.
Koutsoyiannis, D., and C. Onof, A computer program for temporal rainfall disaggregation using adjusting procedures (HYETOS), XXV General Assembly of European Geophysical Society, Nice, Geophysical Research Abstracts, 2, 2000.
For Bartlett-Lewis rectangular pulse rainfall 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
For disaggregation by adjusting procedures the user is referenced to:
Koutsoyiannis, D., A stochastic disaggregation method for design storms and flood synthesis, Journal of Hydrology, 156, 193-225, 1994.
Koutsoyiannis, D., and A. Manetas, Simple disaggregation by accurate adjusting procedures, Water Resources Research, 32(7), 2105-2117, 1996.
Koutsoyiannis, D., Coupling stochastic models of different time scales, Water Resources Research, 37(2), 379-391, 2001.
Koutsoyiannis, D., Rainfall Disaggregation Methods: Theory and Applications, Workshop on Statistical and Mathematical Methods for Hydrological Analysis, Rome, 2003.
Find older versions of Hyetos at http://itia.ntua.gr/en/softinfo/3/
# Example 1: Disaggregate daily rainfall depths into hourly, # using the the original Bartlett-Lewis model # The original hourly series is generated by the model # To disaggregate the daily rainfall depths of first 5 clusters of wet days use ex11 <- DisagSimul.test(Length=100,TimeScale=1,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),RepetOpt=list(DistAllowed=0.1, FacLevel1Rep=20,MinLevel1Rep=50,TotalRepAllowed=5000),NumOfSequences=5, Statistics=list(print=TRUE,plot=FALSE),ExportSynthData=list(exp=FALSE,FileContent=c("AllDays"), file="BLts.txt",DaysPerSeason=31),ImportHistData=list(imp=FALSE,file="heathrow1a.txt", na.values="NA",FileContent=c("WetDays"),DailyValues=TRUE,DaysPerSeason=31,ImpDataTimeScale=1), PlotHyetographs=FALSE,RandSeed=5) # Example 2: Disaggregate historical daily rainfall depths # into hourly, with the random parameter # Bartlett-Lewis model, with cell intensities # from gamma distribution # The original (daily and hourly) data is imported # from the "HistHourlyData2.txt" file # The synthetic hourly depths are exported to "DisagHistHourlyData2.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 disaggregate the daily rainfall depths of first 5 clusters of wet days use ex12 <- DisagSimul.test(Length=100,TimeScale=1,BLpar=list(lambda=0.45967,phi=0.03946, kappa=0.1479426,alpha=3.9529358,v=0.014187,mx=158.109,sxmx=55.6506/158.109), CellIntensityProp=list(Weibull=FALSE,iota=NA),RepetOpt=list(DistAllowed=0.1, FacLevel1Rep=20,MinLevel1Rep=50,TotalRepAllowed=5000),NumOfSequences=5, Statistics=list(print=TRUE,plot=FALSE),ExportSynthData=list(exp=TRUE, FileContent=c("AllDays"),file="DisagHistHourlyData2.txt",DaysPerSeason=30), ImportHistData=list(imp=TRUE,file="HistHourlyData2.txt",na.values="NA",FileContent=c("AllDays"), DailyValues=TRUE,DaysPerSeason=30,ImpDataTimeScale=1),PlotHyetographs=FALSE,RandSeed=5) # Example 3: Disaggregate daily rainfall depths into 5-min intervals, # with the random parameter Bartlett-Lewis model, with cell intensities # from gamma distribution # The original 5-min series is generated by the model # The daily data is produced via aggregation of the original 5-min data # Disaggregated 5-min data is exported to "SynthRPBLGM.txt" file # To disaggregate the daily rainfall depths of first 5 clusters of wet days use ex13 <- DisagSimul.test(Length=100,TimeScale=1/12,BLpar=list(lambda=0.024*24,phi=0.040, kappa=0.173,alpha=2,v=0.1855804/24,mx=NA,sxmx=1),CellIntensityProp=list(Weibull=FALSE, iota=0.879),RepetOpt=list(DistAllowed=0.1,FacLevel1Rep=20,MinLevel1Rep=50,TotalRepAllowed=5000), NumOfSequences=5,Statistics=list(print=TRUE,plot=FALSE), ExportSynthData=list(exp=TRUE,FileContent=c("AllDays"),file="Disag10minData.txt",DaysPerSeason=31), ImportHistData=list(imp=FALSE,file="data.txt",na.values="NA",FileContent=c("AllDays"), DailyValues=TRUE,DaysPerSeason=31,ImpDataTimeScale=1/12),PlotHyetographs=FALSE,RandSeed=5) # Example 4: Disaggregate daily rainfall depths into 5-min intervals, # with the random parameter Bartlett-Lewis model, with cell intensities # from gamma distribution # The original 5-min series is imported from "Hist5minData.txt" file # Disaggregated 5-min data is exported to "Hist5minData_Disag.txt" file # To load the data set "HistHourlyData2" use data(Hist5minData) # To export the daily and hourly rainfall depths of "HistHourlyData2" data #in the chosen working directory use write.table(Hist5minData,file="Hist5minData.txt",sep="\t", quote=FALSE,row.names=FALSE,col.names=FALSE) # To disaggregate the daily rainfall depths of first 5 clusters of wet days use ex14 <- DisagSimul.test(Length=100,TimeScale=1/12,BLpar=list(lambda=0.024*24,phi=0.040, kappa=0.173,alpha=2,v=0.1855804/24,mx=NA,sxmx=1),CellIntensityProp=list(Weibull=FALSE, iota=0.879),RepetOpt=list(DistAllowed=0.1,FacLevel1Rep=20,MinLevel1Rep=50,TotalRepAllowed=5000), NumOfSequences=5,Statistics=list(print=TRUE,plot=FALSE), ExportSynthData=list(exp=TRUE,FileContent=c("AllDays"),file="Hist5minData_Disag.txt", DaysPerSeason=31),ImportHistData=list(imp=TRUE,file="Hist5minData.txt", na.values="NA",FileContent=c("AllDays"),DailyValues=TRUE,DaysPerSeason=31, ImpDataTimeScale=1/12),PlotHyetographs=FALSE,RandSeed=5)