Add user guide examples

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!