RNCEP (version 1.0.10)

NCEP.vis.area: Visualize Weather Data on a Map

Description

This function creates a filled contour map from weather data. It visualizes data from a single layer (i.e. timestep) of a data array as returned by NCEP.gather or a single aggregated layer as returned by NCEP.aggregate

Usage

NCEP.vis.area(wx.data, layer=1, show.pts=TRUE, draw.contours=TRUE,
    cols=heat.colors(64), transparency=.5, axis.args=NULL, map.args=NULL,
    grid.args=NULL, title.args=NULL, interp.loess.args=NULL, 
    image.plot.args=NULL, contour.args=NULL, points.args=NULL)

Value

A plot is produced. No data are returned.

Arguments

wx.data

A 3-D array of weather data as returned by NCEP.gather or NCEP.aggregate

layer

Either a numerical indication of the layer (default is the first layer) or a character expression of the datetime of a particular layer.

show.pts

Logical. Should the points at which data were obtained be plotted?

draw.contours

Logical. Should the map include contour lines?

cols

A vector of colors such as that generated by rainbow, heat.colors, topo.colors, terrain.colors, or similar functions indicating the colors of the filled contours on the map.

transparency

A numeric value between 0 and 1 indicating the transparency of the filled contours on the map.

axis.args

A list of arguments controlling the drawing of axes. See axis for acceptable arguments and the examples below for a demonstration.

map.args

A list of arguments controlling the drawing of the map. See map for acceptable arguments and the examples below for a demonstration.

grid.args

A list of arguments controlling the drawing of the lat/long grid lines. See abline for acceptable arguments and the examples below for a demonstration.

title.args

A list of arguments controlling the how titles and axis lables are written. See title for acceptable arguments and the examples below for a demonstration.

interp.loess.args

A list of arguments controlling the interpolation between grid points. See interp.loess for acceptable arguments and the examples below for a demonstration.

image.plot.args

A list of arguments controlling the plotting of the filled contour surface, the color-bar legend, and the legend axis and labels. See image.plot for acceptable arguments and the examples below for a demonstration.

contour.args

A list of arguments controlling the drawing of contour lines. See contour for acceptable arguments and the examples below for a demonstration.

points.args

A list of arguments controlling the plotting of grid points. See points for acceptable arguments and the examples below for a demonstration.

Author

Michael U. Kemp

Details

If the specification of layer is not numeric, it must specify a layer by a character expression of its datetime using the format "%Y-%m-%d %H". Leading zeros in the month, day, and hour components must be given (e.g. "2006-01-01 06")

If the data array has been aggregated in some way, the datetime dimension may no longer contain information on one or more temporal component: year, month, day, or hour. In this case, replace missing datetime componets with "XX" or "XXXX" (e.g. "XXXX-01-XX XX") when specifying a layer by a character expression of its datetime. Use dimnames to see the datetime dimension labels.

If the geographical area to be plotted contains no landmass, the plot will exhibit a small unfilled border.

Most of the components of a plot produced by this function can be controlled by supplying a list of arguments to the embedded function that produces the particular component of the plot. For example, the text and size of the plot's title can be controlled by specifying a list of acceptable arguments to title.args. Similarly, the axes, map, and grid lines are controlled by specifying a list of acceptable arguements to axis.args, map.args, and grid.args, respectively. Through the argument image.plot.args the user can control the plotting of the filled contour surface, the color-bar legend, and the color-bar's title and axis labels. A list of arguments passed to interp.loess.args controls the interpolation of the filled-contour surface. See the examples below for a demonstration of how to apply these different arguments.

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.

Examples

if (FALSE) {
library(RNCEP)
## Retrieve data for a specified spatial and temporal extent ##
wx.extent <- NCEP.gather(variable = "air", level=850,
    months.minmax = 11, years.minmax = 2000,
    lat.southnorth = c(50, 60), lon.westeast = c(0, 10),
    reanalysis2 = FALSE, return.units = TRUE)

## Visualize the first layer (i.e. first timestep) of the
## variable on a map
## Note how to specify the plot's title
## Note also the adjustment of the Kernal span argument for 
## 		interpolation using interp.loess.args
NCEP.vis.area(wx.data=wx.extent, layer=1, show.pts=TRUE, draw.contours=TRUE,
    cols=heat.colors(64), transparency=.6, title.args=list(main="Example"),
    interp.loess.args=list(span=.75))

## Now visualize a particular layer by specifying its datetime ##
NCEP.vis.area(wx.data=wx.extent, layer='2000-11-01 18', show.pts=TRUE,
    draw.contours=TRUE, cols=terrain.colors(64), transparency=.6,
    title.args=list(main="Example: select layer by datetime"),
    interp.loess.args=list(span=0.5))
	
## Now produce the same graph as above ##
## This time, label the color-bar legend ##
NCEP.vis.area(wx.data=wx.extent, layer='2000-11-01 18', show.pts=TRUE,
    draw.contours=TRUE, cols=terrain.colors(64), transparency=.6,
    title.args=list(main="Example: select layer by datetime"),
    interp.loess.args=list(span=0.5), 
    image.plot.args=list(legend.args=list(text='Kelvin', cex=1.15, padj=-1, adj=-.25)))

## Now produce the same graph as above ##
## This time, explicitly specify the size and location 
## of the color-bar legend using the smallplot argument 
## in the list of image.plot.args ##
NCEP.vis.area(wx.data=wx.extent, layer='2000-11-01 18', show.pts=TRUE,
    draw.contours=TRUE, cols=terrain.colors(64), transparency=.6,
    title.args=list(main="Example: select layer by datetime"),
    interp.loess.args=list(span=0.5), 
    image.plot.args=list(legend.args=list(text='Kelvin', cex=1.15, padj=-1, adj=-.25),
        smallplot=c(0.8475, 0.875, 0.20, 0.8)))

###########################################################
## This function can also show a layer after aggregation ##
###########################################################
## Calculate the average hourly temperature from the data
## obtained above ##
wx.ag <- NCEP.aggregate(wx.data=wx.extent, YEARS=FALSE, MONTHS=FALSE,
    HOURS=TRUE, DAYS=FALSE, fxn='mean')

## Now plot the mean temperature at midnight ##
## Note the adjustment of axis labels
## Note also the adjustment of the point type
NCEP.vis.area(wx=wx.ag, layer=1, interp.loess.args=list(span=0.5),
    title.args=list(main='Example: aggregated layer', xlab='Long [degrees]',
    ylab='Lat [degrees]'), points.args=list(pch=19))

## Now produce the same plot as above ##
## This time, change the font size used in the
## contour labels ##
NCEP.vis.area(wx=wx.ag, layer=1, interp.loess.args=list(span=0.5),
    title.args=list(main='Example: aggregated layer', xlab='Long [degrees]',
    ylab='Lat [degrees]'), points.args=list(pch=19),
    contour.args=list(labcex=.6))
	
## Notice how you can plot an aggregated layer by specifying
## it explicitly ##
NCEP.vis.area(wx=wx.ag, layer="XXXX-XX-XX 18", interp.loess.args=list(span=0.5),
    title.args=list(main='Example: aggregated layer', xlab='Long [degrees]',
    ylab='Lat [degrees]'), points.args=list(pch=19),
    contour.args=list(labcex=.6))
}