Type:	Package
Title:	Time Series Management and Analysis for Hydrological Modelling
Version:	0.7-0.1
Maintainer:	Mauricio Zambrano-Bigiarini <mzb.devel@gmail.com>
Description:	S3 functions for management, analysis, interpolation and plotting of time series used in hydrology and related environmental sciences. In particular, this package is highly oriented to hydrological modelling tasks. The focus of this package has been put in providing a collection of tools useful for the daily work of hydrologists (although an effort was made to optimise each function as much as possible, functionality has had priority over speed). Bugs / comments / questions / collaboration of any kind are very welcomed, and in particular, datasets that can be included in this package for academic purposes.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Depends:	R (≥ 3.5.0), zoo (≥ 1.7-2)
Imports:	xts (≥ 0.9-7), e1071, stats, utils, methods, graphics, grDevices, lattice, classInt
Suggests:	knitr, rmarkdown, gridExtra
VignetteBuilder:	knitr
URL:	https://github.com/hzambran/hydroTSM, https://cran.r-project.org/package=hydroTSM
MailingList:	https://stat.ethz.ch/mailman/listinfo/r-sig-ecology
BugReports:	https://github.com/hzambran/hydroTSM/issues
LazyLoad:	yes
NeedsCompilation:	no
Repository:	CRAN
Packaged:	2024-11-04 16:49:45 UTC; hornik
Author:	Mauricio Zambrano-Bigiarini [aut, cre, cph]
Date/Publication:	2024-11-04 16:55:31 UTC

Management, analysis, and plot of hydrological time series, with focus on hydrological modelling

Description

S3 functions for management, analysis, interpolation and plotting of time series used in hydrology and related environmental sciences. In particular, this package is highly oriented to hydrological modelling tasks. The focus of this package has been put in providing a collection of tools useful for the daily work of hydrologists (although an effort was made to optimise each function as much as possible, functionality has had priority over speed). Bugs / comments / questions / collaboration of any kind are very welcomed, and in particular, datasets that can be included in this package for academic purposes.

Details

—————————————————————————————————————————
Datasets:

Temporal aggregation:

Temporal manipulation:

Hydrological functions:

Miscelaneous functions:

Author(s)

Mauricio Zambrano-Bigiarini

Maintainer: Mauricio Zambrano-Bigiarini <mzb.devel@gmail>

See Also

https://github.com/hzambran/hydroGOF.
https://github.com/hzambran/hydroPSO.

Examples

## Loading the monthly time series (10 years) of precipitation for the Ebro River basin.
data(EbroPPtsMonthly)

#######
## Ex1) Graphical correlation among the ts of monthly precipitation of the first 
##      3 stations in 'EbroPPtsMonthly' (its first column stores the dates).
hydropairs(EbroPPtsMonthly[,2:4])

#######
## Ex2) Annual values of precipitation at the station "P9001"
sname2ts(EbroPPtsMonthly, sname="P9001", dates=1, var.type="Precipitation", 
         tstep.out="annual")

#######
## Ex3) Monthly and annual plots
sname2plot(EbroPPtsMonthly, sname="P9001", var.type="Precipitation", pfreq="ma")


#######
## Ex5)  Mean monthly values of streamflows
## Loading daily streamflows (3 years) at the station 
## Oca en Ona (Ebro River basin, Spain)
data(OcaEnOnaQts)
monthlyfunction(OcaEnOnaQts, FUN=mean, na.rm=TRUE)

(sub)Daily/Monthly -> Annual

Description

Generic function for transforming a (sub)DAILY/MONTHLY (weekly and quarterly) regular time series into an ANNUAL one.

Usage

daily2annual(x, ...)
subdaily2annual(x, ...)
monthly2annual(x, ...)

## Default S3 method:
daily2annual(x, FUN, na.rm=TRUE, na.rm.max=0, out.fmt="%Y", ...)

## S3 method for class 'zoo'
daily2annual(x, FUN, na.rm=TRUE, na.rm.max=0, out.fmt="%Y-%m-%d", ...)

## S3 method for class 'data.frame'
daily2annual(x, FUN, na.rm=TRUE, na.rm.max=0, out.fmt="%Y", dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", verbose = TRUE, ...)

## S3 method for class 'matrix'
daily2annual(x, FUN, na.rm = TRUE, na.rm.max=0, out.fmt="%Y", 
        dates=1, date.fmt = "%Y-%m-%d", out.type = "data.frame", verbose = TRUE, ...)

Arguments

Value

When FUN!=max and FUN!=min the output is a zoo object with annual time frequency, where the time attribute has the format defined in out.fmt.
When FUN!=max and FUN!=min and out.fmt="%Y-%m-%d" the time attribute of the output zoo object will use the 1st of January of each year to create a full Date object from the corresponding year of each element of the output object (e.g., fi the year is 2022, the time attribute will be 2022-01-01). The only exception occurrs when FUN=max or FUN=min, where the time attribute of each element will correspond to the actual date where the annual maximum/minimum occurs (which is very useful for identifying the date of the annual maximum or the annual minimum of a time series).

When FUN=max or FUN=min and x is a single time series, the output is a zoo object with annual time frequency, where the time attribute has the same class than time(x), and the date(time) value corresponds to the date(time) where the maximum/minimum value actually occurs.
When FUN=max or FUN=min and x has two or more time series, the output is a list object where each element has an annual time frequency. The time attribute of each list element has the same class than time(x), and the date(time) value of each list element corresponds to the date(time) where the maximum/minimum value actually occurs.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

subhourly2hourly, daily2monthly, monthly2annual, hydroplot, annualfunction, vector2zoo, as.Date

Examples

######################
## Ex1: Computation of annual values, removing any missing value in 'x'

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three months (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Agreggating from Daily to Annual, removing any missing value in 'x'
( a <- daily2annual(x, FUN=sum, na.rm=TRUE) )

######################
## Ex2: Compuation of annual values only when the percentage of NAs in each
#       year is lower than a user-defined percentage (10% in this example).

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three months (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Daily to annual, only for months with less than 10% of missing values
( a2 <- daily2annual(x, FUN=sum, na.rm=TRUE, na.rm.max=0.1) )

# Verifying that the second and third month of 'x' had 10% or more of missing values
cmv(x, tscale="annual")


######################
## Ex3: Getting the annual maximum value, including the date where this annual 
##      maximum actually occurs
daily2annual(x, FUN=max)


######################
## Ex4: Monthly to Annual (same result as )
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)
monthly2annual(m, FUN=sum, na.rm=TRUE)


######################
## Ex5: Loading the time series of HOURLY streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

# Sub-daily to monthly ts
subdaily2annual(x, FUN=mean, na.rm=TRUE)

############
## Ex6: Loading the monthly time series of precipitation within the Ebro River basin
data(EbroPPtsMonthly)

# computing the annual values for the first 10 gauging stations in 'EbroPPtsMonthly'
a <- monthly2annual(EbroPPtsMonthly[,1:11], FUN=sum, dates=1)

# same as before, but with a nicer format of years
a <- monthly2annual(EbroPPtsMonthly[,1:11], FUN=sum, dates=1, out.fmt="%Y")

(sub)Daily -> Monthly

Description

Generic function for transforming a DAILY (sub-daily or weekly) regular time series into a MONTHLY one

Usage

daily2monthly(x, ...)
subdaily2monthly(x, ...)

## Default S3 method:
daily2monthly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

## S3 method for class 'zoo'
daily2monthly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

## S3 method for class 'data.frame'
daily2monthly(x, FUN, na.rm=TRUE, na.rm.max=0, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", out.fmt="numeric", 
        verbose=TRUE, ...)

## S3 method for class 'matrix'
daily2monthly(x, FUN, na.rm=TRUE, na.rm.max=0, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", out.fmt="numeric", 
        verbose=TRUE, ...)

Arguments

Value

a zoo object with monthly time frequency

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

cmv, subhourly2hourly, daily2annual, subdaily2daily, monthlyfunction, hydroplot, vector2zoo, izoo2rzoo, as.Date

Examples

######################
## Ex1: Computation of monthly values, removing any missing value in 'x'

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three months (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Agreggating from Daily to Monthly, removing any missing value in 'x'
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)

######################
## Ex2: Computation of monthly values only when the percentage of NAs in each
#       month is lower than a user-defined percentage (10% in this example).

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three months (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Daily to monthly, only for months with less than 10% of missing values
m2 <- daily2monthly(x, FUN=sum, na.rm=TRUE, na.rm.max=0.1)

# Verifying that the second and third month of 'x' had 10% or more of missing values
cmv(x, tscale="month")

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

# Sub-daily to monthly ts
subdaily2monthly(x, FUN=mean, na.rm=TRUE)

Hydrometeorological time series for "Cauquenes en El Arrayan" catchment

Description

Daily time series of precipitation, maximum air temperature, minimum air temperature, potential evapotranspiration, and observed streamflows for the catchment draining into the 'Cauquenes en El Arrayan' streamflow station (Cod.BNA: 7336001, Lat:-36.02, Lon:-72.38). This catchment is located in El Maule Region in Chile, with a pluvial regime, a total drainage area of 622.1 km2, and elevations ranging from 134 to 736 m a.s.l. Data were downloaded from the CAMELS-CL dataset (https://camels.cr2.cl) from 01/Jan/1979 to 31/Dec/2019 (including some missing values).

Usage

data(Cauquenes7336001)

Format

zoo matrix with 5 time series:
-) P_mm: Spatially-averaged mean daily values of precipitation computed based on the CR2met dataset, [mm/day].
-) Tmx_degC: Spatially-averaged maximum daily values of air temperature computed based on the CR2met dataset, [degree Celsius].
-) Tmin_degC: Spatially-averaged minimum daily values of air temperature computed based on the CR2met dataset, [degree Celsius].
-) PET_mm: Spatially-averaged mean daily values of precipitation computed based on the Hargreaves-Samani equation and daily maximum and minimum air temperatures obtained from the CR2met dataset, [mm/day].
-) Qobs_mm: Daily sreamflows, [mm], measured at the "Cauquenes en El Arrayan" (7336001) station.
-) Qobs_m3s: Daily sreamflows, [m3/s], measured at the "Cauquenes en El Arrayan" (7336001) station.

Source

