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




``` {r setup, include = FALSE}
library(StormR)
library(terra)
library(rworldxtra)
data("countriesHigh")
```

The `defStormsList()` function allows to extract tropical cyclone track data for a
given tropical cyclone or set of tropical cyclones nearby a given location of
interest (`loi`). The `loi` can be defined using a country name, a specific
point (defined by its longitude and latitude coordinates), or any user imported
or defined spatial polygon shapefiles. By default only observations located
within 300 km around the `loi` are extracted but this can be changed using the
`max_dist` argument. Users can also extract tropical cyclones using the `name`
of the storm or the `season` during which it occurred. If both the `name` and
the `season` arguments are not filled then the `defStormsList()` function extracts all
tropical cyclones since the first cyclonic season in the database. Once the data
are extracted, the `plotStorms()` function can be used to visualize the
trajectories and points of observation of extracted tropical cyclones on a map.

In the following example we use the `test_dataset` provided with the package to
illustrate how cyclone track data can be extracted and visualised using country
and cyclone names, specific point locations, and polygon shapefiles, as
described below.

### Getting and ploting tropical cyclone track data

#### Using country names

We extract data on the tropical cyclone Pam (2015) nearby Vanuatu as follows:  

``` {r chunk1}
sds <- defStormsDataset(verbose = 0)
st <- defStormsList(sds = sds, loi = "Vanuatu", names = "PAM", verbose = 0)
```

The `defStormsList()` function returns a `stormsList` object in which the first slot
`@data` contains a list of `Storm` objects. With the above specification the
`stormsList` contains only one `Storm` object corresponding to cyclone PAM and
the track data can be obtained using the `getObs()` function as follows:

``` {r chunk2}
head(getObs(st, name = "PAM"))
```

The number of observation and the indices of the observations can be obtained
using the `getNbObs()` and `getInObs()` as follows:

``` {r chunk3}
getNbObs(st, name = "PAM")
getInObs(st, name = "PAM")
```

The data can be visualised on a map as follows:

``` {r chunk4}
plotStorms(st, labels = TRUE)
```

#### Using a specified point location

We can extract all tropical cyclones near Nouméa (longitude = 166.45, latitude =
-22.27) between 2015 and 2021 as follows:

``` {r chunk5}
pt <- c(166.45, -22.27)
st <- defStormsList(sds = sds, loi = pt, seasons = c(2015, 2021), verbose = 0)
```

The number, the names, and the season of occurrence of the storms in the
returned `stormsList` object can be obtained using the `getNbStorms()`,
`getNames()`, and `getSeasons()` functions as follows:

``` {r chunk6}
getNbStorms(st)
getNames(st)
getSeasons(st)
```

We can plot track data for the topical cyclone Niran only using the `names`
argument of the `plotStorms()` function as follows:

``` {r chunk7}
plotStorms(st, names = "NIRAN", labels = TRUE, legends = "bottomleft")
```

The track data for Niran can also be extracted and stored in a new object using
the `getStorm()` function as follows:

``` {r chunk8}
NIRAN <- getStorm(st, name = "NIRAN")
getNames(NIRAN)
```

#### Using a user defined spatial polygon shapefile 

We can extract all tropical cyclones that occurred between 2015 and 2021 near
the New Caledonia exclusive economic zone using the `eezNC` shapefile provided
with the `StormR` package as follows:

``` {r chunk9}
sp <- eezNC
st <- defStormsList(sds = sds, loi = eezNC, season = c(2015, 2021), verbose = 0)
```


Information about the spatial extent of the track data exaction can be obtained
using the `getLOI()`, `getBuffer()`, and `getBufferSize()` functions as follows:

``` {r chunk10}
LOI <- getLOI(st)
Buffer <- getBuffer(st)
BufferSize <- getBufferSize(st)
terra::plot(Buffer, lty = 3, main = paste(BufferSize, "km buffer arround New Caledonian EEZ", sep = " "))
terra::plot(LOI, add = TRUE)
terra::plot(countriesHigh, add = TRUE)
```

### Working with multiple storms

When extracting multiple storms for a long period of time, you can find yourself 
with multiple storms sharing the same name, that can later break `StormR`. You need 
to avoid working with duplicated name (especially relevant when both storms in a 
stormsList have the same name on the same season). Some 
workarounds may help you with that:

- use the "removeUnnamed" argument to `defStormsList`
- use the `renameStorms` function:

``` {r duplicatedNames}
getNames(st)
st_renamed <- renameStorms(st)
getNames(st_renamed)
```

### Using different wind scale


By default the Saffir-Simpson hurricane wind scale (SSHS) is used in `defStormsList()`
to assign level to storms.

The maximum level reached in the scale for each cyclone
can then be obtained using the `getScale()` function as follows:

``` {r chunk11}
getScale(st)
```

In this case, the SSHS scale is composed of 6 thresholds resulting in 6 levels
spanning from level 0 to level 6.

We can only plot cyclones that reached level 5 and 6 using the `category`
argument of the `plotStorms()` function as follows:

``` {r chunk12}
plotStorms(st, category = c(5, 6), labels = FALSE, legends = "topright")
```
Finally, the user can choose his own scale and associated palette, by setting the `scale` and `scalePalette` inputs in `defStormsList()`. In the following example, we use the Tokyo's tropical cyclone intensity scale to analyse tropical storm PAM.

StormR provides default palette and category names:

```{r chunk 12}
# Tokyo's tropical cyclone intensity scale
RSMCScale <- c(16.94, 24.44, 32.5, 43.33, 53.61)

sts_jpn <- defStormsList(sds = sds,
                         loi = "Vanuatu",
                         names = "PAM",
                         scale = RSMCScale,
                         verbose = 0)

plotStorms(sts_jpn)
```

But you can also easily customize them:
```{r chunk 13}
RSMCPalette <- c("#6ec1ea", "#4dffff", "#c0ffc0", "#ffd98c", "#ff738a", "#a188fc")
names(RSMCPalette) <- c("Tropical depression",
                        "Tropical storm",
                        "Severe tropical storm",
                        "Typhoon",
                        "Very strong typhoon",
                        "Violent typhoon")

sts_jpn <- defStormsList(sds = sds,
                         loi = "Vanuatu",
                         names = "PAM",
                         scale = RSMCScale,
                         scalePalette = RSMCPalette,
                         verbose = 0)

plotStorms(sts_jpn)
```


### Dynamic plot

`plotStorms` allows the user to dynamically plot tracks within an interactive map using leaflet
library by setting `dynamicPlot` to `TRUE`. Doing so, the user can explore the map the way he wants
and click and each dotted colored observations to see there informations.

``` {r chunk13}
# Example of dynamic plot, using the same parameters above
plotStorms(st, category = c(4, 5), labels = FALSE, legends = "topright", dynamicPlot=TRUE)
```

