# Interpolates Weather Data to a point in space and time

### Description

This function queries a weather variable via the Internet from the NCEP/NCAR Reanalysis or NCEP/DOE Reanalysis II datasets and subsequently calculates values at desired locations in space and time by interpolation.

### Usage

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | ```
NCEP.interp(variable, level, lat, lon, dt, reanalysis2 = FALSE,
interpolate.space = TRUE, interpolate.time = TRUE,
keep.unpacking.info = FALSE, return.units = TRUE,
interp = 'linear', p = 1, status.bar=TRUE)
## NCEP.interp is a wrapper function that calls one of the
## following functions based on the value of level.
## Users should avoid using these functions directly.
NCEP.interp.gaussian(variable, lat, lon, dt, reanalysis2 = FALSE,
interpolate.space = TRUE, interpolate.time = TRUE,
keep.unpacking.info = FALSE, return.units = TRUE,
interp = 'linear', p = 1, status.bar=TRUE)
NCEP.interp.pressure(variable, lat, lon, dt, pressure,
reanalysis2 = FALSE, interpolate.space = TRUE,
interpolate.time = TRUE, keep.unpacking.info = FALSE,
return.units = TRUE, interp = 'linear', p = 1, status.bar=TRUE)
NCEP.interp.surface(variable, lat, lon, dt, reanalysis2 = FALSE,
interpolate.space = TRUE, interpolate.time = TRUE,
keep.unpacking.info = FALSE, return.units = TRUE,
interp = 'linear', p = 1, status.bar=TRUE)
``` |

### Arguments

`variable` |
Character. The name of the weather variable to be obtained. See ‘Variable Naming Conventions’ below for possible variable names. |

`level` |
A numeric pressure level or one of either ‘gaussian’ or ‘surface’. See ‘Details’. |

`lat` |
Numeric. The latitude to which the weather variable should be interpolated. |

`lon` |
Numeric. The longitude to which the weather variable should be interpolated. |

`dt` |
Character. The datetime (specified in UTC) to which the weather variable should be interpolated. Must use the format |

`reanalysis2` |
Logical. Should the data be obtained from the Reanalysis II dataset or from Reanalysis I(default)? |

`interpolate.space` |
Logical. Should interpolation be done in space? |

`interpolate.time` |
Logical. Should interpolation be done in time? |

`keep.unpacking.info` |
Logical. Should the information needed to unpack the data be used for all queries in the function call? |

`return.units` |
Logical. Should the units of the variable being obtained be printed after the query finishes? |

`interp` |
Method of interpolation. One of 'linear' (default) or 'IDW'. See ‘Details’. |

`p` |
A positive real number. The power parameter controlling interpolation. Only matters when |

`pressure` |
Numeric. A pressure level in millibars that is assigned automatically from the value of |

`status.bar` |
Logical. Should a status bar be shown indicating the percentage of completion? |

### Details

`NCEP.interp`

is a wrapper function that applies one of `NCEP.interp.gaussian`

,

`NCEP.interp.pressure`

, or `NCEP.interp.surface`

depending
on the value of `level`

.

`level`

must specify one of either ‘gaussian’ or ‘surface’ or give a numerical pressure level in millibars. Numeric pressure levels must be one of 1000, 925, 850, 700, 600, 500, 400, 300, 250, 200, 150, 100, 70, 50, 30, 20, 10.
See ‘Variable Naming Conventions’ below to determine if your variable of interest is stored relative to the surface, a pressure level, or a T62 Gaussian grid.
Note that variables on a T62 Gaussian grid are evenly spaced in longitude but unevenly spaced in latitude while variables from either the surface or a particular pressure level are evenly spaced in both latitude and longitude (2.5 deg. x 2.5 deg.).

All arguments except `keep.unpacking.info`

, `return.units`

, and `status.bar`

can be vectors. The remaining arguments are recycled to the length of the longest arguement.

`lat`

and `lon`

should be given in decimal degrees. Latitudes south of the equator should be negative. Longitudes west of the Prime Meridian can be specified using either positive (i.e. 350) or negative (i.e. -10) notation.