Provided by Center for Climate and Resilience Research, Universidad de Chile, Santiago, Chile (https://camels.cr2.cl/, last accessed [Nov 2023]).
These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

References

Alvarez-Garreton, C., Mendoza, P. A., Boisier, J. P., Addor, N., Galleguillos, M., Zambrano-Bigiarini, M., Lara, A., Puelma, C., Cortes, G., Garreaud, R., McPhee, J., and Ayala, A (2018). The CAMELS-CL dataset: catchment attributes and meteorology for large sample studies-Chile dataset. Hydrology and Earth System Sciences, 22(11), 5817-5846. doi:10.5194/hess-22-5817-2018.

Ebro Monthly Precipitation Time Series

Description

Time series of monthly precipitation on 331 stations of the Ebro River basin (NW Spain), for the period January/1961 to December/1963.

Usage

data(EbroPPtsMonthly)

Format

A data.frame with 331 monthly time series, plus the first field storing the dates corresponding to each row.

Details

Monthly time series of precipitation on 331 stations of the Ebro River basin (Spain), where some data were in-filled by using the MOSS method and from daily time series used in the technical report "Estudio de Recursos de la Cuenca del Ebro".

Source

Downloaded from the web site of the Confederacion Hidrografica del Ebro (CHE) http://www.chebro.es/ (original link http://oph.chebro.es/DOCUMENTACION/PrecipitacionMensualRelleno/PrecipitacionMensualRelleno.html, last accessed [March 2010]).
These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

Karamea at Gorge, time series of hourly streamflows

Description

Time series with hourly streamflows for the Karamea River(New Zealand) measured at the gauging station "Gorge", for the period 01/Jan/1980 to 31/Dec/1985. Station Number: 95102, Easting Coordinate (NZMG): 2444629.0, Northing Coordinate (NZMG): 5994427.0, Catchment Area (km2): 1160.0.

In November 25th, 2023, the time zone of this data sete was changed from "none" (i.e., your local time zone was used every time you loaded this dataset) to GMT+12, in order to avoid missing datetimes at times where daylight saving time ocurred. After this change, the initial DateTime of this dataset changed from "1980-01-01 08:15:00 -03" (in my local computer) to "1980-01-01 00:15:00" (everywhere). Only two NA elements were removed from the origanl dataset: the first one and the last one.

Usage

data(KarameaAtGorgeQts)

Format

zoo object.

Source

Provided by the National Institute of Water and Atmospheric Research https://niwa.co.nz/, thanks to the gentle collaboration of Shailesh Singh

These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

San Martino, ts of daily precipitation.

Description

Daily time series of precipitation, maximum and minimun air temperature at station Maquehue Temuco Ad. (DMC_ID:380013), Araucania Region, Chile (Lat:-38.770, Lon:-72.637), with data from 01/Jan/1950 to 31/Dec/2015 (including some gaps).

Usage

data(MaquehueTemuco)

Format

zoo matrix with 3 columns:
-) pcp: daily precipitation, [mm/day].
-) tmx: daily maximum air temperature, [degree Celsius].
-) tmn: daily minimum air temperature, [degree Celsius].

Source

Provided by Center for Climate and Resilience Research, Universidad de Chile, Santiago, Chile (https://www.cr2.cl/bases-de-datos/, last accessed [Jan 2024]).
These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

Oca in "Ona" (Q0931), time series of daily streamflows.

Description

Time series with daily streamflows of the Oca River (subcatchment of the Ebro River basin, Spain) measured at the gauging station "Ona" (Q093), for the period 01/Jan/1961 to 31/Dic/1963

Usage

data(OcaEnOnaQts)

Format

zoo object.

Source

Downloaded from the web site of the Confederacion Hidrografica del Ebro (CHE) http://www.chebro.es/ (original link http://oph.chebro.es/documentacion/CaudalEA/CaudalEA.htm, last accessed [March 2010]).

These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

San Martino, ts of daily precipitation.

Description

Daily time series of precipitation, at station San Martino di Castrozza, Trento Province, Italy, with data from 01/Jan/1921 to 31/Dec/1990.

Usage

data(SanMartinoPPts)

Format

zoo object.

Source

Provided by MeteoTrentino, Trento, Italy (via prof. Riccardo Rigon).
These data are intended to be used for research purposes only, being distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

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, ...)

## Default S3 method:
annualfunction(x, FUN, na.rm = TRUE, ...)

## S3 method for class 'zoo'
annualfunction(x, FUN, na.rm = TRUE, ...)

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

Arguments

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.

Note

FUN is first applied to all the values of x belonging to the same year and then it is applied to all the previously computed annual values to get the final result. 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

See Also

monthlyfunction, daily2annual, monthly2annual, yip

Examples

## 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
## Not run: 

## 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
 

## End(Not run)

Baseflow

Description

Given a complete (without missing values) series of streamflow, this function computes the baseflow using the filter proposed by Arnold and Allen (1999).

Usage

baseflow(x, ...)

## S3 method for class 'zoo'
baseflow(x, beta=0.925, from=start(x), to=end(x), date.fmt, tz, 
         na.fill=c("none", "linear", "spline"), out.type=c("last", "all"), 
         plot=TRUE, xcol="black", bfcol=c("blue", "darkcyan", "darkorange3"),
         pch=15, cex=0.3, ...)

Arguments

Details

Although most procedures to separate baseflow from total streamflow are based on physical reasoning, some elements of all separation techniques are subjective.

The digital filter technique (Nathan and McMahon, 1990) implemented in this function was originally proposed by Lyne and Hollick (1979) for signal analysis and processing. Although this technique has no true physical meaning, it is objective and reproducible.

The equation of the filter is:

q(t) = Beta*q(t-1) + [ (1+Beta)/2 ]*[ Q(t) - Q(t-1) ]

where q(t) is the filtered surface runoff (quick response) at the time step t (one day), Q is the original streamflow, and Beta is the filter parameter (Beta=0.925). The value Beta=0.925 was obtained by Nathan and McMahon (1990) and Arnold et al. (1995) to give realistic results when compared to manual separation techniques.

Baseflow b(t) is then computed as:

b(t) = Q(t) - q(t)

The filter can be passed over the streamflow data three times (forward, backward, and forward), depending on the user' selected estimates of baseflow from pilot studies. In general, each pass will result in less baseflow as a percentage of total streamflow.

Value

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

References

Arnold, J. G., Allen, P. M., Muttiah, R., Bernhardt, G. (1995). Automated base flow separation and recession analysis techniques. Groundwater, 33(6), 1010–1018. doi:10.1111/j.1745-6584.1995.tb00046.x.

Arnold, J. G., Allen, P. M. (1999). Automated methods for estimating baseflow and ground water recharge from streamflow records. JAWRA Journal of the American Water Resources Association, 35(2), 411–424. doi:10.1111/j.1752-1688.1999.tb03599.x.

Lyne, V., Hollick, M. (1979). Stochastic time-variable rainfall-runoff modelling. Proceedings of the Hydrology and Water Resources Symposium, Perth, 10–12 September. Institution of Engineers National Conference Publication, No. 79/10, 89–92.

Nathan, R. J., & McMahon, T. A. (1990). Evaluation of automated techniques for base flow and recession analyses. Water resources research, 26(7), 1465–1473. doi:10.1029/WR026i007p01465.

See Also

plot_pq, hydroplot, fdc, fdcu

Examples

######################
## Ex1: Computing and plotting the baseflows for the full time period
##      of a given time series of streamflows.

## First, we load the daily Q time series for the Cauquenes en 
## El Arrayan catchment, where Q, [m3/s] are stored in the sixth column.
data(Cauquenes7336001)
q <- Cauquenes7336001[, 6]

## Computing the daily baseflow for the full time period
#baseflow(q) # it can not run due to NA values in 'x'

# filling the NA values using spline interpolation
baseflow(q, na.fill="spline") 

## Computing and plotting the daily baseflow for the full time period
baseflow(q, na.fill="spline", plot=TRUE)


######################
## Ex2: Computing and plotting the daily baseflow only for a 
##      specific time period, from April to December 2000.
baseflow(q, na.fill="spline", from="2000-04-01", to="2000-12-31")


######################
## Ex3: Computing and plotting the three daily baseflows (one for each pass 
##      of the filter) only for a specific time period, from April to December
##      2000.
baseflow(q, na.fill="spline", from="2000-04-01", to="2000-12-31", 
         out.type="all", plot=TRUE)

Calendar heatmap

Description

Function to plot a heatmap of a daily zoo object with a calendar shape

Usage

calendarHeatmap(x, ...)

## S3 method for class 'zoo'
calendarHeatmap(x, from, to, date.fmt="%Y-%m-%d",
                main="Calendar Heat Map",
                col=colorRampPalette(c("red", "orange", "yellow", "white", 
                    "lightblue2", "deepskyblue", "blue3"),  space = "Lab")(8),  
                cuts, cuts.dec=0, cuts.labels, 
                cuts.style=c("fisher", "equal", "pretty", "fixed", "sd", 
                             "quantile", "kmeans", "bclust", "mzb"), 
                legend.title="", legend.fontsize=15,              
                do.png=FALSE, png.fname="mypng.png", png.width=1500, 
                png.height=900, png.pointsize=12, png.res=90,
                do.pdf=FALSE, pdf.fname="mypdf.pdf", pdf.width=11,
                pdf.height=8.5, pdf.pointsize=12, ...)

Arguments

Details

The original function calendarHeat was developed by Paul Bleicher, as an R version of a graphic from http://stat-computing.org/dataexpo/2009/posters/wicklin-allison.pdf (not available any longer). The original function was made available online in 2009, but then it was removed. Now it is available at https://github.com/tavisrudd/r_users_group_1/blob/master/calendarHeat.R. The original function has "Copyright 2009 Humedica", but it was distributed under the GPL-2 licence, as well as this new version of the function.

This slighly modified verison of the function is also distributed under the GPL-2 licence, and teh main changes with respect to the original function are:

1) uses a zoo object instead of a numeric and character vector, for values and dates, respectively.
2) it allows a customisation of the mian title of the output figure.
3) it allows a customisation of the color palette.
4) it uses a categorical legend instead of a continuos one.
5) it is named calendarHeatmap instead of calendarHeat.

Value

The output of this function is a lattice figure with the calendar heatmap

Note

The maximum amount of years to be plotted is six (6).

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail.com

See Also

colorRampPalette, levelplot

Examples

###########
# EXAMPLE 1: basic plotting of a calendar heatmap
###########

# Loading daily streamflow data for Karamet at Gorges.
data(KarameaAtGorgeQts)

x <- KarameaAtGorgeQts
x <- subdaily2daily(x, FUN=mean)

# Temporal subsetting for a amaximum of 6 years
x <- window(x, start="1980-01-01", end="1985-12-31")

# Calendar Heatmap, 8 colours and cuts defined using Fisher method 
calendarHeatmap(x)

Climograph

Description

Function to draw a climograph based on precipitation and air temperature data, with several options for customisation.

Usage

climograph(pcp, tmean, tmx, tmn, na.rm=TRUE,  
           from, to, date.fmt="%Y-%m-%d", 
           main="Climograph", pcp.label="Precipitation, [mm]", 
           tmean.label="Air temperature, [\U00B0 C]", start.month=1, pcp.solid.thr,
           pcp.ylim, temp.ylim,pcp.col="lightblue", pcp.solid.col="skyblue2", 
           tmean.col="darkred", tmn.col="blue", tmx.col="red",
           pcp.labels=TRUE, 
           tmean.labels=TRUE, tmx.labels=TRUE, tmn.labels=TRUE,
           pcp.labels.cex=0.8, temp.labels.cex=0.8,
           pcp.labels.dx=c(rep(ifelse(plot.pcp.probs, -0.25,  0.0),6), 
                           rep(ifelse(plot.pcp.probs, -0.25,  0.0),6)),
           pcp.labels.dy=rep(2, 12),
           temp.labels.dx=c(rep(-0.2,6), rep(0.2,6)), temp.labels.dy=rep(-0.4, 12),
           plot.pcp.probs=TRUE, pcp.probs=c(0.25, 0.75),
           plot.temp.probs=TRUE, temp.probs=c(0.25, 0.75), 
           temp.probs.col=c("#3399FF", "#FF9966", "#FFCC66"),
           temp.probs.alpha=0.3,
           lat, lon
           )

Arguments

Note

