Struct XArray 

pub struct XArray<T> { /* private fields */ }

Labelled N-dimensional array with named dimensions and coordinate-based indexing.

XArray wraps an NdArray or NdArrayV with per-axis names and optional coordinate labels, enabling selection by value rather than raw position. Owned data and selection views expose the same container interface.

Construction

use minarrow::structs::ndarray::NdArray;
use minarrow::structs::xarray::{XArray, Axis};

// Name the dimensions, no coordinate labels
let data = NdArray::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[3, 2]);
let xa = XArray::new(data, &["station", "measurement"]);
assert_eq!(xa.dim("measurement"), 1);

Coordinate-based selection

Assign coordinate labels to an axis, then select by value:

// 5 stations, 2 measurements each
let data = NdArray::from_slice(
    &[10.0, 20.0, 30.0, 40.0, 50.0, 1.0, 2.0, 3.0, 4.0, 5.0],
    &[5, 2],
);
let mut xa = XArray::new(data, &["station", "measurement"]);

// Label the station axis with latitude values
xa.assign_coords("station", arr_f64![-33.8, 35.7, 51.5, 40.7, -22.9]);

// Select stations between latitudes 35 and 52
let subset = xa.between("station", 35.0, 52.0);
assert_eq!(subset.shape(), vec![3, 2]); // 3 stations matched

Positional selection

Select by axis name and index/range without coordinates:

let data = NdArray::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[3, 2]);
let xa = XArray::new(data, &["obs", "feat"]);

// Range on one axis - keeps the dimension
let sub = xa.select(&[("obs", &(0..2))]);
assert_eq!(sub.shape(), vec![2, 2]);

// Single index collapses the dimension
let col0 = xa.select(&[("feat", &0)]);
assert_eq!(col0.ndim(), 1);

Implementations

impl<T: Float> XArray<T>

pub fn new(data: NdArray<T>, dim_names: &[&str]) -> Self

Create with named dimensions, no coordinates.

pub fn with_axes(data: NdArray<T>, axes: Vec<Axis>) -> Self

Create with fully specified axes.

pub fn from_ndarray(data: NdArray<T>) -> Self

Create from NdArray with auto-generated dim names.

pub fn from_view(view: NdArrayV<T>, axes: Vec<Axis>) -> Self

Wrap an NdArrayV view with axes (zero-copy).

pub fn try_ax(&self, name: &str) -> Option<&Axis>

Get axis by name. Returns None if not found.

pub fn ax(&self, name: &str) -> &Axis

Get axis by name. Panics if not found.

pub fn try_dim(&self, name: &str) -> Option<usize>

Get the position of a named axis. Returns None if not found.

pub fn dim(&self, name: &str) -> usize

Get the position of a named axis. Panics if not found.

pub fn axes(&self) -> &[Axis]

All axes.

pub fn dim_names(&self) -> Vec<&str>

Dim names.

pub fn into_ndarray(self) -> NdArray<T>

Consume and return the inner NdArray, materialising if it is a view.

pub fn to_owned(&self) -> XArray<T>

Materialise to an owned NdArray if currently a view.

pub fn as_view(&self) -> NdArrayV<T>

Borrow the data as a zero-copy NdArrayV, regardless of whether this XArray currently owns its NdArray or already holds a view.

pub fn is_owned(&self) -> bool

True if backed by a single owned NdArray.

pub fn ndim(&self) -> usize

pub fn shape(&self) -> Vec<usize>

pub fn strides(&self) -> &[usize]

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn obs(&self, idx: usize) -> NdArrayV<T>

Zero-copy view of a single observation (axis-0 element).

Returns an (N-1)-dimensional NdArrayV view regardless of the inner storage mode.

pub fn m(&self) -> i32

pub fn n(&self) -> i32

pub fn lda(&self) -> i32

pub fn get(&self, indices: &[usize]) -> T

Single element access.

pub fn set(&mut self, indices: &[usize], value: T)

Mutable element access. Triggers copy-on-write if the owned array is shared with views; an XArray backed by a view cannot be mutated.

pub fn par_iter_obs( &self, ) -> impl ParallelIterator<Item = (usize, NdArrayV<T>)> + '_

where T: Send + Sync,

Parallel iterator over axis-0 observations. Each item is the observation index and a zero-copy NdArrayV view.

pub fn apply(&self, f: impl Fn(T) -> T) -> XArray<T>

Apply a function to every logical element, returning a new labelled array with the same axes. View storage materialises to owned.

pub fn apply_mut(&mut self, f: impl Fn(T) -> T)

Apply a function to every logical element in place. An XArray backed by a view cannot be mutated, matching set.

pub fn rename_dim(&mut self, old: &str, new: &str)

Rename an axis.

pub fn assign_coords(&mut self, dim_name: &str, coords: Array)

Assign or replace coordinates for a named axis.

pub fn drop_coords(&mut self, dim_name: &str)

Remove coordinates from a named axis.

pub fn select(&self, selection: &[(&str, &dyn DataSelector)]) -> XArray<T>

Select sub-arrays by named axis positions. Returns zero-copy XArray backed by NdArrayV.

Single indices collapse that dimension. Ranges keep it.

Examples

xa.select(&[("lat", &(0..3))])                  // single axis range
xa.select(&[("lat", &(0..3)), ("lon", &2)])     // multi-axis mixed