All interpolation is performed assuming a spherical (rather than a planar) grid.

When `interp`

is 'IDW', 2-D spatial interpolation is done using inverse distance weighting followed by a 1-D linear interpolation in time.
When `interp`

is 'linear', the function performs a trilinear interpolation in latitude, longitude, and time.
If `interpolate.space`

or

`interpolate.time`

is `FALSE`

, the function performs ‘nearest neighbor’ interpolation and returns data from the grid point closest in space or time, respectively.
The numerical value of `p`

controls the degree of smoothing in the interpolation only when `interp`

is 'IDW'. Greater values of `p`

assign greater influence to values closest to the interpolated point. For 0 < `p`

< 1 peaks over the interpolated point remain smooth. As `p`

increases beyond 1, the peaks become sharper.

Variables in these datasets on a T62 Gaussian grid describe conditions over an interval of time rather than at a particular point in time. (see ‘Variable Naming Conventions’ below)
As such, it is not appropriate to perform temporal interpolation on these varaibles.
Therefore, `NCEP.interp`

automatically sets `interpolate.time`

to `FALSE`

when querying one of these variables,
and returns the data corresponding to the interval within which the specified datetime falls.
Spatial interpolation is still performed as long as `interpolate.space`

is `TRUE`

.

Unpacking information is unique to each variable and dataset. Therefore,

`keep.unpacking.info`

can be made `TRUE`

as long as only one variable from one dataset (i.e. Reanalysis I or II) is queried in a single function call, even for multiple times and locations. `keep.unpacking.info`

will be made `FALSE`

, if necessary, with a warning.

The function will run faster when `keep.unpacking.info`

is `TRUE`

.

The robust alternative to `NCEP.interp`

is applied automatically. These robust functions are applied when interpolation requires data from two different years or from both sides of the Prime Meridian.

Some variables are not in both the Reanalysis I and II datasets. If a variable is chosen that is not in the specified dataset, the other dataset will be used... with a warning.

The function also returns, as an attribute, standard deviation calculated on all data used in the interpolation.
This provides an indication of the precision of an interpolated result described in the same units as the interpolated variable.
Smaller values indicate that there is less variability among the points used in interpolation.
Standard deviation is only calcuated on the points used in the interpolation. Therefore, if `interpolate.time`

and `interpolate.space`

are both `TRUE`

,
standard deviation is calculated on eight points.

If `interpolate.time`

is `FALSE`

and `interpolate.space`

is `TRUE`

,
standard deviation is calculated on four points. If `interpolate.time`

is `TRUE`

and `interpolate.space`

is `FALSE`

, standard deviation
is calculated on only two points. If `interpolate.time`

and `interpolate.space`

are both `FALSE`

, standard deviation is not calculated and `NA`

is returned.
This measure of precision is the same irrespective of `interp`

.

Note that the status bar may be hidden behind an active R window.

`variable`

must be specified using one of the names found in the section ‘Variable Naming Conventions’ below...

### Value

A vector of interpolated results with the associated standard deviation of the points used to perform the interpolation as an attribute.

Optionally, the units of the variable being queried are printed when the function completes.

### Variable Naming Conventions

**VARIABLES IN REFERENCE TO A PARTICULAR PRESSURE LEVEL**

‘air’ | Air Temperature | deg K |

‘hgt’ | Geopotential Height | m |

‘rhum’ | Relative Humidity | % |

‘shum’ | Specific Humidity | kg/kg |

‘omega’ | Omega [Vertical Velocity] | Pascal/s |

‘uwnd’ | U-Wind Component [East/West] | m/s |

‘vwnd’ | V-Wind Component [North/South] | m/s |

**VARIABLES IN REFERENCE TO THE SURFACE**

‘air.sig995’ | Air Temperature | (Near Surface) | deg K |

‘lftx.sfc’ | Surface Lifted Index | (At Surface) | deg K |

‘lftx4.sfc’ | Best (4-layer) Lifted Index | (At Surface) | deg K |