If the output climograph present some mixed or not legible characters, you might try resizing the graphical window and run climograph again with the new size, until you get the climograph in the way you want to.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

monthlyfunction

Examples

######################
## Ex1: Loading the DAILY precipitation, maximum and minimum air temperature at 
##      station Maquehue Temuco Ad (Chile)
data(MaquehueTemuco)
pcp <- MaquehueTemuco[, 1]
tmx <- MaquehueTemuco[, 2]
tmn <- MaquehueTemuco[, 3]

## Plotting a full climograph
m <- climograph(pcp=pcp, tmx=tmx, tmn=tmn, na.rm=TRUE, 
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)

## Not run: 
## Plotting a climograph with uncertainty bands around mean values, 
## but with no labels for tmx and tmn
m <- climograph(pcp=pcp, tmx=tmx, tmn=tmn, na.rm=TRUE, tmx.labels=FALSE, tmn.labels=FALSE, 
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)

## Plotting a climograph with uncertainty bands around mean values, but with no labels for 
##  tmx, tmn and pcp
m <- climograph(pcp=pcp, tmx=tmx, tmn=tmn, na.rm=TRUE, 
                pcp.labels=FALSE, tmean.labels=FALSE, tmx.labels=FALSE, tmn.labels=FALSE, 
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)

## Plotting a climograph with no uncertainty bands around mean values
m <- climograph(pcp=pcp, tmx=tmx, tmn=tmn, na.rm=TRUE, plot.pcp.probs=FALSE, plot.temp.probs=FALSE, 
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)

## Plotting the most basic climograph: only mean values of precipiation and air temperature
m <- climograph(pcp=pcp, tmean=0.5*(tmn+tmx), na.rm=TRUE, plot.pcp.probs=FALSE, 
                plot.temp.probs=FALSE, main="Maquehue Temuco Ad (Chile)", 
                lat=-38.770, lon=-72.637)


## Plotting a full climograph, starting in April (start.month=4) instead of January (start.month=1),
## to better represent the hydrological year in Chile (South America)
m <- climograph(pcp=pcp, tmx=tmx, tmn=tmn, na.rm=TRUE, 
                start.month=4, temp.labels.dx=c(rep(-0.2,4), rep(0.2,6),rep(-0.2,2)),
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)


## Plotting a full climograph with monthly data
pcp.m <- daily2monthly(pcp, FUN=sum)
tmx.m <- daily2monthly(tmx, FUN=mean)
tmn.m <- daily2monthly(tmn, FUN=mean)
m <- climograph(pcp=pcp.m, tmx=tmx.m, tmn=tmn.m, na.rm=TRUE, 
                main="Maquehue Temuco Ad (Chile)", lat=-38.770, lon=-72.637)

## End(Not run)

Counting Missing Values

Description

Generic function for counting the percentage/amount of missing values in a zoo object, using a user-defined temporal scale.

Usage

cmv(x, ...)

## Default S3 method:
cmv(x, tscale=c("hourly", "daily", "weekly", "monthly", 
            "quarterly", "seasonal", "annual"),
            out.type=c("percentage", "amount"), dec=3, 
            start="00:00:00", start.fmt= "%H:%M:%S", tz, ...)

## S3 method for class 'zoo'
cmv(x, tscale=c("hourly", "daily", "weekly", "monthly", 
            "quarterly", "seasonal", "annual"),
            out.type=c("percentage", "amount"), dec=3, 
            start="00:00:00", start.fmt= "%H:%M:%S", tz, ...)

## S3 method for class 'data.frame'
cmv(x, tscale=c("hourly", "daily", "weekly", "monthly", 
            "quarterly", "seasonal", "annual"),
            out.type=c("percentage", "amount"), dec=3, 
            start="00:00:00", start.fmt= "%H:%M:%S", tz, 
            dates=1, date.fmt="%Y-%m-%d", ...)

## S3 method for class 'matrix'
cmv(x, tscale=c("hourly", "daily", "weekly", "monthly", 
            "quarterly", "seasonal", "annual"),
            out.type=c("percentage", "amount"), dec=3, 
            start="00:00:00", start.fmt= "%H:%M:%S", tz,
            dates=1, date.fmt="%Y-%m-%d", ...)

Arguments

Details

The amount of missing values in each temporal scale is computed just by counting the amount of NAs in each hour / day / week / month / quarter / season / year, while the percentage of missing values in each temporal scale is computed by dividing the previous number by the total number of data elements in each hour / day / week / month / quarter / season / year.

This function was developed to allow the selective removal of values when agregting from a high temporal resolution into a lower temporal resolution (e.g., from hourly to daily or from daily to monthly), using any of the temporal aggregation functions available int his package (e.g., hourly2daily, daily2monthly)

Value

a zoo object with the percentage/amount of missing values for each temporal scale selected by the user.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dwi, subhourly2hourly, subdaily2daily, daily2monthly, daily2annual, monthlyfunction, izoo2rzoo

Examples

######################
## Ex1: Loading the DAILY precipitation data at SanMartino (25567 daily values)
data(SanMartinoPPts)
x <- SanMartinoPPts

## Transforming into NA the 10% of values in 'x'
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

# Getting the amount of NAs in 'x' for each week (starting on Monday)
cmv(x, tscale="weekly")

# Getting the amount of NAs in 'x' for each month
cmv(x, tscale="monthly")

# Getting the amount of NAs in 'x' for each quarter
cmv(x, tscale="quarterly")

# Getting the amount of NAs in 'x' for each weather season
cmv(x, tscale="seasonal")

# Getting the amount of NAs in 'x' for each year
cmv(x, tscale="annual")
######################
## Ex2: Loading the time series of HOURLY streamflows for the station 
## Karamea at Gorge (52579 hourly values)
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

## Transforming into NA the 30% of values in 'x'
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

# Getting the amount of NAs in 'x' for each day
cmv(x, tscale="daily")

# Getting the amount of NAs in 'x' for each weather season
cmv(x, tscale="seasonal")

Daily -> Weekly

Description

Generic function for transforming a DAILY (or sub-daily) regular time series into a WEEKLY one

Usage

daily2weekly(x, ...)

## Default S3 method:
daily2weekly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

## S3 method for class 'zoo'
daily2weekly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

## S3 method for class 'data.frame'
daily2weekly(x, FUN, na.rm=TRUE, na.rm.max=0, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", out.fmt="numeric", 
        verbose=TRUE, ...)

## S3 method for class 'matrix'
daily2weekly(x, FUN, na.rm=TRUE, na.rm.max=0, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", out.fmt="numeric", 
        verbose=TRUE, ...)

Arguments

Value

a zoo object with weekly time frequency

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

cmv, subhourly2hourly, daily2monthly, daily2annual, subdaily2daily, weeklyfunction, hydroplot, vector2zoo, izoo2rzoo, as.Date

Examples

######################
## Ex1: Computation of weekly values, removing any missing value in 'x'

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three weeks (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Agreggating from Daily to Weekly, removing any missing value in 'x'
w <- daily2weekly(x, FUN=sum, na.rm=TRUE)

######################
## Ex2: Computation of Weekly values only when the percentage of NAs in each
#       week is lower than a user-defined percentage (10% in this example).

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three weeks (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Daily to Weekly, only for weeks with less than 10% of missing values
w2 <- daily2weekly(x, FUN=sum, na.rm=TRUE, na.rm.max=0.1)

# Verifying that the weeks 01, 02, 06, 08, 10, 11, 12 of 'x' had 10% or more of missing values
cmv(x, tscale="weekly")

######################
## Ex3: Computation of Weekly values in a two-column zoo object, 
##      only when the percentage of NAs in each week is lower than a user-defined 
##      percentage (10% in this example).

# Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

# Subsetting 'x' to its first three weeks (Jan/1921 - Mar/1921)
x <- window(x, end="1921-03-31")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Creating a two-column zoo object
X <- cbind(x, y=x)

## Daily to Weekly, only for weeks with less than 10% of missing values
w2 <- daily2weekly(X, FUN=sum, na.rm=TRUE, na.rm.max=0.1)

# Verifying that the weeks 01, 02, 06, 08, 10, 11, 12 of 'x' had 10% or more of missing values
cmv(X, tscale="weekly")

Days in Period

Description

Given any starting and ending dates, it generates:
1) a vector of class Date with all the days between from and to (both of them included), OR
2) the amount of days between the two dates

Usage

dip(from, to, date.fmt = "%Y-%m-%d", out.type = "seq")

Arguments

Value

Depending on the value of out.type, it returns:
1) a vector of class Date with all the days between from and to (both of them included), OR
2) the amount of days between the two dates

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

mip, yip, hip, diy

Examples

## Sequence of daily dates between "1961-01-01" and "1961-12-31" ##
dip("1961-01-01", "1961-12-31")

## Number of days between "1961-01-01" and "1965-06-30", 
## but using "%d-%m-%Y" as date format.
dip("01-01-1961", "30-06-1965", date.fmt= "%d-%m-%Y", out.type = "nmbr")

Days in Year

Description

Given a single numeric value representing a year, it generates:
1) a vector of dates with all the days within the year, OR
2) the amount of days in the specified year

Usage

diy(year, out.type = "seq")

Arguments

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

hip, dip, mip, yip

Examples

## Sequence of daily dates for the year 1961
diy(1961)

## Computing the number of days between in 1961
diy(1961, out.type = "nmbr")

(sub)Daily/Monthly -> Seasonal Values

Description

Generic function for computing a seasonal value for every year of a sub-daily/daily/weekly/monthly time series

Usage

dm2seasonal(x, ...)
subdaily2seasonal(x, ...)

## Default S3 method:
dm2seasonal(x, season, FUN, na.rm = TRUE, out.fmt="%Y", ...)

## S3 method for class 'zoo'
dm2seasonal(x, season, FUN, na.rm = TRUE, out.fmt="%Y", ...)

## S3 method for class 'data.frame'
dm2seasonal(x, season, FUN, na.rm = TRUE, dates=1, date.fmt = "%Y-%m-%d", 
            out.type = "data.frame", out.fmt="%Y", ...)
        
## S3 method for class 'matrix'
dm2seasonal(x, season, FUN, na.rm = TRUE, dates=1, date.fmt = "%Y-%m-%d", 
            out.type = "data.frame", out.fmt="%Y", ...)

Arguments

Value

A numeric vector with the seasonal values for all the years in which x is defined.

Warning

For any year, the FUN value for the winter season (DJF), is computed considering only January and February, and the value of December is used for computing the winter value of the next year.

Note

FUN is applied to all the values of x belonging to the selected season, so the results of this function depends on the frequency sampling of x and the type of function given by FUN

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

, hydroplot, seasonalfunction, time2season, extract, daily2monthly, daily2annual, monthly2annual

Examples

############
## Loading the DAILY precipitation data at SanMartino
data(SanMartinoPPts)
x <- SanMartinoPPts

## Winter (DJF) values of precipitation for each year of 'x'
dm2seasonal(x, FUN=sum, season="DJF")

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

## Mean winter (DJF) values of streamflow for each year of 'x'
dm2seasonal(x, FUN=mean, season="DJF")
subdaily2seasonal(x, FUN=mean, season="DJF") # same as above

Customized Time Axis

Description

For a nice time series plot, this function draws a customized time axis, with annual, monthly, daily and sub-daily time marks and labels.

Usage

