Skip to contents

Open a local NetCDF file as a deferred ocean cube

Source: R/cube_open.R
cube_open.Rd

cube_open() opens one existing local NetCDF file as a read-only deferred NetCDF backend. Construction reads structural metadata and the coordinate values required by the canonical cube, but it does not read scientific variable arrays or create x$data.

Usage

cube_open(
  file,
  vars = NULL,
  lon_name = NULL,
  lat_name = NULL,
  depth_name = NULL,
  time_name = NULL,
  source = "netcdf",
  dataset_id = NULL
)

Arguments

file

A single non-empty path to an existing local NetCDF file. URLs, directories, and multiple files are not supported.

vars

A character vector of unique data-variable names, or NULL. NULL discovers all non-coordinate data variables from NetCDF metadata in source order. The complete discovered set must share one compatible rectilinear cube; incompatible variables cause an error rather than being silently omitted.

lon_name, lat_name, depth_name, time_name

Optional explicit physical dimension names. Explicit mappings take precedence over the backend's CF attribute evidence and known-name fallback.

source

A non-empty source label stored with ingestion metadata.

dataset_id

An optional non-empty dataset identifier.

Value

An ocean_cube with a read-only NetCDF storage backend and no materialized data component.

Details

The returned object has the usual c("ocean_cube", "list") class. Its internal, versioned x$storage descriptor records how bounded I/O can be performed. The descriptor schema is implementation metadata and is not a stable public API. Independently, x$metadata$cf preserves the source CF metadata in a backend-independent internal schema. No NetCDF connection is retained in either object: each scientific read validates the source, opens it, reads the required block, and closes it.

This is deferred I/O with bounded reads for supported operations, not a lazy computation graph. Use cube_collect() when an independent in-memory cube is required. A serialized deferred cube remains usable while its source exists at the same path with the same size, modification time, and compatible physical schema. Moving, deleting, or changing that source causes a deterministic error when an operation next needs it.

See also

read_nc(), cube_collect(), cube_inspect(), cube_crop(), cube_extract()

Examples

if (FALSE) { # \dontrun{
x <- cube_open("ocean.nc", vars = "sst")
cube_inspect(x)

small <- cube_crop(
  x,
  longitude = c(-80, -78),
  latitude = c(-12, -10)
)

values <- cube_extract(
  x,
  longitude = -79,
  latitude = -11,
  match = "nearest",
  mode = "series"
)

mem <- cube_collect(x)
} # }