Select discrete positions or coordinate values from an ocean cube

cube_slice() selects discrete cells from an <ocean_cube> either by one-based array position or by stored coordinate value. It materializes only the requested selection as an independent memory-backed cube.

Usage

cube_slice(
  x,
  longitude = NULL,
  latitude = NULL,
  depth = NULL,
  time = NULL,
  variable = NULL,
  by = c("value", "index"),
  match = c("exact", "nearest"),
  tolerance = NULL
)

Arguments

x

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

longitude, latitude, depth, time, variable

Optional selectors. NULL keeps the complete axis. Calendar-aware time accepts compatible oceancube_cf_time values or calendar-valid character dates.

by

Whether selectors are coordinate "value"s or one-based "index" positions.

match

Coordinate matching method. "exact" requires a stored value; "nearest" selects the closest stored coordinate within the cube domain. Variable names are always matched exactly.

tolerance

Optional fully named list of maximum nearest-neighbour distances. Numeric scalar tolerances are used for longitude, latitude, and depth; time requires a scalar difftime. Equality with the tolerance is accepted.

Value

An <ocean_cube> using the memory backend and retaining all five dimensions.

Details

by = "index" removes the ambiguity between a coordinate such as longitude 2 and the second longitude position. In this mode match and tolerance must not be supplied.

Exact numeric matching uses the values stored in the coordinate vector, without an implicit floating-point tolerance. Nearest-neighbour matching is independent on each axis, chooses the earlier instant on temporal ties, and rejects requests outside the stored axis range. It is not interpolation and does not alter scientific values. Calendar-aware exact and nearest matching uses the same-calendar ordinal and sub-day metric; cross-calendar comparisons are rejected.

Requested order and repeated spatial or depth coordinates are preserved. Resolved time coordinates must remain unique and strictly increasing because the result is itself a canonical cube. Variable names remain unique, so repeated variable selections are rejected.

The result is always materialized in memory, but only after all selectors have been resolved and only through one indexed .cube_read() call. Consequently memory use is proportional to the requested selection, not necessarily to the complete source cube. cube_slice() selects discrete points; it is not a range-based crop or an event extraction operation.

See also

cube_collect()

Examples

values <- array(seq_len(3 * 1 * 1 * 2 * 1), dim = c(3, 1, 1, 2, 1))
cube <- ocean_cube(
  lon = c(-80, -79, -78),
  lat = -12,
  depth = 0,
  time = as.Date(c("2020-01-01", "2020-02-01")),
  vars = "temperature",
  data = values
)
cube_slice(cube, longitude = c(-78, -80), by = "value")
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 2 x 1 x 1 x 2 x 1 [lon x lat x depth x time x var]
#>   lon        : -80 to -78 (n = 2)
#>   lat        : -12 to -12 (n = 1)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2020-01-01 to 2020-02-01 (n = 2)
#>   variables  : temperature
cube_slice(cube, longitude = c(3L, 1L), by = "index")
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 2 x 1 x 1 x 2 x 1 [lon x lat x depth x time x var]
#>   lon        : -80 to -78 (n = 2)
#>   lat        : -12 to -12 (n = 1)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2020-01-01 to 2020-02-01 (n = 2)
#>   variables  : temperature
cube_slice(
  cube,
  longitude = -79.4,
  by = "value",
  match = "nearest",
  tolerance = list(longitude = 0.5)
)
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 1 x 1 x 1 x 2 x 1 [lon x lat x depth x time x var]
#>   lon        : -79 to -79 (n = 1)
#>   lat        : -12 to -12 (n = 1)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2020-01-01 to 2020-02-01 (n = 2)
#>   variables  : temperature