---
title: "Introduction to the thundeR package"
author: "Bartosz Czernecki, Mateusz Taszarek, Piotr Szuster"
output: 
  rmarkdown::html_vignette:
    self_contained: false
vignette: >
  %\VignetteIndexEntry{Introduction to the thundeR package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  self_contained: false
---

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

# thundeR <img src="https://github.com/bczernecki/thundeR/raw/master/man/figures/logo.png" style="float:right" width="150"/>

**`thundeR`** is a freeware R package and collection of functions for rapid computation and visualisation of convective parameters commonly used in the operational forecasting of severe convective storms. Core algorithm is based on C++ code implemented into R language via `Rcpp`. This solution allows to compute over 200 thermodynamic and kinematic parameters in less than 0.02s per profile and process large datasets such as reanalyses or operational NWP models in a reasonable amount of time. Package has been developed since 2017 by research meteorologists specializing in severe convective storms and is constantly updated with new features.

## Online browser:

Online rawinsonde browser of `thundeR` package is available at <http://rawinsonde.com>

## Main functions:

- **`sounding_compute()`** - A core function for calculating convective parameters commonly used in the operational prediction of severe convective storms. Returns a vector of parameters.
 
- **`sounding_plot()`** - Function to plot a composite of Skew-T, hodograph and selected convective parameters on a single layout

- **`sounding_save()`**` - Auxiliary function to `sounding_plot` that plots a composite of Skew-T, hodograph and selected convective parameters on a single layout and exports graphical file.

- **`get_sounding()`** - Download rawinsonde measurement from sounding database of the University of Wyoming in a form convenient to use with `thundeR` package.


## Examples

Examples show aplication of selected `thundeR` package functions

### Example 1

Draw Skew-T, hodograph and convective parameters on a single layout and export to png file:

```{r example1, eval = TRUE, fig.width=9, fig.height=6, fig.fullwidth = TRUE}
library(thunder)
data("sounding_vienna") # load example dataset (Vienna rawinsonde profile for 23 Aug 2011 12UTC):
pressure = sounding_vienna$pressure # vector of pressure [hPa]
altitude = sounding_vienna$altitude # vector of altitude [meters]
temp = sounding_vienna$temp  # vector of temperature [degree Celsius]
dpt = sounding_vienna$dpt # vector of dew point temperature [degree Celsius]
wd = sounding_vienna$wd # vector of wind direction [azimuth in degrees]
ws = sounding_vienna$ws # vector of wind speed [knots]
sounding_save(filename = "Vienna.png",
              title = "Vienna - 23 August 2011 1200 UTC",
              pressure, altitude, temp, dpt, wd, ws)
```

<img src="https://github.com/bczernecki/thundeR/raw/master/inst/figures/Vienna.png" alt="Vienna" width="1000"/>

### Example 2

Download North Platte rawinsonde profile for 03 Jul 1999 00UTC and export to png file: 

```{r example2, eval = TRUE}
profile = get_sounding(wmo_id = 72562, yy = 1999, mm = 7, dd = 3, hh = 0)
head(profile) # show first few rows of downloaded dataset
sounding_save(filename = "NorthPlatte.png", title = "North Platte - 03 July 1999 0000 UTC", profile$pressure, profile$altitude, profile$temp, profile$dpt, profile$wd, profile$ws)
```

<img src="https://github.com/bczernecki/thundeR/raw/master/inst/figures/NorthPlatte.png" alt="North Platte" width="1000"/>

### Example 3

Compute convective parameters based on a sample vertical profile data:

```{r example3, eval = TRUE, fig.width=8, fig.height=8, fig.fullwidth = TRUE}
pressure = c(1000, 855, 700, 500, 300, 100, 10) # pressure [hPa]
altitude = c(0, 1500, 2500, 6000, 8500, 12000, 25000) # altitude [meters]
temp = c(25, 10, 0, -15, -30, -50, -92) # temperature [degree Celsius]
dpt = c(20, 5, -5, -30, -55, -80, -99) # dew point temperature [degree Celsius]
wd = c(0, 90, 135, 180, 270, 350, 0) # wind direction [azimuth in degress]
ws = c(5, 10, 20, 30, 40, 5, 0) # wind speed [knots]
accuracy = 2 # accuracy of computations where 3 = high (slow), 2 = medium (recommended), 1 = low (fast)
sounding_compute(pressure, altitude, temp, dpt, wd, ws, accuracy)
```

### Example 4

Download sounding and draw hodograph:

```{r example4, eval = TRUE, fig.width=6, fig.height=6, fig.fullwidth = TRUE}
data("northplatte")
sounding_hodograph(ws = northplatte$ws, wd = northplatte$wd, 
                   altitude = northplatte$altitude,max_speed = 40)
title("North Platte - 03.07.1999, 00:00 UTC")
```

### Example 5 - thunder in Python

It is possible to launch `thunder` under Python via `rpy2` library. Below you can find the minimum reproducible example.
Make sure that `pandas` and `rpy2` libraries are available for your Python environment. If not install required python packages with `pip install pandas` and `pip install rpy2`

Launch `thunder` under Python with `rpy2` and `numpy`:

```{r example7, echo=TRUE}
### load required packages
#> from rpy2.robjects.packages import importr
#> from rpy2.robjects import r,pandas2ri
#> import rpy2.robjects as robjects
#> pandas2ri.activate()

### load thunder package (make sure that it was installed in R before)
#> importr('thunder')

### download North Platte sounding 
#> profile = robjects.r['get_sounding'](wmo_id = 72562, yy = 1999, mm = 7, dd = 3,hh = 0)

### compute convective parameters
#> parameters = robjects.r['sounding_compute'](profile['pressure'], profile['altitude'], #> profile['temp'], profile['dpt'], profile['wd'], profile['ws'], accuracy = 2)


### customize output and print all computed variables, e.g. most-unstable CAPE (first element) equals 9413 J/kg

#> print(list(map('{:.2f}'.format, parameters)))
# '9413.29', '233.35', '1713.74', '0.00', '775.00', '775.00', '15500.00', '-16.55', 
# '137.21', '-66.63', '23.98', '23.98', '23.36', '9413.29', '233.35', '1713.74', '0.00', 
# '775.00', '775.00', '15500.00', '-16.55', '137.21', '-66.63', '23.98', '23.98', '23.36',
# '7805.13', '115.22', '1515.81', '-4.35', '950.00', '950.00', '15000.00', '-14.66', 
# '124.94', '-68.41', '22.46', '22.46', '21.17', '-9.57', '-6.68', '-8.80', '-8.68', 
# '-9.06', '-7.70', '4250.00', '3500.00', '0.00', '2866.00', '50.57', '52.93', '1381.81', 
# '308.98', '29.00', '37.59', '87.03', '0.58', '0.40', '0.47', '8.85', '11.21', '13.88', 
# '20.28', '29.33', '6.84', '21.70', '28.32', '28.32', '27.17', '17.06', '12.53', '12.53',
# '11.74', '7.09', '6.08', '7.77', '7.69', '19.89', '62.07', '110.06', '156.48', '6.25', 
# '7.77', '4.26', '-42.78', '284.67', '5.65', '197.60', '14.19', '218.89', '7.77',
# '31.50', '-12.14', '60.40', '677.12', '4.67', '6.10', '29.46', '29.46', '3.86', '12.35',
# '2783.07', '2783.07', '2534.22', '3886.07', '3886.07', '3395.00']
```



### Important notes

- Remember to always input wind speed data in knots. 
- Script will always consider first height level as the surface (h = 0), therefore input height data can be as above sea level (ASL) or above ground level (AGL). 
- For efficiency purposes it is highly recommended to input data for a maximum of 16-18 km AGL or lower.
- Values of parameters will be different for different accuracy settings. 


```{r cleaning, message=FALSE, warning=FALSE, include=FALSE}
# cleaning
file.remove("Vienna.png")
file.remove("NorthPlatte.png")
options(old_options)
```