---
title: "Distance Classification"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Distance Classification}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
--- 

This document explains the use of "distance" in the classification of
of the hill slopes into Hydrological Response Units (HRUs). This is a key
difference in the classification and model creation scheme used with
dynatopGIS compared to previous model implementations (e.g. the dynatopmodel).

As with earlier versions of Dynamic TOPMODEL "physical" classification of the
raster cells representing the hill slopes by
characteristics such as topographic index, soil parameters and rainfall inputs
forms etc. is the basis of determining HRUs. However having the performed a
"physical" classification there is the need to determine the connectivity of
the HRUs and (possibly) the computational sequence for their solution.

Consider the methods utilised in the `dynatopmodel` package which determined the connectivity based on
the down slope contributions of each raster cell in the HRU. This
resulted in a matrix $\mathbf{M)$ of flow fractions such that if the vector of
outflows from the HRUs was $\mathbf{l}_{o}$ the inflows $\mathbf{l}_{i}$ are
given by 
\[
\mathbf{l}_{i} = \mathbf{M} \mathbf{l}_{o}
\]
Determining the down slope contributions in such as fashion enables a high
degree of spatial averaging of the inflow. For example an area at the bottom
of the hillslope near a channel may fall into the same class as the low
gradient area higher up the hillslope, where it might be reasonable to presume
the inflow from adjacent HRUs was much lower. While such averaging may prove
adequate for the hydrological simulation of the outflow it limits the ability
of the model to represent interventions on a smaller scale (e.g. reforestation
of a low fraction of raster cells; leaky dams limiting slowing the transfer of
surface water)

To address this a "distance" is used to ensure an order to the HRUs. 
Currently the code allows for the computation of four distances

- *Band*. A strict sequencing such that all the cells up slope of a raster cell in band $n$ are in
bands $n+1$ and greater.

- *Shortest length*. The minimum length to a river channel through any flow
  path.
  
- *Dominant length*. The length to a river channel following the flow
direction with the highest fraction for each pixel on the path.

- *Expected length*. The length to a river channel based on the sum of
  down slope flow weighted by the fraction of flow to each cell.
  
The "distance" can be used in two ways. Optionally it can be used within the
classification of the HRUs thereby providing spatially ordered HRUs. 
A "distance" is also used in the determining
the connectivity. Each HRU is assigned a single distance based on the raster
cells within it that are closest to the river. The flow directions from these cells are then used to
determine the down slope contributions; which go to HRUs assigned a shorter distance.

> Although this technique is fairly generic it is strongly suggested that the
> band distance is used, both in classification and model generation.

In handling the flow contributions this way we ensure a computational sequence
for the HRUs is established (that is $\mathbf{M}$ is triangular) which is
required for the computational scheme used within the associated dynatop
package.
