
\documentclass{article}
% \VignetteIndexEntry{Watersheds, an R Package}
% \VignetteDepends{Watersheds}
% \VignetteKeyword{Watersheds}

\usepackage{amsmath}
\usepackage{amscd}
\usepackage[tableposition=top]{caption}
\usepackage{ifthen}
\usepackage[utf8]{inputenc}
\usepackage[top=3.0cm, bottom=2.5cm, left=3.0cm, right=3.0cm]{geometry} %define margins
\usepackage{apacite}	%it allows APA references style
\bibliographystyle{apacite}
	\renewcommand{\bibliographytypesize}{\footnotesize}
\usepackage{amsfonts}


\begin{document}

\title{\bf "Watersheds": Spatial watershed aggregation and spatial drainage network analysis}
\author{J.A. Torres-Matallana\\
{\small \it Water Security and Safety Unit, Department for Environmental Research and
    Innovation}\\
{\small \it Luxembourg Institute of Science and Technology (LIST), Belvaux, Luxembourg}\\
\small arturo.torres@list.lu}
\maketitle

% --------------------- question 1 ------------------------------
% cdir="/Users/Arturo/Desktop/writesummary/vignettes"

\section{Introduction}

The present document has the purpose of illustrating the package {\tt Watersheds} implemented in the programming language {\sf R} Project for Statistical Computing \cite{Ihaka&Gentleman(1996), RDCoreTeam(2013)}.\\

The package allows spatial analysis for watersheds aggregation and ordering accordingly to an outlet point and size of tributary watershed of the current watershed. Also, enables spatial drainage networks analysis inside the aggregated watersheds. It makes use of the functionalities of the spatial classes, functions and methods of the package {\tt sp} \cite{Pebesma&Bivand(2012)}.\\

Creation and handling of objects class {\tt Watershed} for identifying the subbasin that contains the current {\tt station} (class {\tt SpatialPoints}) and subsets the {\tt zhyd} object to subbasin and extract the current {\tt zhy} object that contains {\tt station} via the S4 method {\tt Watershed.Order}. Identification of the inlet and outlet stretches and inlet and outlet nodes of the {\tt zhyd}. Implementation of functions {\tt Watershed. ,IOR1, IOR2, IOR3}, and {\tt IOR4} for determining the actual inlet and outlet nodes.  S4 methods {\tt Watershed.Order2} and {\tt Watershed.Tributary} for defining tributary nodes and tributary catchments of the current {\tt zhyd} watershed.

\section{The data: river Weser basin, Germany}

The package has an example dataset of the ECRINS database for the river Weser basin, Germany. The European Environment Agency (EEA) has been developed the Catchments and Rivers Network System (ECRINS) version 1.1. The ECRINS is the hydrographical system currently in use at the European level as well as widely serving as the reference system for the Water Information System (WISE). The current version of ECRINS is based on previous work carried out by the Joint Research Centre (JRC) Catchment Characterisation and Modelling (CCM) and the EEA (European Lakes, Dams and Reservoirs Database (Eldred2), European Rivers and Catchments (ERICA)), \cite{EEA(2012)}.

\subsection{Subsets}

The dataset contains the following subsets:
\begin{itemize}
\item {\tt basin}: an object {\tt SpatialPolygonsDataFrame} as is defined in package {\tt sp} that represents the river Weser basin. The {\tt data} slot contains 6 variables as attributes of 1 observation.\\
	
\item {\tt ctry}: an object {\tt SpatialPolygonsDataFrame} as is defined in package {\tt sp} that represents the administrative boundary of Germany. The {\tt data} slot contains 6 variables as attributes of 1 observation.\\
	
\item {\tt node:} an object {\tt SpatialPointsDataFrame} as is defined in package {\tt sp} that represents the nodes of the ECRINS river network of the river Weser basin. The {\tt data} slot contains 13 variables as attributes of 3882 observations.\\
	