‘omega.sig995’ | Omega [Vertical Velocity] | (Near Surface) | Pascal/s |

‘pottmp.sig995’ | Potential Temperature | (Near Surface) | deg K |

‘pr_wtr.eatm’ | Precipitable Water | (Entire Atmosphere) | kg/m^2 |

‘pres.sfc’ | Pressure | (At Surface) | Pascals |

‘rhum.sig995’ | Relative Humidity | (Near Surface) | % |

‘slp’ | Sea Level Pressure | (Sea Level) | Pascals |

‘mslp’ | Mean Sea Level Pressure | (Sea Level) | Pascals |

‘uwnd.sig995’ | U-Wind Component [East/West] | (Near Surface) | m/s |

‘vwnd.sig995’ | V-Wind Component [North/South] | (Near Surface) | m/s |

**VARIABLES IN REFERENCE TO A T62 GAUSSIAN GRID**

—– These variables are forecasts valid 6 hours after the reference time —–

‘air.2m’ | Air Temperature | (At 2 meters) | deg K | ||

‘icec.sfc’ | Ice Concentration | (At Surface) | fraction | ||

‘pevpr.sfc’ | Potential Evaporation Rate | (At Surface) | W/m^2 | ||

‘pres.sfc’ | Pressure | (At Surface) | Pascals | ||

‘runof.sfc’ | Water Runoff | (At Surface) | kg/m^2 | ||

‘sfcr.sfc’ | Surface Roughness | (At Surface) | m | ||

‘shum.2m’ | Specific Humidity | (At 2 meters) | kg/kg | ||

‘soilw.0-10cm’ | Soil Moisture | (From 0-10 cm) | fraction | ||

‘soilw.10-200cm’ | Soil Moisture | (From 10-200 cm) | fraction | ||

‘skt.sfc’ | Skin Temperature | (At Surface) | deg K | ||

‘tmp.0-10cm’ | Temperature of 0-10 cm layer | (From 0-10 cm) | deg K | ||

‘tmp.10-200cm’ | Temperature of 10-200 cm layer | (From 10-200 cm) | deg K | ||

‘tmp.300cm’ | Temperature at 300 cm | (From 300 cm) | deg K | ||

‘uwnd.10m’ | U-wind | (At 10 meters) | m/s | ||

‘vwnd.10m’ | V-wind | (At 10 meters) | m/s | ||

‘weasd.sfc’ | Water equivalent of snow depth | (At Surface) | kg/m^2 |

—– These variables are 6 hour hindcasts from the reference time —–

‘tmax.2m’ | Maximum temperature | (At 2 meters) | deg K | ||

‘tmin.2m’ | Minimum temperature | (At 2 meters) | deg K |

—– These variables are 6 hour averages starting at the reference time —–

‘cfnlf.sfc’ | Cloud forcing net longwave flux | (At Surface) | W/m^2 | ||

‘cfnsf.sfc’ | Cloud forcing net solar flux | (At Surface) | W/m^2 | ||

‘cprat.sfc’ | Convective precipitation rate | (At Surface) | Kg/m^2/s | ||

‘csdlf.sfc’ | Clear sky downward longwave flux | (At Surface) | W/m^2 | ||

‘csdsf.sfc’ | Clear sky downward solar flux | (At Surface) | W/m^2 | ||

‘dlwrf.sfc’ | Downward longwave radiation flux | (At Surface) | W/m^2 | ||

‘dswrf.sfc’ | Downward solar radiation flux | (At Surface) | W/m^2 | ||

‘dswrf.ntat’ | Downward solar radiation flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘gflux.sfc’ | Ground heat flux | (At Surface) | W/m^2 | ||

‘lhtfl.sfc’ | Latent heat net flux | (At Surface) | W/m^2 | ||

‘nbdsf.sfc’ | Near IR beam downward solar flux | (At Surface) | W/m^2 | ||

‘nddsf.sfc’ | Near IR diffuse downward solar flux | (At Surface) | W/m^2 | ||

‘nlwrs.sfc’ | Net longwave radiation | (At Surface) | W/m^2 | ||

