Define MAX Data with Time Stamps

Define MAX data with time stamps that can be used with time-varying extreme-value models.

Usage

timeMAXdata(..., blocks = FALSE)

Arguments

...: A named collection of objects each being a list or a numeric vector. See Examples.
blocks: Logical. If TRUE, the results contain a a list of block time series corresponding to the periods. More precisely, each row of the MAXdata data frame correspond to a block, usually with a one-year duration.

Value

An object with class timeMAXdata. This is mainly a list with the following two elements.

MAXinfo A data frame with columns period, start, end, duration. Each row corrrespond to a period or time range with beginning, end and duration indicated by the columns.
MAXdata A data frame with columns block, period, date, y, yL, yU. The column block is for compatibility reason, period links do MAXinfo. The column date give the date of an event in the period or the begining of the year. The columns y, yL and yU give the observed level for the variable of interest and the bounds when the observation is censored.

Unfortunately the name block in MAXdata does not correspond to a block in the block maxima meaning, but rather to a period or time range.

Details

This data structure is inspired by the MAX data structure of Renext. The data relates to a certain variable which is recorded in time but can be censored over periods. The data describes a number of periods in time (or time ranges, see timeRange), in general as so-called historical period. For each period, the largest observations of the variable are given along with a year or date at which the observation was made. The observations for a period are given either as a named numeric vector or as a named list, the names being dates or years in both cases. When a numeric vector is given, each element of the vector is the observation for the year of date. When a list is given, a list element can be either a vector of length \(1\) giving the observation or a vector of length \(2\) giving the lower and upper bounds of an interval in which the observation is known to lie: this is interval censoring. An upper bound can be Inf. However a lower bound can not be -Inf in the block maxima framework unless the period is a one-block period.

Caution

Within a given period, we find observations (I) for which some information is given explicitly, and observations (N) for which no information explicitely given. The observations (N) are assumed to be smaller than all the observations (I), hence to be smaller than the smallest lower bound provided for the observations (I), say minyL. As a result, each observation (N) is considered as surely lying in the interval (-Inf, minyL). So as a rule, an explicit information (yL, yU) should correspond to a quite large value of yL because this applies to one of the (few) largest observation in the period.

Examples

## block maxima style. There should be only one observation by block (year)
timeMAXdata("1961_1980" = list("1961" = 7, "1973" = 40, "1979" = c(3, 30)),
            "1930_1960" = list("1940" = c(14, Inf), "1943" = 22),
            "1900_1929" = list("1910" = c(10, Inf), "1929" = c(20, 30))) 
#> $MAXinfo
#>      period      start        end duration
#> 1 1900_1929 1900-01-01 1930-01-01       30
#> 2 1930_1960 1930-01-01 1961-01-01       31
#> 3 1961_1980 1961-01-01 1981-01-01       20
#> 
#> $MAXdata
#>   block    period       date  y yL  yU
#> 1     1 1900_1929 1910-01-01 NA 10 Inf
#> 2     1 1900_1929 1929-01-01 NA 20  30
#> 3     2 1930_1960 1940-01-01 NA 14 Inf
#> 4     2 1930_1960 1943-01-01 22 22  22
#> 5     3 1961_1980 1961-01-01  7  7   7
#> 6     3 1961_1980 1973-01-01 40 40  40
#> 7     3 1961_1980 1979-01-01 NA  3  30
#> 
#> attr(,"class")
#> [1] "timeMAXdata"

## marked process (POT) style. The observations are attached to a day,
## so there can 
timeMAXdata("1961_1980" = list("1961-12-02" = 7, "1973-12-20" = 40,
                               "1976-01-21" = c(3, 30), "1979-02-19" = 27),
            "1930_1960" = list("1940" = c(14, Inf), "1943" = 22),
            "1900_1929" = list("1910" = c(10, Inf), "1929" = c(12, 30))) 
#> $MAXinfo
#>      period      start        end duration
#> 1 1900_1929 1900-01-01 1930-01-01       30
#> 2 1930_1960 1930-01-01 1961-01-01       31
#> 3 1961_1980 1961-01-01 1981-01-01       20
#> 
#> $MAXdata
#>   block    period       date  y yL  yU
#> 1     1 1900_1929 1910-01-01 NA 10 Inf
#> 2     1 1900_1929 1929-01-01 NA 12  30
#> 3     2 1930_1960 1940-01-01 NA 14 Inf
#> 4     2 1930_1960 1943-01-01 22 22  22
#> 5     3 1961_1980 1961-12-02  7  7   7
#> 6     3 1961_1980 1973-12-20 40 40  40
#> 7     3 1961_1980 1976-01-21 NA  3  30
#> 8     3 1961_1980 1979-02-19 27 27  27
#> 
#> attr(,"class")
#> [1] "timeMAXdata"