Struct Cube 

#[repr(C, align(64))]
pub struct Cube {
    pub tables: Vec<Table>,
    pub n_rows: Vec<usize>,
    pub name: String,
    pub third_dim_index: Option<Vec<String>>,
}

Cube - 3D Type for Advanced Analysis Use Cases

Holds a vector of tables unified by some value, often Time, for special indexing. Useful for data analysis.

Purpose

Useful when the tables represent discrete time snapshots, or a category dimension. This enables comparing data without losing the underlying grain through aggregation, whilst still supporting that.

Description

This is an optional extra enabled by the cube feature, and is not part of the Apache Arrow framework.

Under Development

⚠️ Unstable API and WIP: expect future development. Breaking changes will be minimised, but avoid using this in production unless you are ready to wear API adjustments.

Fields

tables: Vec<Table>

Table entries forming the cube (rectangular prism)

n_rows: Vec<usize>

Number of rows in each table

name: String

Cube name

third_dim_index: Option<Vec<String>>

Implementations

impl Cube

pub fn new( name: String, cols: Option<Vec<FieldArray>>, third_dim_index: Option<Vec<String>>, ) -> Self

Constructs a new Cube with a specified name and optional set of columns. If cols is provided, the columns are used to create the first table. The number of rows will be inferred from the first column. If the name is empty or whitespace, a unique default name is assigned. If no columns are provided, the Cube will be empty.

Examples found in repository

examples/broadcasting/test_broadcasting.rs (line 417)

fn test_cube_broadcasting() {
    #[cfg(feature = "cube")]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("│  Operation: Cube{{2 tables}} + Cube{{2 tables}}");
        println!("│  Expected:  Element-wise addition across all tables");

        // Create first cube with 2 tables
        // First, create columns for table 1
        let t1_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![1, 2]));
        let t1_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![3, 4]));
        let t1_fa1 = minarrow::FieldArray::from_arr("col1", t1_arr1);
        let t1_fa2 = minarrow::FieldArray::from_arr("col2", t1_arr2);

        // Create columns for cube1 via constructor
        let mut cube1 = Cube::new("cube1".to_string(), Some(vec![t1_fa1, t1_fa2]), None);

        // Add second table to cube1
        let t2_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![5, 6]));
        let t2_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![7, 8]));
        let t2_fa1 = minarrow::FieldArray::from_arr("col1", t2_arr1);
        let t2_fa2 = minarrow::FieldArray::from_arr("col2", t2_arr2);
        let mut table2 = Table::new("t2".to_string(), None);
        table2.add_col(t2_fa1);
        table2.add_col(t2_fa2);
        cube1.add_table(table2);

        // Create second cube
        let t3_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![10, 10]));
        let t3_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![20, 20]));
        let t3_fa1 = minarrow::FieldArray::from_arr("col1", t3_arr1);
        let t3_fa2 = minarrow::FieldArray::from_arr("col2", t3_arr2);
        let mut cube2 = Cube::new("cube2".to_string(), Some(vec![t3_fa1, t3_fa2]), None);

        let t4_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![30, 30]));
        let t4_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![40, 40]));
        let t4_fa1 = minarrow::FieldArray::from_arr("col1", t4_arr1);
        let t4_fa2 = minarrow::FieldArray::from_arr("col2", t4_arr2);
        let mut table4 = Table::new("t4".to_string(), None);
        table4.add_col(t4_fa1);
        table4.add_col(t4_fa2);
        cube2.add_table(table4);

        match Value::Cube(Arc::new(cube1)) + Value::Cube(Arc::new(cube2)) {
            Ok(Value::Cube(result)) => {
                println!("│  Result cube with {} tables:", result.n_tables());
                for i in 0..result.n_tables() {
                    println!("│  Table {}:", i);
                    if let Some(table) = result.table(i) {
                        for j in 0..table.n_cols() {
                            let col = &table.cols[j];
                            if let Array::NumericArray(NumericArray::Int32(arr)) = &col.array {
                                println!("│    Column {}: {:?}", j, arr.data.as_slice());
                            }
                        }
                    }
                }
                println!("└─ ✓ Passed\n");
            }
            Ok(other) => println!("└─ ✗ Error: Unexpected result type {:?}\n", other),
            Err(e) => println!("└─ ✗ Error: {:?}\n", e),
        }
    }

    #[cfg(not(feature = "cube"))]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("└─ ⊘ Skipped (cube feature not enabled)\n");
    }
}

pub fn new_empty() -> Self

Constructs a new, empty Cube with a globally unique name.

pub fn add_table(&mut self, table: Table)

Adds a table to the cube.

Examples found in repository

examples/broadcasting/test_broadcasting.rs (line 427)

