v: Plotting spatial data

Description Usage Arguments Details Author(s) References See Also Examples

View source: R/v.r

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
## 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

  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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
################## 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.

Related to v in oceanmap...