Coordinate¶

Coordinate variables define the labeled dimensions of a dataset. They hold all data in memory and support append, prepend, and truncate operations.

Class Hierarchy¶

Variable (base)
  └── CoordinateView (sliced view, read-only)
        └── Coordinate (full coordinate, writable)

Coordinate — the full coordinate with append/prepend/truncate, returned by ds['coord_name'] or creation methods
CoordinateView — a sliced subset, returned by indexing a coordinate

Usage¶

with cfdb.open_dataset(file_path) as ds:
    lat = ds['latitude']
    print(lat.data)        # full array (in memory)
    print(lat.shape)       # (200,)
    print(lat.chunk_shape) # (20,)

Properties¶

Property	Type	Description
`name`	str	Variable name
`data`	np.ndarray	Full coordinate data (always in memory)
`values`	np.ndarray	Alias for `data`
`shape`	tuple	Shape of the coordinate
`chunk_shape`	tuple	Chunk shape
`dtype`	DataType	cfdb data type
`coord_names`	tuple of str	`(name,)` — the coordinate's own name
`ndims`	int	Always 1
`attrs`	Attributes	Variable attributes
`axis`	Axis or None	Physical axis (x, y, z, t, xy)
`step`	number or None	Regular spacing step
`origin`	int	Starting position in global index space
`auto_increment`	bool or None	Whether auto-increment is enabled
`units`	str or None	Physical units
`writable`	bool	Whether the dataset is writable
`loc`	LocationIndexer	Location-based indexer

Methods¶

append(data)¶

Append data to the end of the coordinate. Data must maintain uniqueness and ascending order. If the coordinate has an enforced step and the new data is not adjacent (there is a gap), intermediate values are auto-filled provided the gap is a valid multiple of the step. Data variables at auto-filled positions are empty (NaN/fillvalue) until written.

lat.append(np.array([20.0, 20.1], dtype='float32'))

prepend(data)¶

Prepend data to the beginning of the coordinate. Same auto-fill behavior as append() when a step is enforced.

lat.prepend(np.array([-0.2, -0.1], dtype='float32'))

truncate(start=None, stop=None)¶

Truncate the coordinate to keep only values in [start, stop] (inclusive). Accepts coordinate values (e.g., datetimes, floats, or strings for datetime coordinates). None means "from the beginning" / "to the end". Deletes orphaned chunks for both the coordinate and all associated data variables.

# Keep only February 2023
ds['time'].truncate(start='2023-02-01', stop='2023-02-28')

# Remove everything before a latitude
ds['latitude'].truncate(start=-45.0)

iter_chunks(include_data=False, decoded=True)¶

Iterate through chunks. If include_data=False (default), yields tuples of slices. If include_data=True, yields (slices, data) tuples.

Note

Coordinates use the base Variable.iter_chunks signature. Data variables have a different, unified iter_chunks(chunk_shape=None) signature — see DataVariable.

rechunker()¶

Return a Rechunker for this variable.

load()¶

For EDataset: pre-fetch chunks from S3. No-op for local datasets.

update_step(step)¶

Update the step value. Only on writable datasets.

update_axis(axis)¶

Update the axis value. Only on writable datasets.

update_units(units)¶

Update the units value. Only on writable datasets.

get_chunk(sel=None, missing_none=False)¶

Get data from one chunk.

items(decoded=True)¶

Iterate through all individual index positions yielding (index, value) tuples.