‘nswrs.sfc’ | Net shortwave radiation | (At Surface) | W/m^2 | ||

‘prate.sfc’ | Precipitation rate | (At Surface) | Kg/m^2/s | ||

‘shtfl.sfc’ | Sensible heat net flux | (At Surface) | W/m^2 | ||

‘uflx.sfc’ | Momentum flux (zonal) | (At Surface) | N/m^2 | ||

‘ugwd.sfc’ | Zonal gravity wave stress | (At Surface) | N/m^2 | ||

‘ulwrf.sfc’ | Upward longwave radiation flux | (At Surface) | W/m^2 | ||

‘ulwrf.ntat’ | Upward longwave radiation flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘uswrf.sfc’ | Upward solar radiation flux | (At Surface) | W/m^2 | ||

‘uswrf.ntat’ | Upward solar radiation flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘vbdsf.sfc’ | Visable beam downward solar flux | (At Surface) | W/m^2 | ||

‘vddsf.sfc’ | Visable diffuse downward solar flux | (At Surface) | W/m^2 | ||

‘vflx.sfc’ | Momentum flux (meridional) | (At Surface) | N/m^2 | ||

‘vgwd.sfc’ | Meridional gravity wave stress | (At Surface) | N/m^2 |

—– These variables are 6 hour averages starting at the reference time —–

‘csulf.ntat’ | Clear Sky Upward Longwave Flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘csusf.ntat’ | Clear Sky Upward Solar Flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘dswrf.ntat’ | Downward Solar Radiation Flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘pres.hcb’ | Pressure | (High Cloud Bottom) | Pascals | ||

‘pres.hct’ | Pressure | (High Cloud Top) | Pascals | ||

‘pres.lcb’ | Pressure | (Low Cloud Bottom) | Pascals | ||

‘pres.lct’ | Pressure | (Low Cloud Top) | Pascals | ||

‘pres.mcb’ | Pressure | (Middle Cloud Bottom) | Pascals | ||

‘pres.mct’ | Pressure | (Middle Cloud Top) | Pascals | ||

‘tcdc.eatm’ | Total Cloud Cover | (Entire Atmosphere) | % | ||

‘ulwrf.ntat’ | Upward Longwave Radiation Flux | (Nominal Top of Atmosphere) | W/m^2 | ||

‘uswrf.ntat’ | Upward Solar Radiation Flux | (Nominal Top of Atmosphere) | W/m^2 |

### Author(s)

Michael U. Kemp mukemp+RNCEP@gmail.com

### References

**To cite package 'RNCEP' in publications use:**

Kemp, M.U., van Loon, E.E., Shamoun-Baranes, J.,and Bouten, W. (2011). RNCEP: global weather and climate data at your fingertips. Methods in Ecology and Evolution, DOI:10.1111/j.2041-210X.2011.00138.x.

**To cite the NCEP/NCAR Reanalysis dataset use:**

Kalnay et al. (1996), The NCEP/NCAR 40-year reanalysis project, Bull. Amer. Meteor. Soc., 77, 437-470

**To cite the NCEP/DOE Reanalysis II dataset use:**

Kanamitsu et al. (2002), NCEP-DOE AMIP-II Reanalysis (R-2). Bull. Amer. Meteor. Soc., 83, 1631-1643

