Package 'hydroTSM'

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

Package:	hydroTSM
Type:	Package
Version:	0.7-0
Date:	2024-01-14
License:	GPL >= 2
LazyLoad:	yes
Packaged:	Wed 17 Jan 2024 20:43:17 -03 ; MZB
BuiltUnder:	R version 4.3.2 (2023-10-31) ;x86_64-pc-linux-gnu (64-bit)

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

Cauquenes7336001 Hydrometeorological time series for "Cauquenes en El Arrayan" catchment.

EbroPPtsMonthly Ebro Monthly Precipitation Time Series.

KarameaAtGorgeQts Karamea at Gorge, time series of hourly streamflows.

MaquehueTemuco San Martino, ts of daily precipitation.

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

SanMartinoPPts San Martino, ts of daily precipitation.

---------------------------------------------------------------------------------------------------------------------------

Temporal aggregation:

annualfunction single representative annual value of a zoo object.

weeklyfunction single representative weekly value of a zoo object.

monthlyfunction single representative monthly value of a zoo object.

seasonalfunction representative values of each weather season of a zoo object.

daily2annual Aggregation from daily to annual

subdaily2annual Aggregation from subdaily to annual.

monthly2annual Aggregation from monthly to annual.

daily2monthly Aggregation from daily to monthly.

subdaily2monthly Aggregation from subdaily to monthly.

daily2weekly Aggregation from daily to weekly.

dm2seasonal Aggregation from daily or monthly to seasonal.

subdaily2seasonal Aggregation from subdaily to seasonal.

subdaily2daily Aggregation from subdaily to daily.

subdaily2weekly Aggregation from subdaily to weekly.

subhourly2hourly Aggregation from subhourly to hourly.

subhourly2nminutesAggregation from subhourly to n-minutes.

---------------------------------------------------------------------------------------------------------------------------

Temporal manipulation:

dip Days in period.

diy Days in year.

hip Hours in period.

mip Months in period.

yip Years in period.

izoo2rzoo Irregular zoo object to regular zoo objectl.

time2season Time to weather season.

vector2zoo Numeric and date/times to zoo object.

---------------------------------------------------------------------------------------------------------------------------

Hydrological functions:

baseflow Baseflow computation.

climograph Climograph

dwdays Dry and wet days.

fdc Flow duration curve.

fdcu Flow duration curve with uncertainty bounds.

hydroplot Exploratory figure for hydrological time series.

sname2plot Hydrological time series plotting and extraction.

plot_pq Plot precipitation and streamflow time series in the same figure.

si Seasonality Index for precipitation.

sname2ts Station Name -> Time Series.

zoo2RHtest Zoo object -> RHTest.

---------------------------------------------------------------------------------------------------------------------------

Miscelaneous functions:

calendarHeatmap Calendar heat map.

cmv Counting missing values.

drawxaxis Draw a temporal horizontal axis.

dwi Days with information.

extract Extract a subset of a zoo object.

hydropairs Visual correlation matrix.

infillxy Infills NA values.

istdx Inverse standarization.

ma Moving average.

matrixplot 2D color matrix.

rm1stchar Remove first character.

sfreq Sampling frequency.

smry Improved summary function.

stdx Standarization.

---------------------------------------------------------------------------------------------------------------------------

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

x	zoo, data.frame or matrix object, with (sub)daily/monthly time series. Measurements at several gauging stations can be stored in a data.frame or matrix object, and in that case, each column of x represents the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
FUN	Function that have to be applied for aggregating from (sub)daily/monthly into annual time step (e.g., for precipitation FUN=sum and for temperature and streamflows ts FUN=mean). FUN MUST accept the na.rm argument, because na.rm is passed to FUN. When FUN=max or FUN=min the date(time) where the maximum/minimum value actually occurs is returned in the output object, otherwise, a generic 1st of january for each year is returned.
na.rm	Logical. Should missing values be removed? -) TRUE : the annual values are computed only for years with a percentage of missing values less than na.rm.max -) FALSE: if there is AT LEAST one NA within a year, the corresponing annual values in the output object will be NA.
na.rm.max	Numeric in [0, 1]. It is used to define the maximum percentage of missing values allowed in each year to keep the yearly aggregated value in the output object of this function. In other words, if the percentage of missing values in a given year is larger or equal than na.rm.max the corresponding annual value will be NA.
out.fmt	Character indicating the date format for the output zoo object. See format in as.Date. Possible values are: -) %Y : only the year will be used for the time. Default option. (e.g., "1961" "1962"...) -) %Y-%m-%d: a complete date format will be used for the time. (e.g., "1961-01-01" "1962-01-01"...). See Details.
dates	numeric, factor or Date object indicating how to obtain the dates for corresponding to each gauging station If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days on it be equal to the number of element in x
date.fmt	character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character that defines the desired type of output. Valid values are: -) data.frame: a data.frame, with as many columns as stations are included in x, and row names indicating the Year -) db : a data.frame, with 3 columns will be produced. The first column (StationID) will store the ID of the station The second column (Year) will store the year, The third column (Value) will contain the annual value corresponding to the two previous columns.
verbose	logical; if TRUE, progress messages are printed
...	arguments additional to na.rm passed to FUN.

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