drawxaxis(x, tick.tstep = "auto", lab.tstep = "auto", 
          lab.fmt=NULL, cex.axis=1, mgp=c(3, 2, 0), ...)

Arguments

Note

From version 0.3-0 it changed its name from drawxaxis to drawTimeAxis, in order to have a more intuitive name. The old drawxaxis function is deprecated, but still be kept for compatibility reasons.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

## Loading the SanMartino precipitation data
data(SanMartinoPPts)
x <- window(SanMartinoPPts, end=as.Date("1930-12-31"))

## Plotting the daily ts only, and then automatic 'x' axis
plot(x, xaxt = "n", xlab="Time")
drawTimeAxis(x) 

## Plotting the daily ts only, and then monthly ticks in the 'x' axis, 
## with annual labels.
plot(x, xaxt = "n", xlab="Time")
drawTimeAxis(x, tick.tstep="months", lab.tstep="years") 

Amount of dry/wet days in a time series

Description

Given a daily time series (usually precipitation), this function computes the average amount of wet/dry days in each month.

Usage

dwdays(x, ...)

## Default S3 method:
dwdays(x, thr=0, type="wet", na.rm=TRUE, ... )

## S3 method for class 'data.frame'
dwdays(x, thr=0, type="wet", na.rm=TRUE, 
        dates=1, date.fmt="%Y-%m-%d", verbose=TRUE,...)

## S3 method for class 'matrix'
dwdays(x, thr=0, type="wet", na.rm=TRUE, 
        dates=1, date.fmt="%Y-%m-%d", verbose=TRUE,...)

Arguments

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

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

## Average amount of wet days in each month (for this example, this means days 
## with precipitation larger than 0.1mm) 
dwdays(x, thr=0.1)

Days with Information

Description

This function generates a table indicating the number of days with information (<>NA) within a zoo object, aggregated by year, month or month per year.

Usage

dwi(x, ...)

## Default S3 method:
dwi(x, out.unit = "years", from = start(x), to = end(x), 
     date.fmt = "%Y-%m-%d", tstep="days", ...)
     
## S3 method for class 'zoo'
dwi(x, out.unit = "years", from = start(x), to = end(x), 
     date.fmt = "%Y-%m-%d", tstep="days", ...)

## S3 method for class 'data.frame'
dwi(x, out.unit = "years", from, to, date.fmt = "%Y-%m-%d", tstep="days", 
     dates = 1, verbose = TRUE, ...)
     
## S3 method for class 'matrix'
dwi(x, out.unit = "years", from, to, date.fmt = "%Y-%m-%d", tstep="days", 
     dates = 1, verbose = TRUE, ...)

Arguments

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

matrixplot

Examples

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

## Not run: 
## Days with information per year
dwi(x)

## Days with information per month per year.
dwi(x, out.unit="mpy")

## End(Not run)

###########
## Not run: 
## Loading the monthly time series of precipitation within the Ebro River basin.
data(EbroPPtsMonthly)

## Months with information per year in the 9 first stations of 'EbroPPtsMonthly'
a <- dwi(EbroPPtsMonthly[,1:10], out.unit="years", dates=1)

## Before plotting the results in 'a', and just for obtaining a more interesting
## plot, 70 random numbers (between 1 and 11) are introduced in 'a'
a[sample(length(a), size = 70)] <- rep(1:11, length=70)

## Plotting the amount of months with information per year in each station
matrixplot(a, var.type="Days", main="Number of months with info per year")

## End(Not run)

Extract from Zoo

Description

Extracts from a zoo object all the values belonging to a given month, year or weather season.

Usage

extract(x, ...)

## Default S3 method:
extract(x, trgt, ...)
     
## S3 method for class 'zoo'
extract(x, trgt, ...)

Arguments

Value

a zoo object with the extracted values.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

time2season, seasonalfunction, daily2annual, daily2monthly

Examples

### Loading temperature data ##
data(SanMartinoPPts)
x <- SanMartinoPPts

## Extracting all the values belonging to February (FEB=2)
extract(x, trgt=2)

## Extracting all the values belonging to February (FEB=2) and April (APR=4)
extract(x, trgt=c(2,4))

## Extracting all the values belonging to the year 1970
extract(x, trgt=1970)

## Extracting all the values belonging to the years 1970 and 1972
extract(x, trgt=c(1970,1972))

## Extracting all the values belonging to the autumn
extract(x, trgt="SON")

Flow Duration Curve

Description

Computes and plots the Flow Duration Curve (FDC) corresponding to a given time series of streamflow discharges.

Usage

fdc(x, ...)

## Default S3 method:
fdc(x,lQ.thr=0.7,hQ.thr=0.2, plot=TRUE, log="y", 
    main="Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
    ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), col="black", 
    pch=1, lwd=1, lty=1, cex=0.4, cex.axis=1.2, cex.lab=1.2, leg.txt=NULL, leg.cex=1, 
    leg.pos="topright", verbose= TRUE, thr.shw=TRUE, new=TRUE, ...)

## S3 method for class 'matrix'
fdc(x, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
    main= "Flow Duration Curve",  xlab="% Time flow equalled or exceeded", 
    ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
    col=palette("default")[1:ncol(x)], pch=1:ncol(x), lwd=rep(1, ncol(x)), 
    lty=1:ncol(x), cex=0.4, cex.axis=1.2, cex.lab=1.2, leg.txt=NULL, 
    leg.cex=1, leg.pos="topright",verbose=TRUE, thr.shw=TRUE, new=TRUE, ...)

## S3 method for class 'data.frame'
fdc(x, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
     main= "Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
     ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
     col=palette("default")[1:ncol(x)], pch=1:ncol(x), lwd=rep(1, ncol(x)), 
     lty=1:ncol(x), cex=0.4, cex.axis=1.2, cex.lab=1.2, leg.txt=NULL, 
     leg.cex=1, leg.pos="topright", verbose=TRUE, thr.shw=TRUE, new=TRUE, ...)
     
## S3 method for class 'zoo'
fdc(x, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
     main= "Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
     ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
     col=palette("default")[1:NCOL(x)], pch=1:NCOL(x), lwd=rep(1, NCOL(x)), 
     lty=1:NCOL(x), cex=0.4, cex.axis=1.2, cex.lab=1.2, leg.txt=NULL, 
     leg.cex=1, leg.pos="topright", verbose=TRUE, thr.shw=TRUE, new=TRUE, ...)

Arguments

Value

numeric, matrix or data.frame whose columns contains the % of time each one of the streamflow magnitudes given as input was equalled or exceeded. The resulting values have to be multiplied by 100 to get a percentage.

When plot is TRUE (default), the resulting flow duration curve is plotted in a new window.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

References

Vogel, R., and N. M. Fennessey (1994), Flow duration curves I: A new interpretation and confidence intervals, ASCE, Journal of Water Resources Planning and Management, 120(4).

Vogel, R., and N. Fennessey (1995), Flow duration curves II: A review of applications in water resources planning, Water Resources Bulletin, 31(6), 1029-1039, doi:10.1111/j.1752-1688.1995.tb03419.x.

Yilmaz, K. K., H. V. Gupta, and T. Wagener (2008), A process-based diagnostic approach to model evaluation: Application to the NWS distributed hydrologic model, Water Resour. Res., 44, W09417, doi:10.1029/2007WR006716.

See Also

fdcu

Examples

## Loading daily streamflows at the station Oca en Ona (Ebro River basin, Spain) ##
data(OcaEnOnaQts)

## Daily Flow Duration Curve
fdc(OcaEnOnaQts)

###################
# Getting the streamflow values corresponding to 5 and 95% of time equalled or 
# exceeded (and also the first streamflow value in 'x' just for verification)
x  <- OcaEnOnaQts

# First streamflow value (x1=42.1 m3/s)
x1 <- x[1]

# Daily FDC for 'x'
y <- fdc(x)

# value of the FDC for x1 (y1=0.002739726)
y1 <- y[1]

# Performing cubic (or Hermite) spline interpolation of 'x' and 'y'
f <- splinefun(y,x)

# Getting the (known) streamflow value for 'y1'
f(y1) # 42.1 m3/s, equal to the known 'x1'

# Streamflow values corresponding to 5 and 95% of time equalled or exceeded
f(c(.05, .95))

###################
## Getting 
data(OcaEnOnaQts)

## Daily Flow Duration Curve
fdc(OcaEnOnaQts)

Flow Duration Curve with uncertainty bounds.

Description

Computes and plots the Flow Duration Curve (FDC) for the streamflows given by x and for two uncertainty bounds, with the possibility of plotting an additional FDC representing simulated streamflows for x, in order to compare them.

Usage

fdcu(x, lband, uband, ...)

## Default S3 method:
fdcu(x, lband, uband, sim=NULL, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
     main="Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
     ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
     col=c("black", "red"), pch=c(1, 15), lwd=c(1, 0.8), lty=c(1, 3), cex=0.2, 
     cex.axis=1.2, cex.lab=1.2, leg.txt= c("Qobs", "Qsim", "95PPU"), 
     leg.cex=1, leg.pos="auto", verbose= TRUE, thr.shw=TRUE, border=NA, 
     bands.col="lightcyan", bands.density=NULL, bands.angle=45, new=TRUE, ...)

## S3 method for class 'matrix'
fdcu(x, lband, uband, sim=NULL, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
     main="Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
     ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
     col=matrix(c(rep("black", ncol(x)), 
     palette("default")[2:(ncol(x)+1)]), byrow=FALSE, ncol=2), 
     pch=matrix(rep(c(1, 15), ncol(x)), byrow=TRUE, ncol=2),
     lwd=matrix(rep(c(1, 0.8), ncol(x)), byrow=TRUE, ncol=2),
     lty=matrix(rep(c(1, 3), ncol(x)), byrow=TRUE, ncol=2),                        
     cex=rep(0.1, ncol(x)), cex.axis=1.2, cex.lab=1.2, 
     leg.txt=c("OBS", colnames(x), "95PPU"),  leg.cex=1, leg.pos="auto", 
     verbose= TRUE,  thr.shw=TRUE, border=rep(NA, ncol(x)), 
     bands.col=rep("lightcyan", ncol(x)), bands.density=rep(NULL, ncol(x)), 
     bands.angle=rep(45, ncol(x)), new=TRUE, ...)

## S3 method for class 'data.frame'
fdcu(x, lband, uband, sim=NULL, lQ.thr=0.7, hQ.thr=0.2, plot=TRUE, log="y", 
     main="Flow Duration Curve", xlab="% Time flow equalled or exceeded", 
     ylab="Q, [m3/s]", ylim, yat=c(0.01, 0.1, 1), xat=c(0.01, 0.025, 0.05), 
     col=matrix(c(rep("black", ncol(x)), 
     palette("default")[2:(ncol(x)+1)]), byrow=FALSE, ncol=2),
     pch=matrix(rep(c(1, 15), ncol(x)), byrow=TRUE, ncol=2),
     lwd=matrix(rep(c(1, 0.8), ncol(x)), byrow=TRUE, ncol=2),
     lty=matrix(rep(c(1, 3), ncol(x)), byrow=TRUE, ncol=2),                        
     cex=rep(0.1, ncol(x)), cex.axis=1.2, cex.lab=1.2,
     leg.txt=c("OBS", colnames(x), "95PPU"), leg.cex=1, leg.pos="auto", 
     verbose= TRUE, thr.shw=TRUE, border=rep(NA, ncol(x)), 
     bands.col=rep("lightcyan", ncol(x)), bands.density=rep(NULL, ncol(x)), 
     bands.angle=rep(45, ncol(x)), new=TRUE, ...)