fn test_cube_broadcasting() {
    #[cfg(feature = "cube")]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("│  Operation: Cube{{2 tables}} + Cube{{2 tables}}");
        println!("│  Expected:  Element-wise addition across all tables");

        // Create first cube with 2 tables
        // First, create columns for table 1
        let t1_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![1, 2]));
        let t1_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![3, 4]));
        let t1_fa1 = minarrow::FieldArray::from_arr("col1", t1_arr1);
        let t1_fa2 = minarrow::FieldArray::from_arr("col2", t1_arr2);

        // Create columns for cube1 via constructor
        let mut cube1 = Cube::new("cube1".to_string(), Some(vec![t1_fa1, t1_fa2]), None);

        // Add second table to cube1
        let t2_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![5, 6]));
        let t2_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![7, 8]));
        let t2_fa1 = minarrow::FieldArray::from_arr("col1", t2_arr1);
        let t2_fa2 = minarrow::FieldArray::from_arr("col2", t2_arr2);
        let mut table2 = Table::new("t2".to_string(), None);
        table2.add_col(t2_fa1);
        table2.add_col(t2_fa2);
        cube1.add_table(table2);

        // Create second cube
        let t3_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![10, 10]));
        let t3_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![20, 20]));
        let t3_fa1 = minarrow::FieldArray::from_arr("col1", t3_arr1);
        let t3_fa2 = minarrow::FieldArray::from_arr("col2", t3_arr2);
        let mut cube2 = Cube::new("cube2".to_string(), Some(vec![t3_fa1, t3_fa2]), None);

        let t4_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![30, 30]));
        let t4_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![40, 40]));
        let t4_fa1 = minarrow::FieldArray::from_arr("col1", t4_arr1);
        let t4_fa2 = minarrow::FieldArray::from_arr("col2", t4_arr2);
        let mut table4 = Table::new("t4".to_string(), None);
        table4.add_col(t4_fa1);
        table4.add_col(t4_fa2);
        cube2.add_table(table4);

        match Value::Cube(Arc::new(cube1)) + Value::Cube(Arc::new(cube2)) {
            Ok(Value::Cube(result)) => {
                println!("│  Result cube with {} tables:", result.n_tables());
                for i in 0..result.n_tables() {
                    println!("│  Table {}:", i);
                    if let Some(table) = result.table(i) {
                        for j in 0..table.n_cols() {
                            let col = &table.cols[j];
                            if let Array::NumericArray(NumericArray::Int32(arr)) = &col.array {
                                println!("│    Column {}: {:?}", j, arr.data.as_slice());
                            }
                        }
                    }
                }
                println!("└─ ✓ Passed\n");
            }
            Ok(other) => println!("└─ ✗ Error: Unexpected result type {:?}\n", other),
            Err(e) => println!("└─ ✗ Error: {:?}\n", e),
        }
    }

    #[cfg(not(feature = "cube"))]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("└─ ⊘ Skipped (cube feature not enabled)\n");
    }
}

pub fn schema(&self) -> Vec<Arc<Field>>

Gets the schemea from the first table as representative of the rest

pub fn n_tables(&self) -> usize

Returns the number of tables.

Examples found in repository

examples/broadcasting/test_broadcasting.rs (line 447)

fn test_cube_broadcasting() {
    #[cfg(feature = "cube")]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("│  Operation: Cube{{2 tables}} + Cube{{2 tables}}");
        println!("│  Expected:  Element-wise addition across all tables");

        // Create first cube with 2 tables
        // First, create columns for table 1
        let t1_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![1, 2]));
        let t1_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![3, 4]));
        let t1_fa1 = minarrow::FieldArray::from_arr("col1", t1_arr1);
        let t1_fa2 = minarrow::FieldArray::from_arr("col2", t1_arr2);

        // Create columns for cube1 via constructor
        let mut cube1 = Cube::new("cube1".to_string(), Some(vec![t1_fa1, t1_fa2]), None);

        // Add second table to cube1
        let t2_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![5, 6]));
        let t2_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![7, 8]));
        let t2_fa1 = minarrow::FieldArray::from_arr("col1", t2_arr1);
        let t2_fa2 = minarrow::FieldArray::from_arr("col2", t2_arr2);
        let mut table2 = Table::new("t2".to_string(), None);
        table2.add_col(t2_fa1);
        table2.add_col(t2_fa2);
        cube1.add_table(table2);

        // Create second cube
        let t3_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![10, 10]));
        let t3_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![20, 20]));
        let t3_fa1 = minarrow::FieldArray::from_arr("col1", t3_arr1);
        let t3_fa2 = minarrow::FieldArray::from_arr("col2", t3_arr2);
        let mut cube2 = Cube::new("cube2".to_string(), Some(vec![t3_fa1, t3_fa2]), None);

        let t4_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![30, 30]));
        let t4_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![40, 40]));
        let t4_fa1 = minarrow::FieldArray::from_arr("col1", t4_arr1);
        let t4_fa2 = minarrow::FieldArray::from_arr("col2", t4_arr2);
        let mut table4 = Table::new("t4".to_string(), None);
        table4.add_col(t4_fa1);
        table4.add_col(t4_fa2);
        cube2.add_table(table4);

        match Value::Cube(Arc::new(cube1)) + Value::Cube(Arc::new(cube2)) {
            Ok(Value::Cube(result)) => {
                println!("│  Result cube with {} tables:", result.n_tables());
                for i in 0..result.n_tables() {
                    println!("│  Table {}:", i);
                    if let Some(table) = result.table(i) {
                        for j in 0..table.n_cols() {
                            let col = &table.cols[j];
                            if let Array::NumericArray(NumericArray::Int32(arr)) = &col.array {
                                println!("│    Column {}: {:?}", j, arr.data.as_slice());
                            }
                        }
                    }
                }
                println!("└─ ✓ Passed\n");
            }
            Ok(other) => println!("└─ ✗ Error: Unexpected result type {:?}\n", other),
            Err(e) => println!("└─ ✗ Error: {:?}\n", e),
        }
    }

    #[cfg(not(feature = "cube"))]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("└─ ⊘ Skipped (cube feature not enabled)\n");
    }
}

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