\item {\tt rAller} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Aller, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 88 observations.\\
	
\item {\tt rDiemel} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Diemel, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 39 observations.\\
	
\item {\tt rFulda} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Fulda, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 82 observations.\\
	
\item {\tt rHunte} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Hunte, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 34 observations.\\
	
\item {\tt river} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the ECRINS river network of the river Weser basin. The {\tt data} slot contains 52 variables as attributes of 3874 observations.\\
	
\item {\tt rWerra} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Werra, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 120 observations.\\

\item {\tt rWeser} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Weser. The {\tt data} slot contains 74 variables as attributes of 104 observations.\\

\item {\tt rWiumme} an object {\tt SpatialLinesDataFrame} as is defined in package {\tt sp} that represents the basin of the river Wiumme, a major tributary of the river Weser. The {\tt data} slot contains 74 variables as attributes of 18 observations.\\

\item {\tt station} an object {\tt SpatialPoints} as is defined in package {\tt sp} that represents a point of interest for which the watershed will be aggregated an ordered. Could be a point with the coordinates of a measurement station.\\

\item {\tt subbasin} an object {\tt SpatialPolygonsDataFrame} as is defined in package {\tt sp} that represents the subbasins of the tributaries of the river Weser. The {\tt data} slot contains 4 variables as attributes of 4 observations.\\

\item {\tt zhyd} an object {\tt SpatialPolygonsDataFrame} as is defined in package {\tt sp} that contains the primary hydrological units of the river Weser basin accordingly with ECRINS. The {\tt data} slot contains 50 variables as attributes and 915 observations.\\
\end{itemize}

Some examples for visualising the dataset are presented as follows:

<<c1, eval = TRUE, include = TRUE>>=
	library(Watersheds)
	data(WatershedsData)
	#ls()
	#str(WatershedsData)
	#str(WatershedsData["basin"])


	# plotting river Weser basin
	plot(WatershedsData["ctry"][[1]], col="gray60")
	plot(WatershedsData["basin"][[1]], col="gray30", add=TRUE)
	title("River Weser basin, Germany")

	# plotting subbasins river Weser basin
	plot(WatershedsData["basin"][[1]])
	plot(WatershedsData["subbasin"][[1]], col="gray60",add=TRUE)
	plot(WatershedsData["rWeser"][[1]],col="blue",lwd=2,add=TRUE)
	plot(WatershedsData["rAller"][[1]],col="blue",lwd=1,add=TRUE)
	plot(WatershedsData["rDiemel"][[1]],col="blue",lwd=1,add=TRUE)
	plot(WatershedsData["rFulda"][[1]],col="blue",lwd=1,add=TRUE)
	plot(WatershedsData["rHunte"][[1]],col="blue",lwd=1,add=TRUE)
	plot(WatershedsData["rWerra"][[1]],col="blue",lwd=1,add=TRUE)
	plot(WatershedsData["rWiumme"][[1]],col="blue",lwd=1,add=TRUE)
	title("Subbasins River Weser")

	# plotting primary zhyd watersheds and drainage network inside river Werra subbasin
	# subsetting the river Werra subbasin
	id = list(gIntersects(WatershedsData["rWerra"][[1]], WatershedsData["subbasin"][[1]],byid=TRUE))
	subbasin_rWerra = SpDF_Subset(id,WatershedsData["subbasin"][[1]])
	
	# subsetting the river Werra zhyd watersheds
	id = list(gIntersects(WatershedsData["rWerra"][[1]], WatershedsData["zhyd"][[1]],byid=TRUE))
	zhyd_rWerra = SpDF_Subset(id,WatershedsData["zhyd"][[1]])
	plot(subbasin_rWerra, col="grey60")
	plot(zhyd_rWerra,col="grey50",add=TRUE)
	plot(WatershedsData["rWerra"][[1]],col="blue",lwd=1,add=TRUE)
	title("Subbasin River Weser and primary zhyd watersheds")

	# subsetting the river Werra river drainage watersheds
	id = list(gIntersects(subbasin_rWerra, WatershedsData["river"][[1]],byid=TRUE))
	river_rWerra = SpDF_Subset(id,WatershedsData["river"][[1]])
	plot(subbasin_rWerra,col="grey60")
	plot(WatershedsData["rWerra"][[1]],col="blue",lwd=3,add=TRUE)
	plot(river_rWerra,col="blue1",add=TRUE)
	title("Subbasin River Weser and drainage network")
