Merge cd3aa84e60 into af70f9ffd7

.github/.archive/pr-checks.yml

@@ -0,0 +1,34 @@
+# name: pr-checks
+
+# on:
+#   pull_request:
+#     branches: [pr_checks_disabled_for_now]
+#     types:
+#       - opened
+#       # - synchronize
+#       - reopened
+#       - edited
+#       - ready_for_review
+
+# concurrency:
+#   group: pr-checks-${{ github.event.number }}
+
+# permissions:
+#   contents: read
+#   pull-requests: read
+#   checks: write
+
+# jobs:
+#   pr-checks:
+#     name: pr-checks
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+
+#       - name: Run PR checks
+#         shell: bash
+#         env:
+#           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#           PR_NUMBER: ${{ github.event.number }}
+#         run: |
+#           python .github/scripts/pr_checks.py $PR_NUMBER

.github/htmldocs/index.html

@@ -58,14 +58,6 @@
         <h2>A lightweight dataframe & math toolkit for Rust</h2>
         <hr style="border: 1px solid #d4d4d4; margin: 20px 0;">
         <p>
-
-            🐙 <a href="https://github.com/Magnus167/rustframe">GitHub</a>
-            <br><br>
-            
-            📖 <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>
 
@@ -73,7 +65,8 @@
             🦀 <a href="https://crates.io/crates/rustframe">Crates.io</a> |
             🔖 <a href="https://docs.rs/rustframe/latest/rustframe/">docs.rs</a>
             <br><br>
-            <!-- 🌐 <a href="https://gitea.nulltech.uk/Magnus167/rustframe">Gitea mirror</a> -->
+            🐙 <a href="https://github.com/Magnus167/rustframe">GitHub</a> |
+            🌐 <a href="https://gitea.nulltech.uk/Magnus167/rustframe">Gitea mirror</a>
         </p>
     </main>
 </body>

.github/scripts/ci_checks.py

@@ -1,64 +0,0 @@
-import os
-import sys
-from typing import Any, Dict, Optional
-import tomllib
-import packaging.version
-import requests
-
-sys.path.append(os.getcwd())
-
-ACCESS_TOKEN: Optional[str] = os.getenv("GH_TOKEN", None)
-
-GITHUB_REQUEST_CONFIG = {
-    "Accept": "application/vnd.github.v3+json",
-    "Authorization": f"token {ACCESS_TOKEN}",
-    "X-GitHub-Api-Version": "2022-11-28",
-}
-REPO_OWNER_USERNAME: str = "Magnus167"
-REPO_NAME: str = "rustframe"
-REPOSITORY_WEB_LINK: str = f"github.com/{REPO_OWNER_USERNAME}/{REPO_NAME}"
-
-CARGO_TOML_PATH: str = "Cargo.toml"
-
-
-def load_cargo_toml() -> Dict[str, Any]:
-    if not os.path.exists(CARGO_TOML_PATH):
-        raise FileNotFoundError(f"{CARGO_TOML_PATH} does not exist.")
-
-    with open(CARGO_TOML_PATH, "rb") as file:
-        return tomllib.load(file)
-
-def get_latest_crates_io_version() -> str:
-    url = "https://crates.io/api/v1/crates/rustframe"
-    try:
-        response = requests.get(url, headers=GITHUB_REQUEST_CONFIG)
-        response.raise_for_status()
-        data = response.json()
-        return data["crate"]["max_version"]
-    except requests.RequestException as e:
-        raise RuntimeError(f"Failed to fetch latest version from crates.io: {e}")
-
-
-def get_current_version() -> str:
-    cargo_toml = load_cargo_toml()
-    version = cargo_toml.get("package", {}).get("version", None)
-    if not version:
-        raise ValueError("Version not found in Cargo.toml")
-    return version
-
-
-def check_version() -> None:
-    latest_version = get_latest_crates_io_version()
-    latest_version_tuple = packaging.version.parse(latest_version)
-    current_version = get_current_version()
-    current_version_tuple = packaging.version.parse(current_version)
-
-    if latest_version_tuple >= current_version_tuple:
-        print(f"Current version {current_version_tuple} is less than or equal to latest version {latest_version_tuple} on crates.io.")
-        sys.exit(1)
-
-    print(f"Current version: {current_version_tuple}")
-
-
-if __name__ == "__main__":
-    check_version()

.github/scripts/pr_checks.py

