Crate rustframe

Source
Expand description

§rustframe

🐙 GitHub | 📚 Docs | 📖 User Guide | 🦀 Crates.io | 🔖 docs.rs

codecov Coverage gitea-mirror

§Rustframe: A lightweight dataframe & math toolkit for Rust

Rustframe provides intuitive dataframe, matrix, and series operations for data analysis and manipulation.

Rustframe keeps things simple, safe, and readable. It is handy for quick numeric experiments and small analytical tasks as well as for educational purposes. It is designed to be easy to use and understand, with a clean API implemented in 100% safe Rust.

Rustframe is an educational project, and is not intended for production use. It is not meant to compete with powerhouse crates like polars or ndarray. It is a work in progress, and the API is subject to change. There are no guarantees of stability or performance, and it is not optimized for large datasets or high-performance computing.

§What it offers

  • Matrix operations - Element-wise arithmetic, boolean logic, transpose, and more.
  • Math that reads like math - element-wise +, −, ×, ÷ on entire frames or scalars.
  • Frames - Column major data structure for single-type data, with labeled columns and typed row indices.
  • Compute module - Implements various statistical computations and machine learning models.
  • Random number utils - Built-in pseudo and cryptographically secure generators for simulations.
  • [Coming Soon] DataFrame - Multi-type data structure for heterogeneous data, with labeled columns and typed row indices.
§Matrix and Frame functionality
  • Matrix operations - Element-wise arithmetic, boolean logic, transpose, and more.
  • Frame operations - Column manipulation, sorting, and more.
§Compute Module

The compute module provides implementations for various statistical computations and machine learning models.

Statistics, Data Analysis, and Machine Learning:

  • Correlation analysis

  • Descriptive statistics

  • Distributions

  • Inferential statistics

  • Dense Neural Networks

  • Gaussian Naive Bayes

  • K-Means Clustering

  • Linear Regression

  • Logistic Regression

  • Principal Component Analysis

§Heads up

  • Not memory‑efficient (yet) - footprint needs work.
  • The feature set is still limited - expect missing pieces.

§Somewhere down the line

  • Optional GPU acceleration (Vulkan or similar) for heavier workloads.
  • Straightforward Python bindings using pyo3.

§Quick start

use chrono::NaiveDate;
use rustframe::{
    frame::{Frame, RowIndex},
    matrix::{BoolOps, Matrix, SeriesOps},
    utils::{DateFreq, BDatesList},
};

let n_periods = 4;

// Four business days starting 2024-01-02
let dates: Vec<NaiveDate> =
    BDatesList::from_n_periods("2024-01-02".to_string(), DateFreq::Daily, n_periods)
        .unwrap()
        .list().unwrap();

let col_names: Vec<String> = vec!["a".to_string(), "b".to_string()];

let ma: Matrix<f64> =
    Matrix::from_cols(vec![vec![1.0, 2.0, 3.0, 4.0], vec![5.0, 6.0, 7.0, 8.0]]);
let mb: Matrix<f64> =
    Matrix::from_cols(vec![vec![4.0, 3.0, 2.0, 1.0], vec![8.0, 7.0, 6.0, 5.0]]);

let fa: Frame<f64> = Frame::new(
    ma.clone(),
    col_names.clone(),
    Some(RowIndex::Date(dates.clone())),
);
let fb: Frame<f64> = Frame::new(mb, col_names, Some(RowIndex::Date(dates)));

// Math that reads like math
let result: Frame<f64> = &fa * &fb; // element‑wise multiply
let total: f64 = result.sum_vertical().iter().sum::<f64>();
assert_eq!(total, 184.0);

// broadcast & reduce
let result: Matrix<f64> = ma.clone() + 1.0; // add scalar
let result: Matrix<f64> = result + &ma - &ma; // add matrix
let result: Matrix<f64> = result - 1.0; // subtract scalar
let result: Matrix<f64> = result * 2.0; // multiply by scalar
let result: Matrix<f64> = result / 2.0; // divide by scalar

let check: bool = result.eq_elem(ma.clone()).all();
assert!(check);

// Alternatively:
let check: bool = (&(&(&(&ma + 1.0) - 1.0) * 2.0) / 2.0)
    .eq_elem(ma.clone())
    .all();
assert!(check);

// or even as:
let check: bool = ((((ma.clone() + 1.0) - 1.0) * 2.0) / 2.0)
    .eq_elem(ma.clone())
    .all();
assert!(check);

// Matrix multiplication
let mc: Matrix<f64> = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]);
let md: Matrix<f64> = Matrix::from_cols(vec![vec![5.0, 6.0], vec![7.0, 8.0]]);
let mul_result: Matrix<f64> = mc.matrix_mul(&md);
// Expected:
assert_eq!(mul_result.data(), &[23.0, 34.0, 31.0, 46.0]);

// Dot product (alias for matrix_mul for FloatMatrix)
let dot_result: Matrix<f64> = mc.dot(&md);
assert_eq!(dot_result, mul_result);

// Transpose
let original_matrix: Matrix<f64> = Matrix::from_cols(vec![vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0]]);
let transposed_matrix: Matrix<f64> = original_matrix.transpose();
assert_eq!(transposed_matrix.rows(), 2);
assert_eq!(transposed_matrix.cols(), 3);
assert_eq!(transposed_matrix.data(), &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);

// Map
let matrix = Matrix::from_cols(vec![vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0]]);
// Map function to double each value
let mapped_matrix = matrix.map(|x| x * 2.0);
assert_eq!(mapped_matrix.data(), &[2.0, 4.0, 6.0, 8.0, 10.0, 12.0]);

// Zip
let a = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); // 2x2 matrix
let b = Matrix::from_cols(vec![vec![5.0, 6.0], vec![7.0, 8.0]]); // 2x2 matrix
                                                                   // Zip function to add corresponding elements
let zipped_matrix = a.zip(&b, |x, y| x + y);
assert_eq!(zipped_matrix.data(), &[6.0, 8.0, 10.0, 12.0]);

§More examples

See the examples directory for some demonstrations of Rustframe’s syntax and functionality.

To run the examples, use:

cargo run --example <example_name>

E.g. to run the game_of_life example:

cargo run --example game_of_life

More demos:

cargo run --example linear_regression
cargo run --example logistic_regression
cargo run --example k_means
cargo run --example pca
cargo run --example stats_overview
cargo run --example descriptive_stats
cargo run --example correlation
cargo run --example inferential_stats
cargo run --example distributions

To simply list all available examples, you can run:

# this technically raises an error, but it will list all examples
cargo run --example

Each demo runs a couple of mini-scenarios showcasing the APIs.

§Running benchmarks

To run the benchmarks, use:

cargo bench --features "bench"

§Building the user-guide

To build the user guide, use:

cargo binstall mdbook
bash docs/build.sh

This will generate the user guide in the docs/book directory.

Modules§

compute
Documentation for the crate::compute module. Algorithms and statistical utilities built on top of the core matrices.
frame
Documentation for the crate::frame module. High-level interface for working with columnar data and row indices.
matrix
Documentation for the crate::matrix module. Core matrix types and operations.
random
Documentation for the crate::random module. Random number generation utilities.
utils
Documentation for the crate::utils module. Assorted helper utilities.