v: Plotting spatial data

In oceanmap: A Plotting Toolbox for 2D Oceanographic Data

Description

Plots spatial data (e.g. 2D oceanographic data). Valid input data are objects of class 'Raster' ('RasterLayer', 'RasterStack' or 'RasterBrick'), 'ncdf4' (already loaded netcdf files) or a character strings indicating 'bathy'metric data, 'gz'- or '.nc-files' (netcdf). See also name_split for further information on '.gz'-file nomenclature.

Usage

## S4 method for signature 'bathy'
v(obj, v_area, lon, lat, resolution=4, keep=F, 
  savename.bathy, folder.bathy=".", adaptive.vals=T, cb.title, show.colorbar=T,...)

## S4 method for signature 'nc'
v(obj, varname, t=1, layer=t, adaptive.vals=T, dates, 
  cb.xlab=varname, lonname="lon", latname='lat', show.colorbar=T ,...)

## S4 method for signature 'ncdf4'
v(obj, varname, t=1, layer=t, adaptive.vals=T, dates, 
  cb.xlab=varname, lonname="lon", latname='lat', show.colorbar=T, ...)

## S4 method for signature 'RasterLayer'
v(obj, varname, t=1, layer=t, ...)

## S4 method for signature 'RasterBrick'
v(obj, varname, t=1, layer=t,  ...)

## S4 method for signature 'RasterStack'
v(obj, varname, t=1, layer=t,  ...)

## S4 method for signature 'gz'
v(obj, v_area, adaptive.vals=F, show.colorbar=T,...)

Arguments

