From 9738154dacbd6d4c1ef2d613d5cf683dbf17a166 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:07:18 +0100 Subject: [PATCH 01/23] Add user guide examples --- docs/src/SUMMARY.md | 7 ++++++ docs/src/compute.md | 31 +++++++++++++++++++++++++ docs/src/data-manipulation.md | 43 +++++++++++++++++++++++++++++++++++ docs/src/introduction.md | 15 ++++++++++++ docs/src/machine-learning.md | 39 +++++++++++++++++++++++++++++++ docs/src/utilities.md | 24 +++++++++++++++++++ 6 files changed, 159 insertions(+) create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/compute.md create mode 100644 docs/src/data-manipulation.md create mode 100644 docs/src/introduction.md create mode 100644 docs/src/machine-learning.md create mode 100644 docs/src/utilities.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..4479e5d --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +- [Introduction](./introduction.md) +- [Data Manipulation](./data-manipulation.md) +- [Compute Features](./compute.md) +- [Machine Learning](./machine-learning.md) +- [Utilities](./utilities.md) diff --git a/docs/src/compute.md b/docs/src/compute.md new file mode 100644 index 0000000..33b9d6e --- /dev/null +++ b/docs/src/compute.md @@ -0,0 +1,31 @@ +# Compute Features + +The `compute` module provides statistical routines like descriptive +statistics and correlation measures. + +## Basic Statistics + +```rust +# extern crate rustframe; +use rustframe::compute::stats::{mean, stddev}; +use rustframe::matrix::Matrix; + +let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2); +let mean_val = mean(&m); +let std_val = stddev(&m); +``` + +## Correlation + +```rust +# extern crate rustframe; +use rustframe::compute::stats::pearson; +use rustframe::matrix::Matrix; + +let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2); +let y = Matrix::from_vec(vec![2.0, 4.0, 6.0, 8.0], 2, 2); +let corr = pearson(&x, &y); +``` + +With the basics covered, explore predictive models in the +[machine learning](./machine-learning.md) chapter. diff --git a/docs/src/data-manipulation.md b/docs/src/data-manipulation.md new file mode 100644 index 0000000..34aa99c --- /dev/null +++ b/docs/src/data-manipulation.md @@ -0,0 +1,43 @@ +# Data Manipulation + +RustFrame's `Frame` type couples tabular data with +column labels and a typed row index. + +## Creating a Frame + +```rust +# extern crate rustframe; +use rustframe::frame::{Frame, RowIndex}; +use rustframe::matrix::Matrix; + +let data = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); +let frame = Frame::new(data, vec!["A", "B"], None); +assert_eq!(frame["A"], vec![1.0, 2.0]); +``` + +## Indexing Rows + +```rust +# extern crate rustframe; +use rustframe::frame::{Frame, RowIndex}; +use rustframe::matrix::Matrix; + +let data = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); +let index = RowIndex::Int(vec![10, 20]); +let frame = Frame::new(data, vec!["A", "B"], Some(index)); +assert_eq!(frame.get_row(20)["B"], 4.0); +``` + +## Aggregations + +```rust +# extern crate rustframe; +use rustframe::frame::Frame; +use rustframe::matrix::{Matrix, SeriesOps}; + +let frame = Frame::new(Matrix::from_cols(vec![vec![1.0, 2.0]]), vec!["A"], None); +assert_eq!(frame.sum_vertical(), vec![3.0]); +``` + +When you're ready to run analytics, continue to the +[compute features](./compute.md) chapter. diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 0000000..f3b49b6 --- /dev/null +++ b/docs/src/introduction.md @@ -0,0 +1,15 @@ +# Introduction + +Welcome to the **RustFrame User Guide**. This book provides a tour of +RustFrame's capabilities from basic data handling to advanced machine learning +workflows. Each chapter contains runnable snippets so you can follow along. + +To build this guide locally run `./build.sh` in the `docs/` directory. The +chapters are arranged sequentially: + +1. [Data manipulation](./data-manipulation.md) for loading and transforming data. +2. [Compute features](./compute.md) for statistics and analytics. +3. [Machine learning](./machine-learning.md) for predictive models. +4. [Utilities](./utilities.md) for supporting helpers and upcoming modules. + +Let's begin with some tabular data! diff --git a/docs/src/machine-learning.md b/docs/src/machine-learning.md new file mode 100644 index 0000000..1694da8 --- /dev/null +++ b/docs/src/machine-learning.md @@ -0,0 +1,39 @@ +# Machine Learning + +RustFrame ships with several algorithms: + +- Linear and logistic regression +- K-means clustering +- Principal component analysis (PCA) +- Naive Bayes and dense neural networks + +## Linear Regression + +```rust +# extern crate rustframe; +use rustframe::compute::models::linreg::LinReg; +use rustframe::matrix::Matrix; + +let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 4, 1); +let y = Matrix::from_vec(vec![2.0, 3.0, 4.0, 5.0], 4, 1); +let mut model = LinReg::new(1); +model.fit(&x, &y, 0.01, 100); +let preds = model.predict(&x); +assert_eq!(preds.rows(), 4); +``` + +## K-means Walkthrough + +```rust +# extern crate rustframe; +use rustframe::compute::models::k_means::KMeans; +use rustframe::matrix::Matrix; + +let data = Matrix::from_vec(vec![1.0, 1.0, 5.0, 5.0], 2, 2); +let (model, _labels) = KMeans::fit(&data, 2, 10, 1e-4); +let new_point = Matrix::from_vec(vec![0.0, 0.0], 1, 2); +let cluster = model.predict(&new_point)[0]; +``` + +For helper functions and upcoming modules, visit the +[utilities](./utilities.md) section. diff --git a/docs/src/utilities.md b/docs/src/utilities.md new file mode 100644 index 0000000..1bed694 --- /dev/null +++ b/docs/src/utilities.md @@ -0,0 +1,24 @@ +# Utilities + +Utilities provide handy helpers around the core library. Existing tools +include: + +- Date utilities for generating calendar sequences. + +## Date Helpers + +```rust +# extern crate rustframe; +use rustframe::utils::dateutils::{DatesList, DateFreq}; + +let list = DatesList::new("2024-01-01".into(), "2024-01-03".into(), DateFreq::Daily); +assert_eq!(list.count().unwrap(), 3); +``` + +Upcoming utilities will cover: + +- Data import/export helpers +- Visualization adapters +- Streaming data interfaces + +Contributions to these sections are welcome! From 9db8853d755ee45a6445fca2f3c545f302662605 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:07:32 +0100 Subject: [PATCH 02/23] Add user guide configuration and update .gitignore --- .gitignore | 4 +++- docs/book.toml | 7 +++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 docs/book.toml diff --git a/.gitignore b/.gitignore index ac6b27b..5198bcf 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,6 @@ data/ tarpaulin-report.* -.github/htmldocs/rustframe_logo.png \ No newline at end of file +.github/htmldocs/rustframe_logo.png + +docs/book/ \ No newline at end of file diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..2de58a0 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,7 @@ +[book] +title = "RustFrame User Guide" +author = ["RustFrame Contributors"] +description = "Guided journey through RustFrame capabilities." + +[build] +build-dir = "book" From b78dd75e77925514425d63198957fa0cb22e3345 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:07:38 +0100 Subject: [PATCH 03/23] Add build script for RustFrame user guide using mdBook --- docs/build.sh | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100755 docs/build.sh diff --git a/docs/build.sh b/docs/build.sh new file mode 100755 index 0000000..e67049f --- /dev/null +++ b/docs/build.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env sh +# Build and test the RustFrame user guide using mdBook. +set -e +# Ensure the library is compiled so examples can link against it. + +cargo clean + +cargo build --manifest-path ../Cargo.toml +# Run embedded code examples as tests. +mdbook test -L ../target/debug/deps "$@" +# Finally, render the book. +mdbook build "$@" + +cargo build +cargo build --release From 4876a74e01dc9f0b9bd6e968b68d260d8bbe10a8 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:11:10 +0100 Subject: [PATCH 04/23] Add user guide build and output steps to CI workflow --- .github/workflows/docs-and-testcov.yml | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index 3b40067..2ef211b 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -153,7 +153,6 @@ jobs: echo "" > target/doc/rustframe/index.html - mkdir output cp tarpaulin-report.html target/doc/docs/ cp tarpaulin-report.json target/doc/docs/ cp tarpaulin-badge.json target/doc/docs/ @@ -166,6 +165,20 @@ jobs: # copy the benchmark report to the output directory cp -r benchmark-report target/doc/ + mkdir output + cp -r target/doc/* output/ + + - name: Build user guide + run: | + cd docs + ./build.sh + cd .. + + - name: Copy user guide to output directory + run: | + mkdir -p target/doc/user-guide + cp -r docs/book/* target/doc/user-guide/ + - name: Add index.html to output directory run: | cp .github/htmldocs/index.html target/doc/index.html From ca2ca2a738583d15c7f5949445bbf0354d8d97fa Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:11:15 +0100 Subject: [PATCH 05/23] Add link to User Guide in the main index page --- .github/htmldocs/index.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/htmldocs/index.html b/.github/htmldocs/index.html index b39f850..85484c6 100644 --- a/.github/htmldocs/index.html +++ b/.github/htmldocs/index.html @@ -58,6 +58,10 @@

