Merge 1dcd9727b4ad4021098e8e4b688ace2427501d62 into 7d0978e5fba98538de20d0fdb9d66e6cbf80d3f7

.github/htmldocs/index.html

@@ -58,6 +58,10 @@
         <h2>A lightweight dataframe & math toolkit for Rust</h2>
         <hr style="border: 1px solid #d4d4d4; margin: 20px 0;">
         <p>
+
+            📖 <a href="https://magnus167.github.io/rustframe/user-guide">User Guide</a>
+            <br><br>
+
             📚 <a href="https://magnus167.github.io/rustframe/docs">Docs</a> |
             📊 <a href="https://magnus167.github.io/rustframe/benchmark-report/">Benchmarks</a>
 

.github/workflows/docs-and-testcov.yml

@@ -153,7 +153,6 @@ jobs:
 
           echo "<meta http-equiv=\"refresh\" content=\"0; url=../docs/index.html\">" > 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,16 +165,32 @@ 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: |
+          cargo binstall mdbook -q
+          cd docs
+          ./build.sh
+          cd ..
+
+      - name: Copy user guide to output directory
+        run: |
+          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/htmldocs/index.html output/index.html
-          cp .github/rustframe_logo.png target/doc/rustframe_logo.png
+          cp .github/rustframe_logo.png output/rustframe_logo.png
 
       - name: Upload Pages artifact
         # 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'

.github/workflows/run-unit-tests.yml

@@ -78,3 +78,10 @@ jobs:
         uses: codecov/test-results-action@v1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Test build user guide
+        run: |
+          cargo binstall mdbook -q
+          cd docs
+          ./build.sh
+          cd ..

.gitignore

@@ -16,4 +16,6 @@ data/
 
 tarpaulin-report.*
 
-.github/htmldocs/rustframe_logo.png
+.github/htmldocs/rustframe_logo.png
+
+docs/book/

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"

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

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)

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.

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.

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!

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.

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!