@

\section{The {\tt Watersheds} objects}

A class {\tt "Watershed"} for representing {\tt "Watershed"} objects.

<<c2, eval = TRUE, include = TRUE>>=
	station1 = WatershedsData["station"][[1]]
	subbasin1 = WatershedsData["subbasin"][[1]]
	zhyd1 = WatershedsData["zhyd"][[1]]
	river1 = WatershedsData["river"][[1]]
	node1 = WatershedsData["node"][[1]]
	
	station1 = SpatialPoints(station1, 
		proj4string=slot(subbasin1,"proj4string"))
	watershed = new("Watershed",station=station1,subbasin=subbasin1,
		zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)
	class(watershed)
@

\section{The {\tt Watersheds.Order} method}

The Method for function {\tt Watershed.Order} allows definition of the properties of the current {\tt zhyd} watershed over {\tt Watershed} objects.

The function takes the object of class {\tt Watershed} and identifies the subbasin that contains the current {\tt station} (class {\tt SpatialPoints}) and subsets the {\tt zhyd} object to subbasin and extract the current {\tt zhy} object that contains {\tt station}. Posteriorly, identifies the inlet and outlet stretches and probable inlet and outlet nodes of the {\tt zhyd}. Then, runs the functions {\tt Watershed. ,IOR1, IOR2, IOR3}, or {\tt IOR4} for determining the actual inlet and outlet nodes. Finally, the method executes the S4 method {\tt Watershed.Tributary} for defining tributary nodes and tributary catchments of the current {\tt zhyd} watershed.

<<c3, eval = TRUE, include = TRUE, warning=FALSE>>=
	station1 = WatershedsData["station"][[1]]
	subbasin1 = WatershedsData["subbasin"][[1]]
	zhyd1 = WatershedsData["zhyd"][[1]]
	river1 = WatershedsData["river"][[1]]
	node1 = WatershedsData["node"][[1]]	

	station1 = SpatialPoints(coords=cbind(4328448.74, 3118576.86), 
		proj4string=slot(subbasin1,"proj4string"))
	watershed = new("Watershed",station=station1,subbasin=subbasin1,
		zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)

	a = Watershed.Order(watershed)
	c1 = a[[1]]
	c1_inlet = a[[2]]
	c1_outlet = a[[3]]
	c2 = a[[4]]
	c3 = a[[5]]
	node_trib = a[[6]]
	sb1 = a[[7]]
	riverIO = a[[8]]
	nodeIO = a[[9]]			
	c1_river = a[[10]]
	c1_node = a[[11]]	

	bbox1 = slot(c1, "bbox")
	bbox = matrix(0,2,2)
	bbox[,1] = bbox1[,1]*.998
	bbox[,2] = bbox1[,2]*1.002
	
	plot(c1, xlim=bbox[1,], ylim=bbox[2,],col="gray50")			
	plot(c2, col="gray75", add=TRUE)
	plot(c3, col="gray85", add=TRUE)
	plot(slot(watershed,"station"),pch=24, bg="blue",add= TRUE)
	plot.PolyLineAttribute(c1, "order", 450, 0.8)
	plot.PolyLineAttribute(c2, "order", 450, 0.8)
	plot.PolyLineAttribute(c3, "order", 450, 0.8)				
	plot(c1_river, col="blue", add=TRUE)
	plot(c1_node,pch=21,bg="blue",cex=.5,add=TRUE)
	plot(nodeIO,pch=21,bg="blue",cex=.5,add=TRUE)
	plot(c1_inlet, pch=21, bg="green",add= TRUE)
	plot(c1_outlet,pch=21, bg="red",add= TRUE)
	plot.PointAttribute(nodeIO,"ELEV",600,0.7)
	title(main="Current zhyd watershed (1)",
		sub="First order tributary watersheds (1.1, 1.2)")
