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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The UKFE package offers a range of functions that can produce plots. Some of these help visualise data prior to analysis, while others plot results. Examples can be seen throughout the other articles. The examples in this article are from the functions' help files; these also contain further details about each function.

We will start by loading the UKFE package:
```{r setup}
library(UKFE)
```

# Plotting flow and rainfall data

The following functions can be used to plot annual maxima (AMAX) and peaks over threshold (POT) data:

* `AMplot()`: Produces a bar plot of AMAX data.

```{r fig.alt="Bar chart of annual maximum (AMAX) flow values. Each bar represents the highest recorded flow in a given year, with year index on the x-axis and flow magnitude on the y-axis. The chart shows variation across years, with particularly large peaks in 1980, 1999, and 2020."}

# Get an AMAX sample and plot
AMplot(GetAM(58002))
```

* `POTextract()` and `POTt()`: Plot a hydrograph with POT data shown. Note that these functions extract the data and then plot as a handy by-product. They cannot be used to plot POT data once extracted.

```{r fig.alt="Time series plot of flow showing extraction of peaks over threshold events. The x-axis shows time and the y-axis shows flow magnitude. Red circles mark exceedances above the blue threshold line. A green line indicates div, which defines independence between peaks; in this case it is set to the mean. Exceedances occur throughout the record, with a lull around 2005, followed by a marked increase in frequency afterwards."}
# Extract POT flows for the Thames at Kingston (NRFA gauge 39001) and plot. Note that 
# the indexing 'ThamesPQ[, c(1, 3)]' is necessary because the date is in the first 
# column of the 'ThamesPQ' data frame and the flow is in the third.
ThamesQPOT <- POTextract(ThamesPQ[, c(1, 3)], thresh = 0.9, Plot = TRUE)
```

```{r fig.alt="Plot showing extraction of peaks over threshold (POT) events from a rainfall time series. The x-axis shows time and the y-axis shows flow magnitude. Red circles mark rainfall values exceeding the blue threshold line, which identifies independent extreme events. Exceedances occur throughout, with particularly large peaks around 2000, 2007, and 2014."}

# Extract POT rainfall for the Thames at Kingston (NRFA gauge 39001) and plot. Note that
# the indexing 'ThamesPQ[, 1:2]' is necessary because the date is in the first column 
# of the 'ThamesPQ' data frame and the rainfall is in the second.
ThamesPPOT <- POTt(ThamesPQ[, 1:2], threshold = 0.95, div = 14, Plot = TRUE)
```

* `HydroPlot()`: Plots concurrent precipitation and discharge from a time series, with a choice of date range (defaulting to all the data).

```{r fig.alt="“Time series plot showing precipitation and river discharge together. The x-axis shows time. River discharge is shown as a line with flow values on the left y-axis, while precipitation is displayed as inverted bars with rainfall on the right y-axis. This allows comparison of rainfall events with resulting river flows. A sustained period of elevated rainfall and associated discharge is evident from December 2013 through to March 2014.”"}
# Plot the 2013 water year precipitation and discharge for the Thames at Kingston 
# (NRFA gauge 39001), adjusting the closeness of the precipitation and discharge 
# on the y-axis to 1.8.
HydroPlot(ThamesPQ, From = "2013-10-01", To = "2014-09-30", adj.y = 1.8)
```

* `MonthlyStats()`: Derives monthly statistics from a time series. There is an option to plot these.

```{r fig.alt="Bar plot showing mean river discharge for each calendar month, with the x-axis representing months and mean flow values on the y-axis. Flows are highest in winter, with January showing the maximum, and lowest in late summer, with September showing the minimum. As expected. Discharge is elevated from November through March, and decreases gradually into summer before rising again into autumn."}
# Calculate the mean flows for each month for the Thames at Kingston (NRFA gauge 39001)
# and set the plot title using the 'main' argument
QMonThames <- MonthlyStats(ThamesPQ[, c(1, 3)], Stat = mean, ylab = "Discharge (m3/s)", 
                           main = "Thames at Kingston monthly mean flow", Plot = TRUE)
```

```{r fig.alt="Bar plot showing the mean total rainfall for each calendar month. The x-axis shows months and the y-axis shows rainfall totals, allowing comparison of rainfall patterns across the year. Rainfall is relatively high throughout, with a clear minimum in September and a maximum in November. The wettest period extends from October through January."}
# Calculate the monthly sums of rainfall for the Thames at Kingston and set the plot 
# title using the 'main' argument
PMonThames <- MonthlyStats(ThamesPQ[, c(1, 2)], Stat = sum, ylab = "Rainfall (mm)", 
                           main = "Thames at Kingston monthly rainfall", Plot = TRUE)
```

* `BFI()`: Calculates the baseflow index from a daily mean flow series and plots the flow time series (black) and the associated baseflow (red).

```{r fig.alt="Line plot showing river discharge over time. The x-axis shows time in days and the y-axis shows daily mean flow. Total flow is shown in black, and baseflow is shown in red. Flows are relatively constant overall, with peaks occurring at fairly regular intervals. Baseflow rises and falls with total flow, but remains lower in magnitude."}
# Calculate the BFI from daily discharge at Kingston upon Thames (which is in the 
# third column of the 'ThamesPQ' data)
BFI(ThamesPQ[, 3])
```