Arguments

Note

If you do not want to use logarithmic scale for the streamflow axis, you can do it by passing the log=" " to the ... argument.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

References

Vogel, R., and N. M. Fennessey (1994), Flow duration curves I: A new interpretation and confidence intervals, ASCE, Journal of Water Resources Planning and Management, 120(4).

Vogel, R., and N. Fennessey (1995), Flow duration curves II: A review of applications in water resources planning, Water Resources Bulletin, 31(6), 1029-1039, doi:10.1111/j.1752-1688.1995.tb03419.x.

Yilmaz, K. K., H. V. Gupta, and T. Wagener (2008), A process-based diagnostic approach to model evaluation: Application to the NWS distributed hydrologic model, Water Resour. Res., 44, W09417, doi:10.1029/2007WR006716.

See Also

fdc

Examples

## Loading daily streamflows at the station Oca en Ona (Ebro River basin, Spain) ##
data(OcaEnOnaQts)
q <- OcaEnOnaQts

# Creating a fictitious lower uncertainty band
lband <- q - min(q, na.rm=TRUE)

# Giving a fictitious upper uncertainty band
uband <- q + mean(q, na.rm=TRUE)

# Plotting the flow duration curve corresponding to 'q', with two uncertainty bounds
fdcu(q, lband, uband)

Hours in Period

Description

Given any starting and ending date/time objects, it generates:
1) a vector of class c("POSIXct" "POSIXt") with all the hours between the two date/time objects (both of them included), OR
2) the amount of hours between the two date/time objects

Usage

hip(from, to, date.fmt="%Y-%m-%d %H", out.type = "seq", tz="UTC")

Arguments

Value

Depending on the value of out.type, it returns:
1) a vector of class c("POSIXct" "POSIXt") with all the hours between from and to (both of them included), OR
2) the amount of hours between the two date/time objects

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dip, mip, yip, diy, timeBasedSeq

Examples

## Sequence of hours between "1961-01-01 00:00" and "1961-01-10 00:00", giving the
## starting and ending date/time objects with hours and skipping the minutes (default)
hip("1961-01-01 00", "1961-12-31 00")

## Sequence of hours between "1961-01-01 00:00" and "1961-01-10 00:00", giving the
## starting and ending date/time objects only with hours and minutes(skipping the minutes)
hip("1961-01-01 00:00", "1961-12-31 00:00", date.fmt="%Y-%m-%d %H:%M")

## Number of hours between the 10:00 AM of "1961-Jan-02" and the 11:00 AM of "1961-Jan-01", 
## using "%d/%m/%Y" as date/time format.
hip("01/01/1961 10", "02/01/1961 11", date.fmt= "%d/%m/%Y %H", out.type = "nmbr")

Internal hydroTSM objects

Description

Internal hydroTSM objects.

Details

These are not to be called by the user.

Visual Correlation Matrix

Description

Visualization of a correlation matrix. On top the (absolute) value of the correlation plus the result of the cor.test as stars. On bottom, the bivariate scatterplots, with a fitted line. On the diagonal, an histogram of each variable.

Usage

hydropairs(x, dec = 3, use = "pairwise.complete.obs", method = "pearson",...)

Arguments

Value

Note

Original idea taken from the R Graph Gallery (nowadays not available on its original link: http://addictedtor.free.fr/graphiques/graphcode.php?graph=137).

Histogram panel was taken from the R help of the original pairs function

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

cor, pairs

Examples

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

## Visualizing the correlation among the monthly precipitation values 
## of the first 3 gauging stations in 'EbroPPtsMonthly'. 
## The first column of 'EbroPPtsMonthly' has the dates.
hydropairs(EbroPPtsMonthly[,2:4])

Hydrological time series plotting and extraction.

Description

hydroplot: When x is a zoo object it plots (a maximum of) 9 graphs (lines plot, boxplots and/or histograms) of the daily, monthly, annual and/or seasonal time series.

sname2plot: When x is a data frame whose columns contain the time series of several gauging stations, it takes the name of one gauging station and plots the graphs described above.

Usage

hydroplot(x, ...)
sname2plot(x, ...)

## Default S3 method:
hydroplot(x, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", pfreq="dma",                      
          var.type, var.unit="units", main=NULL, xlab="Time", ylab,
          win.len1=0, win.len2=0, tick.tstep="auto", lab.tstep="auto", 
          lab.fmt=NULL, cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3, 
          col=c("blue", "lightblue", "lightblue"), 
          from=NULL, to=NULL, dates=1, date.fmt= "%Y-%m-%d", 
          stype="default", season.names=c("Winter", "Spring", "Summer", "Autumn"), 
          h=NULL, ...)

## S3 method for class 'zoo'
hydroplot(x, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", pfreq="dma",                      
          var.type, var.unit="units", main=NULL, xlab="Time", ylab,
          win.len1=0, win.len2=0, tick.tstep="auto", lab.tstep="auto", 
          lab.fmt=NULL, cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3, 
          col=c("blue", "lightblue", "lightblue"), 
          from=NULL, to=NULL, dates=1, date.fmt= "%Y-%m-%d", 
          stype="default", season.names=c("Winter", "Spring", "Summer", "Autumn"), 
          h=NULL, ...)

## S3 method for class 'data.frame'
hydroplot(x, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", pfreq="dma",                      
          var.type, var.unit="units", main=NULL, xlab="Time", ylab,
          win.len1=0, win.len2=0, tick.tstep="auto", lab.tstep="auto", 
          lab.fmt=NULL, cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3, 
          col=c("blue", "lightblue", "lightblue"), 
          from=NULL, to=NULL, dates=1, date.fmt= "%Y-%m-%d", 
          stype="default", season.names=c("Winter", "Spring", "Summer", "Autumn"), 
          h=NULL, ...)

## Default S3 method:
sname2plot(x, sname, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", 
           pfreq="dma", var.type, var.unit="units", main=NULL, 
           xlab="Time", ylab=NULL, win.len1=0, win.len2=0, 
           tick.tstep="auto", lab.tstep="auto", lab.fmt=NULL, 
           cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3,
           col=c("blue", "lightblue", "lightblue"), 
           dates=1, date.fmt = "%Y-%m-%d", from=NULL, to=NULL, stype="default", 
           season.names=c("Winter", "Spring", "Summer", "Autumn"), 
           h=NULL, ...)

## S3 method for class 'zoo'
sname2plot(x, sname, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", 
           pfreq="dma", var.type, var.unit="units", main=NULL, 
           xlab="Time", ylab=NULL, win.len1=0, win.len2=0, 
           tick.tstep="auto", lab.tstep="auto", lab.fmt=NULL, 
           cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3,
           col=c("blue", "lightblue", "lightblue"), 
           dates=1, date.fmt = "%Y-%m-%d", from=NULL, to=NULL, stype="default", 
           season.names=c("Winter", "Spring", "Summer", "Autumn"), 
           h=NULL, ...)

## S3 method for class 'data.frame'
sname2plot(x, sname, FUN, na.rm=TRUE, ptype="ts+boxplot+hist", 
           pfreq="dma", var.type, var.unit="units", main=NULL, 
           xlab="Time", ylab=NULL, win.len1=0, win.len2=0, 
           tick.tstep="auto", lab.tstep="auto", lab.fmt=NULL, 
           cex=0.3, cex.main=1.3, cex.lab=1.3, cex.axis=1.3,
           col=c("blue", "lightblue", "lightblue"), 
           dates=1, date.fmt = "%Y-%m-%d", from=NULL, to=NULL, stype="default", 
           season.names=c("Winter", "Spring", "Summer", "Autumn"), 
           h=NULL, ...)

Arguments

Details

Plots of the daily/monthly/annual/seasonal values of the time series given as input.
Depending on the value of pfreq, daily, monthly, annual and/or seasonal time series plots, boxplots and histograms are produced.
Depending on the value of ptype, time series plots, boxplots and/or histograms are produced.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

sname2ts

Examples

#############
## Loading daily streamflows at the station Oca en Ona (Ebro River basin, Spain) ##
data(OcaEnOnaQts)

## 3 ts, 3 boxplots and 3 histograms
hydroplot(OcaEnOnaQts, FUN=mean, ylab= "Q", var.unit = "m3/s")

## only the original time series
hydroplot(OcaEnOnaQts, pfreq="o")

## only the year 1962 of the original time series
hydroplot(OcaEnOnaQts, pfreq="o", from="1962-01-01", to="1962-12-31")

## Not run: 
## seasonal plots
hydroplot(OcaEnOnaQts, pfreq="seasonal", FUN=mean, stype="default")

## custom season names (let's assume to be in the Southern Hemisphere)
hydroplot(OcaEnOnaQts, pfreq="seasonal", FUN=mean, 
          stype="default", season.names=c("Summer","Autumn", "Winter","Spring"))

## End(Not run)

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

## Plotting the monthly and annual values of precipitation at station "P9001", 
## stored in 'EbroPPtsMonthly'.
sname2plot(EbroPPtsMonthly, sname="P9001", var.type="Precipitation", dates=1, 
           pfreq="ma")

## Plotting seasonal precipitation at station "P9001"
par(mar=c(5.1, 4.1, 4.1, 2.1))

sname2plot(EbroPPtsMonthly, sname="P9001", FUN=sum, dates=1, pfreq="seasonal", 
           stype="default")

Infills NA values

Description

Infill all the missing values (NA) in x with the corresponding values in sim.

Usage

infillxy(x, ...)
## Default S3 method:
infillxy(x, sim, ...)
## S3 method for class 'matrix'
infillxy(x, sim, ...)
## S3 method for class 'data.frame'
infillxy(x, sim, ...)

Arguments

Details

It gives as a result an object of the same dimension of x, in which all the NA values were infilled with the corresponding values of sim.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

obs <- c(1, NA, 3, 4, NA, 5)
sim <- rep(2, 6)

## Filling in the missing values in 'x' with the corresponding values in 'sim'
infillxy(x=obs, sim)

Inverse Standarization

Description

This function back transforms a standarized vector/matrix z into their original values, i.e., re-scales all the values in the [0,1] interval to the original range of values z = re-scale(x) = x*[ xmax - xmin ] + xmin.

Usage

istdx(x, ...)
## Default S3 method:
istdx(x, xmin, xrange, ...)

Arguments

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

stdx, scale

Examples

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

## Computing xmin and the range of 'x'
xmin <- min(x, na.rm=TRUE)
r <- diff(range(x, na.rm=TRUE))

## Standarized variable
s <- stdx(x)

## Inverse of the standarized variable
si <- istdx(s, xmin, xrange=r)

## 'si' and 'x' should be the same
summary(x-si)

###########
### Standarizing a subset of the stations 9 to 12 in 'EbroPPtsMonthly'

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

pp <- EbroPPtsMonthly[1:70,10:13]
xmin   <- apply(pp, 2, min, na.rm=TRUE)
xrange <- apply(pp, 2, range, na.rm=TRUE)
xrange <- apply(xrange, 2, diff, na.rm=TRUE)

## Standarized variable
s <- stdx(as.matrix(pp))

## Inverse of the standarized variable
si <- istdx(s, xmin, xrange)

## 'si' and 'pp' should be the same
summary(pp - si)

Irregular Zoo -> Regular Zoo

Description

It takes an irregular zoo object (with non-existing values for some dates) and converts it into a regularly spaced zoo object within the time period defined by from and to, by filling the missing dates with ‘NA’

Usage

izoo2rzoo(x, ...)

## Default S3 method:
izoo2rzoo(x, from= start(x), to= end(x), 
                   date.fmt, tstep, tz, ...)
     
## S3 method for class 'zoo'
izoo2rzoo(x, from= start(x), to= end(x), 
                   date.fmt, tstep, tz, ...)

Arguments

Details

If the full time period of x is a subset of the time period defined by from and to, the time period of the resulting zoo is the one defined by from and to, assigning 'NA' to all the dates in which x do not have a value.

Value

a regularly spaced zoo object, with values given by x and time stamps going from from to to at intervals defined by tsteps

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

zoo, vector2zoo, as.POSIXct, Sys.timezone

Examples

##
## Example 1: Adding NA for February 29th to an existing zoo object

# dummy values and dates (February 29th is not present !)
x <- 1:9
dates <- c("1964-02-25", "1964-02-26", "1964-02-27", "1964-02-28", "1964-03-01", 
           "1964-03-02", "1964-03-03", "1964-03-04", "1964-03-05")

# From 'character' to 'Date' class
dates <- as.Date(dates)

## From 'numeric' to 'zoo' class
( x <- zoo(x, dates) ) # Feb 29th is still not present in 'x'
## checking the length of 'x'
length(x) # 9 elements (there is no data for Feb 29th)

## Adding a missing value (NA in this case) for Feb 29th
( y <- izoo2rzoo(x) )

## checking the new length
length(y) # 1 element more than the original 'x' (thre is an NA value in Feb 29th)


##
## Example 2: Extending the original 'x' object from February 1st to the end of March, 
#             assigning 'NA' to the days in which 'x' do not have a value.
( y <- izoo2rzoo(x, from="1964-02-01", to="1964-03-31") )


##
## Example 3: Working with a zoo matrix with two identical 'x' time series, 
##            from 1964-02-25 to 1964-03-05
( Y <- cbind(x,x) )

# Adding a missing value (NA in this case) for Feb 29th in all the columns of Y
( rY <- izoo2rzoo(Y) )


##
## Example 4: Working with hourly data, from 01:00 to 10:00 UTC on 12th December 2000
dates  <- ISOdatetime(year=2000, month=12, day=12, hour=1:10, min=0, sec=0, tz="UTC")
values <- 1:10
x      <- zoo(values, dates)

# removing four values in 'x', from 02:00 to 05:00, i.e., they will not be present 
# anymore in 'x' at all, not even NA !)
x <- x[-c(2:5)]
time(x)
length(x)

# Adding missing values (NA in this case) from 02:00 to 05:00
y <-  izoo2rzoo(x)
time(y)
length(y)


##
## Example 5: Extending hourly data to a DateTime before 'start(x)', 
##            specifying only the date.
##            Time of 'x' is in local time zone (tz="") instead of UTC
dt <- hip("2021-01-01 00:00:00", "2021-01-01 20:00:00", tz="")
x  <- zoo(0:20, dt)
(y  <- izoo2rzoo(x, from="2020-12-31") )# 00:00:00 is ommited


##
## Example 6: Extending hourly data to a DateTime before 'start(x)', 
##            specifying date and time.
##            Time of 'x' is in local time zone (tz="") instead of UTC
dt <- hip("2021-01-01 00:00:00", "2021-01-01 20:00:00", tz="")
x  <- zoo(0:20, dt)
( y  <- izoo2rzoo(x, from="2020-12-31 20:00:00") )


##
## Example 7: Extending hourly data to a DateTime after 'end(x)', 
##            specifying date and time.
##            Time of 'x' is in local time zone (tz="") instead of UTC
dt <- hip("2021-01-01 00:00:00", "2021-01-01 20:00:00", tz="")
x  <- zoo(0:20, dt)
( y  <- izoo2rzoo(x, to="2021-01-02 12:00:00") )


##
## Example 8: Extending hourly data to a DateTime before 'start(x)'.
##            Note that the 'tz' argument can be ommited in the 'hip' function, 
##            because by default it assumes UTC as time zone
dt <- hip("2021-01-01 00:00:00", "2021-01-01 20:00:00", tz="UTC")
x  <- zoo(0:20, dt)
( y  <- izoo2rzoo(x, from="2020-12-31 20:00:00", tz="UTC") )


##
## Example 9: Extending hourly data to a date before 'start(x)'. However, hourly 'x'
##            values are given at HH:15:00 hours instead of HH:00:00 hours.

## Loading the time series of hourly streamflows for the station Karamea at Gorge
## Time Zone for 'KarameaAtGorgeQts' data is GMT+12 (see ?KarameaAtGorgeQts)
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

# Subsetting 'x' to its first day only
# (01/Jan/1980 08:15:00 - 01/Jan/1980 23:15:00)
x <- window(x, end="1980-01-01 23:59:00")

# Adding NA hourly data since 1979-12-31 21:15:00
izoo2rzoo(x, from="1979-12-31 21:15:00", tz="GMT+12")

Moving Average

Description

Generic function for computing a moving (sliding) average of ts.

Usage

ma(x, ...)

## Default S3 method:
ma(x, win.len, FUN = mean, ...)

## S3 method for class 'zoo'
ma(x, win.len, FUN = mean, ...)

Arguments

Value

a vector with the moving average termns. The length of the resulting vector is the same of x, but the first and last (win.len-1)/2 elements will be NA.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

Examples

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

## Daily to Monthly ts
m <- daily2monthly(x, FUN=mean, na.rm=FALSE)

# Plotting the monthly values
plot(m, xlab="Time")

## Plotting the annual moving average in station 'x'
lines(ma(m, win.len=12), col="blue")

Matrixplot

Description

Plots a color matrix, representing the values stored in x.
Originally, it was thought to represent the amount of days with information per year in a set of gauging stations, but it can be used for plotting the information stored in any two dimensional matrix.

Usage

matrixplot(x, ColorRamp="Days", ncolors = 70, main = "", ...)

Arguments

Note

Adapted from a not available web page (http://www2.warwick.ac.uk/fac/sci/moac/currentstudents/peter_cock/r/matrix_contour/)

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dwi

Examples

## Loading the SanMartino precipitation data
data(SanMartinoPPts)

# Selecting only the values up to Dec/1960
x <- window(SanMartinoPPts, end=as.Date("1960-12-31"))

## Daily zoo to monthly zoo
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)

# Creating a data.frame with monthly values per year in each column
M <- matrix(m, ncol=12, byrow=TRUE)
colnames(M) <- month.abb
rownames(M) <- unique(format(time(m), "%Y"))

# Plotting the monthly precipitation values from 1921 to 1960.
# Useful for identifying dry/wet months
matrixplot(M, ColorRamp="Precipitation", 
           main="Monthly precipitation at San Martino st., [mm/month]")

Months in Period

Description

Given any starting and ending dates, it generates:
1) a vector of class 'Date' with all the months between the two dates (both of them included), OR
2) the amount of months between the two dates

