Construct an oceanographic data cube — ocean

ocean_cube() stores gridded oceanographic data in a standard 5D array: [longitude, latitude, depth, time, variable]. Surface fields can be stored with a single depth level set to NA_real_.

Usage

ocean_cube(
  lon,
  lat,
  time,
  data,
  depth = NULL,
  vars = NULL,
  units = NULL,
  source = NULL,
  dataset_id = NULL,
  spatial_extent = NULL,
  temporal_extent = NULL,
  depth_extent = NULL,
  mask = NULL,
  dc = NULL,
  climatology = NULL,
  anomaly = NULL,
  provenance = NULL,
  qa = NULL
)

Arguments

lon: Non-empty finite numeric vector of longitudes, using either the [-180, 180] or [0, 360] convention.
lat: Non-empty finite numeric vector of latitudes in [-90, 90].
time: Non-empty, unique, strictly increasing Date, POSIXct, internal oceancube_cf_time, or unambiguous ISO character vector. Civil dates remain Date; POSIXct instants retain sub-day precision and are normalized to UTC. Calendar-aware values produced by the NetCDF readers preserve their non-Gregorian calendar identity.
data: Numeric array. Preferred shape is 5D: [lon, lat, depth, time, var]. A 4D array [lon, lat, time, var] is accepted and internally promoted to a single-depth cube.
depth: Numeric vector of depth levels. If NULL, a single surface/no-depth level is used. A single NA_real_ represents a surface cube without an explicit depth coordinate.
vars: Non-empty character vector of unique variable names.
units: Optional character vector or list with one unit per variable. If named, names must match vars uniquely.
source: Optional data source label.
dataset_id: Optional dataset identifier.
spatial_extent: Optional finite c(lon_min, lon_max, lat_min, lat_max) covering the coordinates.
temporal_extent: Optional ordered pair using the same temporal class and calendar semantics as time, covering the coordinate.
depth_extent: Optional finite ordered depth range covering depth, or c(NA_real_, NA_real_) for a surface cube.
mask: Optional mask object.
dc: Optional distance-to-coast matrix in nautical miles.
climatology: Optional climatology object.
anomaly: Optional anomaly metadata.
provenance: Optional provenance metadata.
qa: Optional QA/QC metadata.

Value

An object of class <ocean_cube>. NetCDF readers may attach internal, independently versioned scientific metadata at x$metadata$cf. Manually constructed cubes use x$metadata = NULL; the nested metadata representation is internal and is not a stable public accessor contract.

Details

The stable dimensional contract is [longitude, latitude, depth, time, variable]. For current in-memory cubes:

dim(data) == c(length(lon), length(lat), length(depth),
               length(time), length(vars))

Coordinate values are preserved in the supplied order; the constructor does not sort, deduplicate, or convert longitude conventions. Time is the exception to otherwise permissive coordinate ordering: it must be unique and strictly increasing so that temporal identity is unambiguous and aligned data are never reordered silently. Positive and negative depth values are accepted without inferring vertical direction. Variable names must be unique.

Dimension lengths and axis order form the primary contract. Names attached to dim(data) or dimnames(data) are descriptive and are not used to determine axis meaning. The current data array is retained for compatibility, but the physical storage mechanism is an internal concern that may be represented by another backend in a future version.

Canonical temporal provenance records class, timezone, source timezone or offset when known, calendar, decoder, and normalization. Memory inputs use proleptic-Gregorian R semantics. NetCDF calendar policy is applied by read_nc() and the lazy backend before this constructor is reached. Vertical positive-direction metadata are not inferred here.

Examples

lon <- seq(-82, -80, length.out = 3)
lat <- seq(-12, -10, length.out = 4)
time <- as.Date("2000-01-01") + 0:2
data <- array(rnorm(3 * 4 * 1 * 3 * 1), dim = c(3, 4, 1, 3, 1))
cube <- ocean_cube(lon = lon, lat = lat, depth = 0, time = time, data = data, vars = "thetao")
cube
#> <ocean_cube>
#>   backend    : memory
#>   source     : <unspecified>
#>   dimensions : 3 x 4 x 1 x 3 x 1 [lon x lat x depth x time x var]
#>   lon        : -82 to -80 (n = 3)
#>   lat        : -12 to -10 (n = 4)
#>   depth      : 0 to 0 (n = 1)
#>   time       : 2000-01-01 to 2000-01-03 (n = 3)
#>   variables  : thetao
summary(cube)
#>       field n        min        max
#> 1 longitude 3        -82        -80
#> 2  latitude 4        -12        -10
#> 3     depth 1          0          0
#> 4      time 3 2000-01-01 2000-01-03
#> 5  variable 1       <NA>       <NA>