cube_transect() resolves the rows of path as ordered
longitude-latitude pairs and extracts
one time, one or more depths, and selected variables. Unlike
cube_extract(), spatial coordinates never form a Cartesian product.
Usage
cube_transect(
x,
path,
lon_col = "longitude",
lat_col = "latitude",
id_col = NULL,
depth = NULL,
time = NULL,
variable = NULL,
by = c("value", "index"),
match = c("nearest", "exact"),
tolerance = NULL,
mode = c("auto", "horizontal", "section", "profile"),
format = c("long", "wide"),
keep_index = FALSE
)Arguments
- x
A valid
<ocean_cube>using the memory or NetCDF backend.- path
A data frame (or matrix) with one row per ordered point. Values are interpreted as geographic longitude and latitude in degrees. Objects inheriting from
sforsfcare rejected explicitly; convert them to an ordinary longitude-latitude table in EPSG:4326 first.- lon_col, lat_col
Column names containing longitude and latitude values, or one-based positions when
by = "index".- id_col
Optional column name used as
point_id. Factors are converted safely to their labels. Duplicated identifiers are preserved.- depth, time, variable
Depth, time, and variable selectors. Exactly one time must resolve.
NULLretains an entire axis, except thattime = NULLis valid only for a singleton time axis.- by
Whether selectors contain coordinate
"value"s or one-based"index"positions.- match
"nearest"selects the closest stored coordinate within each axis domain;"exact"requires a stored coordinate. Ties select the first stored position. This argument is not supplied withby = "index". The historical default is nearest; omittingmatchemits a compatibility warning so new code makes the scientific choice explicit.- tolerance
Optional fully named list of non-negative maximum distances for nearest matching. Spatial and depth tolerances are numeric; time uses
difftime.- mode
"profile"requires one point,"horizontal"at least two points and one depth, and"section"at least two points and at least two depths."auto"infers these rules.- format
"long"returns point-depth-variable rows."wide"returns one point-depth-time row and one column per variable.- keep_index
Include global one-based cube indices for longitude, latitude, depth, time, and variable. The default remains
FALSEfor backward-compatible schemas.
Value
A fully materialized base data.frame. Long output contains
point_id, point_order, longitude_requested, latitude_requested,
longitude, latitude, match_distance_km, requested_distance_km,
matched_distance_km, depth, time, variable, unit, and value.
When keep_index = TRUE, global longitude_index, latitude_index,
depth_index, time_index, and variable_index columns are appended.
Details
Row order in long format is point, then depth, then variable. Supplied vertices are not densified. Point order, repeated vertices, zero-length segments, selected depth order, and variable order are preserved without aggregation. A path of two or more points whose total requested distance is zero produces a warning; a single point remains valid as a profile. Wide output rejects duplicated variables and keeps scientific names without syntactic conversion.
All distances use the spherical Haversine formula with mean Earth radius
6371.0088 km. requested_distance_km is cumulative distance along the user
path, matched_distance_km is cumulative distance along matched grid cells,
and match_distance_km is the pointwise displacement from each requested
coordinate to its matched grid coordinate. This is not exact ellipsoidal
distance. Antimeridian crossings (a segment with an absolute longitude
change greater than 180 degrees, including 359 to 1) are rejected;
longitudes are not normalized. Vertical distance is not added.
Nearest matching selects cells independently on the longitude and latitude
axes. It does not interpolate spatially, vertically, or temporally. Explicit
nearest matching without tolerance emits a scientific warning; supplied
per-axis tolerances retain their existing units and semantics. Exact matching
never falls back to nearest. With by = "index", requested and matched paths
use the selected cube coordinates and match_distance_km is zero.
Ordinary path tables must use one recognized longitude convention,
[-180, 180] or [0, 360], compatible with the cube. Latitude must lie in
[-90, 90]. CRS-bearing objects are never interpreted silently.
Duplicate stored depth or time coordinates and duplicate explicit depth,
time, or variable selectors are rejected as ambiguous. The approved
singleton NA_real_ surface-depth representation remains valid. Exactly one
time must resolve; time = NULL is therefore valid only for singleton time.
Fully and partially outside paths error; boundary points remain valid.
NetCDF reads use one connection per call, one physical block per unique spatial pair and unique selected variable, and reconstruct repeated points. Non-contiguous depths are subset from their smallest enclosing vertical block. A diagonal path therefore avoids reading its spatial bounding box.
Function comparison:
| Function | Spatial semantics | Output |
cube_extract() | Cartesian product | table |
link_events() | event rows | enriched table |
cube_transect() | ordered pairs | distance-depth table |
cube_crop() | rectangular subdomain | cube |
Examples
values <- array(seq_len(3 * 2 * 2 * 1 * 1), dim = c(3, 2, 2, 1, 1))
cube <- ocean_cube(
lon = c(-80, -79, -78), lat = c(-12, -11), depth = c(0, 50),
time = as.Date("2021-02-01"), vars = "temperature",
units = c(temperature = "degC"), data = values
)
path <- data.frame(
station = c("A", "B", "C"),
longitude = c(-80, -79, -78),
latitude = c(-12, -11, -12)
)
cube_transect(
cube, path, id_col = "station", depth = c(0, 50),
time = as.Date("2021-02-01"), match = "exact", mode = "section"
)
#> point_id point_order longitude_requested latitude_requested longitude
#> 1 A 1 -80 -12 -80
#> 2 A 1 -80 -12 -80
#> 3 B 2 -79 -11 -79
#> 4 B 2 -79 -11 -79
#> 5 C 3 -78 -12 -78
#> 6 C 3 -78 -12 -78
#> latitude match_distance_km requested_distance_km matched_distance_km depth
#> 1 -12 0 0.000 0.000 0
#> 2 -12 0 0.000 0.000 50
#> 3 -11 0 155.682 155.682 0
#> 4 -11 0 155.682 155.682 50
#> 5 -12 0 311.364 311.364 0
#> 6 -12 0 311.364 311.364 50
#> time variable unit value
#> 1 2021-02-01 temperature degC 1
#> 2 2021-02-01 temperature degC 7
#> 3 2021-02-01 temperature degC 5
#> 4 2021-02-01 temperature degC 11
#> 5 2021-02-01 temperature degC 3
#> 6 2021-02-01 temperature degC 9