x	zoo, data.frame or matrix object, with (sub)daily time series. Measurements at several gauging stations can be stored in a data.frame or matrix object, and in that case, each column of x represents the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
FUN	Function that have to be applied for transforming from daily to monthly time step (e.g., for precipitation FUN=sum and for temperature and streamflow ts FUN=mean). FUN MUST accept the na.rm argument, because na.rm is passed to FUN.
na.rm	Logical. Should missing values be removed? -) TRUE : the monthly values are computed only for months with a percentage of missing values less than na.rm.max -) FALSE: if there is AT LEAST one NA within a month, the corresponing monthly values in the output object will be NA.
na.rm.max	Numeric in [0, 1]. It is used to define the maximum percentage of missing values allowed in each month to keep the monthly aggregated value in the output object of this function. In other words, if the percentage of missing values in a given month is larger or equal than na.rm.max the corresponding monthly value will be NA.
dates	numeric, factor or Date object indicating how to obtain the dates for each gauging station If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days on it be equal to the number of elements in x
date.fmt	character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character that defines the desired type of output. Valid values are: -) data.frame: a data.frame, with as many columns as stations are included in x, and row names indicating the month and year for each value. -) db : a data.frame, with 4 columns will be produced. The first column (StationID) stores the ID of the station, The second column (Year) stores the year The third column (Month) stores the Month The fourth column (Value) stores the numerical values corresponding to the values specified in the three previous columns.
out.fmt	OPTIONAL. Only used when x is a matrix or data.frame object /cr character, for selecting if the result will be a matrix/data.frame or a zoo object. Valid values are: numeric, zoo.
verbose	logical; if TRUE, progress messages are printed
...	arguments additional to na.rm passed to FUN.

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)

---

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

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

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

x	zoo or numeric object with streamflow records. The suggested time frequency should be hourly or daily, but the algorithm will work with any time frequency.
beta	numeric representing the filter parameter. Default value is 0.925 as recommended by Arnold and Allen (1999)
from	Character indicating the starting date for subsetting x. It has to be in the format indicated by date.fmt. The default value corresponds to the date of the first element of x.
to	Character indicating the ending date for subsetting x. It has to be in the format indicated by date.fmt. The default value corresponds to the date of the last element of x.
date.fmt	character indicating the format in which the dates are stored in from and to, e.g. %Y-%m-%d. See ‘Details’ section in strptime. By default, date.fmt is missing, and it is automatically set to %Y-%m-%d when time(x) is Date object, and set to %Y-%m-%d %H:%M:%S when x is a sub-daily zoo object.
tz	character, with the specification of the time zone used for from, to. System-specific (see time zones), but "" is the current time zone, and "GMT" is UTC (Universal Time, Coordinated). See Sys.timezone and as.POSIXct. If tz is missing (the default), it is automatically set to the time zone used in time(x). This argument can be used when working with sub-daily zoo objects to force using time zones other than the local time zone for from and to. It should be used with caution, being well aware of the time zone of the data. See examples.
na.fill	Character indicating how to fill any NA present in x. Valid values are: -) remove => NAs are not plotted -) linear => NAs are removed by linear interpolation, using na.approx -) spline => NAs are removed by spline interpolation, using na.spline
out.type	Character indicating the type of result that is given by this function. Valid values are: -) last => only the baseflow computed after the third pass of the filter is returned. -) all => the 3 baseflows computed after each pass of the filter are returned in a matrix or zoo object.
plot	logical. Indicates if the baseflow should be plotted or not. If plotted, the original x values are plotted as well.
xcol	character, representing the color to be used for ploting the streamflow time series. Only used when plot=TRUE.
bfcol	character of lenght 3, representing the color(s) to be used for ploting the baseflow time series. The first, second and third element are used to represent the baseflow after the third, second and first pass of the filter, respectively. Only used when plot=TRUE.
pch	numeric, representing the symbols used for ploting the streamflow time series (both, the original series and the baseflow). Only used when plot=TRUE.
cex	a numerical vector giving the amount by which plotting characters and symbols should be scaled relative to the default. This works as a multiple of par("cex"). See plot.default. Only used when plot=TRUE.
...	further arguments passed to or from other methods. Not used yet.

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

If out.type="last"	(default value), only the baseflow computed after the third pass of the filter is returned.
If out.type="all"	the 3 baseflows computed after each pass of the filter are returned in a matrix or zoo object.

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

x	daily zoo object to be plotted. Its maximum amount of daily data should be less than 6 years or otherwise it will not be plotted.
from	Character indicating the starting date for subsetting x. It has to be in the format indicated by date.fmt.
to	Character indicating the ending date for subsetting x. It has to be in the format indicated by date.fmt.
date.fmt	character indicating the format in which the dates are stored in from and to, e.g. %Y-%m-%d. See ‘Details’ section in strptime.
main	character, Main chart title.
col	A color palette, i.e. a vector of n contiguous colors generated by functions like rainbow, heat.colors, topo.colors, bpy.colors or one of your own making, perhaps using colorRampPalette. If none is provided, a color ramp with 8 colours is created using colorRampPalette.
cuts	Numeric, indicating the values used to divide the range of x in the legend of colours. If not provided, it is automatically selected as a function of lenght(col).
cuts.dec	Number of decimal places used to present the numbers in the legend of colours.
cuts.labels	Character indicating the label to be used in the colour legend for each one of the values defined by cuts. If not provided, as.character(cuts) is used.
cuts.style	discarded because takes too much time or not alway provide the required number of classes: "dpih", "headtails", "hclust", "jenks".
legend.title	text to be displayed above the legend of colours.
legend.fontsize	size of text (in points) used in the legend of colours.
do.png	Do you want to write the figure as a .png file? logical, set TRUE to save the image.
png.fname	character, indicating the name of the file (possibly with a meaninful file extension) that will be used to write the output file.
png.width	numeric, the width of the device.
png.height	numeric, the height of the device.
png.pointsize	integer, the default pointsize of plotted text, interpreted as big points (1/72 inch) at res ppi.
png.res	integer, the nominal resolution in ppi which will be recorded in the bitmap file, if a positive integer. Also used for units other than the default, and to convert points to pixels.
do.pdf	Do you want to write the figure as a .pdf file? logical, set TRUE to save the image.
pdf.fname	character, indicating the name of the file (possibly with a significant extension) that will be used to write the output file.
pdf.width	numeric, the width of the device.
pdf.height	numeric, the height of the device.
pdf.pointsize	integer, the default point size to be used. Strictly speaking, in bp, that is 1/72 of an inch, but approximately in points. Defaults to 12.
...	further arguments passed to functions or from other methods. Not used yet.

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, [email protected]

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)

