weeklyfunction: Weekly Function
In hzambran/hydroTSM: Time Series Management and Analysis for Hydrological Modelling

weeklyfunction

R Documentation

Weekly Function

Description

Generic function for obtaining 52 weekly values of a zoo object, by applying any R function to ALL the values in the object belonging to each one of the 52 calendar weeks (starting on Monday).

Usage

weeklyfunction(x, ...)

## Default S3 method:
weeklyfunction(x, FUN, na.rm=TRUE, na.rm.max=0, start="00:00:00", 
                                 start.fmt= "%H:%M:%S", tz, ...)

## S3 method for class 'zoo'
weeklyfunction(x, FUN, na.rm=TRUE, na.rm.max=0, start="00:00:00", 
                             start.fmt= "%H:%M:%S", tz, ...)

## S3 method for class 'data.frame'
weeklyfunction(x, FUN, na.rm=TRUE, na.rm.max=0, start="00:00:00", 
                        start.fmt= "%H:%M:%S", tz, dates=1, date.fmt="%Y-%m-%d",
                        out.type="data.frame", verbose=TRUE,...)
             
## S3 method for class 'matrix'
weeklyfunction(x, FUN, na.rm=TRUE, na.rm.max=0, start="00:00:00", 
                        start.fmt= "%H:%M:%S", tz, dates=1, date.fmt="%Y-%m-%d",
                        out.type="data.frame", verbose=TRUE,...)

Arguments

`x`	zoo, xts, data.frame or matrix object, with daily or monthly 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 applied to ALL the values in `x` belonging to each one of the 12 months of the year (e.g., FUN can be some of `mean`, `sum`, `max`, `min`, `sd`).
`na.rm`	Logical. Should missing values be removed? -) `TRUE` : the monthly values and FUN are computed considering only those values in `x` different from NA -) `FALSE`: if there is AT LEAST one NA within a month, the corresponding monthly value will be NA
`na.rm.max`	Numeric in [0, 1]. It is used to define the maximum percentage of missing values allowed in each month to keep the weekly aggregated value in the output object of this function. In other words, if the percentage of missing values in a given month is larger or equal than `na.rm.max` the corresponding weekly value will be `NA`.
`start`	character, indicating the starting time used for aggregating sub-daily time series into daily ones. It MUST be provided in the format specified by `start.fmt`. This value is used to define the time when a new day begins (e.g., for some rain gauge stations). -) All the values of `x` with a time attribute before `start` are considered as belonging to the day before the one indicated in the time attribute of those values. -) All the values of `x` with a time attribute equal to `start` are considered to be equal to `"00:00:00"` in the output zoo object. -) All the values of `x` with a time attribute after `start` are considered as belonging to the same day as the one indicated in the time attribute of those values. It is useful when the daily values start at a time different from `"00:00:00"`. Use with caution. See examples.
`start.fmt`	character indicating the format in which the time is provided in `start`, By default `date.fmt=%H:%M:%S`. See `format` in `as.POSIXct`.
`tz`	character, with the specification of the time zone used in both `x` and `start`. System-specific (see time zones), but `""` is the current time zone, and `"GMT"` is UTC (Universal Time, Coordinated). See `Sys.timezone` and `as.POSIXct`. If `tz` is missing (the default), it is automatically set to the time zone used in `time(x)`. This argument can be used to force using the local time zone or any other time zone instead of UTC as time zone.
`dates`	It is only used when `x` is not a zoo object. numeric, factor, Date indicating how to obtain the dates. 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 is 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`	It is only used when `x` is not a zoo object. 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"`.
`out.type`	It is only used when `x` is a matrix or data.frame. Character defining the desired type of output. Valid values are: -) `data.frame`: a data.frame, with 12 columns representing the months, and as many rows as gauging stations are included in `x` -) `db` : a data.frame, with 4 columns will be produced. Useful for a posterior boxplot The first column ('StationID') will store the ID of the station, The second column ('Year') will store the year, The third column ('Month') will store month, The fourth column ('Value') will contain the monthly value corresponding to the three previous columns.
`verbose`	Logical; if TRUE, progress messages are printed
`...`	further arguments passed to or from other methods

Value

When x is a zoo object, a numeric vector with 12 elements representing the computed monthly value for each month.
When x is a data.frame which columns represent measurements at different gauging stations, the resulting object is a data.frame with 12 columns and as many rows as gauging stations are in x, each row storing the computed 12 monthly value for each gauging station.

Note

Due to the fact that FUN is applied over all the elements in x belonging to a given calendar month, its result will depend on the sampling frequency of x and the type of function provided by FUN (special attention have to be put when FUN=sum)

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

## Ex1: Computation of mean WEEKLY values from DAILY ts, removing any missing value in 'x'

# Loading DAILY streamflows (3 years) at the station 
# Oca en Ona (Ebro River basin, Spain)
data(OcaEnOnaQts)
x <- OcaEnOnaQts

## Mean WEEKLY streamflows at station 'x'
weeklyfunction(x, FUN=mean, na.rm=TRUE)

######################
## Ex2: Computation of mean WEEKLY values from HOURLY ts, removing any missing value in 'x'

# Loading HOURLY streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

## Mean WEEKLY streamflows at station 'x'. Each day starts at 00:00:00
weeklyfunction(x, FUN=mean, na.rm=TRUE)

######################
## Ex3: Computation of mean WEEKLY values from HOURLY ts, removing any missing value in 'x'
##      and starting each day at 08:00:00

# Loading HOURLY streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

## Mean WEEKLY streamflows at station 'x'. Each day starts at 00:00:00
weeklyfunction(x, FUN=mean, na.rm=TRUE, start="00:00:00")

hzambran/hydroTSM documentation built on April 29, 2024, 3:12 a.m.