Struct FeatureMatrix 

pub struct FeatureMatrix { /* private fields */ }

A feature matrix optimized for column-wise access in machine learning.

FeatureMatrix stores data in column-major format using ndarray::Array2, making feature extraction efficient for algorithms that process columns repeatedly. This is particularly beneficial for decision trees during split finding.

Invariants

• n_samples > 0 && n_features > 0
• feature_names.len() == n_features
• All data values are finite (validated at construction)

Thread Safety

Cloning creates a new copy of the data; the struct is not designed for shared mutable access. Use immutable references or ownership passing.

Implementations

impl FeatureMatrix

pub fn new(data: Array2<f64>) -> Result<Self, FeatureMatrixError>

Creates a new feature matrix with auto-generated names.

Generates feature names in the format “feature_0”, “feature_1”, etc.

Parameters

• data: 2D array with shape (n_samples, n_features)

Returns

Ok(FeatureMatrix) if validation passes

Errors

• FeatureMatrixError::InvalidShape if data has zero rows or columns

pub fn with_feature_names( data: Array2<f64>, feature_names: Vec<String>, ) -> Result<Self, FeatureMatrixError>

Creates a new feature matrix with custom feature names.

Parameters

• data: 2D array with shape (n_samples, n_features)
• feature_names: Vector of names, one per column

Returns

Ok(FeatureMatrix) if validation passes

Errors

• FeatureMatrixError::InvalidShape if data has zero rows or columns
• FeatureMatrixError::InvalidShape if feature_names length doesn’t match columns

pub fn n_samples(&self) -> usize

Returns the number of samples (rows) in the matrix.

pub fn n_features(&self) -> usize

Returns the number of features (columns) in the matrix.

pub fn shape(&self) -> (usize, usize)

Returns the shape as (n_samples, n_features).

pub fn data(&self) -> &Array2<f64>

Returns a reference to the underlying data array.

pub fn feature_names(&self) -> &[String]

Returns a slice of feature names.

pub fn get_feature( &self, feature_idx: usize, ) -> Result<ArrayView1<'_, f64>, FeatureMatrixError>

Gets a column view for a specific feature.

Parameters

• feature_idx: Zero-based column index

Returns

Array view of shape (n_samples,)

Errors

• FeatureMatrixError::FeatureIndexOutOfBounds if index >= n_features

pub fn get_sample( &self, sample_idx: usize, ) -> Result<ArrayView1<'_, f64>, FeatureMatrixError>

Gets a row view for a specific sample.

Parameters

• sample_idx: Zero-based row index

Returns

Array view of shape (n_features,)

Errors

• FeatureMatrixError::SampleIndexOutOfBounds if index >= n_samples

pub fn get( &self, sample_idx: usize, feature_idx: usize, ) -> Result<f64, FeatureMatrixError>

Gets a single element at (sample_idx, feature_idx).

Parameters

• sample_idx: Row index
• feature_idx: Column index

Returns

The scalar value at that position

Errors

• FeatureMatrixError::SampleIndexOutOfBounds if sample_idx >= n_samples
• FeatureMatrixError::FeatureIndexOutOfBounds if feature_idx >= n_features

pub fn view(&self) -> ArrayView2<'_, f64>

Gets a view of the entire matrix.

Useful for passing to ndarray-based algorithms.

pub fn samples(&self) -> impl Iterator<Item = ArrayView1<'_, f64>> + '_

Returns an iterator over samples (rows).

Each iteration yields a view of shape (n_features,).

pub fn features(&self) -> impl Iterator<Item = ArrayView1<'_, f64>> + '_

Returns an iterator over features (columns).

Each iteration yields a view of shape (n_samples,). This is cache-friendly due to column-major storage.

pub fn feature_ranges(&self) -> Vec<(f64, f64)>

Computes the min and max range for each feature.

Useful for decision tree split finding and feature scaling.

Returns

Vector of (min, max) tuples, one per feature

pub fn feature_means(&self) -> Vec<f64>

Computes the mean of each feature.

Useful for imputation and model initialization.

Returns

Vector of means, one per feature

pub fn select_samples( &self, sample_indices: &[usize], ) -> Result<Self, FeatureMatrixError>

Creates a submatrix with selected samples (rows).

Parameters

• sample_indices: Row indices to include in the subset

Returns

New FeatureMatrix containing only selected rows

Errors

• FeatureMatrixError::SampleIndexOutOfBounds if any index >= n_samples

pub fn select_features( &self, feature_indices: &[usize], ) -> Result<Self, FeatureMatrixError>

Creates a submatrix with selected features (columns).

Parameters

• feature_indices: Column indices to include in the subset

Returns

New FeatureMatrix containing only selected columns

Errors

• FeatureMatrixError::FeatureIndexOutOfBounds if any index >= n_features

pub fn from_csv<P: AsRef<Path>>(path: P) -> Result<Self, FeatureMatrixError>

Loads a feature matrix from a CSV file.

Parameters

• path: Path to CSV file with headers

Returns

FeatureMatrix with data and column names

Errors

• FeatureMatrixError::CsvError if CSV parsing fails
• FeatureMatrixError::IoError if file cannot be read
• FeatureMatrixError::InvalidShape if file is empty

CSV Format

• First row: column headers (become feature names)
• Subsequent rows: numeric data (NaN for missing values)

Trait Implementations

impl Clone for FeatureMatrix

fn clone(&self) -> FeatureMatrix

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FeatureMatrix

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for FeatureMatrix

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for FeatureMatrix

Equality comparison for feature matrices.

Two matrices are equal if they have:

• Identical underlying data (element-wise)
• Same feature names (in same order)

fn eq(&self, other: &Self) -> 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 Serialize for FeatureMatrix

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.