From 4af584a748c2a7d45f629251ea3c3d9b63f82f51 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Sat, 26 Apr 2025 02:35:38 +0100
Subject: [PATCH] Revise README.md for clarity and structure; enhance
 documentation and quick start section

---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 67 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a1e4d0b..0388311 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,74 @@
 # rustframe
 
-___
-[![github-homepage](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) [![tarpaulin-badge](https://img.shields.io/endpoint?url=https://magnus167.github.io/rustframe/rustframe/tarpaulin-badge.json)](https://magnus167.github.io/rustframe/rustframe/tarpaulin-report.html)
-___
+📚 [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/)
 
-A simple dataframe library.
+<!-- [![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/rustframe/tarpaulin-badge.json)](https://magnus167.github.io/rustframe/rustframe/tarpaulin-report.html)
 
-Link to documentation: [https://magnus167.github.io/rustframe/](https://magnus167.github.io/rustframe/)
+---
 
-Link to GitHub repo: [https://github.com/Magnus167/rustframe](https://github.com/Magnus167/rustframe)
+## Rustframe: *A lightweight dataframe helper for Rust*
 
-Link to crates.io: [https://crates.io/crates/rustframe](https://crates.io/crates/rustframe)
+Rustframe is a simple dataframe helper for simple math and data manipulation in Rust.
 
-Link to Gitea Mirror: [https://gitea.nulltech.uk/Magnus167/rustframe](https://gitea.nulltech.uk/Magnus167/rustframe)
+Rustframe keeps things simple, safe, and readable. It is handy for quick numeric experiments and small analytical tasks, but it is **not** meant to compete with powerhouse crates like `polars` or `ndarray`.
+
+### What it offers
+
+- **Math that reads like math** – element‑wise `+`, `−`, `×`, `÷` on entire frames or scalars.
+- **Broadcast & reduce** – sum, product, any/all across rows or columns without boilerplate.
+- **Boolean masks made simple** – chain comparisons, combine with `&`/`|`, get a tidy `BoolMatrix` back.
+- **Date‑centric row index** – business‑day ranges and calendar slicing built in.
+- **Pure safe Rust** – 100 % safe, zero `unsafe`.
+
+### Heads up
+
+- **Not memory‑efficient (yet)** – footprint needs work.
+- **Feature set still small** – expect missing pieces.
+
+### On the horizon
+
+- Optional GPU help (Vulkan or similar) for heavier workloads.
+- Straightforward Python bindings using `pyo3`.
+
+---
+
+## Quick start
+
+```rust
+use chrono::NaiveDate;
+use rustframe::{
+    frame::{Frame, RowIndex},
+    matrix::{BoolOps, Matrix, SeriesOps},
+    utils::{BDateFreq, BDatesList},
+};
+
+let n_periods = 4;
+
+// Four business days starting 2024‑01‑02
+a let dates: Vec<NaiveDate> =
+    BDatesList::from_n_periods("2024-01-02", BDateFreq::Daily, n_periods)
+        .unwrap()
+        .list()
+        .unwrap();
+
+let col_names = vec!["a".into(), "b".into()];
+
+let ma = Matrix::from_cols(vec![
+    vec![1.0, 2.0, 3.0, 4.0],
+    vec![5.0, 6.0, 7.0, 8.0],
+]);
+let mb = Matrix::from_cols(vec![
+    vec![4.0, 3.0, 2.0, 1.0],
+    vec![8.0, 7.0, 6.0, 5.0],
+]);
+
+let fa = Frame::new(ma, col_names.clone(), Some(RowIndex::Date(dates.clone())));
+let fb = Frame::new(mb, col_names, Some(RowIndex::Date(dates)));
+
+// Math that reads like math
+let result = &fa * &fb;            // element‑wise multiply
+let total = result.matrix().sum_vertical().iter().sum::<f64>();
+assert_eq!(total, 184.0);
+```