---

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.

---

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

pcp	variable of type zoo with monthly, daily or subdaily precipitation data.
tmean	variable of type 'zoo' with monthly, daily or subdaily mean temperature data.
tmx	variable of type 'zoo' with monthly, daily or subdaily maximum temperature data. ONLY used (together with tmn) when tmean' is missing.
tmn	variable of type 'zoo' with monthly, daily or subdaily minimum temperature data. ONLY used (together with tmx) when tmean is missing.
na.rm	Logical. Should missing values be removed? -) TRUE : the monthly values are computed considering only those values different from NA -) FALSE: if there is AT LEAST one NA within a month, the resulting average monthly value is NA .
from	OPTIONAL, used for extracting a subset of values. Character indicating the starting date for the values to be extracted. It must be provided in the format specified by date.fmt.
to	OPTIONAL, used for extracting a subset of values. Character indicating the ending date for the values to be extracted. It must be provided in the format specified by date.fmt.
date.fmt	Character indicating the format in which the dates are stored in dates, from and to. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
main	Character representing the main title of the plot.
pcp.label	Character used in the legend to represent the monthly average precipitation (mostly thought for languages different from English).
tmean.label	Character used in the legend to represent the monthly average temperature (mostly thought for languages different from English).
start.month	[OPTIONAL]. Only used when the (hydrological) year of interest is different from the calendar year. numeric in [1:12] indicating the starting month of the (hydrological) year. Numeric values in [1, 12] represents months in [January, December]. By default start.month=1.
pcp.solid.thr	[OPTIONAL]. Only used when using (sub)daily precipitation and temperature are gives as input data. numeric, indicating the temperature, in degrees Celsius, used to discriminate between solid and liquid precipitation. When daily tmean <= pcp.solid.thr the precipitation for that day is considered as solid precipitation.
pcp.ylim	[OPTIONAL] numeric of length 2 with the the range used for the precipitation axis. The second value should be larger than the first one.
temp.ylim	[OPTIONAL] numeric of length 2 with the the range used for the secondary temperature axis. The second value should be larger than the first one.
pcp.col	Color used in the legend to represent the monthly average precipitation.
pcp.solid.col	Color used in the legend to represent the monthly average solid precipitation.
tmean.col	Color used in the legend to represent the monthly average temperature.
tmn.col	Color used in the legend to represent the monthly minimum temperature.
tmx.col	Color used in the legend to represent the monthly maximum temperature.
pcp.labels	logical. Should monthly precipitation values to be shown above the bars?. By default pcp.labels=TRUE.
tmean.labels	logical. Should monthly mean temperature values to be shown above the lines?. By default tmean.labels=TRUE.
tmx.labels	logical. Should monthly maximum temperature values to be shown above the lines?. By default tmx.labels=TRUE.
tmn.labels	logical. Should monthly minimum temperature values to be shown above the lines?. By default tmn.labels=TRUE.
pcp.labels.cex	numeric giving the amount by which plotting characters used to show the numeric values of monthly precipitation values are scaled relative to the default. It is only used when pcp.labels=TRUE.
temp.labels.cex	numeric giving the amount by which plotting characters used to show the numeric values of monthly air temperature values (mean, maximum, minimum) are scaled relative to the default. It is only used when tmean.labels=TRUE or tmx.labels=TRUE or tmn.labels=TRUE.
pcp.labels.dx	numeric of length 12 giving the amount of horizontal coordinate positions that have to be used to shift the labels of monthly precipitation values. It is only used when pcp.labels=TRUE. Lengths smaller than 12 are recycled and larger lengths are not used.
pcp.labels.dy	numeric of length 12 giving the amount of vertical coordinate positions that have to be used to shift the labels of monthly precipitation values. It is only used when pcp.labels=TRUE. Lengths smaller than 12 are recycled and larger lengths are not used.
temp.labels.dx	numeric of length 12 giving the amount of horizontal coordinate positions that have to be used to shift the labels of monthly air temperature values (mean, maximum, minimum). It is only used when tmean.labels=TRUE or tmx.labels=TRUE or tmn.labels=TRUE. Lengths smaller than 12 are recycled and larger lengths are not used.
temp.labels.dy	numeric of length 12 giving the amount of vertical coordinate positions that have to be used to shift the labels of monthly air temperature values (mean, maximum, minimum). It is only used when tmean.labels=TRUE or tmx.labels=TRUE or tmn.labels=TRUE. Lengths smaller than 12 are recycled and larger lengths are not used.
plot.pcp.probs	logical used to decide whether to show uncertainty values around the monthly mean precipitation values. By default plot.pcp.probs=TRUE. When plot.pcp.probs=TRUE the pcp.probs argument is used to define the values of the lower an upper uncertainty bounds.
pcp.probs	numeric of length 2. It defines the quantile values used to compute the lower an upper uncertainty bounds for each one of the 12 monthly precipitation values. By default pcp.probs=c(0.25, 0.75), which indicates that the quantiles 0.25 and 0.75 are used to compute the lower an upper uncertainty bounds for each one of the 12 monthly precipitation values. If pcp is a (sub)daily zoo object, it is first aggregated into monthly values using mean, and then the pcp.probs quantiles are computed over all the monthly values belonging to a calendar month.
plot.temp.probs	logical used to decide whether to show uncertainty values around the monthly mean temperature values. By default plot.temp.probs=TRUE. When plot.temp.probs=TRUE the temp.probs argument is used to define the values of the lower an upper uncertainty bounds.
temp.probs	numeric of length 2. It is used to define quantile values used to compute the lower an upper uncertainty bounds for each one of the 12 monthly mean temperature values. If tmx and tmn are provided, then temp.probs are used to compute the lower an upper uncertainty bounds for each one of the 12 monthly maximum/minimum temperature values. By default temp.probs=c(0.25, 0.75), which indicates that the quantiles 0.25 and 0.75 are used to compute the lower an upper uncertainty bounds for each one of the 12 monthly mean(maximum/minimum) values. If tmx/tmn is provided and is a (sub)daily zoo object, it is first aggregated into monthly values using mean, and then the temp.probs quantiles are computed over all the monthly values belonging to a calendar month.
temp.probs.col	character of length 3, with the colors used to for plotting the uncertainty bands around the average monthly values of the minimum, mean and maximum air temperature, respectively. If tmx and tmn are not provided by the user, the second element of temp.probs.col will still be used to define the color of the uncertainty band around the mean monthly values of air temperature.
temp.probs.alpha	numeric of length 1, with the factor used to modify the opacity of temp.probs.col. Typically in [0,1], with 0 indicating a completely transparent colour and 1 indicating no transparency.
lat	[OPTIONAL] numeric or character used to show the latitude for which the climograph was plotted for.
lon	[OPTIONAL] numeric or character used to show the longitude for which the climograph was plotted for.

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