Usage

mip(from, to, date.fmt = "%Y-%m-%d", out.type = "seq")

Arguments

Value

Depending on the value of out.type, it returns:
1) a vector of class Date with all the months between from and to (both of them included), OR
2) a single numeric value with the amount of months between the two dates.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dip, diy, hip, yip

Examples

# Sequence of monthly dates between "1961-01-01" and "1961-12-31" ##
mip("1961-01-01", "1961-12-31")

## Computing the number of months between "1961-01-01" and "1965-06-30", 
## with the date format  "%d-%m-%Y" ##
mip("01-01-1961", "30-06-1965", date.fmt= "%d-%m-%Y", out.type = "nmbr")

Monthly Function

Description

Generic function for obtaining 12 monthly values of a zoo object, by applying any R function to ALL the values in the object belonging to each one of the 12 calendar months (Jan...Dec).

Usage

monthlyfunction(x, ...)

## Default S3 method:
monthlyfunction(x, FUN, na.rm = TRUE, ...)

## S3 method for class 'zoo'
monthlyfunction(x, FUN, na.rm=TRUE,...)

## S3 method for class 'data.frame'
monthlyfunction(x, FUN, na.rm = TRUE, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", verbose = TRUE, ...)
             
## S3 method for class 'matrix'
monthlyfunction(x, FUN, na.rm = TRUE, dates=1, 
        date.fmt = "%Y-%m-%d", out.type = "data.frame", verbose = TRUE, ...)

Arguments

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

See Also

annualfunction, seasonalfunction, dm2seasonal, daily2monthly, daily2annual

Examples

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

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


############################
## Boxplot of monthly values

## Daily to Monthly
m <- daily2monthly(x, FUN=mean, na.rm=TRUE)

## Median of the monthly values at the station
monthlyfunction(m, FUN=median, na.rm=TRUE)

## Vector with the three-letter abbreviations of the month names
cmonth <- format(time(m), "%b")

## Creating ordered monthly factors
months <- factor(cmonth, levels=unique(cmonth), ordered=TRUE)

## Boxplot of the monthly values
boxplot( coredata(m) ~ months, col="lightblue", main="Monthly streamflows, [m3/s]")


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

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

## Monthly precipitation of all the stations in 'x'
## Not run: 

## Sum of the monthly values in each station of 'x'
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" )

m <- monthlyfunction(z, FUN=sum)


## Another way of computing the sum of the monthly values in each station of 'x'
## This way is usefult for posteriori boxplots
m2 <- monthlyfunction(x, FUN=sum, dates=1, out.type="db")

## Average monthly precipitation in each station of 'x'
m2$Value <- m2$Value / nyears 

## Creating monthly factors
m2$Month <- factor(m2$Month, levels=month.abb)

## boxplot of the monthly values in all stations
boxplot(Value ~ Month, m2, col="lightyellow", main="Monthly Precipitation, [mm/month]")

## End(Not run)

Plot precipitation and streamflow time series in the same figure.

Description

Given a time series of precipitation and streamflow, this function plots the two time series in the same figure, streamflows as a normal time series and preciitation as bars comming from the upper part of the plotting window.

Usage

plot_pq(p, ...)

## S3 method for class 'zoo'
plot_pq(p, q, ptype=c("original", "monthly"),
                na.fill=c("remove", "linear", "spline"), 
                from=start(p), to=end(p), date.fmt=NULL, tz=NULL,
                main=ifelse(ptype=="original", "Precipitation and Streamflows", 
                            "Monthly Precipitation and Streamflows"),
                xlab=ifelse(ptype=="original", "Time", "Month"), 
                ylab=c("P, [mm]", "Q, [m3/s]"), 
                p.col=ifelse(ptype=="original", "blue", "lightblue"),
                q.col=ifelse(ptype=="original", "black", "blue"), 
                leg.title="", leg.text=c("P", "Q"),
                q.pch=16, q.cex=0.3,
                            
                start.month=1, 
                plot.p.probs=TRUE, p.probs=c(0.25, 0.75), 
                p.alpha=0.8,
                plot.q.probs=TRUE, q.probs=c(0.25, 0.75), 
                q.probs.col="lightskyblue1", q.probs.alpha=0.8, 
                labels=TRUE, labels.cex=0.8,
                labels.p.dy=-median(daily2monthly(p, FUN=sum, na.rm=TRUE), 
                             na.rm=TRUE)*1.1,
                labels.q.dx=c(rep(-0.2,6), rep(0.2,6)),
                labels.q.dy=rep(median(q, na.rm=TRUE)*1.3, 12),
                
                ...)

Arguments

Details

Given a time series of precipitation and streamflow, this function plots the two time series in the same figure, streamflows as a normal time series and precipitation as bars comming from the upper part of the plotting window.

Value

A figure with the two time series in the same graphical area, streamflows as a normal time series and precipitation as bars comming from the upper part of the plotting window.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

hydroplot, climograph, fdc, fdcu, monthlyfunction

Examples

######################
## Ex1: Plotting precipitation and streamflows for the full time period of both
##      time series.
##      First, we load the daily P and Q time series for the Cauquenes en 
##      El Arrayan catchment. P, [mm] is the first column and Q, [mm] is the 
##      fifth column.

data(Cauquenes7336001)
p <- Cauquenes7336001[, 1]
q <- Cauquenes7336001[, 5]

## Plotting P and Q for the full time period of both time series
plot_pq(p=p, q=q)

######################
## Ex2: Plotting precipitation and streamflows only for a specific time period,
##      from April to December 2000.
plot_pq(p, q, from="2000-04-01", to="2000-12-31")

######################
## Ex3: Plotting monthly values of precipitation and streamflows for the 
##      full time period of both time series.
plot_pq(p, q, ptype="monthly")

######################
## Ex4: Plotting monthly values of precipitation and streamflows for the 
##      full time period of both time series, but using a hydrologic year
##      starting on April
plot_pq(p, q, ptype="monthly", start.month=4)

Remove First Character(s)

Description

Deletes the first n character(s) of a character object.

Usage

rm1stchar(x, n = 1)

Arguments

Value

character object of the same length as x.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

substr

Examples

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

# Getting the name of each gauging station.
names <- colnames(EbroPPtsMonthly)

# Removing the initial letter 'P' of the name of each gauging station.
rm1stchar(names)

Seasonal Function

Description

Generic function for applying any R function to a zoo object, in order to obtain 4 representative seasonal values.

Usage

seasonalfunction(x, ...)

## Default S3 method:
seasonalfunction(x, FUN, na.rm = TRUE, type="default", ...)

## S3 method for class 'zoo'
seasonalfunction(x, FUN, na.rm = TRUE, type="default", ...)

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

Arguments

Warning

The FUN value for the winter season (DJF) is computed considering the consecutive months of December, January and February. Therefore, if x starts in January and ends in December of any year, the winter value of the first year is computed considering only the January and February value of that year, whereas the December value of the first year is used to compute the winter value of the next year.

Note

FUN is applied to all the values of x belonging to each one of the four weather seasons, so the results of this function depends on the frequency sampling of x and the type of function given by FUN

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dm2seasonal, time2season, monthlyfunction, annualfunction, extract

Examples

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

# Amount of years
nyears <- yip(from=start(x), to=end(x), out.type="nmbr")

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

#####################
### verification ####
# Mean winter (DJF) value
sum( extractzoo(x, trgt="DJF") ) / nyears

# Mean spring (MAM) value
sum( extractzoo(x, trgt="MAM") ) / nyears

# Mean summer (JJA) value
sum( extractzoo(x, trgt="JJA") ) / nyears

# Mean autumn (SON) value
sum( extractzoo(x, trgt="SON") ) / nyears

Sampling Frequency

Description

This function identifies the sampling frequency of a zoo object. It is wrapper to the periodicity function of the xts package.

Usage

sfreq(x, min.year = 1800)

Arguments

Details

See further details in the periodicity function of the xts package.

Value

Character. Possible values are:
-) minute : indicating that the sampling frequency in x is sub-hourly
-) hourly : indicating that the sampling frequency in x is hourly
-) daily : indicating that the sampling frequency in x is daily
-) weekly : indicating that the sampling frequency in x is weekly
-) monthly : indicating that the sampling frequency in x is monthly
-) quarterly : indicating that the sampling frequency in x is quarterly
-) annual : indicating that the sampling frequency in x is annual

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

