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

knitr::opts_chunk$set(echo = TRUE)

Citation

If you use hydroTSM, please cite it as Zambrano-Bigiarini (2024):

Zambrano-Bigiarini, Mauricio (2024). hydroTSM: Time Series Management and Analysis for Hydrological Modelling. R package version 0.7-0. URL:https://cran.r-project.org/package=hydroTSM. doi:10.5281/zenodo.839565.

Installation

Installing the latest stable version (from CRAN):

install.packages("hydroTSM")

\noindent Alternatively, you can also try the under-development version (from Github):

if (!require(devtools)) install.packages("devtools")
library(devtools)
install_github("hzambran/hydroTSM")

Setting up the environment

Loading the hydroTSM package, which contains data and functions used in this analysis:

library(hydroTSM)

Loading daily streamflow data at the station Cauquenes en el Arrayan, Maule Region, Chile, from 01/Jan/1979 to 31/Dec/2020.

data(Cauquenes7336001)

Selecting only a 30-years time slice for the analysis

x <- window(Cauquenes7336001, start="1981-01-01", end="2010-12-31")

Dates of the daily values of 'x':

dates <- time(x)

Amount of years in 'x' (needed for computations):

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

The Cauquenes7336001 dataset stores 5 variables (in this order): P, [mm], Tmx, [degC], Tmn, [deg C], PET, [mm], Qobs, [mm], Qobs, [m3/s]. For the rest of the analysis, only streamflows (Q, [mm]) and precipitations (P, [mm]) will be selected:

P <- x[, 1]
Q <- x[, 5]

Basic exploratory data analysis (EDA)

1) Summary statistics of streamflows:

smry(Q)

2) Amount of days with information (not NA) per year:

dwi(Q)

3) Amount of days with information (not NA) per month per year:

dwi(Q, out.unit="mpy")

4) Since v0.7-0, hydroTSM allows the computation of the amount/percentage of days with missing data in different temporal scales (e.g., hourly, weekly, seasonal). By default, the cmv function returns the percentage of missing values in the desired temporal scale using decimal values:

( pmd <- cmv(Q, tscale="monthly") )

Identifying months with more than 10 percent of missing data:

index <- which(pmd >= 0.1)
time(pmd[index])

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

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

6) Basic exploratory figures:

Using the hydroplot function, which (by default) plots 9 different graphs: 3 ts plots, 3 boxplots and 3 histograms summarizing 'x'. For this example, only daily and monthly plots are produced, and only data starting on 01-Jan-1987 are plotted.

hydroplot(Q, var.type="Flow", main="at Cauquenes en el Arrayan", 
          pfreq = "dm", from="2000-01-01")

Plotting P and Q for the full time period of both time series:

plot_pq(p=P, q=Q)

Plotting precipitation and streamflows only for a specific time period, from April to December 2000:

plot_pq(p=P, q=Q, from="2000-04-01", to="2000-12-31")

Plotting monthly values of precipitation and streamflows for the full time period of both time series:

plot_pq(p=P, q=Q, ptype="monthly")

Plotting monthly values of precipitation and streamflows for the full time period of both time series, but using a hydrologic year starting on April:

plot_pq(p=P, q=Q, ptype="monthly", start.month=4)

Selecting only a six-year time period for streamflows and then plotting a calendar heatmap (six years maximum) to visually identify dry, normal and wet days:

q <- window(Q, start="2005-01-01", end="2010-12-31")
calendarHeatmap(q)

This figure allows to easily identify periods with missing data (e.g., Apr/2008 and Aug/2009). For each month, this figure is read from top to bottom. For example, January 1st 2007 was Monday, January 31th 2007 was Wednesday and October 1st 2010 was Friday.

Flow duration curve (FDC)

Flow duration curve of the 30-year daily streamflow data using logarithmic scale for the y axis (i.e., to put focus on the low flows):

fdc2 <- fdc(Q)

Please note that log="y" was not provided as an argument to fdc because it is the default value used in the function.

Flow duration curve of the 30-year daily streamflow data using logarithmic scale for the x axis (i.e., to put focus on the high flows):

fdc3 <- fdc(Q, log="x")