x	zoo, data.frame or matrix object, with the time series to be analised. Measurements at several gauging stations can be stored in a data.frame or matrix object, and in that case, each column of x represents the time series measured in a gauging statio, and the column names of x have to correspond to the ID of each station (starting by a letter).
tscale	character with the temporal scale to be used for analysing the mssing data. Valid values are: -) hourly: the percentage/amount of missing values will be given for each hour and ,therefore, the expected time frequency of x must be sub-hourly. -) daily: the percentage/amount of missing values will be given for each day and, therefore, the expected time frequency of x must be sub-daily (i.e., hourly or sub-hourly). -) weekly: the percentage/amount of missing values will be given for each week (starting on Monday) and, therefore, the expected time frequency of x must be sub-weekly (i.e., daily, (sub)hourly). -) monthly: the percentage/amount of missing values will be given for each month and, therefore, the expected time frequency of x must be sub-monthly (i.e., daily, hourly or sub-hourly). -) quarterly: the percentage/amount of missing values will be given for each quarter and, therefore, the expected time frequency of x must be sub-quarterly (i.e., monthly, daily, hourly or sub-hourly). -) seasonal: the percentage/amount of missing values will be given for each weather season (see ?time2season) and, therefore, the expected time frequency of x must be sub-seasonal (i.e., monthly, daily, hourly or sub-hourly). -) annual: the percentage/amount of missing values will be given for each year and, therefore, the expected time frequency of x must be sub-annual (i.e., seasonal, monthly, daily, hourly or sub-hourly).
dec	integer indicating the amount of decimal places included in the output. It is only used when out.type=='percentage'.
start	character, indicating the starting time used for aggregating sub-daily time series into daily ones. It MUST be provided in the format specified by start.fmt. This value is used to define the time when a new day begins (e.g., for some rain gauge stations). -) All the values of x with a time attribute before start are considered as belonging to the day before the one indicated in the time attribute of those values. -) All the values of x with a time attribute equal to start are considered to be equal to "00:00:00" in the output zoo object. -) All the values of x with a time attribute after start are considered as belonging to the same day as the one indicated in the time attribute of those values. It is useful when the daily values start at a time different from "00:00:00". Use with caution. See examples.
start.fmt	character indicating the format in which the time is provided in start, By default date.fmt=%H:%M:%S. See format in as.POSIXct.
tz	character, with the specification of the time zone used in both x and start. System-specific (see time zones), but "" is the current time zone, and "GMT" is UTC (Universal Time, Coordinated). See Sys.timezone and as.POSIXct. If tz is missing (the default), it is automatically set to the time zone used in time(x). This argument can be used to force using the local time zone or any other time zone instead of UTC as time zone.
dates	numeric, factor, POSIXct or POSIXt object indicating how to obtain the dates and times for each column of x (e.g., gauging station). If dates is a number, it indicates the index of the column in x that stores the date and times. If dates is a factor, it is converted into POSIXct class, using the date format specified by date.fmt If dates is already of POSIXct or POSIXt class, this function verifies that the number of elements on it be equal to the number of elements in x.
date.fmt	character indicating the format in which the dates are stored in dates, By default date.fmt=%Y-%m-%d %H:%M:%S. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	character indicating how should be returned the missing values for each temporal scale. Valid values are: -) percentage: the missing values are returned as an real value, representing the percentage of missing values in each temporal scale. -) amount: the missing values are returned as an integer value, representing the absolute amount of missing values in each temporal scale.
...	further arguments passed to or from other methods.

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