@@ -0,0 +1,236 @@
+import os
+import sys
+import urllib.request
+import urllib.error
+import json
+from typing import Any, Dict, List, Optional, Tuple
+import warnings
+import urllib.parse
+
+from time import sleep
+
+sys.path.append(os.getcwd())
+
+ACCESS_TOKEN: Optional[str] = os.getenv("GH_TOKEN", None)
+
+REQUEST_CONFIG = {
+    "Accept": "application/vnd.github.v3+json",
+    "Authorization": f"token {ACCESS_TOKEN}",
+    "X-GitHub-Api-Version": "2022-11-28",
+}
+REPO_OWNER_USERNAME: str = "Magnus167"
+REPO_NAME: str = "rustframe"
+REPOSITORY_WEB_LINK: str = f"github.com/{REPO_OWNER_USERNAME}/{REPO_NAME}"
+
+
+def perform_api_call(
+    target_url: str,
+    call_headers: Optional[dict] = REQUEST_CONFIG,
+    query_parameters: Dict[str, Any] = {},
+    http_method: str = "GET",
+    maximum_attempts: int = 5,
+) -> Any:
+    assert http_method in ["GET", "DELETE", "POST", "PATCH", "PUT"]
+
+    attempt_count = 0
+    while attempt_count < maximum_attempts:
+        try:
+            if query_parameters:
+                encoded_parameters = urllib.parse.urlencode(query_parameters)
+                target_url = f"{target_url}?{encoded_parameters}"
+
+            http_request_object = urllib.request.Request(target_url, method=http_method)
+
+            if call_headers:
+                for key, value in call_headers.items():
+                    http_request_object.add_header(key, value)
+
+            with urllib.request.urlopen(http_request_object) as server_response:
+                if server_response.status == 404:
+                    raise Exception(f"404: {target_url} not found.")
+
+                return json.loads(server_response.read().decode())
+
+        except urllib.error.HTTPError as error_details:
+            unrecoverable_codes = [403, 404, 422]
+            if error_details.code in unrecoverable_codes:
+                raise Exception(f"Request failed: {error_details}")
+
+            print(f"Request failed: {error_details}")
+            attempt_count += 1
+            sleep(1)
+
+        except Exception as error_details:
+            print(f"Request failed: {error_details}")
+            attempt_count += 1
+            sleep(1)
+
+    raise Exception("Request failed")
+
+
+valid_title_prefixes: List[str] = [
+    "Feature:",
+    "Bugfix:",
+    "Documentation:",
+    "CI/CD:",
+    "Misc:",
+    "Suggestion:",
+]
+
+
+def validate_title_format(
+    item_title: str,
+) -> bool:
+    estr = "Skipping PR title validation"
+    for _ in range(5):
+        warnings.warn(estr)
+        print(estr)
+    return True
+
+    is_format_correct: bool = False
+    for prefix_pattern in valid_title_prefixes:
+        cleaned_input: str = item_title.strip()
+        if cleaned_input.startswith(prefix_pattern):
+            is_format_correct = True
+            break
+
+    if not is_format_correct:
+        issue_message: str = (
+            f"PR title '{item_title}' does not match any "
+            f"of the accepted patterns: {valid_title_prefixes}"
+        )
+        raise ValueError(issue_message)
+
+    return is_format_correct
+
+
+def _locate_segment_indices(
+    content_string: str,
+    search_pattern: str,
+    expect_numeric_segment: bool = False,
+) -> Tuple[int, int]:
+    numeric_characters: List[str] = list(map(str, range(10))) + ["."]
+    assert bool(content_string)
+    assert bool(search_pattern)
+    assert search_pattern in content_string
+    start_index: int = content_string.find(search_pattern)
+    end_index: int = content_string.find("-", start_index)
+    if end_index == -1 and not expect_numeric_segment:
+        return (start_index, len(content_string))
+
+    if expect_numeric_segment:
+        start_index = start_index + len(search_pattern)
+        for char_index, current_character in enumerate(content_string[start_index:]):
+            if current_character not in numeric_characters:
+                break
+        end_index = start_index + char_index
+
+    return (start_index, end_index)
+
+
+def _verify_no_merge_flag(
+    content_string: str,
+) -> bool:
+    assert bool(content_string)
+    return "DO-NOT-MERGE" not in content_string
+
+
+def _verify_merge_dependency(
+    content_string: str,
+) -> bool:
+    assert bool(content_string)
+    dependency_marker: str = "MERGE-AFTER-#"
+
+    if dependency_marker not in content_string:
+        return True
+
+    start_index, end_index = _locate_segment_indices(
+        content_string=content_string, pattern=dependency_marker, numeric=True
+    )
+    dependent_item_id: str = content_string[start_index:end_index].strip()
+    try:
+        dependent_item_id = int(dependent_item_id)
+    except ValueError:
+        issue_message: str = f"PR number '{dependent_item_id}' is not an integer."
+        raise ValueError(issue_message)
+
+    dependent_item_data: Dict[str, Any] = fetch_item_details(
+        item_identifier=dependent_item_id
+    )
+    is_dependent_item_closed: bool = dependent_item_data["state"] == "closed"
+    return is_dependent_item_closed
+
+
+def evaluate_merge_conditions(
+    item_details: Dict[str, Any],
+) -> bool:
+    item_body_content: str = item_details["body"]
+
+    if item_body_content is None:
+        return True
+
+    item_body_content = item_body_content.strip().replace(" ", "-").upper()
+    item_body_content = f" {item_body_content} "
+
+    condition_outcomes: List[bool] = [
+        _verify_no_merge_flag(content_string=item_body_content),
+        _verify_merge_dependency(content_string=item_body_content),
+    ]
+
+    return all(condition_outcomes)
+
+
+def validate_item_for_merge(
+    item_data: Dict[str, Any],
+) -> bool:
+    assert set(["number", "title", "state", "body"]).issubset(item_data.keys())
+    accumulated_issues: str = ""
+    if not validate_title_format(item_title=item_data["title"]):
+        accumulated_issues += (
+            f"PR #{item_data['number']} is not mergable due to invalid title.\n"
+        )
+
+    if not evaluate_merge_conditions(item_details=item_data):
+        accumulated_issues += (
+            f"PR #{item_data['number']} is not mergable due to merge restrictions"
+            " specified in the PR body."
+        )
+
+    if accumulated_issues:
+        raise ValueError(accumulated_issues.strip())
+
+    return True
+
+
+def fetch_item_details(
+    item_identifier: int,
+):
+    api_request_url: str = f"https://api.github.com/repos/{REPO_OWNER_USERNAME}/{REPO_NAME}/pulls/{item_identifier}"
+
+    raw_api_response_data: Dict[str, Any] = perform_api_call(target_url=api_request_url)
+
+    extracted_item_info: Dict[str, Any] = {
+        "number": raw_api_response_data["number"],
+        "title": raw_api_response_data["title"],
+        "state": raw_api_response_data["state"],
+        "body": raw_api_response_data["body"],
+    }
+
+    return extracted_item_info
+
+
+def process_item_request(requested_item_id: int):
+    extracted_item_info: Dict[str, Any] = fetch_item_details(
+        item_identifier=requested_item_id
+    )
+    if not validate_item_for_merge(item_data=extracted_item_info):
+        raise ValueError("PR is not mergable.")
+
+    print("PR is mergable.")
+
+    return True
+
+
+if __name__ == "__main__":
+    requested_item_id: int = int(sys.argv[1])
+    process_item_request(requested_item_id=requested_item_id)

.github/workflows/ci-checks.yml

@@ -1,41 +0,0 @@
-name: ci-checks
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    types: [review_requested, ready_for_review, synchronize, opened, reopened]
-    branches:
-      - main
-      - test
-      - develop
-
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  id-token: write
-  pages: write
-
-jobs:
-  ci-checks:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Python
-        uses: actions/setup-python@v5
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-      - name: Install dependencies
-        run: |
-          uv venv
-          uv pip install requests packaging
-      - name: Run CI checks
-        run: |
-          uv run .github/scripts/ci_checks.py

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

@@ -153,6 +153,7 @@ 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/
@@ -165,30 +166,16 @@ 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
-          bash ./docs/build.sh
-
-      - 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 output/index.html
+          cp .github/htmldocs/index.html target/doc/index.html
-          cp .github/rustframe_logo.png output/rustframe_logo.png
+          cp .github/rustframe_logo.png target/doc/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-benchmarks.yml

@@ -2,12 +2,9 @@ name: run-benchmarks
 
 on:
   workflow_dispatch:
-  pull_request:
-    branches:
-      - main
   push:
     branches:
-      - test
+      - main
 
 jobs:
   pick-runner:
@@ -37,9 +34,9 @@ jobs:
           toolchain: stable
 
       - name: Install Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v4
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v5
       - name: Setup venv
         run: |
           uv venv

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

@@ -5,8 +5,6 @@ on:
     types: [review_requested, ready_for_review, synchronize, opened, reopened]
     branches:
       - main
-      - test
-      - develop
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -80,8 +78,3 @@ jobs:
         uses: codecov/test-results-action@v1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-
-      - name: Test build user guide
-        run: |
-          cargo binstall mdbook
-          bash ./docs/build.sh

.gitignore

@@ -17,5 +17,3 @@ data/
 tarpaulin-report.*
 
 .github/htmldocs/rustframe_logo.png
-
-docs/book/

Cargo.toml

@@ -1,12 +1,11 @@
 [package]
 name = "rustframe"
 authors = ["Palash Tyagi (https://github.com/Magnus167)"]
-version = "0.0.1-a.20250805"
+version = "0.0.1-a.20250716"
 edition = "2021"
 license = "GPL-3.0-or-later"
 readme = "README.md"
