plot_field_2d: Map 2-dimensional fields

View source: R/plot_field_2d.R

plot_field_2dR Documentation

Map 2-dimensional fields

Description

This function creates a map of the environmental conditions over space, as resolved across the nodes or elements of an unstructured grid, for a given depth/altitude, and time. Scalar fields are shown as a coloured surface, with the colour of a grid cell corresponding to the value of that cell. Vector fields are shown as coloured arrows ontop of the unstructured grid which point in the direction of mass flow and whose colour corresponds to the total magnitude of the vector, derived from the two (u and v) vector components

Usage

plot_field_2d(
  coastline,
  mesh,
  vector_field = FALSE,
  data,
  xlim = NULL,
  ylim = NULL,
  coastline_col = "white",
  coastline_border = "black",
  coastline_lwd = 1,
  coastline_lty = 1,
  mesh_border = "lightgrey",
  mesh_lwd = 0.5,
  mesh_lty = 1,
  ncols = 50000,
  col_fn = grDevices::heat.colors,
  colour_bar_add = TRUE,
  colour_bar_x = NULL,
  colour_bar_y = ylim,
  element_xy = NULL,
  arrow_angle = 30,
  arrow_scale = 0.01,
  arrow_length = 0.01,
  arrow_lwd = 0.5,
  arrow_lty = 1,
  xlab = "Longitude (dd)",
  ylab = "Latitude (dd)",
  zlab = "",
  main = "",
  xlab_line = 2.5,
  ylab_line = -3.5,
  zlab_line = 5,
  main_line = 1,
  axes = TRUE,
  nticks = 10,
  cex = 1.2,
  cex.axis = cex - 0.2
)

Arguments

coastline

A spatial object, such as a shapefile (i.e. SpatialPolygonsDataFrame), that delineates the coastline in the study area. This is assumed to have been cropped to the study area (i.e. its extent should be within the region defined by xlim and ylim, see below).

mesh

A SpatialPolygonsDataFrame, created by build_mesh, that defines the unstructured mesh in the study area across which environmental conditions have been resolved. This is also assumed to have been cropped to the study area (i.e. its extent should be within the region defined by xlim and ylim, see below). For conditions resolved at the nodes of an unstructured grid, a mesh around nodes (i.e. based on elements) is required. In contrast, for conditions resolved at the elements of an unstructured grid, a mesh around elements (i.e. based on nodes) is required.

vector_field

A logical object defining whether the data to be plotted across the mesh are a scalar field (e.g. temperature), in which case vector_field = FALSE or a vector field (e.g. wind speed), in which case vector_field = TRUE.

data

The data to be plotted across the mesh ID. For scalar fields, i.e., vector_field = FALSE, this is a single dataframe with two columns: ID, a numeric/factor/character column specifying the ID of each mesh cell, i.e., a unique reference to each element or node that matches that in mesh; and fvcom, a numeric column specifying the value assigned to that cell by the hydrodynamic model. For vector fields, this should be a named list with two elements: one called "udata" and one called "vdata"; each element in the list should contain a dataframe, as described above, that contain the u and v vector components resolved at each element respectively.

xlim

A numeric pair of numbers which define the lower and upper x limits of the study region respectively. These should be on the same scale as the coordinate system used for the coastline and mesh.

ylim

A numeric pair of numbers which define the lower and upper y limits of the study region respectively. These should be on the same scale as the coordinate system used for the coastline and mesh.

coastline_col

The colour of the coastline (i.e. land). This can be specified as a character or numeric value. "white" is the default.

coastline_border

The colour of the coastline border. "black" is the default.

coastline_lwd

The thickness of the coastline border. 1 is the default.

coastline_lty

The line type of the coastline border. 1 is the default.

mesh_border

The colour of the unstructured mesh grid lines. "lightgrey" is the default.

mesh_lwd

The thickness of the mesh grid lines. 1 is the default.

mesh_lty

The line type of the mesh grid lines. 1 is the default.

ncols

The number of colours in a spectrum that is used to colour either mesh cells (for scalar fields) or arrows (for vector fields) according to the value of the environmental variable resolved in that cell. Larger numbers result in smoother scales, which look as if they are continuous, which is desirable, but processing takes longer. 50000 is the default.

col_fn

A function used to create colours. heat.colors is the default colour scheme.

colour_bar_add

A logical input defining whether or not to add a colour bar to the map. TRUE is the default.

colour_bar_x

A pair of numeric values defining the lower and upper x coordinates of the colour bar respectively.

colour_bar_y

A pair of numeric values defining the lower and upper y coordinates of the colour bar respectively.

element_xy