x	zoo, data.frame or matrix object, with (sub)daily time series. Measurements at several gauging stations can be stored in a data.frame or matrix object, and in that case, each column of x represents the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
FUN	Function that have to be applied for transforming from daily to weekly time step (e.g., for precipitation FUN=sum and for temperature and streamflow ts FUN=mean). FUN MUST accept the na.rm argument, because na.rm is passed to FUN.
na.rm	Logical. Should missing values be removed? -) TRUE : the weekly values are computed only for weeks with a percentage of missing values less than na.rm.max -) FALSE: if there is AT LEAST one NA within a month, the corresponing weekly values in the output object will be NA.
na.rm.max	Numeric in [0, 1]. It is used to define the maximum percentage of missing values allowed in each month to keep the weekly aggregated value in the output object of this function. In other words, if the percentage of missing values in a given month is larger or equal than na.rm.max the corresponding weekly value will be NA.
dates	numeric, factor or Date object indicating how to obtain the dates for each gauging station If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days on it be equal to the number of elements in x
date.fmt	character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character that defines the desired type of output. Valid values are: -) data.frame: a data.frame, with as many columns as stations are included in x, and row names indicating the month and year for each value. -) db : a data.frame, with 4 columns will be produced. The first column (StationID) stores the ID of the station, The second column (Year) stores the year The third column (Month) stores the Month The fourth column (Value) stores the numerical values corresponding to the values specified in the three previous columns.
out.fmt	OPTIONAL. Only used when x is a matrix or data.frame object /cr character, for selecting if the result will be a matrix/data.frame or a zoo object. Valid values are: numeric, zoo.
verbose	logical; if TRUE, progress messages are printed
...	arguments additional to na.rm passed to FUN.

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

from	Character indicating the starting date for creating the sequence. It has to be in the format indicated by date.fmt.
to	Character indicating the ending date for creating the sequence. It has to be in the format indicated by date.fmt.
date.fmt	character indicating the format in which the dates are stored in from and to, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character indicating the type of result that is given by this function. Valid values are: 1) seq : a vector of class Date with all the days between the two dates, OR 2) nmbr: a single numeric value with the amount of days between the two dates.

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

year	numeric, the year for which the sequence of days will be generated
out.type	Character indicating the type of result that is given by this function. Valid values are: -) seq : a vectorial sequence with all the days within the given year -) nmbr: the number of days in the vectorial sequence with all the days within the given year

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

x	zoo, xts, data.frame or matrix object, with sub-daily, daily, weekly or monthly time series. Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
season	character, indicating the weather season to be used for selecting the data. Valid values are: -) DJF : December, January, February -) MAM : March, April, May -) JJA : June, July, August -) SON : September, October, November -) DJFM: December, January, February, March -) AM : April, May -) JJAS: June, July, August, September -) ON : October, November
FUN	Function that will be applied to ALL the values of x belonging to the given weather season (e.g., FUN can be some of mean, max, min, sd). The FUN value for the winter season (DJF or DJFM) is computed considering the consecutive months of December, January and February/March. See 'Note' section.
na.rm	Logical. Should missing values be removed? -) TRUE : the seasonal values are computed considering only those values different from NA (very important when FUN=sum) -) FALSE: if there is AT LEAST one NA within a weather season, the corresponding seasonal values are NA
out.fmt	Character indicating the date format for the output time series. See format in as.Date. Possible values are: -) %Y : only the year will be used for the time. Default option. (e.g., "1961" "1962"...) -) %Y-%m-%d: a complete date format will be used for the time. (e.g., "1961-01-01" "1962-01-01"...)
dates	numeric, factor or Date object indicating how to obtain the dates. If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, by using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days on it be equal to the number of elements in x
date.fmt	Character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character that defines the desired type of output. Valid values are: -) data.frame: a data.frame, with as many columns as stations are included in x, the year corresponding to each seasonal value are used as row names. -) db : a data.frame, with 4 columns will be produced. The first column (StationID) stores the ID of the station The second column (Year) stores the year, The third column (Season) stores the season, The fourth column (Value) contains the seasonal value corresponding to the values specified in the previous three columns
...	further arguments passed to or from other methods.

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

x	time series that will be plotted using the X axis that will be draw class(x) must be ts or zoo
tick.tstep	Character indicating the time step that have to be used for putting the ticks on the time axis. Valid values are: auto, years, quarters, months,weeks, days, hours, minutes, seconds.
lab.tstep	Character indicating the time step that have to be used for putting the labels on the time axis. Valid values are: auto, years, quarters, months,weeks, days, hours, minutes, seconds.
lab.fmt	Character indicating the format to be used for the label of the axis. See format in as.Date. If not specified (lab.fmt=NULL), it will try to use: -) "%Y-%m-%d" when lab.tstep=="days", -) "%b-%Y" when lab.tstep=="year" or lab.tstep=="month".
cex.axis	magnification of axis annotation relative to cex (See par).
mgp	The margin line (in mex units) for the axis title, axis labels and axis line (See par). Default value is mgp = c(3, 2, 0).
...	further arguments passed to the axis function or from other methods.

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

x	zoo, data.frame or matrix object, usually with daily time series of precipitation. Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
thr	numeric. Value of daily precipitation used as threshold for classifying a day as dry/wet or not. Days with a precipitation value larger to thr are classified as wet days, whereas precipitation values lower to thr are classified as dry days.
type	character, indicating if the daily values have to be classified as dry or wet days. It works linked to the values specified in thr. Valid values are: wet, dry.
na.rm	Logical. Should missing values be removed before counting?
dates	numeric, factor or Date object indicating how to obtain the dates If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days in dates be equal to the number of element in x
date.fmt	character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
verbose	logical; if TRUE, progress messages are printed
...	further arguments passed to or from other methods.

