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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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/30] 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
From 23a01dab076ca76122680346fb7d7eb99f7834ee Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 00:29:13 +0100
Subject: [PATCH 24/30] Update documentation links
---
.github/htmldocs/index.html | 7 +++++--
README.md | 3 ++-
docs/src/introduction.md | 2 ++
3 files changed, 9 insertions(+), 3 deletions(-)
diff --git a/.github/htmldocs/index.html b/.github/htmldocs/index.html
index 85484c6..3b0d9c3 100644
--- a/.github/htmldocs/index.html
+++ b/.github/htmldocs/index.html
@@ -59,8 +59,12 @@
+ π GitHub
+
+
π User Guide
+
π Docs |
π Benchmarks
@@ -69,8 +73,7 @@
π¦ Crates.io |
π docs.rs
- π GitHub |
- π Gitea mirror
+
diff --git a/README.md b/README.md
index c3b87c1..923e5e9 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,12 @@
# rustframe
-π [Docs](https://magnus167.github.io/rustframe/) | π [GitHub](https://github.com/Magnus167/rustframe) | π [Gitea mirror](https://gitea.nulltech.uk/Magnus167/rustframe) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
+π [Docs](https://magnus167.github.io/rustframe/) | π [GitHub](https://github.com/Magnus167/rustframe) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
[](https://codecov.io/gh/Magnus167/rustframe)
[](https://magnus167.github.io/rustframe/docs/tarpaulin-report.html)
+[](https://gitea.nulltech.uk/Magnus167/rustframe)
---
diff --git a/docs/src/introduction.md b/docs/src/introduction.md
index eb23e40..138366c 100644
--- a/docs/src/introduction.md
+++ b/docs/src/introduction.md
@@ -1,5 +1,7 @@
# Introduction
+π [Docs](https://magnus167.github.io/rustframe/) | π [GitHub](https://github.com/Magnus167/rustframe) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
+
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
From 68a01ab5289f1b63448c3a10a14e7c755a4fb3f8 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 15:52:57 +0100
Subject: [PATCH 25/30] Enhance documentation with additional compute examples
and stats functions
---
docs/src/compute.md | 16 ++++++++++++++--
docs/src/data-manipulation.md | 22 ++++++++++++++++++++++
docs/src/utilities.md | 19 +++++++++++++++++++
3 files changed, 55 insertions(+), 2 deletions(-)
diff --git a/docs/src/compute.md b/docs/src/compute.md
index 8727935..6c5e34c 100644
--- a/docs/src/compute.md
+++ b/docs/src/compute.md
@@ -22,8 +22,6 @@ 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, covariance};
@@ -51,5 +49,19 @@ let pdf = normal_pdf(x, 0.0, 1.0);
assert_eq!(pdf.data().len(), 2);
```
+### More Compute Examples
+
+```rust
+# extern crate rustframe;
+use rustframe::matrix::Matrix;
+use rustframe::compute::stats::inferential::t_test;
+
+let sample1 = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
+let sample2 = Matrix::from_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
+let (t_statistic, p_value) = t_test(&sample1, &sample2);
+assert!((t_statistic + 5.0).abs() < 1e-5);
+assert!(p_value > 0.0 && p_value < 1.0);
+```
+
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
index bcb1b77..7264b62 100644
--- a/docs/src/data-manipulation.md
+++ b/docs/src/data-manipulation.md
@@ -73,5 +73,27 @@ assert_eq!(frame.sum_vertical(), vec![3.0, 7.0]);
assert_eq!(frame.sum_horizontal(), vec![4.0, 6.0]);
```
+## Matrix Operations
+
+```rust
+# extern crate rustframe;
+use rustframe::matrix::Matrix;
+
+let data1 = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let data2 = Matrix::from_vec(vec![5.0, 6.0, 7.0, 8.0], 2, 2);
+
+let sum = data1.clone() + data2.clone();
+assert_eq!(sum.data(), vec![6.0, 8.0, 10.0, 12.0]);
+
+let product = data1.clone() * data2.clone();
+assert_eq!(product.data(), vec![5.0, 12.0, 21.0, 32.0]);
+
+let scalar_product = data1.clone() * 2.0;
+assert_eq!(scalar_product.data(), vec![2.0, 4.0, 6.0, 8.0]);
+
+let equals = data1 == data1.clone();
+assert_eq!(equals, true);
+```
+
With the basics covered, continue to the [compute features](./compute.md)
chapter for statistics and analytics.
diff --git a/docs/src/utilities.md b/docs/src/utilities.md
index 28ddaab..6f0e3ed 100644
--- a/docs/src/utilities.md
+++ b/docs/src/utilities.md
@@ -35,6 +35,25 @@ let v2 = rng.next_u64();
assert_ne!(v1, v2);
```
+## Stats Functions
+
+```rust
+# extern crate rustframe;
+use rustframe::matrix::Matrix;
+use rustframe::compute::stats::descriptive::{mean, median, stddev};
+
+let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
+
+let mean_value = mean(&data);
+assert_eq!(mean_value, 3.0);
+
+let median_value = median(&data);
+assert_eq!(median_value, 3.0);
+
+let std_value = stddev(&data);
+assert_eq!(std_value, 2.0_f64.sqrt());
+```
+
Upcoming utilities will cover:
- Data import/export helpers
From b687fd4e6b3b3828de3700f4cd9d042b1351df05 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 19:21:36 +0100
Subject: [PATCH 26/30] Add advanced matrix operations and Gaussian Naive Bayes
examples to documentation
---
docs/src/compute.md | 92 +++++++++++++++++++++++++++++++++--
docs/src/data-manipulation.md | 58 ++++++++++++++++++++++
docs/src/machine-learning.md | 70 ++++++++++++++++++++++++++
3 files changed, 216 insertions(+), 4 deletions(-)
diff --git a/docs/src/compute.md b/docs/src/compute.md
index 6c5e34c..90bdd9c 100644
--- a/docs/src/compute.md
+++ b/docs/src/compute.md
@@ -8,16 +8,51 @@ some basic inferential tests.
```rust
# extern crate rustframe;
-use rustframe::compute::stats::{mean, mean_vertical, stddev, median};
+use rustframe::compute::stats::{mean, mean_horizontal, mean_vertical, stddev, median, population_variance, percentile};
use rustframe::matrix::Matrix;
let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
assert_eq!(mean(&m), 2.5);
assert_eq!(stddev(&m), 1.118033988749895);
assert_eq!(median(&m), 2.5);
+assert_eq!(population_variance(&m), 1.25);
+assert_eq!(percentile(&m, 50.0), 3.0);
// column averages returned as 1 x n matrix
+let row_means = mean_horizontal(&m);
+assert_eq!(row_means.data(), &[2.0, 3.0]);
let col_means = mean_vertical(&m);
-assert_eq!(col_means.data(), &[1.5, 3.5]);
+assert_eq!(col_means.data(), & [1.5, 3.5]);
+```
+
+### Axis-specific Operations
+
+Operations can be applied along specific axes (rows or columns):
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::{mean_vertical, mean_horizontal, stddev_vertical, stddev_horizontal};
+use rustframe::matrix::Matrix;
+
+// 3x2 matrix
+let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 3, 2);
+
+// Mean along columns (vertical) - returns 1 x cols matrix
+let col_means = mean_vertical(&m);
+assert_eq!(col_means.shape(), (1, 2));
+assert_eq!(col_means.data(), &[3.0, 4.0]); // [(1+3+5)/3, (2+4+6)/3]
+
+// Mean along rows (horizontal) - returns rows x 1 matrix
+let row_means = mean_horizontal(&m);
+assert_eq!(row_means.shape(), (3, 1));
+assert_eq!(row_means.data(), &[1.5, 3.5, 5.5]); // [(1+2)/2, (3+4)/2, (5+6)/2]
+
+// Standard deviation along columns
+let col_stddev = stddev_vertical(&m);
+assert_eq!(col_stddev.shape(), (1, 2));
+
+// Standard deviation along rows
+let row_stddev = stddev_horizontal(&m);
+assert_eq!(row_stddev.shape(), (3, 1));
```
## Correlation
@@ -49,18 +84,67 @@ let pdf = normal_pdf(x, 0.0, 1.0);
assert_eq!(pdf.data().len(), 2);
```
-### More Compute Examples
+### Additional Distributions
+
+Rustframe provides several other probability distributions:
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::distributions::{normal_cdf, binomial_pmf, binomial_cdf, poisson_pmf};
+use rustframe::matrix::Matrix;
+
+// Normal distribution CDF
+let x = Matrix::from_vec(vec![0.0, 1.0], 1, 2);
+let cdf = normal_cdf(x, 0.0, 1.0);
+assert_eq!(cdf.data().len(), 2);
+
+// Binomial distribution PMF
+// Probability of k successes in n trials with probability p
+let k = Matrix::from_vec(vec![0_u64, 1, 2, 3], 1, 4);
+let pmf = binomial_pmf(3, k.clone(), 0.5);
+assert_eq!(pmf.data().len(), 4);
+
+// Binomial distribution CDF
+let cdf = binomial_cdf(3, k, 0.5);
+assert_eq!(cdf.data().len(), 4);
+
+// Poisson distribution PMF
+// Probability of k events with rate parameter lambda
+let k = Matrix::from_vec(vec![0_u64, 1, 2], 1, 3);
+let pmf = poisson_pmf(2.0, k);
+assert_eq!(pmf.data().len(), 3);
+```
+
+### Inferential Statistics
+
+Rustframe provides several inferential statistical tests:
```rust
# extern crate rustframe;
use rustframe::matrix::Matrix;
-use rustframe::compute::stats::inferential::t_test;
+use rustframe::compute::stats::inferential::{t_test, chi2_test, anova};
+// Two-sample t-test
let sample1 = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
let sample2 = Matrix::from_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
let (t_statistic, p_value) = t_test(&sample1, &sample2);
assert!((t_statistic + 5.0).abs() < 1e-5);
assert!(p_value > 0.0 && p_value < 1.0);
+
+// Chi-square test of independence
+let observed = Matrix::from_vec(vec![12.0, 5.0, 8.0, 10.0], 2, 2);
+let (chi2_statistic, p_value) = chi2_test(&observed);
+assert!(chi2_statistic > 0.0);
+assert!(p_value > 0.0 && p_value < 1.0);
+
+// One-way ANOVA
+let group1 = Matrix::from_vec(vec![1.0, 2.0, 3.0], 1, 3);
+let group2 = Matrix::from_vec(vec![2.0, 3.0, 4.0], 1, 3);
+let group3 = Matrix::from_vec(vec![3.0, 4.0, 5.0], 1, 3);
+let groups = vec![&group1, &group2, &group3];
+let (f_statistic, p_value) = anova(groups);
+assert!(f_statistic > 0.0);
+assert!(p_value > 0.0 && p_value < 1.0);
```
With the basics covered, explore predictive models in the
diff --git a/docs/src/data-manipulation.md b/docs/src/data-manipulation.md
index 7264b62..31f91c9 100644
--- a/docs/src/data-manipulation.md
+++ b/docs/src/data-manipulation.md
@@ -95,5 +95,63 @@ let equals = data1 == data1.clone();
assert_eq!(equals, true);
```
+### Advanced Matrix Operations
+
+Matrices support a variety of advanced operations:
+
+```rust
+# extern crate rustframe;
+use rustframe::matrix::{Matrix, SeriesOps};
+
+// Matrix multiplication (dot product)
+let a = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let b = Matrix::from_vec(vec![5.0, 6.0, 7.0, 8.0], 2, 2);
+let product = a.matrix_mul(&b);
+assert_eq!(product.data(), vec![23.0, 34.0, 31.0, 46.0]);
+
+// Transpose
+let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let transposed = m.transpose();
+assert_eq!(transposed.data(), vec![1.0, 3.0, 2.0, 4.0]);
+
+// Map function over all elements
+let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let squared = m.map(|x| x * x);
+assert_eq!(squared.data(), vec![1.0, 4.0, 9.0, 16.0]);
+
+// Zip two matrices with a function
+let a = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let b = Matrix::from_vec(vec![5.0, 6.0, 7.0, 8.0], 2, 2);
+let zipped = a.zip(&b, |x, y| x + y);
+assert_eq!(zipped.data(), vec![6.0, 8.0, 10.0, 12.0]);
+```
+
+### Matrix Reductions
+
+Matrices support various reduction operations:
+
+```rust
+# extern crate rustframe;
+use rustframe::matrix::{Matrix, SeriesOps};
+
+let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 3, 2);
+
+// Sum along columns (vertical)
+let col_sums = m.sum_vertical();
+assert_eq!(col_sums, vec![9.0, 12.0]); // [1+3+5, 2+4+6]
+
+// Sum along rows (horizontal)
+let row_sums = m.sum_horizontal();
+assert_eq!(row_sums, vec![3.0, 7.0, 11.0]); // [1+2, 3+4, 5+6]
+
+// Cumulative sum along columns
+let col_cumsum = m.cumsum_vertical();
+assert_eq!(col_cumsum.data(), vec![1.0, 4.0, 9.0, 2.0, 6.0, 12.0]);
+
+// Cumulative sum along rows
+let row_cumsum = m.cumsum_horizontal();
+assert_eq!(row_cumsum.data(), vec![1.0, 3.0, 5.0, 3.0, 7.0, 11.0]);
+```
+
With the basics covered, continue to the [compute features](./compute.md)
chapter for statistics and analytics.
diff --git a/docs/src/machine-learning.md b/docs/src/machine-learning.md
index ccbec53..b245b6e 100644
--- a/docs/src/machine-learning.md
+++ b/docs/src/machine-learning.md
@@ -72,5 +72,75 @@ let transformed = pca.transform(&data);
assert_eq!(transformed.cols(), 1);
```
+### Gaussian Naive Bayes
+
+Gaussian Naive Bayes classifier for continuous features:
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::gaussian_nb::GaussianNB;
+use rustframe::matrix::Matrix;
+
+// Training data with 2 features
+let x = Matrix::from_rows_vec(vec![
+ 1.0, 2.0,
+ 2.0, 3.0,
+ 3.0, 4.0,
+ 4.0, 5.0
+], 4, 2);
+
+// Class labels (0 or 1)
+let y = Matrix::from_vec(vec![0.0, 0.0, 1.0, 1.0], 4, 1);
+
+// Train the model
+let mut model = GaussianNB::new(1e-9, true);
+model.fit(&x, &y);
+
+// Make predictions
+let predictions = model.predict(&x);
+assert_eq!(predictions.rows(), 4);
+```
+
+### Dense Neural Networks
+
+Simple fully connected neural network:
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::dense_nn::{DenseNN, DenseNNConfig, ActivationKind, InitializerKind, LossKind};
+use rustframe::matrix::Matrix;
+
+// Training data with 2 features
+let x = Matrix::from_rows_vec(vec![
+ 0.0, 0.0,
+ 0.0, 1.0,
+ 1.0, 0.0,
+ 1.0, 1.0
+], 4, 2);
+
+// XOR target outputs
+let y = Matrix::from_vec(vec![0.0, 1.0, 1.0, 0.0], 4, 1);
+
+// Create a neural network with 2 hidden layers
+let config = DenseNNConfig {
+ input_size: 2,
+ hidden_layers: vec![4, 4],
+ output_size: 1,
+ activations: vec![ActivationKind::Sigmoid, ActivationKind::Sigmoid, ActivationKind::Sigmoid],
+ initializer: InitializerKind::Uniform(0.5),
+ loss: LossKind::MSE,
+ learning_rate: 0.1,
+ epochs: 1000,
+};
+let mut model = DenseNN::new(config);
+
+// Train the model
+model.train(&x, &y);
+
+// Make predictions
+let predictions = model.predict(&x);
+assert_eq!(predictions.rows(), 4);
+```
+
For helper functions and upcoming modules, visit the
[utilities](./utilities.md) section.
From 9e6e22fc375181ab6629a4fe109511c768d8ce72 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 20:37:27 +0100
Subject: [PATCH 27/30] Add covariance functions and examples to documentation
---
docs/src/compute.md | 71 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 71 insertions(+)
diff --git a/docs/src/compute.md b/docs/src/compute.md
index 90bdd9c..f478534 100644
--- a/docs/src/compute.md
+++ b/docs/src/compute.md
@@ -70,6 +70,77 @@ assert!((corr - 1.0).abs() < 1e-8);
assert!((cov - 2.5).abs() < 1e-8);
```
+## Covariance
+
+### `covariance`
+
+Computes the population covariance between two equally sized matrices by flattening
+their values.
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::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 cov = covariance(&x, &y);
+assert!((cov - 2.5).abs() < 1e-8);
+```
+
+### `covariance_vertical`
+
+Evaluates covariance between columns (i.e. across rows) and returns a matrix of
+column pair covariances.
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::covariance_vertical;
+use rustframe::matrix::Matrix;
+
+let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let cov = covariance_vertical(&m);
+assert_eq!(cov.shape(), (2, 2));
+assert!(cov.data().iter().all(|&v| (v - 1.0).abs() < 1e-8));
+```
+
+### `covariance_horizontal`
+
+Computes covariance between rows (i.e. across columns) returning a matrix that
+describes how each pair of rows varies together.
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::covariance_horizontal;
+use rustframe::matrix::Matrix;
+
+let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+let cov = covariance_horizontal(&m);
+assert_eq!(cov.shape(), (2, 2));
+assert!(cov.data().iter().all(|&v| (v - 0.25).abs() < 1e-8));
+```
+
+### `covariance_matrix`
+
+Builds a covariance matrix either between columns (`Axis::Col`) or rows
+(`Axis::Row`). Each entry represents how two series co-vary.
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::stats::covariance_matrix;
+use rustframe::matrix::{Axis, Matrix};
+
+let data = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
+
+// Covariance between columns
+let cov_cols = covariance_matrix(&data, Axis::Col);
+assert!((cov_cols.get(0, 0) - 2.0).abs() < 1e-8);
+
+// Covariance between rows
+let cov_rows = covariance_matrix(&data, Axis::Row);
+assert!((cov_rows.get(0, 1) + 0.5).abs() < 1e-8);
+```
+
## Distributions
Probability distribution helpers are available for common PDFs and CDFs.
From 755dee58e781be9fc80d148769e9492ac7caae89 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 22:14:17 +0100
Subject: [PATCH 28/30] Refactor machine learning user-guide
---
docs/src/machine-learning.md | 146 +++++++++++++++++++++++++++++++++--
1 file changed, 141 insertions(+), 5 deletions(-)
diff --git a/docs/src/machine-learning.md b/docs/src/machine-learning.md
index b245b6e..445e867 100644
--- a/docs/src/machine-learning.md
+++ b/docs/src/machine-learning.md
@@ -41,9 +41,6 @@ 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.
-
## Logistic Regression
```rust
@@ -72,7 +69,7 @@ let transformed = pca.transform(&data);
assert_eq!(transformed.cols(), 1);
```
-### Gaussian Naive Bayes
+## Gaussian Naive Bayes
Gaussian Naive Bayes classifier for continuous features:
@@ -101,7 +98,7 @@ let predictions = model.predict(&x);
assert_eq!(predictions.rows(), 4);
```
-### Dense Neural Networks
+## Dense Neural Networks
Simple fully connected neural network:
@@ -142,5 +139,144 @@ let predictions = model.predict(&x);
assert_eq!(predictions.rows(), 4);
```
+## Real-world Examples
+
+### Housing Price Prediction
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::linreg::LinReg;
+use rustframe::matrix::Matrix;
+
+// Features: square feet and bedrooms
+let features = Matrix::from_rows_vec(vec![
+ 2100.0, 3.0,
+ 1600.0, 2.0,
+ 2400.0, 4.0,
+ 1400.0, 2.0,
+], 4, 2);
+
+// Sale prices
+let target = Matrix::from_vec(vec![400_000.0, 330_000.0, 369_000.0, 232_000.0], 4, 1);
+
+let mut model = LinReg::new(2);
+model.fit(&features, &target, 1e-8, 10_000);
+
+// Predict price of a new home
+let new_home = Matrix::from_vec(vec![2000.0, 3.0], 1, 2);
+let predicted_price = model.predict(&new_home);
+println!("Predicted price: ${}", predicted_price.data()[0]);
+```
+
+### Spam Detection
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::logreg::LogReg;
+use rustframe::matrix::Matrix;
+
+// 20 e-mails Γ 5 features = 100 numbers (row-major, spam first)
+let x = Matrix::from_rows_vec(
+ vec![
+ // βββββββββββ spam examples βββββββββββ
+ 2.0, 1.0, 1.0, 1.0, 1.0, // "You win a FREE offer - click for money-back bonus!"
+ 1.0, 0.0, 1.0, 1.0, 0.0, // "FREE offer! Click now!"
+ 0.0, 2.0, 0.0, 1.0, 1.0, // "Win win win - money inside, clickβ¦"
+ 1.0, 1.0, 0.0, 0.0, 1.0, // "Limited offer to win easy moneyβ¦"
+ 1.0, 0.0, 1.0, 0.0, 1.0, // ...
+ 0.0, 1.0, 1.0, 1.0, 0.0, // ...
+ 2.0, 0.0, 0.0, 1.0, 1.0, // ...
+ 0.0, 1.0, 1.0, 0.0, 1.0, // ...
+ 1.0, 1.0, 1.0, 1.0, 0.0, // ...
+ 1.0, 0.0, 0.0, 1.0, 1.0, // ...
+ // βββββββββββ ham examples βββββββββββ
+ 0.0, 0.0, 0.0, 0.0, 0.0, // "See you at the meeting tomorrow."
+ 0.0, 0.0, 0.0, 1.0, 0.0, // "Here's the Zoom click-link."
+ 0.0, 0.0, 0.0, 0.0, 1.0, // "Expense report: money attached."
+ 0.0, 0.0, 0.0, 1.0, 1.0, // ...
+ 0.0, 1.0, 0.0, 0.0, 0.0, // "Did we win the bid?"
+ 0.0, 0.0, 0.0, 0.0, 0.0, // ...
+ 0.0, 0.0, 0.0, 1.0, 0.0, // ...
+ 1.0, 0.0, 0.0, 0.0, 0.0, // "Special offer for staff lunch."
+ 0.0, 0.0, 0.0, 0.0, 0.0, // ...
+ 0.0, 0.0, 0.0, 1.0, 0.0,
+ ],
+ 20,
+ 5,
+);
+
+// Labels: 1 = spam, 0 = ham
+let y = Matrix::from_vec(
+ vec![
+ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, // 10 spam
+ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, // 10 ham
+ ],
+ 20,
+ 1,
+);
+
+// Train
+let mut model = LogReg::new(5);
+model.fit(&x, &y, 0.01, 5000);
+
+// Predict
+// e.g. "free money offer"
+let email_data = vec![1.0, 0.0, 1.0, 0.0, 1.0];
+let email = Matrix::from_vec(email_data, 1, 5);
+let prob_spam = model.predict_proba(&email);
+println!("Probability of spam: {:.4}", prob_spam.data()[0]);
+```
+
+### Iris Flower Classification
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::gaussian_nb::GaussianNB;
+use rustframe::matrix::Matrix;
+
+// Features: sepal length and petal length
+let x = Matrix::from_rows_vec(vec![
+ 5.1, 1.4, // setosa
+ 4.9, 1.4, // setosa
+ 6.2, 4.5, // versicolor
+ 5.9, 5.1, // virginica
+], 4, 2);
+
+let y = Matrix::from_vec(vec![0.0, 0.0, 1.0, 2.0], 4, 1);
+let names = vec!["setosa", "versicolor", "virginica"];
+
+let mut model = GaussianNB::new(1e-9, true);
+model.fit(&x, &y);
+
+let sample = Matrix::from_vec(vec![5.0, 1.5], 1, 2);
+let predicted_class = model.predict(&sample);
+let class_name = names[predicted_class.data()[0] as usize];
+println!("Predicted class: {} ({:?})", class_name, predicted_class.data()[0]);
+```
+
+### Customer Segmentation
+
+```rust
+# extern crate rustframe;
+use rustframe::compute::models::k_means::KMeans;
+use rustframe::matrix::Matrix;
+
+// Each row: [age, annual_income]
+let customers = Matrix::from_rows_vec(
+ vec![
+ 25.0, 40_000.0, 34.0, 52_000.0, 58.0, 95_000.0, 45.0, 70_000.0,
+ ],
+ 4,
+ 2,
+);
+
+let (model, labels) = KMeans::fit(&customers, 2, 20, 1e-4);
+
+let new_customer = Matrix::from_vec(vec![30.0, 50_000.0], 1, 2);
+let cluster = model.predict(&new_customer)[0];
+println!("New customer belongs to cluster: {}", cluster);
+println!("Cluster labels: {:?}", labels);
+```
+
For helper functions and upcoming modules, visit the
[utilities](./utilities.md) section.
From dae60ea1bdfaadd71a1eb646ac71f0e791256b4e Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 22:15:42 +0100
Subject: [PATCH 29/30] Rearrange links in the README for improved visibility
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 923e5e9..a52864d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# rustframe
-π [Docs](https://magnus167.github.io/rustframe/) | π [GitHub](https://github.com/Magnus167/rustframe) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
+π [GitHub](https://github.com/Magnus167/rustframe) | π [Docs](https://magnus167.github.io/rustframe/) | π [User Guide](https://magnus167.github.io/rustframe/user-guide/) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
From a53ba63f309a2c205c325940217516961805da0e Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Mon, 4 Aug 2025 22:20:58 +0100
Subject: [PATCH 30/30] Rearrange links in the introduction for improved
visibility
---
docs/src/introduction.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/introduction.md b/docs/src/introduction.md
index 138366c..1fa82e9 100644
--- a/docs/src/introduction.md
+++ b/docs/src/introduction.md
@@ -1,6 +1,6 @@
# Introduction
-π [Docs](https://magnus167.github.io/rustframe/) | π [GitHub](https://github.com/Magnus167/rustframe) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
+π [GitHub](https://github.com/Magnus167/rustframe) | π [Docs](https://magnus167.github.io/rustframe/) | π [User Guide](https://magnus167.github.io/rustframe/user-guide/) | π¦ [Crates.io](https://crates.io/crates/rustframe) | π [docs.rs](https://docs.rs/rustframe/latest/rustframe/)
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