A lightweight dataframe & math toolkit for Rust

+ + đź“– User Guide +

+ 📚 Docs | 📊 Benchmarks From 676af850ef8b1a917890d09154f33e88a04c4424 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:13:25 +0100 Subject: [PATCH 06/23] Add step to test user guide build in CI workflow --- .github/workflows/run-unit-tests.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml index 0f4ae0b..6ddaade 100644 --- a/.github/workflows/run-unit-tests.yml +++ b/.github/workflows/run-unit-tests.yml @@ -78,3 +78,9 @@ jobs: uses: codecov/test-results-action@v1 with: token: ${{ secrets.CODECOV_TOKEN }} + + - name: Test build user guide + run: | + cd docs + ./build.sh + cd .. From a6a901d6ab72517bdcaa9d7f7beb50c4f56d277d Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 22:16:53 +0100 Subject: [PATCH 07/23] Add step to install mdBook for user guide build in CI workflows --- .github/workflows/docs-and-testcov.yml | 1 + .github/workflows/run-unit-tests.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index 2ef211b..15bebea 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -170,6 +170,7 @@ jobs: - name: Build user guide run: | + cargo binstall mdbook -q cd docs ./build.sh cd .. diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml index 6ddaade..b62f02a 100644 --- a/.github/workflows/run-unit-tests.yml +++ b/.github/workflows/run-unit-tests.yml @@ -81,6 +81,7 @@ jobs: - name: Test build user guide run: | + cargo binstall mdbook -q cd docs ./build.sh cd .. From b62152b4f0ca8656401a28d35d826e9f3a8be550 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:01:54 +0100 Subject: [PATCH 08/23] Update output directory for user guide and artifact upload in CI workflow --- .github/workflows/docs-and-testcov.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index 15bebea..b08ce59 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -178,7 +178,7 @@ jobs: - name: Copy user guide to output directory run: | mkdir -p target/doc/user-guide - cp -r docs/book/* target/doc/user-guide/ + cp -r docs/book/* output/user-guide/ - name: Add index.html to output directory run: | @@ -189,7 +189,8 @@ jobs: # if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' uses: actions/upload-pages-artifact@v3 with: - path: target/doc/ + # path: target/doc/ + path: output/ - name: Deploy to GitHub Pages # if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' From 1dcd9727b4ad4021098e8e4b688ace2427501d62 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:15:54 +0100 Subject: [PATCH 09/23] Update output directory structure for user guide and index files --- .github/workflows/docs-and-testcov.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index b08ce59..7f15bfc 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -177,13 +177,13 @@ jobs: - name: Copy user guide to output directory run: | - mkdir -p target/doc/user-guide + mkdir output/user-guide cp -r docs/book/* output/user-guide/ - name: Add index.html to output directory run: | - cp .github/htmldocs/index.html target/doc/index.html - cp .github/rustframe_logo.png target/doc/rustframe_logo.png + cp .github/htmldocs/index.html output/index.html + cp .github/rustframe_logo.png output/rustframe_logo.png - name: Upload Pages artifact # if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' From 3654c7053c0b7094d02d1ee28dc581c9c8f87247 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:23:10 +0100 Subject: [PATCH 10/23] Refactor build process --- docs/build.sh | 14 +++----------- docs/gen.sh | 14 ++++++++++++++ 2 files changed, 17 insertions(+), 11 deletions(-) create mode 100644 docs/gen.sh diff --git a/docs/build.sh b/docs/build.sh index e67049f..0e109ac 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -1,15 +1,7 @@ #!/usr/bin/env sh # Build and test the RustFrame user guide using mdBook. set -e -# Ensure the library is compiled so examples can link against it. -cargo clean - -cargo build --manifest-path ../Cargo.toml -# Run embedded code examples as tests. -mdbook test -L ../target/debug/deps "$@" -# Finally, render the book. -mdbook build "$@" - -cargo build -cargo build --release +cd docs +bash gen.sh "$@" +cd .. \ No newline at end of file diff --git a/docs/gen.sh b/docs/gen.sh new file mode 100644 index 0000000..b49d4ec --- /dev/null +++ b/docs/gen.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env sh + +set -e + +cargo clean + +cargo build --manifest-path ../Cargo.toml + +mdbook test -L ../target/debug/deps "$@" + +mdbook build "$@" + +cargo build +cargo build --release From c7552f2264d9014f126ef0663296495550e1f96b Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:24:54 +0100 Subject: [PATCH 11/23] Simplify user guide build steps in CI workflows --- .github/workflows/docs-and-testcov.yml | 6 ++---- .github/workflows/run-unit-tests.yml | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index 7f15bfc..9787e59 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -170,10 +170,8 @@ jobs: - name: Build user guide run: | - cargo binstall mdbook -q - cd docs - ./build.sh - cd .. + cargo binstall mdbook + bash ./build.sh - name: Copy user guide to output directory run: | diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml index b62f02a..43e7a5c 100644 --- a/.github/workflows/run-unit-tests.yml +++ b/.github/workflows/run-unit-tests.yml @@ -81,7 +81,5 @@ jobs: - name: Test build user guide run: | - cargo binstall mdbook -q - cd docs - ./build.sh - cd .. + cargo binstall mdbook + bash ./build.sh From ae27ed93737af941d879b3d100eac2b2991c1276 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:25:13 +0100 Subject: [PATCH 12/23] Add instructions for building the user guide --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index fd6123c..5b0f859 100644 --- a/README.md +++ b/README.md @@ -198,3 +198,13 @@ To run the benchmarks, use: ```bash cargo bench --features "bench" ``` + +## Building the user-guide + +To build the user guide, use: + +```bash +cargo binstall mdbook +bash docs/build.sh +``` +This will generate the user guide in the `docs/book` directory. From 83ac9d4821ed0b706048d8fee3f20644e672e2e0 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:25:17 +0100 Subject: [PATCH 13/23] Remove local build instructions from the introduction of the user guide --- docs/src/introduction.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/src/introduction.md b/docs/src/introduction.md index f3b49b6..80a43e7 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -4,12 +4,7 @@ Welcome to the **RustFrame User Guide**. This book provides a tour of RustFrame's capabilities from basic data handling to advanced machine learning workflows. Each chapter contains runnable snippets so you can follow along. -To build this guide locally run `./build.sh` in the `docs/` directory. The -chapters are arranged sequentially: - 1. [Data manipulation](./data-manipulation.md) for loading and transforming data. 2. [Compute features](./compute.md) for statistics and analytics. 3. [Machine learning](./machine-learning.md) for predictive models. 4. [Utilities](./utilities.md) for supporting helpers and upcoming modules. - -Let's begin with some tabular data! From ae327b60608211d756067fb6466ba9f089b7abe3 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:28:03 +0100 Subject: [PATCH 14/23] Update user guide build script path in CI workflows --- .github/workflows/docs-and-testcov.yml | 2 +- .github/workflows/run-unit-tests.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-and-testcov.yml b/.github/workflows/docs-and-testcov.yml index 9787e59..38e2914 100644 --- a/.github/workflows/docs-and-testcov.yml +++ b/.github/workflows/docs-and-testcov.yml @@ -171,7 +171,7 @@ jobs: - name: Build user guide run: | cargo binstall mdbook - bash ./build.sh + bash ./docs/build.sh - name: Copy user guide to output directory run: | diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml index 43e7a5c..8bdf3f3 100644 --- a/.github/workflows/run-unit-tests.yml +++ b/.github/workflows/run-unit-tests.yml @@ -82,4 +82,4 @@ jobs: - name: Test build user guide run: | cargo binstall mdbook - bash ./build.sh + bash ./docs/build.sh From ecd06eb352a400bf63b55589a1090e760ec3a605 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Sun, 3 Aug 2025 23:28:19 +0100 Subject: [PATCH 15/23] update format in README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 5b0f859..c3b87c1 100644 --- a/README.md +++ b/README.md @@ -207,4 +207,5 @@ To build the user guide, use: cargo binstall mdbook bash docs/build.sh ``` + This will generate the user guide in the `docs/book` directory. From 1a9f39770229eaa10a0a9c27aa24e8d0d9c7ebca Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:02:17 +0100 Subject: [PATCH 16/23] Add more statistical routines and examples --- docs/src/compute.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/src/compute.md b/docs/src/compute.md index 33b9d6e..8727935 100644 --- a/docs/src/compute.md +++ b/docs/src/compute.md @@ -1,30 +1,54 @@ # Compute Features -The `compute` module provides statistical routines like descriptive -statistics and correlation measures. +The `compute` module hosts numerical routines for exploratory data analysis. +It covers descriptive statistics, correlations, probability distributions and +some basic inferential tests. ## Basic Statistics ```rust # extern crate rustframe; -use rustframe::compute::stats::{mean, stddev}; +use rustframe::compute::stats::{mean, mean_vertical, stddev, median}; use rustframe::matrix::Matrix; let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2); -let mean_val = mean(&m); -let std_val = stddev(&m); +assert_eq!(mean(&m), 2.5); +assert_eq!(stddev(&m), 1.118033988749895); +assert_eq!(median(&m), 2.5); +// column averages returned as 1 x n matrix +let col_means = mean_vertical(&m); +assert_eq!(col_means.data(), &[1.5, 3.5]); ``` ## Correlation +Correlation functions help measure linear relationships between datasets. + ```rust # extern crate rustframe; -use rustframe::compute::stats::pearson; +use rustframe::compute::stats::{pearson, covariance}; use rustframe::matrix::Matrix; let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2); let y = Matrix::from_vec(vec![2.0, 4.0, 6.0, 8.0], 2, 2); let corr = pearson(&x, &y); +let cov = covariance(&x, &y); +assert!((corr - 1.0).abs() < 1e-8); +assert!((cov - 2.5).abs() < 1e-8); +``` + +## Distributions + +Probability distribution helpers are available for common PDFs and CDFs. + +```rust +# extern crate rustframe; +use rustframe::compute::stats::distributions::normal_pdf; +use rustframe::matrix::Matrix; + +let x = Matrix::from_vec(vec![0.0, 1.0], 1, 2); +let pdf = normal_pdf(x, 0.0, 1.0); +assert_eq!(pdf.data().len(), 2); ``` With the basics covered, explore predictive models in the From 31a5ba2460b935c6c1b8914066c5fe62febbb92d Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:02:46 +0100 Subject: [PATCH 17/23] Improve data manipulation examples --- docs/src/data-manipulation.md | 54 ++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/docs/src/data-manipulation.md b/docs/src/data-manipulation.md index 34aa99c..bcb1b77 100644 --- a/docs/src/data-manipulation.md +++ b/docs/src/data-manipulation.md @@ -1,7 +1,8 @@ # Data Manipulation -RustFrame's `Frame` type couples tabular data with -column labels and a typed row index. +Rustframe's `Frame` type couples tabular data with +column labels and a typed row index. Frames expose a familiar API for loading +data, selecting rows or columns and performing aggregations. ## Creating a Frame @@ -17,27 +18,60 @@ assert_eq!(frame["A"], vec![1.0, 2.0]); ## Indexing Rows +Row labels can be integers, dates or a default range. Retrieving a row returns a +view that lets you inspect values by column name or position. + +```rust +# extern crate rustframe; +# extern crate chrono; +use chrono::NaiveDate; +use rustframe::frame::{Frame, RowIndex}; +use rustframe::matrix::Matrix; + +let d = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap(); +let data = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); +let index = RowIndex::Date(vec![d(2024, 1, 1), d(2024, 1, 2)]); +let mut frame = Frame::new(data, vec!["A", "B"], Some(index)); +assert_eq!(frame.get_row_date(d(2024, 1, 2))["B"], 4.0); + +// mutate by row key +frame.get_row_date_mut(d(2024, 1, 1)).set_by_index(0, 9.0); +assert_eq!(frame.get_row_date(d(2024, 1, 1))["A"], 9.0); +``` + +## Column operations + +Columns can be inserted, renamed, removed or reordered in place. + ```rust # extern crate rustframe; use rustframe::frame::{Frame, RowIndex}; use rustframe::matrix::Matrix; -let data = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); -let index = RowIndex::Int(vec![10, 20]); -let frame = Frame::new(data, vec!["A", "B"], Some(index)); -assert_eq!(frame.get_row(20)["B"], 4.0); +let data = Matrix::from_cols(vec![vec![1, 2], vec![3, 4]]); +let mut frame = Frame::new(data, vec!["X", "Y"], Some(RowIndex::Range(0..2))); + +frame.add_column("Z", vec![5, 6]); +frame.rename("Y", "W"); +let removed = frame.delete_column("X"); +assert_eq!(removed, vec![1, 2]); +frame.sort_columns(); +assert_eq!(frame.columns(), &["W", "Z"]); ``` ## Aggregations +Any numeric aggregation available on `Matrix` is forwarded to `Frame`. + ```rust # extern crate rustframe; use rustframe::frame::Frame; use rustframe::matrix::{Matrix, SeriesOps}; -let frame = Frame::new(Matrix::from_cols(vec![vec![1.0, 2.0]]), vec!["A"], None); -assert_eq!(frame.sum_vertical(), vec![3.0]); +let frame = Frame::new(Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]), vec!["A", "B"], None); +assert_eq!(frame.sum_vertical(), vec![3.0, 7.0]); +assert_eq!(frame.sum_horizontal(), vec![4.0, 6.0]); ``` -When you're ready to run analytics, continue to the -[compute features](./compute.md) chapter. +With the basics covered, continue to the [compute features](./compute.md) +chapter for statistics and analytics. From 039fb1a98e332a90793a8643448c544fca5d85d9 Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:04:07 +0100 Subject: [PATCH 18/23] Enhance utilities documentation with additional date and random number examples --- docs/src/utilities.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/src/utilities.md b/docs/src/utilities.md index 1bed694..28ddaab 100644 --- a/docs/src/utilities.md +++ b/docs/src/utilities.md @@ -3,16 +3,36 @@ Utilities provide handy helpers around the core library. Existing tools include: -- Date utilities for generating calendar sequences. +- Date utilities for generating calendar sequences and business‑day sets +- Random number generators for simulations and testing ## Date Helpers ```rust # extern crate rustframe; -use rustframe::utils::dateutils::{DatesList, DateFreq}; +use rustframe::utils::dateutils::{BDatesList, BDateFreq, DatesList, DateFreq}; +// Calendar sequence let list = DatesList::new("2024-01-01".into(), "2024-01-03".into(), DateFreq::Daily); assert_eq!(list.count().unwrap(), 3); + +// Business days starting from 2024‑01‑02 +let bdates = BDatesList::from_n_periods("2024-01-02".into(), BDateFreq::Daily, 3).unwrap(); +assert_eq!(bdates.list().unwrap().len(), 3); +``` + +## Random Numbers + +The `random` module offers deterministic and cryptographically secure RNGs. + +```rust +# extern crate rustframe; +use rustframe::random::{Prng, Rng}; + +let mut rng = Prng::new(42); +let v1 = rng.next_u64(); +let v2 = rng.next_u64(); +assert_ne!(v1, v2); ``` Upcoming utilities will cover: From 3d11226d57fcc540b75d087688806c731cdb2bfb Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:04:36 +0100 Subject: [PATCH 19/23] Update machine learning documentation for clarity and completeness --- docs/src/machine-learning.md | 43 +++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/src/machine-learning.md b/docs/src/machine-learning.md index 1694da8..ccbec53 100644 --- a/docs/src/machine-learning.md +++ b/docs/src/machine-learning.md @@ -1,11 +1,17 @@ # Machine Learning -RustFrame ships with several algorithms: +The `compute::models` module bundles several learning algorithms that operate on +`Matrix` structures. These examples highlight the basic training and prediction +APIs. For more end‑to‑end walkthroughs see the examples directory in the +repository. + +Currently implemented models include: - Linear and logistic regression -- K-means clustering +- K‑means clustering - Principal component analysis (PCA) -- Naive Bayes and dense neural networks +- Gaussian Naive Bayes +- Dense neural networks ## Linear Regression @@ -37,3 +43,34 @@ let cluster = model.predict(&new_point)[0]; For helper functions and upcoming modules, visit the [utilities](./utilities.md) section. + +## Logistic Regression + +```rust +# extern crate rustframe; +use rustframe::compute::models::logreg::LogReg; +use rustframe::matrix::Matrix; + +let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 4, 1); +let y = Matrix::from_vec(vec![0.0, 0.0, 1.0, 1.0], 4, 1); +let mut model = LogReg::new(1); +model.fit(&x, &y, 0.1, 200); +let preds = model.predict_proba(&x); +assert_eq!(preds.rows(), 4); +``` + +## Principal Component Analysis + +```rust +# extern crate rustframe; +use rustframe::compute::models::pca::PCA; +use rustframe::matrix::Matrix; + +let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2); +let pca = PCA::fit(&data, 1, 0); +let transformed = pca.transform(&data); +assert_eq!(transformed.cols(), 1); +``` + +For helper functions and upcoming modules, visit the +[utilities](./utilities.md) section. From 2845f357b7a893b3311a6afd066bd5d84993d27d Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:04:41 +0100 Subject: [PATCH 20/23] Revise introduction for clarity and detail, enhancing the overview of RustFrame's features and capabilities --- docs/src/introduction.md | 42 +++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 80a43e7..96df2cd 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,10 +1,38 @@ # Introduction -Welcome to the **RustFrame User Guide**. This book provides a tour of -RustFrame's capabilities from basic data handling to advanced machine learning -workflows. Each chapter contains runnable snippets so you can follow along. +Welcome to the **RustFrame User Guide**. Rustframe is a lightweight dataframe +and math toolkit for Rust written in 100% safe Rust. It focuses on keeping the +API approachable while offering handy features for small analytical or +educational projects. -1. [Data manipulation](./data-manipulation.md) for loading and transforming data. -2. [Compute features](./compute.md) for statistics and analytics. -3. [Machine learning](./machine-learning.md) for predictive models. -4. [Utilities](./utilities.md) for supporting helpers and upcoming modules. +Rustframe bundles: + +- column‑labelled frames built on a fast column‑major matrix +- familiar element‑wise math and aggregation routines +- a growing `compute` module for statistics and machine learning +- utilities for dates and random numbers + +```rust +# extern crate rustframe; +use rustframe::{frame::Frame, matrix::{Matrix, SeriesOps}}; + +let data = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); +let frame = Frame::new(data, vec!["A", "B"], None); + +// Perform column wise aggregation +assert_eq!(frame.sum_vertical(), vec![3.0, 7.0]); +``` + +## Resources + +- [GitHub repository](https://github.com/Magnus167/rustframe) +- [Crates.io](https://crates.io/crates/rustframe) & [API docs](https://docs.rs/rustframe) +- [Code coverage](https://codecov.io/gh/Magnus167/rustframe) + +This guide walks through the main building blocks of the library. Each chapter +contains runnable snippets so you can follow along: + +1. [Data manipulation](./data-manipulation.md) for loading and transforming data +2. [Compute features](./compute.md) for statistics and analytics +3. [Machine learning](./machine-learning.md) for predictive models +4. [Utilities](./utilities.md) for supporting helpers and upcoming modules From 080680d095e3ba54f4176b789cc61671e6c1b71e Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:05:13 +0100 Subject: [PATCH 21/23] Update book metadata: correct author field and ensure consistent title casing --- docs/book.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/book.toml b/docs/book.toml index 2de58a0..a742c0e 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -1,7 +1,7 @@ [book] -title = "RustFrame User Guide" -author = ["RustFrame Contributors"] -description = "Guided journey through RustFrame capabilities." +title = "Rustframe User Guide" +authors = ["Palash Tyagi (https://github.com/Magnus167)"] +description = "Guided journey through Rustframe capabilities." [build] build-dir = "book" From 14751568558794eb52af11b1063e2bbed5a4162c Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:05:31 +0100 Subject: [PATCH 22/23] Fix casing in user guide title for consistency --- docs/build.sh | 2 +- docs/src/introduction.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build.sh b/docs/build.sh index 0e109ac..38414e9 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -1,5 +1,5 @@ #!/usr/bin/env sh -# Build and test the RustFrame user guide using mdBook. +# Build and test the Rustframe user guide using mdBook. set -e cd docs diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 96df2cd..eb23e40 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,6 +1,6 @@ # Introduction -Welcome to the **RustFrame User Guide**. Rustframe is a lightweight dataframe +Welcome to the **Rustframe User Guide**. Rustframe is a lightweight dataframe and math toolkit for Rust written in 100% safe Rust. It focuses on keeping the API approachable while offering handy features for small analytical or educational projects. From f4ebd78234519523d4eee38c0779d74760c5dd2c Mon Sep 17 00:00:00 2001 From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com> Date: Mon, 4 Aug 2025 00:06:59 +0100 Subject: [PATCH 23/23] Comment out the release build command in gen.sh for clarity --- docs/gen.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gen.sh b/docs/gen.sh index b49d4ec..02e9949 100644 --- a/docs/gen.sh +++ b/docs/gen.sh @@ -11,4 +11,4 @@ mdbook test -L ../target/debug/deps "$@" mdbook build "$@" cargo build -cargo build --release +# cargo build --release