Author(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

x	zoo, data.frame or matrix object, with daily/monthly/annual time series. Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter).
out.unit	aggregation time for the computation of the amount of days with information. Valid values are: -) months: monthly; -) years : annual; -) mpy : month per year (not available for data.frames)
from	Character indicating the starting date for the computations. It has to be in the format indicated by date.fmt. When x is a data.frame and this value is not provided, the date corresponding to the first row of x is used
to	Character indicating the ending date for the computations. It has to be in the format indicated by date.fmt. When x is a data.frame and this value is not provided, the date corresponding to the last row of x is used
date.fmt	character indicating the format in which the dates are stored in dates, e.g. %Y-%m-%d. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
tstep	Time step used for storing the values in x. Valid values are: days, months, years. Since the version 0.3-0 of hydroTSM, this argument is not required any more, because it is not used any longer.
dates	numeric, factor or Date object indicating how to obtain the dates for each column of x If dates is a number, it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days in dates be equal to the number of element in x
verbose	logical; if TRUE, progress messages are printed
...	further arguments passed to or from other methods.

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)

---

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.

---

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

x	zoo object
trgt	numeric or character indicating the elements to extract from x. Valid values are: 1) integer(s) from 1 to 12: trgt is considered as month(s) (1=JAN, 2=FEB,...., 12=DEC), and all the values in x belonging to the month(s) specified by trgt will be extracted. 2) integer(s) > 12: trgt is considered as year(s), and all the values in x belonging to the year(s) specified by trgt will be extracted 3) character: trgt is considered as a weather season, and all the values in x belonging to the season specified by trgt will be extracted. Valid values are: -) DJF : December, January, February -) MAM : March, April, May -) JJA : June, July, August -) SON : September, October, November -) DJFM: December, January, February, March -) AM : April, May -) JJAS: June, July, August, September -) ON : October, November
...	further arguments passed to or from other methods

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

x	numeric, zoo, data.frame or matrix object with the observed streamflows for which the flow duration curve have to be computed. Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter). When x is a matrix or data.frame, the flow duration curve is computed for each column.
lQ.thr	numeric, low-flow separation threshold. If this value is different from NA, a vertical line is drawn in this value, and all the values to the right of it should be deemed as low flows. Default value is 0.7.
hQ.thr	numeric, high-flow separation threshold. If this value is different from NA, a vertical line is drawn in this value, and all the values to the left of it should br deemed as high flows. Default value is 0.2.
plot	logical. Indicates if the flow duration curve should be plotted or not. Default value is TRUE.
log	character, indicates which axis has to be plotted with a logarithmic scale. Default value is y
main	See plot. An overall title for the plot: see title.
xlab	A title for the x axis. See plot.
ylab	A title for the y axis. See plot.
ylim	The y limits of the plot. See plot.default.
yat	Only used when log="y". numeric, with points at which tick-marks will try to be drawn in the Y axis, in addition to the defaults computed by R. See the at argument in Axis.
xat	Only used when log="x". numeric, with points at which tick-marks will try to be drawn in the x axis, in addition to the defaults computed by R. See the at argument in Axis.
col	The colors to be used for lines and points. Multiple colors can be specified so that each point can be given its own color. If there are fewer colors than points they are recycled in the standard fashion. Lines will all be plotted in the first colour specified. See plot.default.
pch	A vector of plotting characters or symbols: see points. See plot.default.
lwd	The line width, see par. See plot.default.
lty	The line type, see par. See plot.default.
cex	See plot.default. A numerical vector giving the amount by which plotting characters and symbols should be scaled relative to the default. This works as a multiple of par("cex"). 'NULL' and 'NA' are equivalent to '1.0'. Note that this does not affect annotation
cex.axis	magnification of axis annotation relative to 'cex'.
cex.lab	Magnification to be used for x and y labels relative to the current setting of 'cex'. See '?par'.
leg.txt	vector with the names that have to be used for each column of x.
leg.cex	numeric, indicating the character expansion factor for the legend, *relative* to current par("cex"). Default value = 1
leg.pos	keyword to be used to position the legend. One of the list ‘"bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", "center"’. This places the legend on the inside of the plot frame at the given location. See legend.
verbose	logical; if TRUE, progress messages are printed (when x is a matrix or data.frame).
thr.shw	logical, indicating if the streamflow values corresponding to the user-defined thresholds lQ.thr and hQ.thr have to be shown in the plot.
new	logical, if TRUE (default), a new plotting window is created.
...	further arguments passed to or from other methods (to the plotting functions)

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

