---
title: "Getting started with floodflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with floodflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 4
)
set.seed(1)
```

`floodflow` turns a rainfall record and a bit of catchment description into a
flood hazard assessment, and it is built for places with sparse data. The whole
workflow is a chain of stages carried by a single object, and every stage is
designed to return something you could map.

This vignette runs end to end using only the pure-R core, so it works without
any of the optional modelling engines installed. Where an engine (such as
`terra`, `airGR` or `tmap`) would add capability, the text says so.

```{r setup}
library(floodflow)
```

## The project object

Everything hangs on one object, `flood_project()`, which accumulates data and
results as it passes through the pipeline. It starts almost empty.

```{r project}
fp <- flood_project("Odaw basin, Accra", crs = "EPSG:32630")
fp
```

## A minimal end-to-end run

With a daily rainfall record in hand, a flood depth is only a few steps away.
Here we build a synthetic 31-year record, then run rainfall analysis, runoff and
routing.

```{r minimal}
dates <- seq(as.Date("1990-01-01"), as.Date("2020-12-31"), by = "day")
rain <- data.frame(
  date = dates,
  precip_mm = round(rgamma(length(dates), 0.7, scale = 7) *
                    rbinom(length(dates), 1, 0.3), 1)
)

fp$rainfall <- rain
fp <- flood_extremes(fp)
fp <- flood_runoff(fp, engine = "simple")
fp <- flood_route(fp, area_km2 = 300)

fp$route
```

That is the shortest path from rain to a routed flood depth. The remaining
stages add climate scenarios, roughness detail, hydraulics, uncertainty, risk
and mapping.

## Rainfall extremes and a test for change

`flood_extremes()` fits the generalized extreme value distribution to annual
maximum rainfall and, at the same time, tests whether extremes are intensifying
by comparing a stationary fit against one whose location trends with time.

```{r extremes}
fp$extremes
```

The `return_levels` give design rainfall by return period; `trend_detected`
reports the outcome of the likelihood-ratio test.

## Climate scenarios

`flood_scenario()` turns today's design rainfall into a future one. The `delta`
method scales by a change factor (for example from a published CMIP6 summary),
while `trend` projects the fitted trend forward. Here they sit side by side.

```{r scenarios}
baseline <- fp$extremes$return_levels
delta   <- flood_scenario(fp$extremes, method = "delta",
                          change_factor = 1.2)$adjusted
trend   <- flood_scenario(fp$extremes, method = "trend",
                          horizon_year = 2060)$adjusted

data.frame(
  period      = baseline$period,
  present_mm  = baseline$level_mm,
  delta_mm    = delta$level_mm,
  trend_mm    = trend$level_mm
)
```

## Roughness

Manning's roughness is the most sensitive hydraulic input, so `roughness()`
makes the choice explicit. It can be a constant, a lookup from land cover, or a
function of vegetation index.

```{r roughness}
roughness(method = "constant", value = 0.035)$n
roughness(c("urban", "cropland", "forest", "water"), method = "landcover")$n
```

The land-cover values come from the built-in `floodflow_lc_roughness` table,
which you can replace with your own.

## The routing ladder

`flood_route()` offers five methods of increasing physical detail. They share a
depth calculation but differ in how the flood wave attenuates. Sending one
hydrograph through several methods shows the ordering: kinematic routing keeps
the peak highest, diffusive attenuates it most.

```{r ladder}
event <- data.frame(
  date = seq(as.Date("2020-06-01"), by = "day", length.out = 20),
  Q_mm = c(0, 1, 3, 8, 18, 30, 50, 40, 30, 20, 12, 7, 4, 2, 1, rep(0, 5))
)

sapply(c("kinematic", "muskingum-cunge", "diffusive"),
       function(m) flood_route(event, method = m, area_km2 = 300)$attenuation)
```

Values nearer 1 retain more of the peak. The attenuation falls as the method
adds diffusion, which is the physically expected ordering.

## Hydraulics

From a routed flood, `flood_hydraulics()` derives velocity, time of
concentration by several formulae, travel time and an event-relative
time-to-peak.

```{r hydraulics}
fp <- flood_hydraulics(fp, length_m = 12000, overland_m = 200)
fp$hydraulics$tc
```

## Uncertainty and calibration

`flood_uncertainty()` applies GLUE: it samples the uncertain parameters, weights
each run by its agreement with an observed depth, and returns a predictive band
plus inverse parameter estimates. It reports the equifinality among parameters
rather than hiding it.

```{r uncertainty}
u <- flood_uncertainty(fp$route,
                       observed_depth_m = fp$route$peak_depth_m,
                       n_sim = 1000, seed = 1)
u$depth_band
u$obs_in_band
```

## Vulnerability and risk

`flood_vulnerability()` combines the hazard with exposure and social
vulnerability as `Risk = Hazard x Exposure x Vulnerability`, so the output is a
map of where deep water meets vulnerable people, not just where water goes.

```{r vulnerability}
set.seed(2)
v <- flood_vulnerability(
  runif(100, 0, fp$route$peak_depth_m),  # hazard (depth) per cell
  exposure = rpois(100, 60),             # population
  vulnerability = runif(100)             # deprivation index
)
v$summary
```

## Mapping

`flood_map()` renders a chosen layer. With `tmap` or `leaflet` installed and a
spatial layer, it draws an interactive map; otherwise it returns a tidy summary
so the pipeline still works. The scalar example here returns a summary.

```{r map}
flood_map(fp, layer = "depth")$data
```

## Optional engines

The core shown above is pure R. Installing optional engines upgrades individual
stages: `extRemes` for extreme value fitting, `airGR` for GR4J runoff, `terra`
and `whitebox` for spatial terrain work, `ranger` for the surrogate, and `tmap`
or `leaflet` for interactive maps. Each stage checks for its engine and falls
back or reports clearly when it is absent, so nothing here breaks if an engine
is missing.

For the full range of workflows, including spatial-raster and engine-based
scenarios, see the getting-started guide that ships with the package.