Draw a static transect from an ocean cube

viz.transect() delegates ordered path matching and scientific selection to cube_transect(), then draws either a distance-by-depth section or a distance-by-value horizontal transect. It never interpolates values or densifies the supplied path.

Usage

viz.transect(
  x,
  path,
  variable,
  time = NULL,
  depth = NULL,
  lon_col = "longitude",
  lat_col = "latitude",
  id_col = NULL,
  match = c("exact", "nearest"),
  tolerance = NULL,
  mode = c("auto", "section", "horizontal"),
  distance = c("requested", "matched"),
  limits = NULL,
  na.rm = TRUE,
  reverse_depth = TRUE,
  points = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

x

A valid <ocean_cube> using the memory or NetCDF backend.

path

An ordered path accepted by cube_transect(). It is passed unchanged; sf/sfc paths are rejected by the extraction contract.

variable

One non-empty, non-missing variable name.

time

NULL for a singleton time axis or one stored time value.

depth

Optional stored depth selector passed directly to cube_transect(). A section requires at least two depths; a horizontal transect requires exactly one physical depth or the surface depth.

lon_col, lat_col

Column names containing path longitude and latitude.

id_col

Optional path column used as point identifiers.

match

Matching method passed explicitly to cube_transect(). The new visualization API defaults to exact matching. Nearest matching may warn when no scientific tolerance is supplied.

tolerance

Optional nearest-matching tolerance passed unchanged to cube_transect().

mode

Plot mode. "auto" chooses a section for two or more depths and a horizontal plot for one physical depth or a surface cube.

distance

Cumulative distance used on the x axis. "requested", the default, follows the user path; "matched" follows the matched grid path. Point-to-cell match_distance_km is diagnostic and is never the x axis.

limits

NULL or two finite numeric scale limits in increasing order. Values outside the limits are squished to the boundary without removing observations.

na.rm

A single non-missing logical value. Missing values are removed before plotting when TRUE; they are never replaced or interpolated.

reverse_depth

A single non-missing logical value. In section mode, TRUE places the surface at the top and greater depths downward.

points

A single non-missing logical value. In horizontal mode, TRUE adds points to the line; it does not alter a section plot.

title, subtitle, caption

Optional character scalars used as plot labels.

Value

A ggplot object with the resolved variable, time, mode, distance, depth range, backend, matching settings, maximum point-to-cell distance, and path point count recorded in oceancube_* attributes.

Details

cube_transect() is the sole data-selection and coordinate-matching layer. viz.transect() does not recalculate distances, access a backend reader, aggregate duplicate cells, interpolate, or reorder the requested path. Regular distance-by-depth grids use geom_raster() and irregular grids use geom_tile(). Repeated path positions that create duplicate distance-depth cells cannot define a two-dimensional section and are rejected; remove the zero-length segment or choose the alternative distance metric when valid. NetCDF extraction remains selective through cube_transect().

See also

cube_transect(), viz.map(), viz.section(), viz.profile()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  values <- array(1:12, dim = c(3, 1, 4, 1, 1))
  cube <- ocean_cube(
    lon = c(-80, -79, -78), lat = -11, depth = c(0, 25, 50, 100),
    time = as.Date("2020-01-01"), data = values,
    vars = "temperature", units = "degC"
  )
  path <- data.frame(
    longitude = c(-80, -79, -78), latitude = rep(-11, 3)
  )
  viz.transect(cube, path, "temperature", depth = 0)
  viz.transect(cube, path, "temperature", mode = "section")
}