@

\section{The {\tt Watersheds.Order2} method}

S4 Method for function {\tt Watershed.Order2}. Definition of the tributary {\tt zhyd} watersheds of the current {\tt zhyd} watershed.

The method takes the objec of class {\tt Watershed} when object {\tt node\_trib} is length 2. The method identifies the {\tt zhyd} watershed that contaions the current {\tt station} (class {\tt SpatialPoints}) and apply the method {\tt Watershed.Order} on each point of {\tt node\_trib} returning a list of objects {\tt Watershed.Order}. The computation is done via parallel processes for optimizing and take advance of multicore functionalities.

<<c4, eval = TRUE, include = TRUE, warning=FALSE>>=
	station1 = SpatialPoints(coords=cbind(4328650,3174450), 
		proj4string=slot(subbasin1,"proj4string"))
	watershed = new("Watershed",station=station1,subbasin=subbasin1,
		zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)

	a = Watershed.Order(watershed)
	c1 = a[[1]]
	node_trib = a[[6]]
	c1_river = a[[10]]

	watershed2 = new("Watershed", station=node_trib, subbasin=subbasin1, zhyd=zhyd1, river=river1, c1=c1,node=node1)
	c23 = Watershed.Order2(watershed2)
	c2 = c23[[1]]
	c3 = c23[[2]]	
	
	c2.0 = c2[[1]]
	c2_inlet = c2[[2]]
	c2_outlet = c2[[3]]
	c2.1 = c2[[4]]
	c2.2 = c2[[5]]
	c2_node_trib = c2[[6]]
	c2_sb1 = c2[[7]]
	c2_riverIO = c2[[8]]
	c2_nodeIO = c2[[9]]			
	c2_river = c2[[10]]
	c2_node = c2[[11]]	
			
	c3.0 = c3[[1]]
	c3_inlet = c3[[2]]
	c3_outlet = c3[[3]]
	c3.1 = c3[[4]]
	c3.2 = c3[[5]]
	c3_node_trib = c3[[6]]
	c3_sb1 = c3[[7]]
	c3_riverIO = c3[[8]]
	c3_nodeIO = c3[[9]]			
	c3_river = c3[[10]]
	c3_node = c3[[11]]	
	
	# subsetting river networks
	id = list(gIntersects(c2.1, WatershedsData$river,byid=TRUE))
	c21_river = SpDF_Subset(id,WatershedsData$river)

	id = list(gIntersects(c2.2, WatershedsData$river,byid=TRUE))
	c22_river = SpDF_Subset(id,WatershedsData$river)
	
	id = list(gIntersects(c3.1, WatershedsData$river,byid=TRUE))
	c31_river = SpDF_Subset(id,WatershedsData$river)

	id = list(gIntersects(c3.2, WatershedsData$river,byid=TRUE))
	c32_river = SpDF_Subset(id,WatershedsData$river)
	
	# plots
	bbox1 = slot(c3.2, "bbox")
	bbox = matrix(0,2,2)
	bbox[,1] = bbox1[,1]*.995
	bbox[,2] = bbox1[,2]*1.005
							
	plot(c1, col="gray50", xlim=bbox[1,], ylim=bbox[2,])	
	plot(c2.0, col = "gray95", add=TRUE)
	plot(c3.0, col="gray79", add=TRUE)
	plot(c2.1, col="gray78", add=TRUE)
	plot(c2.2, col="gray85", add=TRUE)
	plot(c3.1, col="gray53", add=TRUE)
	plot(c3.2, col="gray63", add=TRUE)

	plot(c1_river, col="blue",add=TRUE)		
	plot(c2_river, col="blue",add=TRUE)		
	plot(c3_river, col="blue",add=TRUE)			
	plot(c21_river, col="blue",add=TRUE)			
	plot(c22_river, col="blue",add=TRUE)			
	plot(c31_river, col="blue",add=TRUE)			
	plot(c32_river, col="blue",add=TRUE)	
	
	title(main="Current zhyd watershed and \n 1st and 2nd order tributary watersheds")