frequency, periodicity

Examples

## Ex1: sub-hourly data
## Creating a dummy 15-min zoo object, with 1 as the only value in each time period
dt  <- seq( from=as.POSIXct("2021-06-30 00:15"), to=as.POSIXct("2021-06-30 23:45"), by="15 min" )
ndt <- length(dt)
shr <- zoo( rep(1, ndt), dt)
sfreq(shr)


## Ex2: hourly data 
## Loading the time series of HOURLY streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
hr <- KarameaAtGorgeQts
sfreq(hr)


## Ex3: Daily data
## Loading daily streamflows at the station Oca en Ona (Ebro River basin, Spain)
data(OcaEnOnaQts)
d <- OcaEnOnaQts
sfreq(d)


## Ex4: Monthly data
m <- daily2monthly(d, FUN=mean, na.rm=TRUE)
sfreq(m)


## Ex5: Annual data
a <- daily2annual(d, FUN=mean, na.rm=TRUE)
sfreq(a)

Seasonality Index

Description

Function to compute the seasonality index defined by Walsh and Lawler (1981) to classify the precipitation regime.

Usage

  si(x, na.rm=TRUE, from=start(x), to=end(x), date.fmt="%Y-%m-%d", start.month=1)

Arguments

Details

The seasonality index is computed as following:

si = (1/R) *sum(i=1, i=12, abs(xi - R/12) )
where:
-) xi: mean monthly precipitation for month i
-) R: mean annual precipitation

This index can theoretically vary from 0 (when all months have the same rainfall) to 1.83 (when all the rainfall ocurrs in a single month). A qualitative classification of degrees of seasonality is the following:
——————————————————–
si values | Rainfall regime
——————————————————–
<= 0.19 | Very equable
0.20 - 0.39 | Equable but with a definite wetter season
0.40 - 0.59 | Rather seasonal with a short drier season
0.60 - 0.79 | Seasonal
0.80 - 0.99 | Markedly seasonal with a long drier season
1.00 - 1.19 | Most rain in 3 months or less
>= 1.20 | Extreme, almost all rain in 1-2 months

Value

numeric with the seasonality index

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

References

Walsh, R. and Lawler, D. (1981). Rainfall seasonality: Description, spatial patterns and change through time (British Isles, Africa). Weather, 36(7), 201-208. doi:10.1002/j.1477-8696.1981.tb05400.x.

See Also

subdaily2daily

Examples

############################
## Ex 1: Seasonality index for a rain gauge with equable precipitation , 
##       but with a definite wetter season 

## Loading daily precipitation data at the station San Martino di Castrozza, 
## Trento Province, Italy, from 01/Jan/1921 to 31/Dec/1990.
data(SanMartinoPPts)
x <- SanMartinoPPts

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


## Boxplot of monthly values, to look at the seasonal cycle

## Daily to Monthly
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)

## Mean monthly values at the station
monthlyfunction(m, FUN=sum, na.rm=TRUE) / nyears

## Vector with the three-letter abbreviations of the month names
cmonth <- format(time(m), "%b")

## Creating ordered monthly factors
months <- factor(cmonth, levels=unique(cmonth), ordered=TRUE)

## Boxplot of the monthly values of precipitation
boxplot( coredata(m) ~ months, col="lightblue", 
         main="Monthly precipitation, [mm]", ylab="P, [mm]")

# computing seasonality index
( si(x) )

############################
## Ex 2: Seasonality index for a rain gauge with markedly seasonal regime 
##       with a long dry season

## Loading daily precipitation data at the station Cauquenes en El Arrayan, 
## Maule Region, Chile, from 01/Jan/1979 to 31/Dec/2020.
data(Cauquenes7336001)
x <- Cauquenes7336001[, 1] # P is the first column

## Boxplot of monthly values, to look at the seasonal cycle

## Daily to Monthly
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)

## Mean monthly values at the station
monthlyfunction(m, FUN=sum, na.rm=TRUE) / nyears

## Vector with the three-letter abbreviations of the month names
cmonth <- format(time(m), "%b")

## Creating ordered monthly factors
months <- factor(cmonth, levels=unique(cmonth), ordered=TRUE)

## Boxplot of the monthly values of precipitation
boxplot( coredata(m) ~ months, col="lightblue", 
         main="Monthly precipitation, [mm]", ylab="P, [mm]")

# computing seasonality index
( si(x) )

Summary

Description

Extended summary function for numeric objects, with 13 summary statistics.

Usage

smry(x, ...)

## Default S3 method:
smry(x, na.rm=TRUE, digits = max(3, getOption("digits")-3), ...)

## S3 method for class 'zoo'
smry(x, na.rm=TRUE, digits = max(3, getOption("digits")-3), ...)

## S3 method for class 'Date'
smry(x, na.rm=TRUE, digits = max(3, getOption("digits")-3), ...)

## S3 method for class 'matrix'
smry(x, na.rm=TRUE, digits = max(3, getOption("digits")-3), ...)

## S3 method for class 'data.frame'
smry(x, na.rm=TRUE, digits = max(3, getOption("digits")-3), ...)

Arguments

Value

Computed summary statistics are:

Note

Skewness and Kurtosis are computed with the e1071 package

Author(s)

Mauricio Zambrano-Bigiarini mzb.devel@gmail

See Also

summary, fivenum, IQR, sd, skewness, kurtosis

Examples

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

## Summary of monthly precipitation values for the first 7 stations in 'EbroPPtsMonthly'
smry(EbroPPtsMonthly[,2:8])

Station Name -> Time Series

Description

This function takes a data.frame whose columns contains the time series of several gauging stations, along with a character representing the name of one gauging station, and extracts the time series corresponding to that station.

Usage

sname2ts(x, sname, dates=1, date.fmt = "%Y-%m-%d", var.type, 
         tstep.out = "daily", FUN, na.rm = TRUE, from, to)

Arguments

Value

zoo object

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

sname2plot

Examples

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

## Annual values of temperature at the station "T9105", stored in 'EbroPPtsMonthly'.
sname2ts(EbroPPtsMonthly, sname="P9001", dates=1, FUN=sum, tstep.out="annual")

Standarization

Description

Standarizes a vector or matrix, i.e., scales all the values in a way that the transformed values will be within the range [0, 1].

Usage

stdx(x, ...)

Arguments

Details

z = \frac{x - x_{min}}{x_{max}-x_{min}}

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

scale, istdx

Examples

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

# Standarizing only some values of 'EbroPPtsMonthly'
stdx(as.matrix(EbroPPtsMonthly[1:70,10:13]))

Sub-daily -> Daily

Description

Generic function for transforming a Sub-DAILY time series into a DAILY one

Usage

subdaily2daily(x, ...)

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

