Crop an ocean cube with closed coordinate ranges

cube_crop() retains every stored cell centre inside closed coordinate intervals. It materializes only the resulting selection as an independent memory-backed <ocean_cube>.

Usage

cube_crop(
  x,
  longitude = NULL,
  latitude = NULL,
  depth = NULL,
  time = NULL,
  variable = NULL,
  bbox = NULL,
  outside = c("error", "clip")
)

Arguments

x: A valid <ocean_cube> using the memory or NetCDF backend.
longitude, latitude, depth: Optional numeric ranges c(lower, upper). NULL keeps the complete axis.
time: Optional two-value temporal range compatible with x$time. Calendar-aware axes accept compatible oceancube_cf_time values or calendar-valid character dates. POSIXct limits match elapsed instants and may use a display timezone other than the cube's canonical UTC.
variable: Optional exact variable names. NULL keeps all variables.
bbox: Optional numeric vector named exactly xmin, ymin, xmax, and ymax. It is an alternative to longitude and latitude.
outside: How ranges extending beyond the cube domain are handled. "error" rejects them; "clip" intersects them with the domain.

Value

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

Details

Ranges are closed: cell centres exactly equal to either limit are included. Limits must be supplied as c(lower, upper). The public API retains this two-limit contract; the shared internal time resolver also supports one open bound for bounded downstream workflows. A range that intersects the numeric domain but contains no stored centre is an error. No nearest-neighbour adjustment, interpolation, cell-bound calculation, or coordinate generation is performed.

bbox is interpreted in the units and longitude convention already used by x$lon and x$lat. General sf geometries, sf::st_bbox() objects, reprojection, longitude conversion, polygons, and boxes crossing the antimeridian are outside this initial contract.

The result is always materialized in memory through one indexed .cube_read() call. For NetCDF inputs, the backend reads only the resolved block and requested variables, so memory use is proportional to the crop rather than necessarily to the complete source cube.

cube_crop() selects intervals of stored centres. Use cube_slice() for explicit coordinate values or positional indices.

Examples

values <- array(seq_len(3 * 2 * 1 * 2 * 1), dim = c(3, 2, 1, 2, 1))
cube <- ocean_cube(
  lon = c(-80, -79, -78),
  lat = c(-12, -11),
  depth = 0,
  time = as.Date(c("2020-01-01", "2020-02-01")),
  vars = "temperature",
  data = values
)
cube_crop(cube, longitude = c(-79.8, -78.8))
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 1 x 2 x 1 x 2 x 1 [lon x lat x depth x time x var]
#>   lon        : -79 to -79 (n = 1)
#>   lat        : -12 to -11 (n = 2)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2020-01-01 to 2020-02-01 (n = 2)
#>   variables  : temperature
cube_crop(
  cube,
  bbox = c(xmin = -80, ymin = -12, xmax = -79, ymax = -11)
)
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 2 x 2 x 1 x 2 x 1 [lon x lat x depth x time x var]
#>   lon        : -80 to -79 (n = 2)
#>   lat        : -12 to -11 (n = 2)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2020-01-01 to 2020-02-01 (n = 2)
#>   variables  : temperature