* `FlowSplit()`: Separates baseflow from runoff (intended for event-scale rather than long-term flow series). Plots the flow time series in black and the baseflow in red.

```{r fig.alt="Time series plot of streamflow and baseflow. The x-axis shows time and the y-axis shows flow. Total flow is shown in black, and baseflow is shown in red. During events, total flow increases sharply, whereas baseflow rises more gradually and remains much lower in magnitude, highlighting the contrast between quick flow responses and the slower baseflow contribution."}
# Extract a wet six-month period at the Thames at Kingston (NRFA gauge 39001) during 
# the 2006-2007 water year (flow is in the third column of ThamesPQ)
ThamesQ <- subset(ThamesPQ[, c(1, 3)], Date >= "2006-11-04" & Date <= "2007-05-06")
# Apply the flow split with default settings
QSplit <- FlowSplit(ThamesQ$Q)
```

* `DesHydro()`: Extracts a mean hydrograph from a flow series. 

```{r fig.alt="Time series plot showing a black line representing the averaged design hydrograph, derived by aligning individual hydrographs on their peak flow and then averaging. The observed hydrographs are shown as coloured and patterned lines. The x-axis represents time and the y-axis shows scaled discharge. The individual hydrographs vary considerably: some display additional smaller peaks around the main one, while others differ in steepness and shape. In general, hydrographs with higher pre-peak discharge also exhibit higher post-peak discharge. All converge at the peak, and the overall mean hydrograph follows the typical triangular, inverted-V shape."}
# Extract a design hydrograph from the Thames at Kingston (NRFA gauge 39001) daily 
# mean flow and print the resulting hydrograph
ThamesDesHydro <- DesHydro(ThamesPQ[, c(1, 3)], EventSep = 10, N = 10)
```

* `FlowDurationCurve()`: Plots flow duration curves for a single flow series or from multiple flow series. These can be winter, summer or annual curves.

```{r fig.alt="Plot showing flow duration curves for a single flow series with seasonal variations. The x-axis shows the percentage of time flow is exceeded, and the y-axis shows discharge. The annual curve is shown as a black line, the winter curve as a blue line, and the summer curve as a green line. Winter flows are consistently highest, followed by annual, then summer. All curves follow the expected pattern of high discharges at low exceedance percentages and progressively lower discharges as exceedance percentages increase."}
# Plot a flow duration curve for the Thames at Kingston (NRFA gauge 39001) using 
# data from Oct 2000 to Sep 2015
FlowDurationCurve(ThamesPQ[, c(1, 3)])
```

* `Rating()`: Optimises a power law rating equation from observed discharge and stage and plots the resulting rating curve.

```{r fig.alt="Plot showing the relationship between discharge (x-axis) and stage (y-axis). Observed measurements are shown as open circles with black borders, and a red line represents the optimised power law rating equation fitted to these observations. For this dataset, stage and discharge exhibit an almost linear relationship, with the fitted curve close to straight but showing a very gradual downward concavity while remaining continuously increasing."}
# Make up some flow (Q) and stage data to act as gaugings
Q <- c(177.685, 240.898, 221.954, 205.55, 383.051, 154.061, 216.582)
Stage <- c(1.855, 2.109, 2.037, 1.972, 2.574, 1.748, 2.016)
Observations <- data.frame(Q, Stage)

# Apply the rating function
Rating(Observations)
```

* `DDFImport()` and `DDFExtract()`: Plot depth-duration-frequency curves. The former imports the depth-duration-frequency 2013 or 2022 results from XML files from either the FEH Web Service or the NRFA Peak Flow Dataset. The latter derives depth-duration-frequency curves from a rainfall time series (assuming that the AMAX data follow a GEV distribution).

```{r fig.alt="Depth–Duration–Frequency (DDF) plot showing rainfall depth in millimetres (y-axis) as a function of storm duration in hours (x-axis) for a range of return periods. Each curve represents a different return period. All curves follow the characteristic DDF shape, with rainfall depth increasing as event rarity increases and with longer storm durations, particularly at the longer return periods."}
# Extract 15-minute rainfall from the St Ives (Cambridgeshire) rain gauge
StIves <- tryCatch(
  GetDataEA_Rain(WISKI_ID = "179365", Period = "15Mins", From = "2022-01-01", To = "2025-01-31"),
  error = function(e) NULL
)


if (!is.null(StIves) && nrow(StIves) > 0) {
  DDFExtract(StIves)
} else {
  message("Environment Agency API did not return data; skipping plot generation.")
}

```

# Plotting results

The following functions can be used to plot results from functions used in Flood Estimation Handbook (FEH) Statistical or Revitalised Flood Hydrograph (ReFH) analyses. Examples can be seen in the respective articles.

## Pooling group diagnostic plots

* `DiagPlots()`

## Distribution fits, growth curves and flood frequency curves

* `ERPlot()`

* `EVPlot()` and `EVPlotAdd()`

* `EVPool()`

## Uncertainty plots

* `Uncertainty()`

## ReFH plots

* `ReFH()`