-description = "A simple dataframe and math toolkit"
+description = "A simple dataframe library"
-documentation = "https://magnus167.github.io/rustframe/"
 
 [lib]
 name = "rustframe"

README.md

@@ -1,12 +1,15 @@
 # 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/)
+<!-- # <img align="center" alt="Rustframe" src=".github/rustframe_logo.png" height="50px" /> rustframe -->
+
+<!-- though the centre tag doesn't work as it would normally, it achieves the desired effect -->
+
+📚 [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/)
 
 <!-- [![Last commit](https://img.shields.io/endpoint?url=https://magnus167.github.io/rustframe/rustframe/last-commit-date.json)](https://github.com/Magnus167/rustframe) -->
 
 [![codecov](https://codecov.io/gh/Magnus167/rustframe/graph/badge.svg?token=J7ULJEFTVI)](https://codecov.io/gh/Magnus167/rustframe)
 [![Coverage](https://img.shields.io/endpoint?url=https://magnus167.github.io/rustframe/docs/tarpaulin-badge.json)](https://magnus167.github.io/rustframe/docs/tarpaulin-report.html)
-[![gitea-mirror](https://img.shields.io/badge/git_mirror-blue)](https://gitea.nulltech.uk/Magnus167/rustframe)
 
 ---
 
@@ -24,9 +27,11 @@ Rustframe is an educational project, and is not intended for production use. It
 - **Math that reads like math** - element-wise `+`, `−`, `×`, `÷` on entire frames or scalars.
 - **Frames** - Column major data structure for single-type data, with labeled columns and typed row indices.
 - **Compute module** - Implements various statistical computations and machine learning models.
-- **Random number utils** - Built-in pseudo and cryptographically secure generators for simulations.
+
 - **[Coming Soon]** _DataFrame_ - Multi-type data structure for heterogeneous data, with labeled columns and typed row indices.
 
+- **Random number utils** - Built-in pseudo and cryptographically secure generators for simulations.
+
 #### Matrix and Frame functionality
 
 - **Matrix operations** - Element-wise arithmetic, boolean logic, transpose, and more.
@@ -50,6 +55,12 @@ The `compute` module provides implementations for various statistical computatio
 - Logistic Regression
 - Principal Component Analysis
 
+### Coming soon
+
+- **CSV I/O** - read/write CSV files with a simple API.
+- **Date Utils** - date math, calendar slicing, indexing, and more.
+- **More math** - more math functions and aggregations.
+
 ### Heads up
 
 - **Not memory‑efficient (yet)** - footprint needs work.
@@ -59,6 +70,7 @@ The `compute` module provides implementations for various statistical computatio
 
 - Optional GPU acceleration (Vulkan or similar) for heavier workloads.
 - Straightforward Python bindings using `pyo3`.
+- Integration with common ML libraries, or introduce simple ML features.
 
 ---
 
@@ -126,6 +138,10 @@ let mc: Matrix<f64> = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]);
 let md: Matrix<f64> = Matrix::from_cols(vec![vec![5.0, 6.0], vec![7.0, 8.0]]);
 let mul_result: Matrix<f64> = mc.matrix_mul(&md);
 // Expected:
+// 1*5 + 3*6 = 5 + 18 = 23
+// 2*5 + 4*6 = 10 + 24 = 34
+// 1*7 + 3*8 = 7 + 24 = 31
+// 2*7 + 4*8 = 14 + 32 = 46
 assert_eq!(mul_result.data(), &[23.0, 34.0, 31.0, 46.0]);
 
 // Dot product (alias for matrix_mul for FloatMatrix)
@@ -134,7 +150,14 @@ assert_eq!(dot_result, mul_result);
 
 // Transpose
 let original_matrix: Matrix<f64> = Matrix::from_cols(vec![vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0]]);
+// Original:
+// 1 4
+// 2 5
+// 3 6
 let transposed_matrix: Matrix<f64> = original_matrix.transpose();
+// Transposed:
+// 1 2 3
+// 4 5 6
 assert_eq!(transposed_matrix.rows(), 2);
 assert_eq!(transposed_matrix.cols(), 3);
 assert_eq!(transposed_matrix.data(), &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);
@@ -143,6 +166,10 @@ assert_eq!(transposed_matrix.data(), &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);
 let matrix = Matrix::from_cols(vec![vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0]]);
 // Map function to double each value
 let mapped_matrix = matrix.map(|x| x * 2.0);
+// Expected data after mapping
+// 2 8
+// 4 10
+// 6 12
 assert_eq!(mapped_matrix.data(), &[2.0, 4.0, 6.0, 8.0, 10.0, 12.0]);
 
 // Zip
@@ -150,10 +177,13 @@ let a = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]); // 2x2 matrix
 let b = Matrix::from_cols(vec![vec![5.0, 6.0], vec![7.0, 8.0]]); // 2x2 matrix
                                                                    // Zip function to add corresponding elements
 let zipped_matrix = a.zip(&b, |x, y| x + y);
+// Expected data after zipping
+// 6 10
+// 8 12
 assert_eq!(zipped_matrix.data(), &[6.0, 8.0, 10.0, 12.0]);
 ```
 
-## More examples
+### More examples
 
 See the [examples](./examples/) directory for some demonstrations of Rustframe's syntax and functionality.
 
@@ -192,21 +222,10 @@ cargo run --example
 
 Each demo runs a couple of mini-scenarios showcasing the APIs.
 
-## Running benchmarks
+### Running benchmarks
 
 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.

docs/book.toml

@@ -1,7 +0,0 @@
-[book]
-title = "Rustframe User Guide"
-authors = ["Palash Tyagi (https://github.com/Magnus167)"]
-description = "Guided journey through Rustframe capabilities."
-
-[build]
-build-dir = "book"

docs/build.sh

@@ -1,7 +0,0 @@
-#!/usr/bin/env sh
-# Build and test the Rustframe user guide using mdBook.
-set -e
-
-cd docs
-bash gen.sh "$@"
-cd ..

docs/gen.sh

@@ -1,14 +0,0 @@
-#!/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

docs/src/SUMMARY.md

@@ -1,7 +0,0 @@
-# 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

@@ -1,222 +0,0 @@
-# Compute Features
-
-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, 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]);
-```
-
-### 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
-
-```rust
-# extern crate rustframe;
-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);
-```
-
-## 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.
-
-```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);
-```
-
-### 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, 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
-[machine learning](./machine-learning.md) chapter.

docs/src/data-manipulation.md

@@ -1,157 +0,0 @@
-# Data Manipulation
-
-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
-
-```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
-
-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, 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![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]);
-```
-
-## 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);
-```
-
-### 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.

docs/src/introduction.md

@@ -1,40 +0,0 @@
-# Introduction
-
-🐙 [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
-API approachable while offering handy features for small analytical or
-educational projects.
-
-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

docs/src/machine-learning.md

@@ -1,282 +0,0 @@
-# Machine Learning
-
-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
-- Principal component analysis (PCA)
-- Gaussian Naive Bayes
-- 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];
-```
-
-## 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);
-```
-
-## 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);
-```
-
-## 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.

docs/src/utilities.md

@@ -1,63 +0,0 @@
-# Utilities
-
-Utilities provide handy helpers around the core library. Existing tools
-include:
-
-- 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::{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);
-```
-
-## 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
-- Visualization adapters
-- Streaming data interfaces
-
-Contributions to these sections are welcome!

examples/game_of_life.rs

@@ -3,7 +3,7 @@
 //! It demonstrates matrix operations like shifting, counting neighbors, and applying game rules.
 //! The game runs in a loop, updating the board state and printing it to the console.
 //! To modify the behaviour of the example, please change the constants at the top of this file.
-
+//! By default,
 
 use rustframe::matrix::{BoolMatrix, BoolOps, IntMatrix, Matrix};
 use rustframe::random::{rng, Rng};
@@ -21,6 +21,8 @@ fn main() {
     let debug_mode = args.contains(&"--debug".to_string());
     let print_mode = if debug_mode { false } else { PRINT_BOARD };
 
+    // Initialize the game board.
+    // This demonstrates `BoolMatrix::from_vec`.
     let mut current_board =
         BoolMatrix::from_vec(vec![false; BOARD_SIZE * BOARD_SIZE], BOARD_SIZE, BOARD_SIZE);
 
@@ -29,11 +31,15 @@ fn main() {
     add_simulated_activity(&mut current_board, BOARD_SIZE);
 
     let mut generation_count: u32 = 0;
+    // `previous_board_state` will store a clone of the board.
+    // This demonstrates `Matrix::clone()` and later `PartialEq` for `Matrix`.
     let mut previous_board_state: Option<BoolMatrix> = None;
     let mut board_hashes = Vec::new();
+    // let mut print_board_bool = true;
     let mut print_bool_int = 0;
 
     loop {
+        // if print_board_bool {
         if print_bool_int % SKIP_FRAMES == 0 {
             print_board(&current_board, generation_count, print_mode);
 
@@ -41,6 +47,7 @@ fn main() {
         } else {
             print_bool_int += 1;
         }
+        // `current_board.count()` demonstrates a method from `BoolOps`.
         board_hashes.push(hash_board(&current_board, primes.clone()));
         if detect_stable_state(&current_board, &previous_board_state) {
             println!(
@@ -61,8 +68,10 @@ fn main() {
             add_simulated_activity(&mut current_board, BOARD_SIZE);
         }
 
+        // `current_board.clone()` demonstrates `Clone` for `Matrix`.
         previous_board_state = Some(current_board.clone());
 
+        // This is the core call to your game logic.
         let next_board = game_of_life_next_frame(&current_board);
         current_board = next_board;
 
@@ -97,6 +106,7 @@ fn print_board(board: &BoolMatrix, generation_count: u32, print_mode: bool) {
         print_str.push_str("| ");
         for c in 0..board.cols() {
             if board[(r, c)] {
+                // Using Index trait for Matrix<bool>
                 print_str.push_str("██");
             } else {
                 print_str.push_str("  ");
@@ -178,38 +188,74 @@ pub fn game_of_life_next_frame(current_game: &BoolMatrix) -> BoolMatrix {
     if rows == 0 && cols == 0 {
         return BoolMatrix::from_vec(vec![], 0, 0); // Return an empty BoolMatrix
     }
+    // Assuming valid non-empty dimensions (e.g., 25x25) as per typical GOL.
+    // Your Matrix::from_vec would panic for other invalid 0-dim cases.
+
     // Define the 8 neighbor offsets (row_delta, col_delta)
     let neighbor_offsets: [(isize, isize); 8] = [
         (-1, -1),
         (-1, 0),
-        (-1, 1),
+        (-1, 1), // Top row (NW, N, NE)
         (0, -1),
-        (0, 1),
+        (0, 1), // Middle row (W, E)
         (1, -1),
         (1, 0),
-        (1, 1),
+        (1, 1), // Bottom row (SW, S, SE)
     ];
 
+    // 1. Initialize `neighbor_counts` with the first shifted layer.
+    //    This demonstrates creating an IntMatrix from a function and using it as a base.
     let (first_dr, first_dc) = neighbor_offsets[0];
     let mut neighbor_counts = get_shifted_neighbor_layer(current_game, first_dr, first_dc);
 
+    // 2. Add the remaining 7 neighbor layers.
+    //    This demonstrates element-wise addition of matrices (`Matrix + Matrix`).
     for i in 1..neighbor_offsets.len() {
         let (dr, dc) = neighbor_offsets[i];
         let next_neighbor_layer = get_shifted_neighbor_layer(current_game, dr, dc);
+        // `neighbor_counts` (owned IntMatrix) + `next_neighbor_layer` (owned IntMatrix)
+        // uses `impl Add for Matrix`, consumes both, returns new owned `IntMatrix`.
         neighbor_counts = neighbor_counts + next_neighbor_layer;
     }
 
+    // 3. Apply Game of Life rules using element-wise operations.
+
+    // Rule: Survival or Birth based on neighbor counts.
+    // A cell is alive in the next generation if:
+    //   (it's currently alive AND has 2 or 3 neighbors) OR
+    //   (it's currently dead AND has exactly 3 neighbors)
+
+    // `neighbor_counts.eq_elem(scalar)`:
+    //   Demonstrates element-wise comparison of a Matrix with a scalar (broadcast).
+    //   Returns an owned `BoolMatrix`.
     let has_2_neighbors = neighbor_counts.eq_elem(2);
-    let has_3_neighbors = neighbor_counts.eq_elem(3);
+    let has_3_neighbors = neighbor_counts.eq_elem(3); // This will be reused
 
-    let has_2_or_3_neighbors = has_2_neighbors | has_3_neighbors.clone();
+    // `has_2_neighbors | has_3_neighbors`:
+    //   Demonstrates element-wise OR (`Matrix<bool> | Matrix<bool>`).
+    //   Consumes both operands, returns an owned `BoolMatrix`.
+    let has_2_or_3_neighbors = has_2_neighbors | has_3_neighbors.clone(); // Clone has_3_neighbors as it's used again
 
+    // `current_game & &has_2_or_3_neighbors`:
+    //   `current_game` is `&BoolMatrix`. `has_2_or_3_neighbors` is owned.
+    //   Demonstrates element-wise AND (`&Matrix<bool> & &Matrix<bool>`).
+    //   Borrows both operands, returns an owned `BoolMatrix`.
     let survives = current_game & &has_2_or_3_neighbors;
 
+    // `!current_game`:
+    //   Demonstrates element-wise NOT (`!&Matrix<bool>`).
+    //   Borrows operand, returns an owned `BoolMatrix`.
     let is_dead = !current_game;
 
+    // `is_dead & &has_3_neighbors`:
+    //   `is_dead` is owned. `has_3_neighbors` is owned.
+    //   Demonstrates element-wise AND (`Matrix<bool> & &Matrix<bool>`).
+    //   Consumes `is_dead`, borrows `has_3_neighbors`, returns an owned `BoolMatrix`.
     let births = is_dead & &has_3_neighbors;
 
+    // `survives | births`:
+    //   Demonstrates element-wise OR (`Matrix<bool> | Matrix<bool>`).
+    //   Consumes both operands, returns an owned `BoolMatrix`.
     let next_frame_game = survives | births;
 
     next_frame_game

examples/logistic_regression.rs

@@ -16,7 +16,7 @@ fn student_passing_example() {
 
     // Hours studied for each student
     let hours = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
-    // Label: 0 denotes failure and 1 denotes success
+    // 0 = fail, 1 = pass
     let passed = vec![0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1.0];
 
     let x = Matrix::from_vec(hours.clone(), hours.len(), 1);

examples/stats_overview.rs

@@ -6,9 +6,9 @@ use rustframe::matrix::{Axis, Matrix};
 /// Demonstrates some of the statistics utilities in Rustframe.
 ///
 /// The example is split into three parts:
-///   - Basic descriptive statistics on a small data set
+///   1. Basic descriptive statistics on a small data set.
-///   - Covariance and correlation calculations
+///   2. Covariance and correlation calculations.
-///   - Simple inferential tests (t-test and chi-square)
+///   3. Simple inferential tests (t-test and chi-square).
 fn main() {
     descriptive_demo();
     println!("\n-----\n");

src/compute/mod.rs

@@ -1,16 +1,3 @@
-//! Algorithms and statistical utilities built on top of the core matrices.
-//!
-//! This module groups together machine‑learning models and statistical helper
-//! functions. For quick access to basic statistics see [`stats`](crate::compute::stats), while
-//! [`models`](crate::compute::models) contains small learning algorithms.
-//!
-//! ```
-//! use rustframe::compute::stats;
-//! use rustframe::matrix::Matrix;
-//!
-//! let m = Matrix::from_vec(vec![1.0, 2.0, 3.0], 3, 1);
-//! assert_eq!(stats::mean(&m), 2.0);
-//! ```
 pub mod models;
 
 pub mod stats;

src/compute/models/activations.rs

@@ -1,15 +1,3 @@
-//! Common activation functions used in neural networks.
-//!
-//! Functions operate element-wise on [`Matrix`] values.
-//!
-//! ```
-//! use rustframe::compute::models::activations::sigmoid;
-//! use rustframe::matrix::Matrix;
-//!
-//! let x = Matrix::from_vec(vec![0.0], 1, 1);
-//! let y = sigmoid(&x);
-//! assert!((y.get(0,0) - 0.5).abs() < 1e-6);
-//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 pub fn sigmoid(x: &Matrix<f64>) -> Matrix<f64> {

src/compute/models/dense_nn.rs

@@ -1,30 +1,3 @@
-//! A minimal dense neural network implementation for educational purposes.
-//!
-//! Layers operate on [`Matrix`] values and support ReLU and Sigmoid
-//! activations. This is not meant to be a performant deep‑learning framework
-//! but rather a small example of how the surrounding matrix utilities can be
-//! composed.
-//!
-//! ```
-//! use rustframe::compute::models::dense_nn::{ActivationKind, DenseNN, DenseNNConfig, InitializerKind, LossKind};
-//! use rustframe::matrix::Matrix;
-//!
-//! // Tiny network with one input and one output neuron.
-//! let config = DenseNNConfig {
-//!     input_size: 1,
-//!     hidden_layers: vec![],
-//!     output_size: 1,
-//!     activations: vec![ActivationKind::Relu],
-//!     initializer: InitializerKind::Uniform(0.5),
-//!     loss: LossKind::MSE,
-//!     learning_rate: 0.1,
-//!     epochs: 1,
-//! };
-//! let mut nn = DenseNN::new(config);
-//! let x = Matrix::from_vec(vec![1.0, 2.0], 2, 1);
-//! let y = Matrix::from_vec(vec![2.0, 3.0], 2, 1);
-//! nn.train(&x, &y);
-//! ```
 use crate::compute::models::activations::{drelu, relu, sigmoid};
 use crate::matrix::{Matrix, SeriesOps};
 use crate::random::prelude::*;

src/compute/models/gaussian_nb.rs

@@ -1,16 +1,3 @@
-//! Gaussian Naive Bayes classifier for dense matrices.
-//!
-//! ```
-//! use rustframe::compute::models::gaussian_nb::GaussianNB;
-//! use rustframe::matrix::Matrix;
-//!
-//! let x = Matrix::from_vec(vec![1.0, 2.0, 1.0, 2.0], 2, 2); // two samples
-//! let y = Matrix::from_vec(vec![0.0, 1.0], 2, 1);
-//! let mut model = GaussianNB::new(1e-9, false);
-//! model.fit(&x, &y);
-//! let preds = model.predict(&x);
-//! assert_eq!(preds.rows(), 2);
-//! ```
 use crate::matrix::Matrix;
 use std::collections::HashMap;
 

src/compute/models/k_means.rs

@@ -1,14 +1,3 @@
-//! Simple k-means clustering working on [`Matrix`] data.
-//!
-//! ```
-//! 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);
-//! assert_eq!(model.centroids.rows(), 2);
-//! assert_eq!(labels.len(), 2);
-//! ```
 use crate::compute::stats::mean_vertical;
 use crate::matrix::Matrix;
 use crate::random::prelude::*;

src/compute/models/linreg.rs

@@ -1,16 +1,3 @@
-//! Ordinary least squares linear regression.
-//!
-//! ```
-//! 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);
-//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 pub struct LinReg {

src/compute/models/logreg.rs

@@ -1,16 +1,3 @@
-//! Binary logistic regression classifier.
-//!
-//! ```
-//! 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, 100);
-//! let preds = model.predict(&x);
-//! assert_eq!(preds[(0,0)], 0.0);
-//! ```
 use crate::compute::models::activations::sigmoid;
 use crate::matrix::{Matrix, SeriesOps};
 

src/compute/models/mod.rs

@@ -1,19 +1,3 @@
-//! Lightweight machine‑learning models built on matrices.
-//!
-//! Models are intentionally minimal and operate on the [`Matrix`](crate::matrix::Matrix) type for
-//! inputs and parameters.
-//!
-//! ```
-//! 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, 1000);
-//! let preds = model.predict(&x);
-//! assert_eq!(preds.rows(), 4);
-//! ```
 pub mod activations;
 pub mod dense_nn;
 pub mod gaussian_nb;

src/compute/models/pca.rs

@@ -1,14 +1,3 @@
-//! Principal Component Analysis using covariance matrices.
-//!
-//! ```
-//! use rustframe::compute::models::pca::PCA;
-//! use rustframe::matrix::Matrix;
-//!
-//! let data = Matrix::from_rows_vec(vec![1.0, 1.0, 2.0, 2.0], 2, 2);
-//! let pca = PCA::fit(&data, 1, 0);
-//! let projected = pca.transform(&data);
-//! assert_eq!(projected.cols(), 1);
-//! ```
 use crate::compute::stats::correlation::covariance_matrix;
 use crate::compute::stats::descriptive::mean_vertical;
 use crate::matrix::{Axis, Matrix, SeriesOps};
@@ -55,7 +44,11 @@ mod tests {
 
     #[test]
     fn test_pca_basic() {
-        // Simple 2D data with points along the y = x line
+        // Simple 2D data, points along y=x line
+        // Data:
+        // 1.0, 1.0
+        // 2.0, 2.0
+        // 3.0, 3.0
         let data = Matrix::from_rows_vec(vec![1.0, 1.0, 2.0, 2.0, 3.0, 3.0], 3, 2);
         let (_n_samples, _n_features) = data.shape();
 
@@ -78,7 +71,15 @@ mod tests {
         assert!((pca.components.get(0, 0) - 1.0).abs() < EPSILON);
         assert!((pca.components.get(0, 1) - 1.0).abs() < EPSILON);
 
-        // Test transform: centered data projects to [-2.0, 0.0, 2.0]
+        // Test transform
+        // Centered data:
+        // -1.0, -1.0
+        //  0.0,  0.0
+        //  1.0,  1.0
+        // Projected: (centered_data * components.transpose())
+        // (-1.0 * 1.0 + -1.0 * 1.0) = -2.0
+        // ( 0.0 * 1.0 +  0.0 * 1.0) =  0.0
+        // ( 1.0 * 1.0 +  1.0 * 1.0) =  2.0
         let transformed_data = pca.transform(&data);
         assert_eq!(transformed_data.rows(), 3);
         assert_eq!(transformed_data.cols(), 1);

src/compute/stats/correlation.rs

@@ -1,16 +1,3 @@
-//! Covariance and correlation helpers.
-//!
-//! This module provides routines for measuring the relationship between
-//! columns or rows of matrices.
-//!
-//! ```
-//! use rustframe::compute::stats::correlation;
-//! use rustframe::matrix::Matrix;
-//!
-//! let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
-//! let cov = correlation::covariance(&x, &x);
-//! assert!((cov - 1.25).abs() < 1e-8);
-//! ```
 use crate::compute::stats::{mean, mean_horizontal, mean_vertical, stddev};
 use crate::matrix::{Axis, Matrix, SeriesOps};
 
@@ -150,7 +137,10 @@ mod tests {
 
     #[test]
     fn test_covariance_scalar_same_matrix() {
-        // Matrix with rows [1, 2] and [3, 4]; mean is 2.5
+        // M =
+        // 1,2
+        // 3,4
+        // mean = 2.5
         let data = vec![1.0, 2.0, 3.0, 4.0];
         let m = Matrix::from_vec(data.clone(), 2, 2);
 
@@ -162,7 +152,10 @@ mod tests {
 
     #[test]
     fn test_covariance_scalar_diff_matrix() {
-        // Matrix x has rows [1, 2] and [3, 4]; y is two times x
+        // x =
+        // 1,2
+        // 3,4
+        // y = 2*x
         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);
 
@@ -174,7 +167,10 @@ mod tests {
 
     #[test]
     fn test_covariance_vertical() {
-        // Matrix with rows [1, 2] and [3, 4]; columns are [1,3] and [2,4], each var=1, cov=1
+        // M =
+        // 1,2
+        // 3,4
+        // cols are [1,3] and [2,4], each var=1, cov=1
         let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
         let cov_mat = covariance_vertical(&m);
 
@@ -188,7 +184,10 @@ mod tests {
 
     #[test]
     fn test_covariance_horizontal() {
-        // Matrix with rows [1,2] and [3,4], each var=0.25, cov=0.25
+        // M =
+        // 1,2
+        // 3,4
+        // rows are [1,2] and [3,4], each var=0.25, cov=0.25
         let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
         let cov_mat = covariance_horizontal(&m);
 
@@ -202,7 +201,10 @@ mod tests {
 
     #[test]
     fn test_covariance_matrix_vertical() {
-        // Test with a simple 2x2 matrix with rows [1, 2] and [3, 4]
+        // Test with a simple 2x2 matrix
+        // M =
+        // 1, 2
+        // 3, 4
         // Expected covariance matrix (vertical, i.e., between columns):
         // Col1: [1, 3], mean = 2
         // Col2: [2, 4], mean = 3
@@ -210,7 +212,9 @@ mod tests {
         // Cov(Col2, Col2) = ((2-3)^2 + (4-3)^2) / (2-1) = (1+1)/1 = 2
         // Cov(Col1, Col2) = ((1-2)*(2-3) + (3-2)*(4-3)) / (2-1) = ((-1)*(-1) + (1)*(1))/1 = (1+1)/1 = 2
         // Cov(Col2, Col1) = 2
-        // Expected matrix filled with 2
+        // Expected:
+        // 2, 2
+        // 2, 2
         let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
         let cov_mat = covariance_matrix(&m, Axis::Col);
 
@@ -222,7 +226,10 @@ mod tests {
 
     #[test]
     fn test_covariance_matrix_horizontal() {
-        // Test with a simple 2x2 matrix with rows [1, 2] and [3, 4]
+        // Test with a simple 2x2 matrix
+        // M =
+        // 1, 2
+        // 3, 4
         // Expected covariance matrix (horizontal, i.e., between rows):
         // Row1: [1, 2], mean = 1.5
         // Row2: [3, 4], mean = 3.5
@@ -230,7 +237,9 @@ mod tests {
         // Cov(Row2, Row2) = ((3-3.5)^2 + (4-3.5)^2) / (2-1) = (0.25+0.25)/1 = 0.5
         // Cov(Row1, Row2) = ((1-1.5)*(3-3.5) + (2-1.5)*(4-3.5)) / (2-1) = ((-0.5)*(-0.5) + (0.5)*(0.5))/1 = (0.25+0.25)/1 = 0.5
         // Cov(Row2, Row1) = 0.5
-        // Expected matrix: [[0.5, -0.5], [-0.5, 0.5]]
+        // Expected:
+        // 0.5, -0.5
+        // -0.5, 0.5
         let m = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
         let cov_mat = covariance_matrix(&m, Axis::Row);
 

src/compute/stats/descriptive.rs

@@ -1,15 +1,3 @@
-//! Descriptive statistics for matrices.
-//!
-//! Provides means, variances, medians and other aggregations computed either
-//! across the whole matrix or along a specific axis.
-//!
-//! ```
-//! use rustframe::compute::stats::descriptive;
-//! use rustframe::matrix::Matrix;
-//!
-//! let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
-//! assert_eq!(descriptive::mean(&m), 2.5);
-//! ```
 use crate::matrix::{Axis, Matrix, SeriesOps};
 
 pub fn mean(x: &Matrix<f64>) -> f64 {
@@ -362,7 +350,11 @@ mod tests {
         let data: Vec<f64> = (1..=24).map(|x| x as f64).collect();
         let x = Matrix::from_vec(data, 4, 6);
 
-        // columns contain sequences increasing by four starting at 1 through 4
+        // columns:
+        //  1,  5,  9, 13, 17, 21
+        //  2,  6, 10, 14, 18, 22
+        //  3,  7, 11, 15, 19, 23
+        //  4,  8, 12, 16, 20, 24
 
         let er0 = vec![1., 5., 9., 13., 17., 21.];
         let er50 = vec![3., 7., 11., 15., 19., 23.];

src/compute/stats/distributions.rs

@@ -1,16 +1,3 @@
-//! Probability distribution functions applied element-wise to matrices.
-//!
-//! Includes approximations for the normal, uniform and gamma distributions as
-//! well as the error function.
-//!
-//! ```
-//! use rustframe::compute::stats::distributions;
-//! use rustframe::matrix::Matrix;
-//!
-//! let x = Matrix::from_vec(vec![0.0], 1, 1);
-//! let pdf = distributions::normal_pdf(x.clone(), 0.0, 1.0);
-//! assert!((pdf.get(0,0) - 0.3989).abs() < 1e-3);
-//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 use std::f64::consts::PI;

src/compute/stats/inferential.rs

@@ -1,14 +1,3 @@
-//! Basic inferential statistics such as t‑tests and chi‑square tests.
-//!
-//! ```
-//! use rustframe::compute::stats::inferential;
-//! use rustframe::matrix::Matrix;
-//!
-//! let a = Matrix::from_vec(vec![1.0, 2.0], 2, 1);
-//! let b = Matrix::from_vec(vec![1.1, 1.9], 2, 1);
-//! let (t, _p) = inferential::t_test(&a, &b);
-//! assert!(t.abs() < 1.0);
-//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 use crate::compute::stats::{gamma_cdf, mean, sample_variance};

src/compute/stats/mod.rs

@@ -1,16 +1,3 @@
-//! Statistical routines for matrices.
-//!
-//! Functions are grouped into submodules for descriptive statistics,
-//! correlations, probability distributions and basic inferential tests.
-//!
-//! ```
-//! use rustframe::compute::stats;
-//! use rustframe::matrix::Matrix;
-//!
-//! let m = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
-//! let cov = stats::covariance(&m, &m);
-//! assert!((cov - 1.25).abs() < 1e-8);
-//! ```
 pub mod correlation;
 pub mod descriptive;
 pub mod distributions;

src/frame/base.rs

@@ -1,19 +1,3 @@
-//! Core data-frame structures such as [`Frame`] and [`RowIndex`].
-//!
-//! The [`Frame`] type stores column-labelled data with an optional row index
-//! and builds upon the [`crate::matrix::Matrix`] type.
-//!
-//! # Examples
-//!
-//! ```
-//! use rustframe::frame::{Frame, RowIndex};
-//! use rustframe::matrix::Matrix;
-//!
-//! let data = Matrix::from_cols(vec![vec![1, 2], vec![3, 4]]);
-//! let frame = Frame::new(data, vec!["L", "R"], Some(RowIndex::Int(vec![10, 20])));
-//! assert_eq!(frame.columns(), &["L", "R"]);
-//! assert_eq!(frame.index(), &RowIndex::Int(vec![10, 20]));
-//! ```
 use crate::matrix::Matrix;
 use chrono::NaiveDate;
 use std::collections::HashMap;

src/frame/mod.rs

@@ -1,21 +1,3 @@
-//! High-level interface for working with columnar data and row indices.
-//!
-//! The [`Frame`](crate::frame::Frame) type combines a matrix with column labels and a typed row
-//! index, similar to data frames in other data-analysis libraries.
-//!
-//! # Examples
-//!
-//! ```
-//! use rustframe::frame::{Frame, RowIndex};
-//! use rustframe::matrix::Matrix;
-//!
-//! // Build a frame from two columns labelled "A" and "B".
-//! 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]);
-//! assert_eq!(frame.index(), &RowIndex::Range(0..2));
-//! ```
 pub mod base;
 pub mod ops;
 

src/frame/ops.rs

@@ -1,16 +1,3 @@
-//! Trait implementations that allow [`Frame`] to reuse matrix operations.
-//!
-//! These modules forward numeric and boolean aggregation methods from the
-//! underlying [`Matrix`](crate::matrix::Matrix) type so that they can be called
-//! directly on a [`Frame`].
-//!
-//! ```
-//! 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]);
-//! ```
 use crate::frame::Frame;
 use crate::matrix::{Axis, BoolMatrix, BoolOps, FloatMatrix, SeriesOps};
 

src/matrix/boolops.rs

@@ -1,14 +1,3 @@
-//! Logical reductions for boolean matrices.
-//!
-//! The [`BoolOps`] trait mirrors common boolean aggregations such as `any` and
-//! `all` over rows or columns of a [`BoolMatrix`].
-//!
-//! ```
-//! use rustframe::matrix::{BoolMatrix, BoolOps};
-//!
-//! let m = BoolMatrix::from_vec(vec![true, false], 2, 1);
-//! assert!(m.any());
-//! ```
 use crate::matrix::{Axis, BoolMatrix};
 
 /// Boolean operations on `Matrix<bool>`

src/matrix/mat.rs

@@ -1028,7 +1028,9 @@ mod tests {
 
     #[test]
     fn test_from_rows_vec() {
-        // Matrix with rows [1, 2, 3] and [4, 5, 6]
+        // Representing:
+        // 1 2 3
+        // 4 5 6
         let rows_data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
         let matrix = Matrix::from_rows_vec(rows_data, 2, 3);
 
@@ -1040,14 +1042,19 @@ mod tests {
 
     // Helper function to create a basic Matrix for testing
     fn static_test_matrix() -> Matrix<i32> {
-        // Column-major data representing a 3x3 matrix of sequential integers
+        // Column-major data:
+        // 1 4 7
+        // 2 5 8
+        // 3 6 9
         let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9];
         Matrix::from_vec(data, 3, 3)
     }
 
     // Another helper for a different size
     fn static_test_matrix_2x4() -> Matrix<i32> {
-        // Column-major data representing a 2x4 matrix of sequential integers
+        // Column-major data:
+        // 1 3 5 7
+        // 2 4 6 8
         let data = vec![1, 2, 3, 4, 5, 6, 7, 8];
         Matrix::from_vec(data, 2, 4)
     }
@@ -1125,7 +1132,10 @@ mod tests {
 
     #[test]
     fn test_from_cols_basic() {
-        // Matrix with columns forming a 3x3 sequence
+        // Representing:
+        // 1 4 7
+        // 2 5 8
+        // 3 6 9
         let cols_data = vec![vec![1, 2, 3], vec![4, 5, 6], vec![7, 8, 9]];
         let matrix = Matrix::from_cols(cols_data);
 
@@ -1502,7 +1512,8 @@ mod tests {
 
         // Delete the first row
         matrix.delete_row(0);
-        // Resulting data should be [3, 6, 9]
+        // Should be:
+        // 3 6 9
         assert_eq!(matrix.rows(), 1);
         assert_eq!(matrix.cols(), 3);
         assert_eq!(matrix.data(), &[3, 6, 9]);

src/matrix/mod.rs

@@ -1,18 +1,3 @@
-//! Core matrix types and operations.
-//!
-//! The [`Matrix`](crate::matrix::Matrix) struct provides a simple column‑major 2D array with a
-//! suite of numeric helpers. Additional traits like [`SeriesOps`](crate::matrix::SeriesOps) and
-//! [`BoolOps`](crate::matrix::BoolOps) extend functionality for common statistics and logical reductions.
-//!
-//! # Examples
-//!
-//! ```
-//! use rustframe::matrix::Matrix;
-//!
-//! let m = Matrix::from_cols(vec![vec![1, 2], vec![3, 4]]);
-//! assert_eq!(m.shape(), (2, 2));
-//! assert_eq!(m[(0,1)], 3);
-//! ```
 pub mod boolops;
 pub mod mat;
 pub mod seriesops;

src/matrix/seriesops.rs

@@ -1,14 +1,3 @@
-//! Numeric reductions and transformations over matrix axes.
-//!
-//! [`SeriesOps`] provides methods like [`SeriesOps::sum_vertical`] or
-//! [`SeriesOps::map`] that operate on [`FloatMatrix`] values.
-//!
-//! ```
-//! use rustframe::matrix::{Matrix, SeriesOps};
-//!
-//! let m = Matrix::from_cols(vec![vec![1.0, 2.0], vec![3.0, 4.0]]);
-//! assert_eq!(m.sum_horizontal(), vec![4.0, 6.0]);
-//! ```
 use crate::matrix::{Axis, BoolMatrix, FloatMatrix};
 
 /// "Series-like" helpers that work along a single axis.
@@ -226,13 +215,20 @@ mod tests {
 
     // Helper function to create a FloatMatrix for SeriesOps testing
     fn create_float_test_matrix() -> FloatMatrix {
-        // 3x3 column-major matrix containing a few NaN values
+        // 3x3 matrix (column-major) with some NaNs
+        // 1.0  4.0  7.0
+        // 2.0  NaN  8.0
+        // 3.0  6.0  NaN
         let data = vec![1.0, 2.0, 3.0, 4.0, f64::NAN, 6.0, 7.0, 8.0, f64::NAN];
         FloatMatrix::from_vec(data, 3, 3)
     }
 
     fn create_float_test_matrix_4x4() -> FloatMatrix {
-        // 4x4 column-major matrix with NaNs inserted at positions where index % 5 == 0
+        // 4x4 matrix (column-major) with some NaNs
+        // 1.0  5.0  9.0  13.0
+        // 2.0  NaN  10.0 NaN
+        // 3.0  6.0  NaN  14.0
+        // NaN  7.0  11.0 NaN
         // first make array with 16 elements
         FloatMatrix::from_vec(
             (0..16)

src/random/crypto.rs

@@ -1,13 +1,3 @@
-//! Cryptographically secure random number generator.
-//!
-//! On Unix systems this reads from `/dev/urandom`; on Windows it uses the
-//! system's preferred CNG provider.
-//!
-//! ```
-//! use rustframe::random::{crypto_rng, Rng};
-//! let mut rng = crypto_rng();
-//! let _v = rng.next_u64();
-//! ```
 #[cfg(unix)]
 use std::{fs::File, io::Read};
 

src/random/mod.rs

@@ -1,18 +1,3 @@
-//! Random number generation utilities.
-//!
-//! Provides both a simple pseudo-random generator [`Prng`](crate::random::Prng) and a
-//! cryptographically secure alternative [`CryptoRng`](crate::random::CryptoRng). The
-//! [`SliceRandom`](crate::random::SliceRandom) trait offers shuffling of slices using any RNG
-//! implementing [`Rng`](crate::random::Rng).
-//!
-//! ```
-//! use rustframe::random::{rng, SliceRandom};
-//!
-//! let mut rng = rng();
-//! let mut data = [1, 2, 3, 4];
-//! data.shuffle(&mut rng);
-//! assert_eq!(data.len(), 4);
-//! ```
 pub mod crypto;
 pub mod prng;
 pub mod random_core;

src/random/prng.rs

@@ -1,11 +1,3 @@
-//! A tiny XorShift64-based pseudo random number generator.
-//!
-//! ```
-//! use rustframe::random::{rng, Rng};
-//! let mut rng = rng();
-//! let x = rng.next_u64();
-//! assert!(x >= 0);
-//! ```
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use crate::random::Rng;

src/random/random_core.rs

@@ -1,11 +1,3 @@
-//! Core traits for random number generators and sampling ranges.
-//!
-//! ```
-//! use rustframe::random::{rng, Rng};
-//! let mut r = rng();
-//! let value: f64 = r.random_range(0.0..1.0);
-//! assert!(value >= 0.0 && value < 1.0);
-//! ```
 use std::f64::consts::PI;
 use std::ops::Range;
 

src/random/seq.rs

@@ -1,11 +1,3 @@
-//! Extensions for shuffling slices with a random number generator.
-//!
-//! ```
-//! use rustframe::random::{rng, SliceRandom};
-//! let mut data = [1, 2, 3];
-//! data.shuffle(&mut rng());
-//! assert_eq!(data.len(), 3);
-//! ```
 use crate::random::Rng;
 
 /// Trait for randomizing slices.

src/utils/dateutils/dates.rs

@@ -1,10 +1,3 @@
-//! Generation and manipulation of calendar date sequences.
-//!
-//! ```
-//! use rustframe::utils::dateutils::dates::{DateFreq, DatesList};
-//! let list = DatesList::new("2024-01-01".into(), "2024-01-03".into(), DateFreq::Daily);
-//! assert_eq!(list.count().unwrap(), 3);
-//! ```
 use chrono::{Datelike, Duration, NaiveDate, Weekday};
 use std::collections::HashMap;
 use std::error::Error;

src/utils/dateutils/mod.rs

@@ -1,13 +1,3 @@
-//! Generators for sequences of calendar and business dates.
-//!
-//! See [`dates`] for all-day calendars and [`bdates`] for business-day aware
-//! variants.
-//!
-//! ```
-//! use rustframe::utils::dateutils::{DatesList, DateFreq};
-//! let list = DatesList::new("2024-01-01".into(), "2024-01-02".into(), DateFreq::Daily);
-//! assert_eq!(list.count().unwrap(), 2);
-//! ```
 pub mod bdates;
 pub mod dates;
 

src/utils/mod.rs

@@ -1,14 +1,3 @@
-//! Assorted helper utilities.
-//!
-//! Currently this module exposes date generation utilities in [`dateutils`](crate::utils::dateutils),
-//! including calendar and business date sequences.
-//!
-//! ```
-//! use rustframe::utils::DatesList;
-//! use rustframe::utils::DateFreq;
-//! let dates = DatesList::new("2024-01-01".into(), "2024-01-03".into(), DateFreq::Daily);
-//! assert_eq!(dates.count().unwrap(), 3);
-//! ```
 pub mod dateutils;
 
 pub use dateutils::{BDateFreq, BDatesGenerator, BDatesList};