Returns the number of rows

pub fn n_cols(&self) -> usize

Returns the number of columns.

pub fn is_empty(&self) -> bool

Returns true if the cube is empty (no tables, no columns or no rows).

pub fn table(&self, idx: usize) -> Option<&Table>

Returns a reference to a table by index.

Examples found in repository

examples/broadcasting/test_broadcasting.rs (line 450)

fn test_cube_broadcasting() {
    #[cfg(feature = "cube")]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("│  Operation: Cube{{2 tables}} + Cube{{2 tables}}");
        println!("│  Expected:  Element-wise addition across all tables");

        // Create first cube with 2 tables
        // First, create columns for table 1
        let t1_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![1, 2]));
        let t1_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![3, 4]));
        let t1_fa1 = minarrow::FieldArray::from_arr("col1", t1_arr1);
        let t1_fa2 = minarrow::FieldArray::from_arr("col2", t1_arr2);

        // Create columns for cube1 via constructor
        let mut cube1 = Cube::new("cube1".to_string(), Some(vec![t1_fa1, t1_fa2]), None);

        // Add second table to cube1
        let t2_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![5, 6]));
        let t2_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![7, 8]));
        let t2_fa1 = minarrow::FieldArray::from_arr("col1", t2_arr1);
        let t2_fa2 = minarrow::FieldArray::from_arr("col2", t2_arr2);
        let mut table2 = Table::new("t2".to_string(), None);
        table2.add_col(t2_fa1);
        table2.add_col(t2_fa2);
        cube1.add_table(table2);

        // Create second cube
        let t3_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![10, 10]));
        let t3_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![20, 20]));
        let t3_fa1 = minarrow::FieldArray::from_arr("col1", t3_arr1);
        let t3_fa2 = minarrow::FieldArray::from_arr("col2", t3_arr2);
        let mut cube2 = Cube::new("cube2".to_string(), Some(vec![t3_fa1, t3_fa2]), None);

        let t4_arr1 = Array::from_int32(IntegerArray::from_slice(&vec64![30, 30]));
        let t4_arr2 = Array::from_int32(IntegerArray::from_slice(&vec64![40, 40]));
        let t4_fa1 = minarrow::FieldArray::from_arr("col1", t4_arr1);
        let t4_fa2 = minarrow::FieldArray::from_arr("col2", t4_arr2);
        let mut table4 = Table::new("t4".to_string(), None);
        table4.add_col(t4_fa1);
        table4.add_col(t4_fa2);
        cube2.add_table(table4);

        match Value::Cube(Arc::new(cube1)) + Value::Cube(Arc::new(cube2)) {
            Ok(Value::Cube(result)) => {
                println!("│  Result cube with {} tables:", result.n_tables());
                for i in 0..result.n_tables() {
                    println!("│  Table {}:", i);
                    if let Some(table) = result.table(i) {
                        for j in 0..table.n_cols() {
                            let col = &table.cols[j];
                            if let Array::NumericArray(NumericArray::Int32(arr)) = &col.array {
                                println!("│    Column {}: {:?}", j, arr.data.as_slice());
                            }
                        }
                    }
                }
                println!("└─ ✓ Passed\n");
            }
            Ok(other) => println!("└─ ✗ Error: Unexpected result type {:?}\n", other),
            Err(e) => println!("└─ ✗ Error: {:?}\n", e),
        }
    }

    #[cfg(not(feature = "cube"))]
    {
        println!("┌─ Test 12: Cube (3D) Broadcasting");
        println!("└─ ⊘ Skipped (cube feature not enabled)\n");
    }
}

