Mask an ocean cube with polygon cell-centre coverage

cube_mask() classifies the longitude-latitude cell centres of an <ocean_cube> against polygon geometry. It preserves the complete five dimensional cube and replaces values in cells not retained by the mask with NA.

Usage

cube_mask(
  x,
  polygons,
  crs = NULL,
  keep = c("inside", "outside"),
  boundary = c("include", "exclude")
)

Arguments

x

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

polygons

An sf, sfc, or polygonal sfg object containing only POLYGON or MULTIPOLYGON geometries.

crs

Optional CRS used only to assign a CRS to geometry that has none. Geometry with an existing CRS is never reinterpreted.

keep

Whether to retain centres "inside" or "outside" the polygon union.

boundary

Whether cell centres on polygon boundaries are included or excluded.

Value

A memory-backed <ocean_cube> with the same coordinates, units, dimensions, and extents as x. Its <ocean_mask> records coverage and lightweight geometry metadata.

Details

Coverage is determined only from cell centres. fraction_cells_kept is a fraction of cell centers, not a fraction of geographic area. No cell areas, partial overlaps, interpolation, resampling, or area weighting are computed.

Several polygon features are combined as one geometric union; overlaps are counted once and polygon holes are respected. boundary = "include" uses a covered-by relation, while "exclude" uses strict within. Exact boundary classification is subject to the numerical behaviour of the spatial engine.

Cubes currently have no explicit CRS field, so longitude and latitude are interpreted as geographic EPSG:4326 coordinates. Polygon geometry must already use a compatible geographic CRS and the same longitude convention as x$lon. Geometry is not transformed. Dateline-crossing polygons are not supported in this phase.

An existing compatible 3D <ocean_mask> is combined using logical AND and never overwritten or reactivated. Distance-to-coast metadata is preserved. Climatology, anomaly, and dimensional QA components are discarded because they can become stale.

A NetCDF input is read only after centre classification. For keep = "inside", only the smallest longitude-latitude bounding rectangle containing effective retained centres is read. keep = "outside" may require a full spatial read in the initial implementation. Output is always fully materialized in memory and independent of the source file.

Function	Geometry	Action	Output
cube_crop()	rectangular range	reduces axes	smaller cube
cube_mask()	polygon	replaces outside with NA	same-shape cube
future cube_polygon_summary()	polygon	summarizes values	table

See also

cube_crop(), stock_mask(), crop_stock()

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  values <- array(seq_len(3 * 2), dim = c(3, 2, 1, 1, 1))
  cube <- ocean_cube(
    lon = c(-80, -79, -78), lat = c(-12, -11), depth = 0,
    time = as.Date("2021-01-01"), vars = "temperature", data = values
  )
  polygon <- sf::st_sfc(sf::st_polygon(list(matrix(
    c(-80.5, -12.5, -78.5, -12.5, -78.5, -10.5,
      -80.5, -10.5, -80.5, -12.5),
    ncol = 2, byrow = TRUE
  ))), crs = 4326)
  cube_mask(cube, polygon)
}
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 3 x 2 x 1 x 1 x 1 [lon x lat x depth x time x var]
#>   lon        : -80 to -78 (n = 3)
#>   lat        : -12 to -11 (n = 2)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2021-01-01 to 2021-01-01 (n = 1)
#>   variables  : temperature