---
title: "`weathermetrics` package vignette"
author: "G. Brooke Anderson, Roger D. Peng, and Joshua M. Ferreri"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{weathermetrics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
references: 
- id: anderson2013heat 
  title: Methods to calculate the heat index as an exposure metric in environmental health research. 
  author: 
  - family: Anderson 
    given: G. Brooke 
  - family: Bell 
    given: Michelle L. 
  - family: Peng 
    given: Roger D. 
  container-title: Environmental Health Perspectives 
  volume: 121 
  URL: 'http://ehp.niehs.nih.gov/1206273/' 
  DOI: 10.1289/ehp.1206273 
  issued: 
    year: 2013
  issue: 10 
  pages: 1111-1119 
  type: article-journal
---

```{r echo = FALSE}
library(weathermetrics)
```


## Package contents

The `weathermetrics` package provides the following functions to calculate or convert between several weather metrics:

Weather variable | Function | Input and / or output metric choices
-----------------|---------------------|----------------
Temperature | `convert_temperature` | `"kelvin"`, `"celsius"`, `"fahrenheit"`
Wind speed | `convert_wind_speed` | `"knots"`, `"mph"`, `"mps"`, `"ftps"`, `"kmph"`
Precipitation | `convert_precip` | `"inches"`, `"mm"`, `"cm"`
Dew point temperature | `humidity.to.dewpoint` | `"celsius"`, `"fahrenheit"`
Relative humidity | `dewpoint.to.humidity` | `"celsius"`, `"fahrenheit"`
Heat index | `heat.index` | `"celsius"`, `"fahrenheit"`

Algorithms for heat index and wind speed are adapted for R from the algorithms used by the United States National Weather Service's [online heat index calculator](http://www.wpc.ncep.noaa.gov/html/heatindex.shtml) (accessed December 18, 2015) and the National Oceanic and Atmospheric Administration's [online wind speed conversion](http://www.srh.noaa.gov/epz/?n=wxcalc_windconvert) (accessed February 22, 2016). 

## Converting or calculating weather metrics

### Converting between temperature measurements

This package includes a function, `convert_temperature`, that allows you to convert between common temperature measures including degrees Celsius, Fahrenheit, and Kelvin. The following examples show the use of this function for three example datasets:

To convert between degrees Celsius, Fahrenheit, and Kelvin, use the `convert_temperature` function:

```{r}
#Convert from degrees Celsius to degress Fahrenheit
data(lyon)
lyon$TemperatureF <- convert_temperature(lyon$TemperatureC,
   old_metric = "celsius", new_metric = "fahrenheit")
lyon$DewpointF <- convert_temperature(lyon$DewpointC, 
   old_metric = "celsius", new_metric = "fahrenheit")
lyon
#Convert from degrees Fahrenheit to degrees Celsius
data(norfolk)
norfolk$TemperatureC <- convert_temperature(norfolk$TemperatureF,
   old_metric = "f", new_metric = "c")
norfolk$DewpointC <- convert_temperature(norfolk$DewpointF, 
   old_metric = "f", new_metric = "c")
norfolk
#Convert from degrees Kelvin to degrees Celsius
data(angeles)
angeles$TemperatureC <- convert_temperature(angeles$TemperatureK,
   old_metric = "kelvin", new_metric = "celsius")
angeles$DewpointC <- convert_temperature(angeles$DewpointK, 
   old_metric = "kelvin", new_metric = "celsius")
angeles
```

You can specify whether air temperature and dew point temperature inputs are in degrees Celsius, Fahrenheit, or Kelvin using the `old_metric` and `new_metric` options (possible values are `'celsius'`, `'fahrenheit'`, `'kelvin'`, or `'c'`, `'f'`, and `'k'` for the same). The input for `old_metric` should be the temperature measure that you want to convert from, and the input for `new_metric` should be the temperature measure you wish to convert to. 

The `convert_temperature` function is a wrapper function for a variety of individual temperature conversion functions, including: `celsius.to.fahrenheit`, `fahrenheit.to.celsius`, `celsius.to.kelvin`, `kelvin.to.celsius`, `fahrenheit.to.kelvin`, and `kelvin.to.fahrenheit` functions, which you can use individually if you would like. 

### Calculating relative humidity and dew point temperature

The `weathermetrics` package includes two functions for converting between air temperature, dew point temperature, and relative humidity:
`dewpoint.to.humidity` and `humidity.to.dewpoint`. 

For example, the `lyon` data set includes daily values of both air temperature (`lyon$TemperatureC`) and dew point temperature (`lyon$DewpointC`).  Since this data set includes both air temperature and dew point temperature, you can calculate relative humidity using the `dewpoint.to.humidity` function:

```{r}
data(lyon)
lyon$RH <- dewpoint.to.humidity(t = lyon$TemperatureC,
                                dp = lyon$DewpointC,
                                temperature.metric = "celsius")
lyon
```

You should specify whether air temperature and dew point temperature inputs are in degrees Fahrenheit or Celsius using the `temperature.metric` argument (possible values are `'fahrenheit'` and `'celsius'`). If input values for temperature and dew point temperature are in different metrics (i.e., one is in degrees Fahrenheit and the other in degrees Celsius), you must convert one of the inputs using either `celsius.to.fahrenheit` or `fahrenheit.to.celsius` before you can input the values to the `dewpoint.to.humidity` function.

As an example of calculating dew point temperature, the `newhaven` data set gives daily values of air temperature in degrees Fahrenheit (`newhaven$TemperatureF`) and relative humidity in % (`newhaven$Relative.Humidity`). Since this data set includes values for both temperature and relative humidity, you can calculate dew point temperature using the `humidity.to.dewpoint` function:

```{r}
data(newhaven)
newhaven$DP <- humidity.to.dewpoint(t = newhaven$TemperatureF,
                                    rh = newhaven$Relative.Humidity,
                                    temperature.metric = "fahrenheit")
newhaven
```

Relative humidity must be input as %, and you must specify the metric of air temperature using the `temperature.metric` argument (possible values: `'fahrenheit'` or `'celsius'`). The dew point temperature will be calculated using the same metric as the air temperature input to the function. If you wish to get dew point temperature in a different metric than air temperature, you can use the `convert_temperature` function. For example:

```{r}
data(newhaven)
newhaven$DP <- humidity.to.dewpoint(t = newhaven$TemperatureF,
                                    rh = newhaven$Relative.Humidity,
                                    temperature.metric = "fahrenheit")
newhaven$DP_C <- convert_temperature(newhaven$DP, old_metric = "f", new_metric = "c")
newhaven
```

Calculations between air temperature, relative humidity, and dew point temperature are based on algorithms used by the United States National Weather Service's [online heat index calculator](http://www.wpc.ncep.noaa.gov/html/heatindex.shtml) (accessed December 18, 2015). These are approximations rather than exact conversions.

### Calculating heat index

The `weathermetrics` package includes a function, `heat.index`, that allows you to calculate a vector of heat index values from vectors of air temperature and either dew point temperature or relative humidity. For example, the `suffolk` data set gives daily values of air temperature in degrees Fahrenheit (`suffolk$TemperatureF`) and relative humidity in % (`suffolk$Relative.Humidity`) for Suffolk, VA, for the week of July 12, 1998. To calculate daily heat index values for this data set, use the `heat.index` function:

```{r}
data(suffolk)
suffolk$HI <- heat.index(t = suffolk$TemperatureF,
                         rh = suffolk$Relative.Humidity,
                         temperature.metric = "fahrenheit",
                         output.metric = "fahrenheit")
suffolk
```

You must specify whether the air temperature input to the function is in degrees Celsius or Fahrenheit using the `temperature.metric` option (possible values: `'fahrenheit'` or `'celsius'`). You can choose which metric for heat index output using using the `output.metric` option (the default is to give heat index in the same metric as the air temperature values input to the function).

As another example, the `lyon` data set gives daily values of air temperature (`lyon$TemperatureC`) and dew point temperature (`lyon$DewpointC`), both in degrees Celsius. You can use this data to calculate daily heat index values in degrees Fahrenheit using:

```{r}
data(lyon)
lyon$HI_F <- heat.index(t = lyon$TemperatureC,
                      dp = lyon$DewpointC,
                      temperature.metric = "celsius",
                      output.metric = "fahrenheit")
lyon
```

When calculating heat index from air temperature and dew point temperature, both must be input in the same metric (either degrees Fahrenheit or degrees Celsius). If this is not the case, you can use `convert_temperature` to convert one of the metrics before using `heat.index`.

The algorithm for calculating heat index is adapted for R
from the algorithms used by the United States National Weather Service's [online heat index calculator](http://www.wpc.ncep.noaa.gov/html/heatindex.shtml) (accessed December 18, 2015). Therefore, results should agree with results from the US National Weather Service online calculator. However, heat index is sometimes calculated using a simpler algorithm. Therefore, heat index values from the \texttt{heat.index} function will sometimes differ by one or two degrees compared to other heat index calculators or charts.

### Converting between units of wind speed

The `weathermetrics` package includes a function, `convert_wind_speed`, that allows you to convert wind speed values between several common units of wind speed: knots (`'knots'`), miles per hour(`'mph'`), meters per second (`'mps'`), feet per second (`'ftps'`), and kilometers per hour (`'kmph'`). The following code shows examples of applying this function to several sample datasets:

```{r}
data(beijing)
beijing$knots <- convert_wind_speed(beijing$kmph,
   old_metric = "kmph", new_metric = "knots")
beijing

data(foco)
foco$mph <- convert_wind_speed(foco$knots, old_metric = "knots",
   new_metric = "mph", round = 0)
foco$mph <- convert_wind_speed(foco$knots, old_metric = "knots",
   new_metric = "mps", round = NULL)
foco$kmph <- convert_wind_speed(foco$mph, old_metric = "mph",
   new_metric = "kmph")
foco
```

You must specify the unit of wind speed that you wish to convert from using the `old_metric` option, and the unit of wind speed you wish to convert to using the `new_metric` option (possible values: `'knots'`, `'mph'`, `'mps'`, `'ftps'`, or `'kmph'`). The unit for `old_metric` cannot be the same as the unit for `new_metric`. You can specify the number of decimal places you wish to round to using the `round` argument. The default value for `round` is 1, consistant with the algorithms used by the National Oceanic and Atmospheric Administration's [online wind speed conversion](http://www.srh.noaa.gov/epz/?n=wxcalc_windconvert) (accessed February 22, 2016). When `round` is set to `NULL`, the output value will not be rounded.  

### Converting between precipitation measurements

The `weathermetrics` package includes a function, `convert_precip`, that allows you to convert a vector of precipitation measurement values between inches (`'inches'`), millimeters (`'mm'`), and centimeters (`'cm'`). For example:

```{r}
data(breck)
breck$Precip.mm <- convert_precip(breck$Precip.in,
   old_metric = "inches", new_metric = "mm", round = 2)
breck

data(loveland)
loveland$Precip.in <- convert_precip(loveland$Precip.mm,
   old_metric = "mm", new_metric = "inches", round = NULL)
loveland$Precip.cm <- convert_precip(loveland$Precip.mm,
   old_metric = "mm", new_metric = "cm", round = 3)
loveland
```

You must specify the unit of precipitation measure that you wish to convert from using the `old_metric` option, and the unit of precipitation measure you wish to convert to using the `new_metric` option (possible values: `'inches'`, `'mm'`, and `'cm'`). You can specify the number of decimal places you wish to round to using the `round` argument. The default value for `round` is 2. When `round` is set to `NULL`, the output value will not be rounded. 

Calculations between inches and metric units for precipitation measures use the algorithms used by the United States National Weather Service's [Meteorological Conversions](http://www.srh.noaa.gov/ama/?n=conversions) (accessed March 20, 2016).

## Handling missing or impossible weather values

When any of the functions in this package encounter a missing value (`NA`) within any of the input vectors, the output weather metric for that observation will also be set as `NA`. For example:

```{r}
df <- data.frame(T = c(NA, 90, 85),
                 DP = c(80, NA, 70))
df$RH <- dewpoint.to.humidity(t = df$T, dp = df$DP,
                              temperature.metric = "fahrenheit")
df
```

Certain values of dew point temperature or relative humidity are impossible. Relative humidity cannot be lower than 0% or higher than 100%. Dew point temperature cannot be higher than air temperature (except in the case of supersaturation) . When any of these functions encounter an impossible weather metric in an input vector, it returns `NA` as the output weather metric for that observation. For example:

```{r}
df <- data.frame(T = c(90, 90, 85),
                 DP = c(80, 95, 70))
df$heat.index <- heat.index(t = df$T, dp = df$DP,
                            temperature.metric = 'fahrenheit')
df
```

Additionally, the function returns a warning to alert the user that the input data includes impossible values for some observations. 

## Rounding output values

All functions have defaults for rounding that are consistent with the algorithms used by the United States National Weather Service's online converters. For several of the functions, you may also specify that outputs are rounded to a different number of digits using the `round` option. For example:

```{r}
data(suffolk)
suffolk$TempC <- convert_temperature(suffolk$TemperatureF,
                                     old_metric = "f",
                                     new_metric = "c",
                                     round = 5)
suffolk$HI <- heat.index(t = suffolk$TemperatureF, 
                         rh = suffolk$Relative.Humidity,
                         round = 3)
suffolk
```

## Citation for package

For conversions other than heat index, cite this package as: 

G. Brooke Anderson, Roger D. Peng, and Joshua M. Ferreri. 2016. `weathermetrics`: Functions to Convert Between Weather Metrics. R package version 1.2.2.

To cite this package when calculating the heat index, use: 

---
nocite: | 
  @anderson2013heat 
...