annualfunction: Annual Function

Description

Generic function for obtaining a SINGLE annual value of a zoo object, by applying any R function to ALL the values in x belonging to the same year, and then applying the same function to ALL the previously computed annual values (e.g., for computing the average annual precipitation or the mean annual streamflow of a long-term time series).

Usage

annualfunction(x, FUN, na.rm = TRUE, ...)
# S3 method for default
annualfunction(x, FUN, na.rm = TRUE, ...)
# S3 method for zoo
annualfunction(x, FUN, na.rm = TRUE, ...)
# S3 method for data.frame
annualfunction(x, FUN, na.rm = TRUE, dates=1, date.fmt = "%Y-%m-%d", 
        verbose = TRUE, ...)
        
# S3 method for matrix
annualfunction(x, FUN, na.rm = TRUE, dates=1, date.fmt = "%Y-%m-%d", 
        verbose = TRUE, ...)

Value

When x is a time series, a single annual value is returned.

For a data frame, a named vector with the appropriate method being applied column by column.

Arguments

x: zoo, xts, data.frame or matrix object, with daily/monthly/annual time series.
Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
FUN: Function that will be used to compute the final annual value (e.g., FUN may be some of mean, sum, max, min, sd) .
na.rm: Logical. Should missing values be removed?.
-) TRUE : the annual values are computed considering only those values different from NA
-) FALSE: if there is AT LEAST one NA within a year, the resulting annual value will be NA
dates: numeric, factor or Date object indicating how to obtain the dates corresponding to each gauging station.
If dates is a number (default), it indicates the index of the column in x that stores the dates
If dates is a factor, it have to be converted into Date class, using the date format specified by date.fmt
If dates is already of Date class, the code verifies that the number of days in dates be equal to the number of elements in x
date.fmt: character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date.
ONLY required when class(dates)=="factor" or class(dates)=="numeric".
verbose: Logical; if TRUE, progress messages are printed.
...: further arguments passed to or from other methods.

Author

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

Run this code

## Loading the SanMartino daily precipitation data (1921-1990)
data(SanMartinoPPts)
x <- SanMartinoPPts

# Amount of years in 'x' (needed for computing the average)
nyears <- length( seq(from=time(x[1]), to=time(x[length(x)]), by="years") )

## Average annual precipitation for the 70 years period. 
# It is necessary to divide by the amount of years to obtain the average annual value, 
# otherwise it will give the total precipitation for all the 70 years.
annualfunction(x, FUN=sum, na.rm=TRUE) / nyears


#####################
### verification ####
# Daily to annual
a <- daily2annual(x, FUN=sum, na.rm=TRUE)

# Mean annual value
mean(a)

##############################
##############################
## Loading the monthly time series of precipitation within the Ebro River basin.
data(EbroPPtsMonthly)
x <- EbroPPtsMonthly

## Dates of 'x'
dates <- as.Date(x[,1])


## Computation of the average annual precipitation
if (FALSE) {

## Transforming 'x' into a zoo object
z <- zoo( x[, 2:ncol(x)], dates)

# Amount of years in 'x' (needed for computing the average)
nyears <- yip(from=start(z), to=end(z), out.type="nmbr" )

## Average annual precipitation, for the first 5 stations in 'x'
annualfunction(z[ ,1:5], FUN=sum)/nyears
 
}