Please acknowledge the use of NCEP data in any publications by including text such as, “NCEP Reanalysis data provided by the NOAA/OAR/ESRL PSD, Boulder, Colorado, USA, from their Web site at http://www.esrl.noaa.gov/psd/”. They would also appreciate a copy of any publications using NCEP data.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | ```
## Not run:
library(RNCEP)
###############################################################
###############################################################
## The function can be applied to interpolate a single variable
## to a single point in space and time ##
## Interpolate temperature from the 850 mb pressure level ##
wx.interp <- NCEP.interp(variable='air', level=850, lat=55.1,
lon=11.3, dt='2006-10-12 17:23:12',
interp='linear')
## Interpolate precipitable water (for the entire atmosphere, but
## described in reference to the surface)
wx.interp <- NCEP.interp(variable='pr_wtr.eatm', level='surface',
lat=55.1, lon=11.3, dt='2006-10-12 17:23:12',
interp='linear')
## Interpolate specific humidity (at the surface, but in
## reference to a T62 Gaussian grid) using the IDW interpolation
wx.interp <- NCEP.interp(variable='shum.2m', level='gaussian',
lat=55.1, lon=11.3, dt='2006-10-12 17:23:12',
interp='IDW', p=1)
###################################################################
###################################################################
## The function can also be applied to interpolate several variables,
## locations, datetimes, and/or methods of interpolation in a single
## function call ##
## Interpolate temperature from the 850 and 700 mb pressure levels ##
## for the same time and location ##
wx.interp <- NCEP.interp(variable='air', level=c(850,700), lat=55.1,
lon=11.3, dt='2006-10-12 17:23:12',
interp='linear')
## Interpolate temperature and relative humidity from the 1000 mb
## pressure level ##
wx.interp <- NCEP.interp(variable=c('air','rhum'), level=1000,
lat=55.1, lon=11.3, dt='2006-10-12 17:23:12', interp='linear')
## Interpolate temperature and relative humidity
## from the 1000 and 700 mb pressure levels, respectively
## for the same datetime ##
wx.interp <- NCEP.interp(variable=c('air','rhum'),
level=c(1000,700), lat=55.1, lon=11.3,
dt='2006-10-12 17:23:12', interp='linear')
## Interpolate temperature and relative humidity
## from the 1000 and 700 mb pressure levels, respectively
## for different datetimes ##
wx.interp <- NCEP.interp(variable=c('air','rhum'), level=c(1000,700), lat=55.1,
lon=11.3, dt=c('2006-10-12 17:23:12', '2006-10-12 18:05:31'),
interp='linear')
## Interpolate geopotential height using 'linear', 'IDW', and
## 'nearest neighbor' interpolation ##
wx.interp <- NCEP.interp(variable='hgt', level=700, lat=55.1,
lon=11.3, dt='2006-10-12 17:23:12',
interp=c('linear','IDW','IDW'),
interpolate.space=c(TRUE,TRUE,FALSE))
###############################################################
###############################################################
## Alternatively the function can be applied to interpolate a
## weather variable to multiple datetime and point locations
## in a single function call ##
## In this example, we use datetime and locational data obtained
## from a GPS device attached to a lesser black-backed gull.
## We interpolate wind information to to each point in the dataset
data(gull)
## Take a subset of the data based on the datetime of
## the measurement ##
ss <- subset(gull, format(gull$datetime, "%Y-%m-%d %H:%M:%S") >=
"2008-09-19 16:00:00" & format(gull$datetime,
"%Y-%m-%d %H:%M:%S") <= "2008-09-19 19:30:00")
## Now collect wind information for each point in the subset ##
uwind <- NCEP.interp(variable='uwnd', level=925,
lat=ss$latitude, lon=ss$longitude, dt=ss$datetime,
reanalysis2=TRUE, keep.unpacking.info=TRUE)
vwind <- NCEP.interp(variable='vwnd', level=925,
lat=ss$latitude, lon=ss$longitude, dt=ss$datetime,
reanalysis2=TRUE, keep.unpacking.info=TRUE)
## Now calculate the tailwind component from the U and V
## wind components assuming that the bird's preferred
## direction is 225 degrees
tailwind <- (sqrt(uwind^2 + vwind^2)*cos(((atan2(uwind,vwind)*
(180/pi))-225)*(pi/180)))
## Now visualize the subset of the GPS track using color
## to indicate the tailwind speed ##
NCEP.vis.points(wx=tailwind, lats=ss$latitude, lons=ss$longitude,
cols=rev(heat.colors(64)),
title.args=list(main='Lesser black-backed gull'),
image.plot.args=list(legend.args=list(text='Tailwind m/s',
adj=0, padj=-2, cex=1.15)),
map.args=list(xlim=c(-7,4), ylim=c(40,50)))
## End(Not run)
``` |