(optional) For vector fields only, element_xy is matrix containing the coordinates of each element in the mesh. If this is not supplied, then these are obtained from the mesh object. However, if you are applying this function in a custom iterative procedure, supplying this matrix will improve computational performance (especially for large meshes) because it does not have to be recalculated every time.

arrow_angle

For vector fields only, a numeric value specifying the angle between the two sides of the arrow head in degrees (see arrows).

arrow_scale

For vector fields only, a numeric value which scales the length of the arrows. Smaller numbers produce smaller arrows.

arrow_length

For vector fields only, a numeric value which specifies the length of the arrow head.

arrow_lwd

For vector fields only, the thickness of the arrows.

arrow_lty

For vector fields only, the line type of the arrows.

xlab

An expression or string specifying the title of the x axis.

ylab

An expression or string specifying the title of the y axis.

zlab

An expression or string specifying the title of the z axis.

main

An expression or string specifying the title of the plot.

xlab_line

The number of lines the x axis title is away from the x axis.

ylab_line

The number of lines the y axis title is away from the y axis.

zlab_line

The number of lines the z axis title is away from the z axis.

main_line

The number of lines the plot title is away from the top of the plot.

axes

A logical input specifying whether or not to add axes to the plot. The function tries hard to find pretty labels within the limits set by xlim and ylim.

nticks

A numeric value specifying the approximate number of ticks between the x and y limits of the plot. This is approximate because the actual number of ticks depends on how many 'pretty' points lie between the x and y limits.

cex

A numerics value giving the amount by which axes titles should be magnified relative to the default. See par.

cex.axis

As above, but for the numbers assigned to axes tick marks.

Value

A plot of environmental conditions over an unstructured mesh at a snapshot in time.

Author(s)

Edward Lavender

Examples


#### (1) Plot a scalar variable (e.g. surface temperature) over space at a snapshot in time.
# This example plots temperature over space for a snapshot in time.
# The key arguments to note here are:
# mesh = dat_mesh_around_nodes; this is necessary because temperature is resolved at the nodes,
# ... so we need a grid which has a node at the heart of every grid cell.
# vector_field = FALSE; this is necessary because temperature is a scalar field.
# data = dat_temp; this is a pre-processed dataframe which provides a snapshot of
# ... of surface temperatures for a single timepoint.
xlim <- c(dat_area_boundaries$xlim1,
          dat_area_boundaries$xlim2)
ylim <- c(dat_area_boundaries$ylim1,
          dat_area_boundaries$ylim2)
plot_field_2d(coastline = dat_coast_around_oban,
              mesh = dat_mesh_around_nodes,
              vector_field = FALSE,
              data = dat_temp,
              xlim = xlim,
              ylim = ylim,
              ncols = 50,
              colour_bar_add = TRUE,
              colour_bar_x = c(xlim[2] + c(0.01, 0.02)),
              colour_bar_y = ylim,
              zlab = expression(paste("Temperature (", degree, "C)")),
              main = "2016-03-01"
              )

#### (2) Plot tidal elevation over space at a snapshot in time.
## Example not run simply to minimise CPU required for examples

plot_field_2d(coastline = dat_coast_around_oban,
              mesh = dat_mesh_around_nodes,
              vector_field = FALSE,
              data = dat_tidal_elevation,
              xlim = c(dat_area_boundaries$xlim1,
                       dat_area_boundaries$xlim2),
              ylim = c(dat_area_boundaries$ylim1,
              dat_area_boundaries$ylim2),
              zlab = "Tidal Elevation (m)",
              main = "2016-03-01"
              )


#### (3) Plot a vector field over space at a snapshot in time.

# Note that vector fields are resolved at the elements of WeStCOMS, so
# ... we need a mesh around elements. Also note vector_field = TRUE.
# Note also that the data needs to be supplied as a list comprising udata and vdata
# ... (i.e. dataframes of the u and v vector components respectively).
plot_field_2d(coastline = dat_coast_around_oban,
              mesh = dat_mesh_around_elements,
              vector_field = TRUE,
              data = list(udata = dat_uwind_speed,
                           vdata = dat_vwind_speed),
              xlim = c(dat_area_boundaries$xlim1,
                       dat_area_boundaries$xlim2),
              ylim = c(dat_area_boundaries$ylim1,
                       dat_area_boundaries$ylim2),
              # You can adjust the properties of the arrows for vector fields:
              arrow_angle = 30,
              arrow_scale = 0.0001,
              arrow_length = 0.01,
              arrow_lwd = 0.5,
              arrow_lty = 1,
              zlab = "Wind Speed (m)",
              main = "2016-03-01"
)



edwardlavender/fvcom.tbx documentation built on Nov. 26, 2022, 10:28 p.m.