@

\section{The {\tt Watersheds.IOR1} function}

The {\tt Watersheds.IOR1} function means Watershed inlet and outlet nodes: case 1. The function determines the inlet and outlet nodes for {\tt zhyd} watershed objects. This case 1 is for those watersheds that its river inlet and outlet object is length 1 (length(riverIO)=1).

<<c5, eval = TRUE, include = TRUE, warning=FALSE>>=
station1 = SpatialPoints(coords=cbind(4232972,3327634), 
		proj4string=slot(subbasin1,"proj4string"))
	watershed = new("Watershed",station=station1,subbasin=subbasin1,
		zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)

	a = Watershed.Order(watershed)
	c1 = a[[1]]
	nodeIO = a[[9]]			
	c1_river = a[[10]]
			
	# determining inlet and outlet watershed nodes
		# determining distances of nodeIO to c1
		boundary = gBoundary(c1)
		dist = gDistance(nodeIO, boundary, byid =TRUE)
		a = Watershed.IOR1(x=nodeIO, dist=dist)
		c1_inlet = a["inlet"][[1]]; c1_inlet
		c1_outlet = a["outlet"][[1]]; c1_outlet
		
	plot(c1,col="gray50")			
	plot(station1,pch=24, bg="blue",add= TRUE)
	plot(c1_river, col="blue", add=TRUE)
	plot(c1_outlet,pch=21, bg="red",add= TRUE)
	plot.PointAttribute(c1_outlet,"ELEV",700,0.8)
	title(main="Watershed outlet, case I")
@

\section{The {\tt Watersheds.IOR2} function}
The {\tt Watersheds.IOR1} function means Watershed inlet and outlet nodes: case 2. The function determines the inlet and outlet nodes for {\tt zhyd} watershed objects. This case 2 is for those watersheds that its river inlet and outlet object is length 2 (length(riverIO)=2).

<<c6, eval = TRUE, include = TRUE, warning=FALSE>>=
	station1 = SpatialPoints(coords=cbind(4330341.36,3284797.06), 
			proj4string=slot(subbasin1,"proj4string"))
		watershed = new("Watershed",station=station1,subbasin=subbasin1,
			zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)
	
		a = Watershed.Order(watershed)
		c1 = a[[1]]
		nodeIO = a[[9]]			
		c1_river = a[[10]]
		c1_node = a[[11]]	
				
		# determining inlet and outlet watershed nodes
			# determining distances of nodeIO to c1
			boundary = gBoundary(c1)
			dist = gDistance(nodeIO, boundary, byid =TRUE)
			a = Watershed.IOR2(x=nodeIO, dist=dist, node=c1_node)	
		c1_inlet = a["inlet"][[1]]; c1_inlet
		c1_outlet = a["outlet"][[1]]; c1_outlet
			
		plot(c1,col="gray60")			
		plot(station1,pch=24, bg="blue",add= TRUE)
		plot(c1_river, col="blue", add=TRUE)
		plot(c1_outlet,pch=21, bg="red",add= TRUE)
		plot.PointAttribute(c1_outlet,"ELEV",700,0.8)
		title(main="Watershed outlet, case II")
@

\section{The {\tt Watersheds.IOR3} function}
The {\tt Watersheds.IOR1} function means: Watershed inlet and outlet nodes: case 3. The function determines the inlet and outlet nodes for {\tt zhyd} watershed objects. This case 3 is for those watersheds that its river inlet and outlet object is length 3 (length(riverIO)=3).