obj	object of class 'Raster' ('RasterLayer', 'RasterStack' or 'RasterBrick'), 'ncdf4' or a character string indicating , 'bathy'metric data, '.gz'- or '.nc'-files to plot.
v_area	character string identifying the region that should be plotted, or in case of obj == 'bathy', also a Raster* or Extent object. If missing, region is derived from the '.gz'-filename. See region_definitions for area definitions and use add.region to add new regions.
adaptive.vals	sets minimum and maximum z-value according to the '.gz'-files value range. (ATTENTION! minv and maxv are disregarded if set!). (default is TRUE for non-'.gz'-files. If FALSE or not set, default value from the parameter_definitions-dataset will be applied according to the param-value.
t, layer	layer/time stemp to select in multi-layer files/objects (e.g. ncdf4, RasterStack).
dates	vector of type 'character' indicating dates per layer, used to define the title of the colorbar. Argument is omitted for '.gz'-files but date-information is derived from the filename. For '.nc'-files or 'ncdf4'-objects, date information is derived from the time-vector. For raster-objects the layer name is applied.
varname	character string indicating the name of the variable to plot. For '.nc'-files or 'ncdf4'-objects, this name must correspond to a variable name defined in the file/object. Sets also colorbar-title for non-'.gz'-files if cb.xlab is missing.
cb.title	character string indicating the title of the colorbar (default is set to date information/empty string if date information is missing.)
cb.xlab	character string indicating the x-axis label of the colorbar and cb.xlab.line its placement line (default is 0). If not defined, it will be set to varname for raster, ncdf4-objects and '.nc'-files or for '.gz'-files to a predefined title in the parameter_definitions-dataset according to the param-value.
lonname	character string indicating the name of the longitude-variable of ncdf4-objects and '.nc'-files to plot (default is 'lon')
latname	character string indicating the name of the latitude-variable of ncdf4-objects and '.nc'-files to plot (default is 'lat')
lon	Vector returning longitude coordinates of the area to be plotted, only valable for obj == 'bathy'.
lat	Vector returning latitude coordinates of the area to be plotted, only valable for obj == 'bathy'.
resolution	resolution of the bathymetric grid, in minutes (default is 4), only valable for obj == 'bathy'.
keep	whether to write the data downloaded from NOAA into a file (default is FALSE), only valable for obj == 'bathy'.
savename.bathy	savename for the bathymetric data file, if not specified set to type 'bathy_lon-lat_res.resolution.dat' or 'bathy_v_area_res.resolution.dat', only valable for obj == 'bathy'.
folder.bathy	directory where bathymetric data should be saved (default is current working directory), only valable for obj == 'bathy'.
show.colorbar	weather a colorbar should be plotted for image plots(default is T).
...	additional arguments to be passed: region see v_area. minv, maxv minimum and maximum z-value to be plotted. If not set, default value from the parameter_definitions-dataset will be applied. Argument is overwritten by adaptive.vals and zlim. replace.na whether missing values should be replaced by minimum values (default is FALSE.) param character string indicating the parameter name for the dataset treatment. See parameter_definitions for available parameters. For '.gz'-files, param is derived from the filename. For non-'.gz'-files this value is non-obligatory, but can replace the varname-argument and vise versa. See examples. main an overall title for the plot: see title. cbpos letter ("b", "l", "t", "r") indicating the position of the colorbar (bottom, left, top, right). Overwrites cbx and cby values. cbx the horizontal limits (x1, x2) of the colorbar. If missing and the value can not be reconstructed by the region information (e.g. v_area, '.gz'-file), the user will be asked for manual colorbar placement. cby the vertical limits (y1, y2) of the colorbar. If missing and the value can not be reconstructed by the region information (e.g. v_area, '.gz'-file), the user will be asked for manual colorbar placement. nticks number of tick marks for the colorbar (default is 5). pal color map to be plotted (default is the 'jet'-colormap, or in case of '.gz'-files derived from the parameter_definitions-dataset. See cmap for available color maps and parameter_definitions for predefined colormaps for different parameters.) sidelabels whether an additional y-axis label and title should be added to the plot device (default is FALSE). If TRUE, y-axis label is defined by Ylab, the additional title is derived from the date-information and gives the month information. Ylab an additional title for the y axis (default is date information), only used when sidelabels is set TRUE. Default value is year-information. axeslabels whether axeslabels should be shown (default is TRUE, set as 'longitude' and 'latitude') subplot whether '.gz'-file will be plotted as a sub plot to an existing plot device (default is FALSE; see: par) width, height the width and height of the plotting window, in inches. For '.gz'-files, default values are derived from the region-name as indicated by the filename. See region_definitions for predescribed definitions and use add.region to add new region definitions. figdim numeric vector indicating the width and height of the plot device in inches. For '.gz'-files, default values are derived from the region-name as indicated by the filename. Value is overwritten if both, width and height are provided. See region_definitions for predescribed definitions and use add.region to add new region definitions. xpos integer: initial position of the top left corner of the figure window on the pc-screen, given in pixels. Negative values are from the opposite corner. (default is -1). Disregarded under Mac OS and if Save is set TRUE. Save whether the a plot device should be saved automatically as an image file of type fileformat in a folder specified by plotfolder (default is FALSE) plotfolder directory where images should be saved (default is current working directory). plotname the name of the output file(s). If not set, value will be derived from the provided file information (For '.gz'-files, default plotname is equal to the '.gz'-filename, replacing the '.gz'-fileformat-suffix with the defined image-fileformat. fileformat fielformat of image file to be saved (only png and eps are accepted; default is png). suffix suffix to be added to the image filename, before the filetype specification (e.g. '...suffix.png'). v_image whether an image-plot should be plotted (default is TRUE) v_contour whether contour lines should be plotted (default is FALSE). If levels are specified, v_contour is set TRUE. levels numeric vector of levels at which to draw contour lines. contour.labels a vector giving the labels for the contour lines. By default levels are used as labels. v_arrows whether current or wind vectors should be plotted (default is TRUE; Argument is disregarded for non-.gz-files and omitted if non current or wind data-files are provided) scale_arrow scale factor needed for current and wind vector plots (default is 1; Argument is disregarded for non-.gz-files and omitted if no current or wind data-files are provided, indicated by the param-argument (valid param-definitions are: 'uz' and 'vz', for current data, 'wu' and 'wz' for wind data)) terrain whether the to keep terrain data (default is FALSE). If set FALSE and visualize is TRUE, grid command in plotmap is disabled! verbose whether the plot information shall be printed in the R-console (by default TRUE) ... Additional arguments to be passed to plotmap (bwd, fill, col, border, grid, grid.res, axeslabels, ticklabels, cex.lab, cex.ticks).

Details

v uses the maps and maptools functions to plot the landmask. See clim_plot for aligned plots of satallite-data climatologies.

Author(s)

Robert K. Bauer

References

Bauer, R. K., Stepputtis, D., Grawe, U., Zimmermann, C., and Hammer, C. 2013. Wind-induced variability in coastal larval retention areas: a case study on Western Baltic spring-spawning herring. Fisheries Oceanography, 22: 388-399.

See Also

clim_plot, readbin, name_split, regions, plotmap, v

Examples

################## simple example section:

## Example 1: load & plot a sample Raster-object
path <- system.file("test_files", package="oceanmap")
load(paste0(path,"/medw4_modis_sst2_4km_1d_20020705_20020705.r2010.0.qual0.Rdata"),verbose=TRUE)
dat <- raster::crop(dat,extent(c(0,10,40,44))) ## crop data, xlim/ylim not yet implemented in v()
print(dat)
v(dat, main="Raster-object", cbpos='r')


## Example 2: load & plot sample netcdf-file ('.nc'-file)
nfiles <- Sys.glob(paste0(path,'/*.nc')) # load list of sample-'.nc'-files
head(nfiles)

### option a) load netcdf-file with ncdf4-package and plot it
library('ncdf4')
ncdf <- nc_open(nfiles[1])
# print(ncdf)
# v(obj = ncdf, cbpos="r")

### option b) load and plot netcdf-file as RasterStack object
# nc <- nc2raster(nfiles[1])
# v(nc,cbpos="r") # plot RasterStack object

### option c) plot netcdf-file directly
# v(nfiles[1], cbpos="r")
# v(nfiles[1], cbpos="r", replace.na=TRUE)

###### plot multiple layers:
# par(mfrow=c(2,2))
# v(nfiles[1], t=1:4, cbpos="r", replace.na=TRUE, subplot = TRUE)


# ## Example 2: load & plot bathymetry data from the NOAA-ETOPO1 database
# par(mfrow=c(2,1))
# bathy <- get.bathy("medw4", terrain=T, res=3, keep=T, visualize=T, subplot = TRUE, grid=F)
# # load('bathy_medw4_res.3.dat',verbose = T); bathy <- h
# v(bathy, param="bathy", subplot = TRUE, terrain=F, levels=c(200,2000)) # show contours
# 
# ## b) only contour lines:
# par(mfrow=c(1,2))
# h <- get.bathy("lion",terrain=F,res=3, visualize=T,
#                subplot=T, v_image = FALSE, levels=c(200,2000))
# 
# ## use v-function for same plot but on subregion:
# v(h,v_area = "survey", param="bathy",
#   subplot=T, v_image = FALSE, levels=c(200,2000)) 


## Example 3: plot sample-'.gz'-file
gz.files <- Sys.glob(paste0(path,'/*.gz'))
# v(gz.files[2]) ## plot content of gz-file
 
 
## Example 4: load sample-'.gz'-file manually as Raster-object and plot it
obj <- readbin(gz.files[2],area='lion')
# par(mfrow=c(1,2))
# v(obj,param="sst",subplot = TRUE)
# v(obj,param="Temp",subplot = TRUE) ## note unset "pal" (colormap) for unkown "param"-values!


## Example 5: available color maps
data('cmap') # load color maps data
names(cmap) # list available color maps

gz.files <- Sys.glob(paste0(path,'/*.gz'))
# figure(width=15,height=15)
# par(mfrow=c(4,5))
# for(n in names(cmap)) v(gz.files[2], v_area='lion', subplot=TRUE,
#                         pal=n, adaptive.vals=TRUE, main=n)

## define new color maps from blue to red to white:
n <- colorRampPalette(c('blue','red','white'))(100)
# v(gz.files[2], v_area='lion', subplot=TRUE,
#  pal=n, adaptive.vals=TRUE, main="own colormap")


## Example 6: available parameters
data(parameter_definitions)
names(parameter_definitions)
# ?parameter_definitions

# figure(width=12, height=6.2)
# par(mfrow=c(2,3))
# v('*sst2*707*',v_area="medw4",main="sst", folder=path, subplot=TRUE)
# v('*chla*531*',v_area="medw4",main="chla", folder=path, subplot=TRUE)
# v('*chlagrad*',v_area="medw4",main="chlagrad",folder=path, subplot=TRUE)
# v('*p100*',v_area="medw4",main="p100 (oceanic fronts)",folder=path, subplot=TRUE)
# v('*sla*',v_area="medw4",main="sla",folder=path, subplot=TRUE)
# h <- get.bathy("medw4",visualize=TRUE,terrain=F,res=4, subplot=TRUE,main="bathy")

################## advanced example section:

## Example I: plot bathymetry using a v_area-keyword
## requires server connection!
# par(mfrow=c(2,1))
# v("bathy","lion",res=4, keep=TRUE,border='grey',subplot=TRUE, 
#   main='Gulf of Lions bathymetry',cb.title="resolution 4 min")

# v("bathy","lion",res=1, keep=TRUE,border='grey',subplot=TRUE,
#   cb.title="resolution 1 min")  # can take some time depending on server connection!


## Example II: plot bathymetry of the Baltic Sea defined by longitude and latidtue coordinates
## requires server connection!
lon <- c(9, 31)
lat <- c(53.5, 66)
#v("bathy",lon=lon,lat=lat,main="Baltic Sea")


## Example III: plot landmask of the Baltic Sea defined by an extent- or raster-object
## requires server connection!
library('raster')
ext <- extent(lon,lat)
# v("bathy",ext,main="Baltic Sea",res=4,levels=200) # extent-object


## Example IV: plot '.gz'-files, following default plot-procedure

check_gzfiles(folder=path) # return file summary-table
gz.files <- Sys.glob(paste0(path,'/*.gz')) # load sample-'.gz'-files
# v(gz.files[1:4])
# v(gz.files[4],bwd=2)

## Example V: plot climatologies from '.gz'-files 
##            (ATTENTION: not working for non-'gz'-files, requiring ImageMagick)
# clim_plot('*1s*.gz' ,folder = path,bwd=0.7,adaptive.vals=TRUE,plotname="seasonal_climatology.png")

## Example VI: plot subregion of gz-files as subplots
# graphics.off()
# par(mfrow=c(2,1))
# v(gz.files[1:2],v_area='lion',subplot=TRUE) # run ?region_definitions to see predefined regions


## Example VII: plot subregion of raster file

# all manual:
obj <- readbin(gz.files[2],area='lion')
dev.new()
ticks <- seq(20,30,5)
par(mar=c(5,4,5,8))
image(obj,zlim=range(ticks),col=cmap$jet)
plotmap('lion',add=TRUE) # add landmask
# set.colorbar(ticks=ticks,cb.title='cb.title',cb.xlab='cb.xlab')

## using v, reconstructing region information
# obj <- readbin(gz.files[2],area='lion')
# v(obj,varname="sst2",cb.title='cb.title',cb.xlab='cb.xlab')

# using v for another subregion
ncorse <- crop(obj,extent(6,9,40,42))
# v(ncorse,grid.res=1)
# v(ncorse,zlim=c(20,30),cbx=c(8.3,8.9),cby=c(40.7,40.8)) # skipping colorbar widget


## Example VIII: Add region by supplying raster-object, colorbar positions and running the widget
#add.region(ncorse,cbx=c(8.3,8.9),cby=c(40.7,40.8))


## Example IX: plot netcdf-files ('.nc'-files)
nfiles <- Sys.glob(paste0(path,'/*.nc')) # load sample-'.nc'-files
head(nfiles)

## plot herring larval dispersal from Bauer et al. (2013)
# par(mfrow=c(2,2))
# v(nfiles[1], subplot=TRUE, t=1:4,minv=0, maxv=1000, adaptive.vals=FALSE, replace.na=TRUE)
# par(new=TRUE,mfrow=c(1,1))
# empty.plot(main='herring larval dispersal in the Greifswald lagoon, Germany')
# mtext('see Bauer et al. (2013) as reference')

# plot bathymetric data (obtained from the Leibniz Institute for Baltic Sea Research Warnemuende)
# v(nfiles[2],varname='bathymetry') # following default plot-procedure
# v(nfiles[2],varname='bathymetry',pal='haxbyrev',Log=TRUE, cb.xlab='depth [log m]',levels=50)

oceanmap documentation built on March 23, 2020, 5:06 p.m.