## S3 method for class 'zoo'
subdaily2daily(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'
subdaily2daily(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 %H:%M:%S", out.fmt="zoo", 
           verbose= TRUE, ...)

## S3 method for class 'matrix'
subdaily2daily(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 %H:%M:%S", out.fmt="zoo", 
           verbose= TRUE, ...)

Arguments

Value

a zoo object with daily time series

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

subhourly2hourly, subdaily2monthly, subdaily2annual, subdaily2seasonal, as.POSIXct, dm2seasonal, monthlyfunction, seasonalfunction, hydroplot, vector2zoo, izoo2rzoo

Examples

## Ex1: Computation of daily values, removing any missing value in 'x'

## Loading the time series of hourly streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

# Plotting the hourly streamflow values
plot(x)

# Subsetting 'x' to its first three days (01/Jan/1980 - 03/Jan/1980)
x <- window(x, end="1980-01-03 23:59:00")

## Transforming into NA the 10% of values in 'x'
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Agreggating from Sub-Daily to Daily, removing any missing value in 'x'
( d1 <- subdaily2daily(x, FUN=mean, na.rm=TRUE) )


## Ex2: Computation of daily values, removing any missing value in 'x' and
##      considering that the new day starts at 08:00:00 local time
( d2 <- subdaily2daily(x, FUN=mean, na.rm=TRUE, start="08:00:00") )

## Ex3: Computation of daily values, removing any missing value in 'x' and
##      considering that the new day starts at 08:00:00, and forcing 
#       UTC both for 'x' and 'start'
( d3 <- subdaily2daily(x, FUN=mean, na.rm=TRUE, start="08:00:00", tz="UTC") )

######################
## Ex4: Compuation of daily values only when the percentage of NAs in each
#       day is lower than a user-defined percentage (10% in this example).
( d4 <- subdaily2daily(x, FUN=mean, na.rm=TRUE, na.rm.max=0.1) )

Subdaily -> Weekly

Description

Generic function for transforming a DAILY (or sub-daily) regular time series into a WEEKLY one

Usage

subdaily2weekly(x, ...)

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

## S3 method for class 'zoo'
subdaily2weekly(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'
subdaily2weekly(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 %H:%M:%S",  
           out.fmt="zoo", verbose=TRUE, ...)

## S3 method for class 'matrix'
subdaily2weekly(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 %H:%M:%S",  
           out.fmt="zoo", verbose=TRUE, ...)

Arguments

Value

a zoo object with weekly time frequency

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

cmv, subhourly2hourly, daily2monthly, daily2annual, subdaily2daily, weeklyfunction, hydroplot, vector2zoo, izoo2rzoo, as.Date

Examples

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

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

# Sub-daily to weekly ts
subdaily2weekly(x, FUN=mean, na.rm=TRUE)

## Not run: 
######################
## Ex2: Computation of WEEKLY values from HOURLY ts, only when the percentage of NAs in 
#       each week is lower than a user-defined percentage (10

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

# Subsetting 'x' to its first three weeks 
# (Monday 2nd December 1985 - Sunday 29th uanuary 20th 1980)
x <- window(x, end="1985-12-31 23:59:00")

## Transforming into NA the 10
set.seed(10) # for reproducible results
n           <- length(x)
n.nas       <- round(0.1*n, 0)
na.index    <- sample(1:n, n.nas)
x[na.index] <- NA

## Daily to Weekly, only for weeks with less than 10
( w2 <- subdaily2weekly(x, FUN=sum, na.rm=TRUE, na.rm.max=0.1) )

# Verifying that the second and third month of 'x' had 10
cmv(x, tscale="weekly")

######################
## Ex3: Computation of WEEKLY values from HOURLY ts, removing any missing value in 'x'
#       Loading the HOURLY streamflows for the station Karamea at Gorge
data(KarameaAtGorgeQts)
x <- KarameaAtGorgeQts

# Sub-daily to weekly ts
subdaily2weekly(x, FUN=mean, na.rm=TRUE)

## End(Not run)

Sub-hourly -> Hourly

Description

Generic function for transforming a sub-HOURLY time series into an HOURLY one

Usage

subhourly2hourly(x, ...)

## Default S3 method:
subhourly2hourly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

## S3 method for class 'zoo'
subhourly2hourly(x, FUN, na.rm=TRUE, na.rm.max=0, ...)

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

## S3 method for class 'matrix'
subhourly2hourly(x, FUN, na.rm=TRUE, na.rm.max=0,
           dates=1, date.fmt="%Y-%m-%d %H:%M:%S", out.fmt="zoo", 
           verbose= TRUE, ...)

Arguments

Value

a zoo object with hourly time series

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

subhourly2nminutes,, subdaily2daily, subdaily2monthly, subdaily2annual, subdaily2seasonal, as.POSIXct, dm2seasonal, monthlyfunction, seasonalfunction, hydroplot, vector2zoo, izoo2rzoo

Examples

## Creating a 15-min time sequence and counting its length
dt  <- seq( from=as.POSIXct("2021-06-30 00:15"), to=as.POSIXct("2021-06-30 23:45"), by="15 min" )
ndt <- length(dt)

## Creating a dummy 15-min zoo object, with 1 as the only value in each time period
x <- zoo( rep(1, ndt), dt)


## sub-hourly to hourly
h1 <- subhourly2hourly(x, FUN=sum, na.rm=TRUE)

## Aggregation of 3 sub-hourly ts (i.e., a zoo matrix) into an hourly one
X  <- cbind(x, x, x)
h2 <- subhourly2hourly(X, FUN=sum, na.rm=TRUE)

Sub-hourly -> n-minutes

Description

Generic function for aggregating a sub-hourly time series into a "n-minutes' one.

Usage

subhourly2nminutes(x, ...)

## Default S3 method:
subhourly2nminutes(x, nminutes, FUN, na.rm=TRUE, 
                                     from=start(x), to=end(x), ...)

## S3 method for class 'zoo'
subhourly2nminutes(x, nminutes, FUN, na.rm=TRUE, 
                                 from=start(x), to=end(x), ...)

## S3 method for class 'data.frame'
subhourly2nminutes(x, nminutes, FUN, na.rm=TRUE, 
        from=start(x), to=end(x), dates=1, date.fmt="%Y-%m-%d %H:%M:%S", 
        out.fmt="zoo", verbose= TRUE, ...)

## S3 method for class 'matrix'
subhourly2nminutes(x, nminutes, FUN, na.rm=TRUE, 
        from=start(x), to=end(x), dates=1, date.fmt="%Y-%m-%d %H:%M:%S", 
        out.fmt="zoo", verbose= TRUE, ...)

Arguments

Value

a zoo object with hourly time series

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

subhourly2hourly, subdaily2daily, subdaily2monthly, subdaily2annual, subdaily2seasonal, as.POSIXct, dm2seasonal, monthlyfunction, seasonalfunction, hydroplot, vector2zoo, izoo2rzoo

Examples

## Creating a 5-min time sequence and counting its length
dt  <- seq( from=as.POSIXct("2021-06-30 00:00"), to=as.POSIXct("2021-06-30 23:55"), by="5 min" )
ndt <- length(dt)

## Creating a dummy 5-min zoo object, with 1 as the only value in each time period
x <- zoo( rep(1, ndt), dt)


## Aggregation from 5-minute single ts into 10-minute ts
h1 <- subhourly2nminutes(x, nminutes= 10, FUN=sum, na.rm=TRUE)

## Aggregation of 3 ts with 5-minute time frequency (i.e., a zoo matrix) 
## into a 30-minute zoo object.
X  <- cbind(x, x, x)
h2 <- subhourly2nminutes(X, nminutes= 30, FUN=sum, na.rm=TRUE)

Date/DateTime character -> Seasonal character

Description

This function transforms a character vector of Dates or DateTimes into a character vector of seasons (summer, winter, autumn, spring), depending on the value of type:

When type=default -) winter = DJF: December, January, February
-) spring = MAM: March, April, May
-) summer = JJA: June, July, August
-) autumn = SON: September, October, November

When type=FrenchPolynesia -) winter = DJFM: December, January, February, March
-) spring = AM : April, May
-) summer = JJAS: June, July, August, September
-) autumn = ON : October, November

Usage

time2season(x, out.fmt = "months", type="default")

Arguments

Value

character vector with the weather season to which each date in x belongs

Note

Weather seasons corresponding to French Polynesia were defined following a comment from Lydie Sichoix

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dm2seasonal, seasonalfunction, extract, dip, mip

Examples

## Sequence of daily dates between "1961-01-01" and "1961-12-31"
t <- dip("1961-01-01", "1961-12-31")
time2season(t)

## Sequence of monthly dates between "1961-01-01" and "1961-12-31"
t <- mip("1961-01-01", "1961-12-31")
time2season(t)
time2season(t, out.fmt="seasons")

Vector -> Zoo

Description

Transform a numeric vector and its corresponding dates into a zoo object.

Usage

vector2zoo(x, dates, date.fmt = "%Y-%m-%d")

Arguments

Value

a zoo object, with values given by x and time stamps given by dates

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

zoo, izoo2rzoo, dip, mip, yip

Examples

##
## Example1: creating daily data

# Generating a numeric variable (e.g., read from the outputs of an hydrological model)
x <- 1:31

# Generating the dates corresponding to the previous values
dates <- dip("1961-01-01", "1961-01-31")

## Transforming from 'numeric' to 'zoo' class
z <- vector2zoo(x, dates)

##
## Example2: creating hourly data

# Generating a numeric variable
x <- rnorm(7)

# Generating hourly times since 17:00:00 up to 23:00:00 for 2012-Oct-15
dates <- ISOdatetime(2012, 10, 15, 17:23, 00, 0)

## Transforming from 'numeric' to 'zoo' class
z <- vector2zoo(x, dates)

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

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

See Also

annualfunction, seasonalfunction, dm2seasonal, daily2monthly, daily2annual

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")

Years in Period

Description

Given any starting and ending dates, it generates:
1) a vector of class Date with all the years between the two dates (both of them included), OR
2) the amount of years between the two dates

Usage

yip(from, to, date.fmt = "%Y-%m-%d", out.type = "seq")

Arguments

Value

Depending on the value of out.type, it returns:
1) seq : a vector of class Date with all the years between from and to (both of them included), OR
2) nmbr: a single numeric value with the amount of years between the two dates.

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

See Also

dip, diy, mip

Examples

# Sequence of monthly dates between "1961-01-01" and "1961-12-31"
yip("1961-01-01", "1961-12-31")

## Computing the number of years between 1961 and 1975, 
## by using "%d-%m-%Y" as date format   ##
yip("01-01-1961", "01-01-1975", date.fmt= "%d-%m-%Y", out.type = "nmbr")

Zoo -> RHTest

Description

It creates the input file to the 'RHtest_dlyPrcp.r' script, used for testing the homogeneity of climatological time series (available at: http://etccdi.pacificclimate.org/software.shtml)

Usage

zoo2RHtest(x, fname="pcp.txt", tstep.out="daily", dec=".", na="-999.0")

Arguments

Author(s)

Mauricio Zambrano-Bigiarini, mzb.devel@gmail

References

http://etccdi.pacificclimate.org/software.shtml http://etccdi.pacificclimate.org/RHtest/RHtestsV4_UserManual_10Dec2014.pdf

Examples

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

#Getting the monthly ts
pcp.m <- daily2monthly(x, FUN=sum, na.rm=FALSE)

## Not run: 
# From zoo to the input format required by 'FindU.dlyPrcp' function
zoo2RHtest(x=pcp.m, fname="pcp-monthly.txt", tstep.out="monthly", na="-999.0")

# Homogeneity analysis
FindU.dlyPrcp(InSeries="pcp-monthly.txt", output="pcp-monthly", MissingValueCode="-999.0", 
GUI=FALSE, pthr=0, Mq=10, p.lev=0.95, Iadj=10000)

## End(Not run)