<<c7, eval = TRUE, include = TRUE, warning=FALSE>>=
	station1 = SpatialPoints(coords=cbind(4217199.42,3353511.83), 
		proj4string=slot(subbasin1,"proj4string"))
	watershed = new("Watershed",station=station1,subbasin=subbasin1,
		zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)

	a = Watershed.Order(watershed)
	c1 = a[[1]]
	riverIO = a[[8]]
	nodeIO = a[[9]]			
	c1_river = a[[10]]
			
	# determining inlet and outlet watershed nodes
		# determining distances of nodeIO to c1
		boundary = gBoundary(c1)
		dist = gDistance(nodeIO, boundary, byid =TRUE)
		a = Watershed.IOR3(x=nodeIO, y=riverIO, dist=dist)	
		c1_inlet = a["inlet"][[1]]; c1_inlet
		c1_outlet = a["outlet"][[1]]; c1_outlet
		
	plot(c1,col="gray60")			
	plot(station1,pch=24, bg="blue",add= TRUE)
	plot(c1_river, col="blue", add=TRUE)
	plot(c1_outlet,pch=21, bg="red",add= TRUE)
	plot(c1_inlet,pch=21, bg="green",add= TRUE)
	plot.PointAttribute(c1_outlet,"ELEV",1000,0.8)
	plot.PointAttribute(c1_inlet,"ELEV",1000,0.8)
	title(main="Watershed outlet and inlet, case III")	
@

\section{The {\tt Watersheds.IOR4} function}
The {\tt Watersheds.IOR1} function means Watershed inlet and outlet nodes: case 4. The function determines the inlet and outlet nodes for {\tt zhyd} watershed objects. This case 4 is for those watersheds that its river inlet and outlet object is length 4 (length(riverIO)=4).

<<c8, eval = TRUE, include = TRUE, warning=FALSE>>=
		station1 = SpatialPoints(coords=cbind(4357947,3284525), 
			proj4string=slot(subbasin1,"proj4string"))
		watershed = new("Watershed",station=station1,subbasin=subbasin1,
			zhyd=zhyd1,river=river1,c1=subbasin1,node=node1)
	
		a = Watershed.Order(watershed)
		c1 = a[[1]]
		riverIO = a[[8]]
		nodeIO = a[[9]]			
		c1_river = a[[10]]
				
		# determining inlet and outlet watershed nodes
			# determining distances of nodeIO to c1
			boundary = gBoundary(c1)
			dist = gDistance(nodeIO, boundary, byid =TRUE)
			a = Watershed.IOR4(x=nodeIO, y=riverIO, dist=dist)
		c1_inlet = a["inlet"][[1]]; c1_inlet
		c1_outlet = a["outlet"][[1]]; c1_outlet
			
		plot(c1,col="gray60")			
		plot(station1,pch=24, bg="blue",add= TRUE)
		plot(c1_river, col="blue", add=TRUE)
		plot(c1_outlet,pch=21, bg="red",add= TRUE)
		plot(c1_inlet,pch=21, bg="green",add= TRUE)
		plot.PointAttribute(c1_outlet,"ELEV",1000,0.8)
		plot.PointAttribute(c1_inlet,"ELEV",1000,0.8)
		title(main="Watershed outlet and inlet, case IV")
@


%\begin{figure}[h!]
%	\begin{center}
%		<<label=fig:plot, echo=FALSE>>=
%			<<fig:plotExtra>>
%		@
%	\end{center}
%	\caption{Plot of {\sf mytracExtra} an object of class {\sf TrajectoryExtra}}
%	\label{fig:plot}
%\end{figure}

%%------------------- Bibliography ----------------------


\bibliography{/Users/Arturo/Documents/00_PhD_Research/PhD}

\end{document}