`weathermetrics` package vignette

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 (accessed December 18, 2015) and the National Oceanic and Atmospheric Administration's online wind speed conversion (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:

#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:

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:

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:

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 (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:

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:

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 (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:

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 (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:

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 (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:

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:

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:

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 ...



Try the weathermetrics package in your browser

Any scripts or data that you put into this service are public.

weathermetrics documentation built on May 29, 2017, 3:39 p.m.