oceanmap (version 0.1.6)

add.region: adding a region to the region_definitions file

Description

adding a region to the region_definitions-file, taking or restoring a backup of region definitions. The basic idea is to provide a region-keyword that is used to access the region-information in later related function-calls (see: v and plotmap, regions). Information consists of a region-keyword, -longname, its spatial extent (longitudes and latitudes), grid resolution, as well as default colorbar position and figure size.

The required information can be provided by an interactive session (widget) that leads step by step through the region definition (is set default), in parts by an extent-object with the missing information then completed by the session or by a one-row data frame that holds the entire information (see: region_definitions).

ATTENTION! When reinstalling or updating the oceanmap package, previous region definitions are getting lost! It is therefore highly recommanded to take and restore own backups (see: backup and restore).

Usage

add.region(add, add.px, cbx, cby, figdim, lib.folder, 
           widget=T, backup=F, backup.folder='.', backup.name, restore=F,backup.regions)

Arguments

add

extent-,raster-object or dataset containing all required region definition entries (label, name, latn, lats, lonw, lone, ncol, nrow, px, cbx1, cbx2, cby1, cby2, figxdim, figydim and grid.res). Ignored when add.px is supplied.

The values latn, lats, lonw, lone define the regions extent, cbx1, cbx2, cby1 and cby2 define the position of the colorbar, gradient the orientation of the colorbar (x for horizontal, y for vertical), oticks the margin where to put the colorbar ticks relative to the colorbar rectangle ('l' left, 'r' right and 'b' for bottom; figxdim and figydim set the default window size of '.gz'-file figures and grid.res the default grid resolution.

add.px

dataframe or list containing region data needed to read gz-compressed '.gz'-files. Required entries include 'label' to identify the region, 'ncol' and 'nrow', to define the number of columns and rows of the 'gz'-file, respectively. These values are automatically set if missing when writing gz-compressed '.gz'-files (see: writebin).

cbx

the horizontal limits (x1, x2) of the colorbar. If missing, the user will be asked for manual colorbar placement.

cby

the vertical limits (y1, y2) of the colorbar. If missing, the user will be asked for manual colorbar placement.

figdim

numeric vector indicating the width and height of the plot device in inches. If missing and force.figdim.widget is set FALSE, figdim is assigned a default width and height of 7in, otherwise the user will be asked to resize the plot device to set plot dimensions.

lib.folder

Character string indicating R-library path in which the oceanmap-package is installed.

widget

whether an interactive session (widget) shall assist the data entry procedure (default is TRUE).

backup

whether the current region_definitions-file should be backuped in the folder 'backup.folder in the file backup.name (default is FALSE). ATTENTION! When reinstalling or updating the oceanmap package, previous region_definitions are getting lost!

backup.folder

Character string indicating the folder where to store the region_definitions-file backup (default is the current working directory).

backup.name

Character string indicating the filename of the region_definitions-file backup (If restore the default is the original oceanmap-region_definitions file; if backup the default is set to 'region_definitions.bkp.%Y%m%d.rda').

restore

whether to restore a backup of the region_definitions-file (default is FALSE).

backup.regions

Vector of region indicators defining which regions should be saved in backup file.

Author

Robert K. Bauer

See Also

delete.region, region_definitions, regions, plotmap, v

Examples

## Example 1: Add region by supplying a one-row data.frame 
##            that holds the entire required information
# data(region_definitions) # load region_definitions
# lion <- region_definitions[region_definitions$label == 'lion',] # selecting Gulf of Lions region
# lion
# junk <- lion 
# junk$label <- 'junk' # rename region label
# add.region(junk) # add junk region
# data(region_definitions) # reload region_definitions
# region_definitions[,1:9]

## Example 2: Delete region
#delete.region("junk") # delete junk region
#data(region_definitions) # reload region_definitions
#region_definitions[,1:9]

## Example 3: Add region by supplying an extent- or raster-object and running the widget
library(raster)

ext <- extent(0,10,50,60)
plotmap(ext)
#add.region(ext) # extent-object

r <- raster(ext)
#add.region(r) # raster-object

## Example 4: Add region by supplying raster-object, colorbar positions and running the widget
#add.region(r,cbx=c(5,9.5),cby=c(51.7,52.4))

## Example 5: Add region by running the widget
#add.region()

## Example 6: Add region by running the widget
#add.region(add.px=list(label="lion",nrow=10,ncol=10))
#data(region_definitions)
#region_definitions[region_definitions$label =="lion",]

## Example 7: Creating a backup
#add.region(backup=T)
#add.region(backup=T, backup.folder=".",backup.regions=c("lion","medw4"))

## Example 8: Restoring the backup of the original region_definitions file
#add.region(restore=T)