---
title: "temporalBehaviour"
output: rmarkdown::html_vignette
date: "`r Sys.Date()`"
vignette: >
   %\VignetteIndexEntry{temporalBehaviour}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
---


``` {r setup, include = FALSE}
library(StormR)
```

The `temporalBehaviour()` function allows computing wind speed and direction for
a given location or set of locations along the lifespan of a tropical cyclone.
It also allows to compute to compute three associated summary statistics: the
maximum sustained wind speed (`product="MSW"`), the power dissipation index
(`product="PDI"`) and the duration of exposure to winds reaching defined speed
thresholds along the life span of the cyclones (`product="Exposure"`).

In the following example we use the `test_dataset` provided with the package to
illustrate how cyclone track data can be used to compute and plot time series of
wind speed and direction and how to compute summary statistics for specific
locations, as described below.

### Computing and plotting time series of wind speed and direction

We compute and plot time series of the speed and direction of winds generated by
the topical cyclone Pam (2015) in two of the main cities of Vanuatu, Port Vila
(longitude = 168.33, latitude = -17.73) and Luganville (longitude = 167.17,
latitude = -15.53). The coordinates of the two locations of interest are
provided in a data frame as follows:

``` {r}
df <- data.frame(x = c(168.33, 167.17), y = c(-17.73, -15.53))
rownames(df) <- c("Port_Vila", "Luganville")
```

The track data for Pam nearby Vanuatu are extracted as follows:

``` {r}
sds <- defStormsDataset()
st <- defStormsList(sds = sds, loi = "Vanuatu", names = "PAM", verbose = 0)
plotStorms(st)
points(df$x, df$y, pch = 3, col = c("blue", "red"))
text(df$x, df$y, labels = c("Port Vila", "Luganville"), pos = 2, col = c("blue", "red"), cex = 0.8)
```

Then the `temporalBehaviour()` function with the `product = "TS"` argument is
used to compute time series. By default the temporal resolution of is set to 1
hour but can be changed using the `tempRes` argument. Here we set the temporal
resolution to 30 min with `tempRes=0.5` as follows:

``` {r}
TS <- temporalBehaviour(st, points = df, product = "TS", tempRes = 30, verbose = 0)
```

With the above specification the `temporalBehaviour()` function returns a list
of two data frames (i.e., one for each location) with the wind speed ("speed"),
direction ("direction"), indices of the observations and the date and time of
the observation ("isoTimes").

``` {r}
str(TS)
```

We use the data frame and the `plotTemporal()` function to draw time series plots for wind speed and wind
direction as follows:

``` {r , include = FALSE}
oldpar <- par(mar = c(10, 4, 4, 2))
```

``` {r}
plotTemporal(data=TS, storm="PAM")
```

``` {r , include = FALSE}
dev.off()
```

``` {r}
plotTemporal(data=TS, storm="PAM", var='direction')
```

``` {r , include = FALSE}
par(oldpar)
dev.off()
```

Maximum sustained wind speed for Port Vila and Luganville can be computed as
follows:

``` {r}
max(TS$PAM$Port_Vila$speed, na.rm = TRUE)
max(TS$PAM$Luganville$speed, na.rm = TRUE)
```

### Getting power dissipation index

The power dissipation index is computed using the `product = "PDI"` argument as
follows:

``` {r}
PDI <- temporalBehaviour(st, points = df, product = "PDI", tempRes = 30, verbose = 0)
PDI
```

### Getting duration of exposure

The duration of exposure is computed using the `product = "Exposure"` argument
as follows:

``` {r}
exposure_SS <- temporalBehaviour(st, points = df, product = "Exposure", tempRes = 30, verbose = 0)
exposure_SS
```

By default, the function returns the duration of exposure (in hours) to wind
speeds above the thresholds used by the Saffir-Simpson hurricane wind scale
(i.e., 18, 33, 42, 49, 58, and 70 $m.s^{-1}$). However, different thresholds can
be set using the `wind_threshold` arguments. We can use the thresholds used by
the Australian Bureau of Meteorology to rank tropical cyclones intensity as
follow:

``` {r}
wt <- c(17.2, 24.4, 32.5, 44.2, 55.0)
exposure_BOM <- temporalBehaviour(st, points = df, product = "Exposure", tempRes = 30, windThreshold = wt, verbose = 0)
exposure_BOM
```