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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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.