Extract ocean-cube cells as a data frame

cube_extract() resolves the same discrete selectors as cube_slice() but returns their Cartesian product as a base data.frame instead of creating another cube.

Usage

cube_extract(
  x,
  longitude = NULL,
  latitude = NULL,
  depth = NULL,
  time = NULL,
  variable = NULL,
  by = c("value", "index"),
  match = c("exact", "nearest"),
  tolerance = NULL,
  mode = c("point", "profile", "series", "table"),
  format = c("long", "wide"),
  keep_index = FALSE,
  keep_distance = FALSE
)

Arguments

x

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

longitude, latitude, depth, time, variable

Optional selectors. NULL retains the complete axis.

by

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

match

Coordinate matching method. "exact" requires stored values; "nearest" selects the nearest stored coordinate inside the domain.

tolerance

Optional fully named list of maximum distances for nearest matching, using numeric values for spatial/depth axes and difftime for time.

mode

Extraction intent: discrete "point"s, a vertical "profile", a temporal "series", or a general Cartesian "table".

format

"long" returns one row per selected array value; "wide" returns one row per longitude-latitude-depth-time key and one column per variable.

keep_index

Add the selected one-based indices in the original cube.

keep_distance

Add requested values and nearest-match distances.

Value

A base data.frame with lightweight selection and provenance attributes. Long output contains longitude, latitude, depth, time, variable, unit, and value.

Details

The selectors form a Cartesian product. In long output, rows follow R array order: longitude changes fastest, followed by latitude, depth, time, and variable. Requested order and repeated coordinate positions are preserved. Wide output rejects repeated variables or coordinate keys because silently aggregating them would be ambiguous.

Nearest matching chooses a stored cell and never interpolates. With keep_distance = TRUE, diagnostics distinguish requested values from the selected coordinates. This option is available only with by = "value", match = "nearest". Temporal matching keeps Date civil-date semantics separate from POSIXct instant semantics. POSIXct results remain UTC with sub-day precision. Equidistant temporal nearest matches choose the earlier instant, and time tolerances must be finite, non-negative scalar difftime values.

A profile requires exactly one longitude, latitude, and time. A series requires exactly one longitude, latitude, and depth. Point and table modes do not change the Cartesian-product semantics.

NetCDF inputs are resolved without opening the file and then read once through the backend. Only the selected envelope and variables are read. Extracting without selectors requests the complete cube and can create a large table; the expected rows and approximate array bytes are calculated before reading. Source temporal provenance is attached to the returned table without copying the backend's raw numeric time vector.

Unlike link_events(), which enriches independent event rows, cube_extract() generates the Cartesian grid of its axis selectors. cube_crop() selects continuous ranges and returns a cube; cube_slice() selects discrete positions and returns a cube.

Function	Input	Semantics	Output
cube_slice()	selectors	Cartesian product	cube
cube_crop()	ranges	rectangular subdomain	cube
cube_extract()	selectors	Cartesian product	table
link_events()	event rows	row by row	enriched table

See also

cube_slice(), cube_crop(), link_events()

Examples

values <- array(seq_len(2 * 1 * 2 * 2 * 1), dim = c(2, 1, 2, 2, 1))
cube <- ocean_cube(
  lon = c(-80, -79),
  lat = -11,
  depth = c(0, 50),
  time = as.Date(c("2020-01-01", "2020-02-01")),
  vars = "temperature",
  units = c(temperature = "degC"),
  data = values
)
cube_extract(
  cube,
  longitude = -79,
  latitude = -11,
  time = as.Date("2020-02-01"),
  mode = "profile"
)
#>   longitude latitude depth       time    variable unit value
#> 1       -79      -11     0 2020-02-01 temperature degC     6
#> 2       -79      -11    50 2020-02-01 temperature degC     8
cube_extract(cube, depth = 0, mode = "table", format = "wide")
#>   longitude latitude depth       time temperature
#> 1       -80      -11     0 2020-01-01           1
#> 2       -79      -11     0 2020-01-01           2
#> 3       -80      -11     0 2020-02-01           5
#> 4       -79      -11     0 2020-02-01           6