pub fn table_mut(&mut self, idx: usize) -> Option<&mut Table>

Returns a mutable reference to a table by index.

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

Returns the names of all tables in the cube.

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

Returns the index of a table by name.

pub fn has_table(&self, name: &str) -> bool

Checks if a table with the given name exists.

pub fn remove_table_at(&mut self, idx: usize) -> bool

Removes a table by index.

pub fn remove_table(&mut self, name: &str) -> bool

Removes a table by name.

pub fn clear(&mut self)

Clears all tables and resets row counts.

pub fn tables(&self) -> &[Table]

Returns an immutable reference to all tables.

pub fn tables_mut(&mut self) -> &mut [Table]

Returns a mutable reference to all tables.

pub fn iter_tables(&self) -> Iter<'_, Table>

Returns an iterator over all tables.

pub fn iter_tables_mut(&mut self) -> IterMut<'_, Table>

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

Returns the list of column names (from the first table).

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

Returns the index of a column by name (from the first table).

pub fn has_col(&self, name: &str) -> bool

Returns true if the cube has a column of the given name (in all tables).

pub fn col(&self, idx: usize) -> Option<Vec<&FieldArray>>

Returns all columns (FieldArrays) with the given index across all tables.

pub fn col_by_name(&self, name: &str) -> Option<Vec<&FieldArray>>

Returns all columns (FieldArrays) with the given name across all tables.

pub fn cols(&self) -> Vec<Vec<&FieldArray>>

Returns all columns for all tables as Vec<Vec<&FieldArray>>.

pub fn remove_col(&mut self, name: &str) -> bool

Removes a column by name from all tables. Returns true if removed from all.

pub fn remove_col_at(&mut self, idx: usize) -> bool

Removes a column by index from all tables. Returns true if removed from all.

pub fn iter_cols( &self, col_idx: usize, ) -> Option<impl Iterator<Item = &FieldArray>>

Returns an iterator over the specified column across all tables.

pub fn iter_cols_by_name<'a>( &'a self, name: &'a str, ) -> Option<impl Iterator<Item = &'a FieldArray> + 'a>

Returns an iterator over the named column across all tables.

pub fn set_third_dim_index<S: Into<String>>(&mut self, cols: Vec<S>)

Sets the third dimensional index

pub fn third_dim_index(&self) -> Option<&[String]>

Retrieves the third dimensional index

pub fn slice_clone(&self, offset: usize, len: usize) -> Self

Returns a new owned Cube containing rows [offset, offset+len) for all tables.

pub fn slice(&self, offset: usize, len: usize) -> CubeV

Returns a zero-copy view over rows [offset, offset+len) for all tables.

pub fn par_iter_tables(&self) -> Iter<'_, Table>

Returns a parallel iterator over all tables.

pub fn par_iter_tables_mut(&mut self) -> IterMut<'_, Table>

Returns a parallel mutable iterator over all tables.

Trait Implementations

impl Add for Cube

Available on crate feature cube only.

type Output = Result<Cube, MinarrowError>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl ByteSize for Cube

Available on crate feature cube only.

fn est_bytes(&self) -> usize

Returns the estimated byte size of this object in memory.

impl Clone for Cube

fn clone(&self) -> Cube

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Concatenate for Cube

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

Concatenates two cubes by appending all tables from other to self.

Requirements

• Both cubes must have the same schema (column names and types)

Returns

A new Cube containing all tables from self followed by all tables from other

Errors

• IncompatibleTypeError if schemas don’t match

impl Debug for Cube

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

Formats the value using the given formatter.

impl Default for Cube

fn default() -> Cube

Returns the “default value” for a type.

impl Div for Cube

Available on crate feature cube only.

type Output = Result<Cube, MinarrowError>

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl From<Cube> for Value

Available on crate feature cube only.

fn from(v: Cube) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Cube

type Item = &'a Table

The type of the elements being iterated over.

type IntoIter = Iter<'a, Table>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Cube

type Item = &'a mut Table

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Table>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Cube

type Item = Table

The type of the elements being iterated over.

type IntoIter = <Vec<Table> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Mul for Cube

Available on crate feature cube only.

type Output = Result<Cube, MinarrowError>

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl PartialEq for Cube

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Rem for Cube

Available on crate feature cube only.

type Output = Result<Cube, MinarrowError>

The resulting type after applying the % operator.

fn rem(self, rhs: Self) -> Self::Output

Performs the % operation.

impl Shape for Cube

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 Sub for Cube

Available on crate feature cube only.

type Output = Result<Cube, MinarrowError>

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl TryFrom<Value> for Cube

Available on crate feature cube only.

type Error = MinarrowError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl StructuralPartialEq for Cube