Traditional flow duration curve of the 30-year daily streamflow data:

fdc1 <- fdc(Q, log="")

Baseflow

Since v0.7-0, hydroTSM allows the computation of baseflow using the filter proposed by Arnold and Allen (1999), which is based on earlier work by Lyne and Hollick (1979).

This first exmaple illustrates the basic usage of the baseflow function for computing and plotting the baseflow for the full time period of a given time series of streamflows:

baseflow(Q) 

The previous code did not run because the streamflow time series has some missing values. You might fill in the missing values using the technique that you like the most and then call this function again. For this example, we will use one of the two built-in techniques already incorporated in the baseflow function the missing data, i.e., na.fill="spline:

baseflow(Q, na.fill="spline") 

Now, we will compute and plot the daily baseflow (i.e., the value obtained after the thir pass of the filter) for the full time period:

baseflow(Q, na.fill="spline", plot=TRUE)

You might also want to compute and plot the daily baseflow for a specific time period. For this example, from April to December 2000:

baseflow(Q, na.fill="spline", from="2000-04-01", to="2000-12-31")

You might want to compute and plot the three daily baseflows (one for each pass of the filter), for a specific time period (April to December 2000):

baseflow(Q, na.fill="spline", from="2000-04-01", to="2000-12-31", 
         out.type="all", plot=TRUE)

Software details

This tutorial was built under:

sessionInfo()$platform
sessionInfo()$R.version$version.string 
paste("hydroTSM", sessionInfo()$otherPkgs$hydroTSM$Version)

Version history

• v0.1: 17-Jan-2024

Appendix

In order to make easier the use of \texttt{hydroTSM} for users not familiar with R, in this section a minimal set of information is provided to guide the user in the R world.

Editors, GUI

• Multi-platform: Sublime Text (https://sublime.weberup.com/) ; RStudio (https://posit.co/)

• GNU/Linux only: ESS (https://ess.r-project.org/)

• Windows only : NppToR (https://sourceforge.net/projects/npptor/)

Importing data

• ?read.table, ?write.table: allow the user to read/write a file (in $~$table format) and create a data frame from it. Related functions are ?read.csv, ?write.csv, ?read.csv2, ?write.csv2.

• ?zoo::read.zoo, ?zoo::write.zoo: functions for reading and writing time series from/to text files, respectively.

• R Data Import/Export: https://cran.r-project.org/doc/manuals/r-release/R-data.html

• foreign R package: read data stored in several R-external formats (dBase, Minitab, S, SAS, SPSS, Stata, Systat, Weka, ...)

• readxl R package: Import MS Excel files into R.

• some examples: https://www.statmethods.net/data-input/importingdata.html

Useful Websites

• Quick R: https://www.statmethods.net/

• Time series in R: https://cran.r-project.org/view=TimeSeries

• Quick reference for the zoo package: https://cran.r-project.org/package=zoo/vignettes/zoo-quickref.pdf

F.A.Q.

How to print more than one matrixplot in a single Figure?

Because matrixplot is based on lattice graphs, normal plotting commands included in base R does not work. Therefore, for plotting ore than 1 matrixplot in a single figure, you need to save the individual plots in an R object and then print them as you want.

In the following sequential lines of code, you can see two examples that show you how to plot two matrixplots in a single Figure:

library(hydroTSM)
data(SanMartinoPPts)
x <- window(SanMartinoPPts, end=as.Date("1960-12-31"))
m <- daily2monthly(x, FUN=sum, na.rm=TRUE)
M <- matrix(m, ncol=12, byrow=TRUE)
colnames(M) <- month.abb
rownames(M) <- unique(format(time(m), "%Y"))
p <- matrixplot(M, ColorRamp="Precipitation", main="Monthly precipitation,")

print(p, position=c(0, .6, 1, 1), more=TRUE)
print(p, position=c(0, 0, 1, .4))

The second and easier way allows you to obtain the same previous figure (not shown here), but you are required to install the gridExtra package:

if (!require(gridExtra)) install.packages("gridExtra")
require(gridExtra) # also loads grid
require(lattice)

grid.arrange(p, p, nrow=2)

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