pub fn slice(&self, selection: &[&dyn DataSelector]) -> NdArrayV<T>

Slice the underlying NdArray/NdArrayV positionally and zero-copy. For named axis selection, use .select() instead.

pub fn try_at( &self, dim_name: &str, value: impl Into<Scalar>, ) -> Result<XArray<T>, MinarrowError>

Select a single position on a named axis by coordinate value. Accepts numeric, string, and datetime values. Collapses that dimension. Returns an error if the value is not found. Float coordinates match by IEEE equality, so NaN never matches and derived values may miss - nearest tolerates rounding.

pub fn at(&self, dim_name: &str, value: impl Into<Scalar>) -> XArray<T>

Select a single position by coordinate value. Panics if not found.

pub fn try_between( &self, dim_name: &str, low: impl Into<Scalar>, high: impl Into<Scalar>, ) -> Result<XArray<T>, MinarrowError>

Select a range by coordinate value bounds (inclusive). Accepts numeric, string, and datetime bounds. Returns an error if no values fall in the range, or if the matching coordinates do not form a contiguous run i.e. the axis is not monotonic over the requested bounds - sort the axis or gather by position for unsorted coordinates.

pub fn between( &self, dim_name: &str, low: impl Into<Scalar>, high: impl Into<Scalar>, ) -> XArray<T>

Select a range by coordinate value bounds. Panics if no values match, or if the axis is not monotonic over the requested bounds.

pub fn try_nearest( &self, dim_name: &str, value: impl Into<Scalar>, ) -> Result<XArray<T>, MinarrowError>

Select the position whose coordinate is closest to value on a named axis. Collapses that dimension. Numeric and datetime coordinates only, since text has no distance metric. Returns an error if the axis has no comparable coordinates.

pub fn nearest(&self, dim_name: &str, value: impl Into<Scalar>) -> XArray<T>

Select the position whose coordinate is closest to value. Panics if the axis has no comparable coordinates.

pub fn transpose(&self, dim_order: &[&str]) -> Result<XArray<T>, MinarrowError>

Transpose (2D only). Reorders axes by name, so the result’s dimensions arrive in dim_order. Passing the current order returns the array unchanged.

impl XArray<f64>

pub fn to_table(self) -> Result<Table, MinarrowError>

Convert a 2D XArray to a Table. Uses axis 1 coords as column names if available, otherwise generates names from the dim name.

Trait Implementations

impl<T: Float> AxisSelection for XArray<T>

Available on crate features select and views only.

Positional selection across every axis at once, delegating to slice. The result is an unlabelled view. For named-axis selection with the labels carried through, use .select().

type View = NdArrayV<T>

The view type returned by axis selection e.g. NdArrayV

fn s(&self, selection: &[&dyn DataSelector]) -> NdArrayV<T>

Select along every axis at once, one DataSelector per axis

fn get_axis_count(&self) -> usize

Get the axis count for selection resolution

fn select(&self, selection: &[&dyn DataSelector]) -> Self::View

Select along every axis at once, one DataSelector per axis

impl<T: Float> ByteSize for XArray<T>

Available on crate feature xarray only.

fn est_bytes(&self) -> usize

Returns the estimated byte size of this object in memory.

fn logical_bytes(&self) -> usize

Returns the exact logical byte size of the data.

impl<T: Clone> Clone for XArray<T>

fn clone(&self) -> XArray<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Float> Concatenate for XArray<T>

fn concat(self, other: Self) -> Result<Self, MinarrowError>

Concatenates self with other, consuming both and returning a new instance.

impl<T: Float> Debug for XArray<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Float + Display> Display for XArray<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<XArray<f64>> for Value

Available on crate feature xarray only.

fn from(v: XArray<f64>) -> Self

Converts to this type from the input type.

impl From<XArray<f64>> for NdArray<f64>

fn from(value: XArray<f64>) -> Self

Drops the axis labels and keeps the contiguous payload.

impl<'a, T: Float> IntoIterator for &'a XArray<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = T> + 'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Float> PartialEq for XArray<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: Float> Shape for XArray<T>

fn shape(&self) -> ShapeDim

Returns arbitrary Shape dimension for any data shape

fn shape_1d(&self) -> usize

Returns the first dimension shape

fn shape_2d(&self) -> (usize, usize)

Returns the first and second dimension shapes

fn shape_3d(&self) -> (usize, usize, usize)

Returns the first, second and third dimension shapes

fn shape_4d(&self) -> (usize, usize, usize, usize)

Returns the first, second, third and fourth dimension shapes

impl TryFrom<Table> for XArray<f64>

type Error = MinarrowError

The type returned in the event of a conversion error.

fn try_from(table: Table) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for XArray<f64>

Available on crate feature xarray only.

fn try_from(v: Value) -> Result<Self, Self::Error>

Takes the XArray carried by Value::XArray, unwrapping the recursive BoxValue and ArcValue wrappers first.

type Error = MinarrowError

The type returned in the event of a conversion error.

impl TryFrom<XArray<f64>> for Table

fn try_from(value: XArray<f64>) -> Result<Self, Self::Error>

Presents the labelled axes as table columns.

type Error = MinarrowError

The type returned in the event of a conversion error.