x	numeric, zoo, data.frame or matrix object with the observed streamflows for which the flow duration curve have to be computed. Measurements at several gauging stations can be stored in a data.frame of matrix object, and in that case, each column of x represent the time series measured in each gauging station, and the column names of x have to correspond to the ID of each station (starting by a letter). When x is a matrix or data.frame, the flow duration curve is computed for each column.
lband	numeric, zoo, data.frame or matrix object with the streamflows representing the the lower uncertainty bound of x, for which the flow duration curve have to be computed. Measurements at several gauging stations can be stored in a data.frame of matrix object. When lband is a matrix or data.frame, the flow duration curve is computed for each column.
uband	numeric, zoo, data.frame or matrix object with the streamflows representing the the upper uncertainty bound of x, for which the flow duration curve have to be computed. Measurements at several gauging stations can be stored in a data.frame of matrix object. When uband is a matrix or data.frame, the flow duration curve is computed for each column.
sim	OPTIONAL. numeric, zoo, data.frame or matrix object with the streamflows simulated for x, for which the flow duration curve have to be computed. Measurements at several gauging stations can be stored in a data.frame of matrix object. When sim is a matrix or data.frame, the flow duration curve is computed for each column.
lQ.thr	numeric, low flows separation threshold. If this value is different from 'NA', a vertical line is drawn in this value, and all the values to the left of it are deemed low flows.
hQ.thr	numeric, high flows separation threshold. If this value is different from 'NA', a vertical line is drawn in this value, and all the values to the right of it are deemed high flows
plot	logical. Indicates if the flow duration curve should be plotted or not.
log	character, indicates which axis has to be plotted with a logarithmic scale. Default value is y.
main	See plot. An overall title for the plot: see title.
xlab	See plot. A title for the x axis: see title.
ylab	See plot. A title for the y axis: see title.
ylim	See plot.default. The y limits of the plot.
yat	Only used when log="y". numeric, with points at which tick-marks will try to be drawn in the Y axis, in addition to the defaults computed by R. See the at argument in Axis.
xat	Only used when log="x". numeric, with points at which tick-marks will try to be drawn in the x axis, in addition to the defaults computed by R. See the at argument in Axis.
col	See plot.default. The colors for lines and points. Multiple colors can be specified so that each point can be given its own color. If there are fewer colors than points they are recycled in the standard fashion. Lines will all be plotted in the first colour specified.
pch	See plot.default. A vector of plotting characters or symbols: see points.
lwd	See plot.default. The line width, see par.
lty	See plot.default. The line type, see par.
cex	See plot.default. A numerical vector giving the amount by which plotting characters and symbols should be scaled relative to the default. This works as a multiple of par("cex"). 'NULL' and 'NA' are equivalent to '1.0'. Note that this does not affect annotation.
cex.axis	magnification of axis annotation relative to 'cex'.
cex.lab	Magnification to be used for x and y labels relative to the current setting of 'cex'. See '?par'.
leg.txt	vector with the names that have to be used for each column of x.
leg.cex	numeric, indicating the character expansion factor for the legend, *relative* to current par("cex"). Default value = 1
leg.pos	keyword to be used to position the legend. One of the list ‘"bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", "center"’. This places the legend on the inside of the plot frame at the given location. See legend. When leg.pos="auto", the legend provided by leg.txt is located on the ‘bottomleft’ when log="y" and on the ‘topright’ otherwise
verbose	logical; if TRUE, progress messages are printed
thr.shw	logical, indicating if the streamflow values corresponding to the user-defined thresholds lQ.thr and hQ.thr have to be shown in the plot. When leg.pos="auto", the legend with the threshold values is located on the ‘topright’ when log="y" and on the ‘bottomleft’ otherwise
border	See polygon. The color to draw the border of the polygon with the uncertainty bounds. The default, 'NA', means to omit borders.
bands.col	See polygon. The color for filling the polygon. The default, 'NA', is to leave polygons unfilled, unless bands.density is specified. If bands.density is specified with a positive value this gives the color of the shading lines.
bands.density	See polygon. The density of shading lines for the polygon with the uncertainty bounds, in lines per inch. The default value of 'NULL' means that no shading lines are drawn. A zero value of bands.density means no shading nor filling whereas negative values (and 'NA') suppress shading (and so allow color filling).
bands.angle	See polygon. The slope of shading lines for the polygon with the uncertainty bounds, given as an angle in degrees (counter-clockwise).
new	logical, if TRUE, a new plotting window is created.
...	further arguments passed to or from other methods (to the plotting functions)

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

from	Character or POSIXct object indicating the starting date/time for creating the sequence. It has to be in the format indicated by date.fmt.
to	Character indicating the ending date/time for creating the sequence. It has to be in the format indicated by date.fmt.
date.fmt	character indicating the format in which the date/time objects are stored in from and to, e.g. %Y-%m-%d %H:%M. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
out.type	Character indicating the type of result that is given by this function. Valid values are: 1) seq : a vector of class Date with all the days between the two dates, OR 2) nmbr: a single numeric value with the amount of days between the two dates.
tz	specification of the desired time zone yo be used. System-specific (see time zones), but "" is the current time zone, and "GMT" (the default value) is UTC (Universal Time, Coordinated). See Sys.timezone and as.POSIXct. This argument can be used when working with subdaily zoo objects to force using the local time zone instead of GMT as time zone.

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

---

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

x	data.frame or matrix object with measurements at several locations. Each column of x represent values measured at different locations.
dec	decimal places to be used for showing the correlation values
use	See cor. An optional character string giving a method for computing covariances in the presence of missing values. This must be (an abbreviation of) one of the strings "everything", "all.obs", "complete.obs", "na.or.complete", or "pairwise.complete.obs".
method	See cor. A character string indicating which correlation coefficient (or covariance) is to be computed. One of "pearson" (default), "kendall", or "spearman", can be abbreviated
...	further arguments passed to or from other methods, in particular it is used in the pairs function.

Value

On top	the (absolute) value of the correlation plus the result of the cor.test as points
On bottom	the bivariate scatterplots, with a fitted line
On diagonal	histograms (from pairs)

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

x	zoo, xts or data.frame object, with columns storing the time series of one or more gauging stations.
sname	ONLY required when x is a data frame. Character representing the name of a station, which have to correspond to one column name in x
FUN	ONLY required when var.type is missing AND pfreq != "o". Function that have to be applied for transforming from daily to monthly or annual time step (e.g., For precipitation FUN=sum and for temperature and flow ts, FUN=mean)
na.rm	Logical. Should missing values be removed before the computations?
ptype	Character indicating the type of plot that will be plotted. Valid values are: -) ts => only time series -) ts+boxplot => only time series + boxplot -) ts+hist => only time series + histogram -) ts+boxplot+hist => time series + boxplot + histogram
pfreq	Character indicating how many plots are desired by the user. Valid values are: -) dma : Daily, Monthly and Annual values are plotted -) dm : Daily and Monthly values are plotted -) ma : Monthly and Annual values are plotted -) o : Only the original zoo object is plotted, and ptype is changed to ts -) seasonal: Line and bloxplots of seasonal time series (see stype and season.names). When pfreq is seasonal, ptype is set to ts+boxplot
var.type	ONLY required when FUN is missing. character representing the type of variable being plotted. Used for determining the function used for computing the monthly and annual values when FUN is missing. Valid values are: -) Precipitation => FUN=sum -) Temperature => FUN=mean -) Flow => FUN=mean
var.unit	Character representing the measurement unit of the variable being plotted. ONLY used for labelling the axes (e.g., "mm" for precipitation, "C" for temperature, and "m3/s" for flow.)
main	Character representing the main title of the plot. If the user do not provide a title, this is created automatically as: main= paste(var.type, "at", sname, sep=" "),
xlab	A title for the x axis. See plot.
ylab	A title for the y axis. See plot.
win.len1	number of days for being used in the computation of the first moving average. A value equal to zero indicates that this moving average is not going to be computed.
win.len2	number of days for being used in the computation of the second moving average. A value equal to zero indicates that this moving average is not going to be computed.
tick.tstep	Character indicating the time step that have to be used for putting the ticks on the time axis. Valid values are: -) days, -) months, -) years
lab.tstep	Character indicating the time step that have to be used for putting the labels on the time axis. Valid values are: -) days, -) months, -) years
lab.fmt	Character indicating with the format to be used for the label of the axis. See format in as.Date. If not specified, it will try "%Y-%m-%d" when lab.tstep=="days", "%b" when lab.tstep=="month", and "%Y" when lab.tstep=="year".
cex	A numerical value giving the amount by which plotting text and symbols should be magnified relative to the default. (See par).
cex.main	The magnification to be used for main titles relative to the current setting of cex (See par).
cex.lab	The magnification to be used for x and y labels relative to the current setting of cex (See par).
cex.axis	The magnification to be used for axis annotation relative to the current setting of cex (See par).
col	A character vector with 3 elements, representing the colors to be used for plotting the lines of the ts, the boxplots, and the histograms, respectively. When pfreq="o", only one character element is needed. See plot.default).
dates	ONLY required when x is a data frame. It is a numeric, factor or Date object indicating how to obtain the dates corresponding to the sname station. If dates is a number (default), it indicates the index of the column in x that stores the dates If dates is a factor, it is converted into Date class, using the date format specified by date.fmt If dates is already of Date class, the code verifies that the number of days in dates be equal to the number of element in x
date.fmt	Character indicating the format in which the dates are stored in dates, from and to. See format in as.Date. ONLY required when class(dates)=="factor" or class(dates)=="numeric".
from	OPTIONAL, used for extracting a subset of values. Character indicating the starting date for the values to be extracted. It must be provided in the format specified by date.fmt.
to	OPTIONAL, used for extracting a subset of values. Character indicating the ending date for the values to be extracted. It must be provided in the format specified by date.fmt.
stype	OPTIONAL, only used when pfreq=seasonal. character, indicating which weather seasons will be used for computing the output. Possible values are: -) default => "winter"= DJF = Dec, Jan, Feb; "spring"= MAM = Mar, Apr, May; "summer"= JJA = Jun, Jul, Aug; "autumn"= SON = Sep, Oct, Nov -) FrenchPolynesia => "winter"= DJFM = Dec, Jan, Feb, Mar; "spring"= AM = Apr, May; "summer"= JJAS = Jun, Jul, Aug, Sep; "autumn"= ON = Oct, Nov
season.names	OPTIONAL, only used when pfreq=seasonal. character of length 4 indicating the names of each one of the weather seasons defined by stype.These names are only used for plotting purposes
h	OPTIONAL, only used when pfreq=seasonal, for plotting horizontal lines in each seasonal plot. numeric, with 1 or 4 elements, with the value used for plotting an horizontal line in each seasonal plot, in the following order: winter (DJF), spring (MAM), summer (JJA), autumn (SON).
...	further arguments passed to the plot.zoo and axis functions or from other methods.

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

x	numeric, data.frame or matrix in which some values are missing (NA).
sim	numeric, data.frame or matrix, with the same dimension of x, which contains the values that will be used for infilling the missing (NA) values in x
...	further arguments passed to or from other methods.

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

x	standarized vector or matrix to be re-scaled, all the values have to be in the range [0,1]
xmin	numeric with the minimum value(s) in the original x -) if x is a vector, xmin has to be a real -) if x is a matrix/data.frame, xmin has to be a vector, with the minimum values for each column of the original x. In this case, the vector of minimums can be obtained as: xmin <- apply(x, 2, min, na.rm=TRUE)
xrange	numeric with the range of value(s) in the original x -) if x is a vector, xrange has to be a real -) if x is a matrix/data.frame, xrange has to be a vector, with the range of values for each column of the original x. In this case, the vector of ranges can be obtained as: xrange <- apply(x, 2,range, na.rm=TRUE) xrange <- apply(xrange, 2, diff, na.rm=TRUE)
...	further arguments passed to or from other methods

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)

---