tweaks to docs

Author: pranav-walimbe

README.md

@@ -278,18 +278,16 @@ The empirical constants ($c_{\text{scan}}$, $c_{\text{tree}}$, $c_{\text{grid}}$
 `select_index` is a rule-based pre-filter that picks a candidate index type:
 
 ```mermaid
-flowchart LR
+flowchart TD
     A[Query arrives] --> B{N < 500\nor sel > 50%?}
     B -- yes --> BF[Brute force]
-    B -- no --> C{kNN and\nk/N > 10%?}
+    B -- no --> C{kNN with\nk/N > 10%?}
     C -- yes --> BF
     C -- no --> D{Polygon\ndataset?}
     D -- yes --> RT[R-tree]
-    D -- no --> E{Query type}
-    E -- kNN / contains --> KD[KD-tree]
-    E -- range --> F{Uniform?}
-    F -- yes --> GR[Grid]
-    F -- no --> KD
+    D -- no --> E{Range query\nand uniform?}
+    E -- yes --> GR[Grid]
+    E -- no --> KD[KD-tree]
 ```
 
 All index types share the same coordinate arrays with no duplication.

docs/api/lazy-frame.md

@@ -1,6 +1,6 @@
 # SpatialLazyFrame
 
-`SpatialLazyFrame` is an immutable plan builder. Operations can be declared in any order — the optimizer reorders, fuses, and pushes them down before execution. Nothing runs until `.collect()` is called.
+`SpatialLazyFrame` is an immutable plan builder. Operations can be declared in any order. The optimizer reorders, fuses, and pushes them down before execution. Nothing runs until `.collect()` is called.
 
 `SpatialGroupBy` is returned by `.group_by()` and holds the keys for a fused aggregate-join.
 

docs/how-it-works/execution-paths.md

@@ -16,7 +16,7 @@ The EXPR path keeps the spatial engine inside Polars' processing loop, allowing
 
 ## IO path
 
-Used when few results are expected (low selectivity — e.g. a tight bounding box or a point-in-polygon query on a sparse dataset). The index is queried directly, and the result row indices are used to slice the DataFrame:
+Used when few results are expected (low selectivity, e.g. a tight bounding box or a point-in-polygon query on a sparse dataset). The index is queried directly, and the result row indices are used to slice the DataFrame:
 
 ```
 index.range_query(bbox) → [i, j, k, ...]  →  df[i, j, k, ...]
@@ -26,7 +26,7 @@ No Polars expression pipeline is involved. This avoids the overhead of batch pro
 
 ## Polars / PyO3 integration
 
-The Rust engine is compiled as a PyO3 extension (`pycanopy._core`). Coordinate arrays are passed as zero-copy numpy views at the Python/Rust boundary — no allocation occurs for the handoff. The index structures themselves (KD-tree, R-tree, grid) are packed immutable Rust structs that live for the lifetime of the `Engine` object.
+The Rust engine is compiled as a PyO3 extension (`pycanopy._core`). Coordinate arrays are passed as zero-copy numpy views at the Python/Rust boundary. No allocation occurs for the handoff. The index structures themselves (KD-tree, R-tree, grid) are packed immutable Rust structs that live for the lifetime of the `Engine` object.
 
 For the EXPR path, the plugin is registered via Polars' `register_plugin_function` API, which lets the Rust closure participate in Polars' lazy evaluation graph natively.
 

docs/how-it-works/query-planner.md

@@ -13,15 +13,15 @@ The optimizer runs a fixed sequence of passes over the plan:
 
 **1. Selectivity estimation**
 
-Each node is annotated with an estimated selectivity — the fraction of the dataset expected to survive. Scalar Polars filters get an estimate from column statistics; spatial predicates use the cost model's histogram or kNN ratio.
+Each node is annotated with an estimated selectivity, the fraction of the dataset expected to survive. Scalar Polars filters get an estimate from column statistics; spatial predicates use the cost model's histogram or kNN ratio.
 
 **2. Predicate pushdown**
 
 Scalar `filter()` nodes are sunk to the bottom of the plan so they run first, reducing the row count before any spatial work begins. A scalar filter that eliminates 90% of rows makes every subsequent spatial operation 10x cheaper.
 
 **3. Cost-sort**
 
-Spatial predicates are reordered by ascending estimated output size. Cheaper, more selective predicates run earlier. kNN and join nodes act as barriers — no reordering crosses them.
+Spatial predicates are reordered by ascending estimated output size. Cheaper, more selective predicates run earlier. kNN and join nodes act as barriers. No reordering crosses them.
 
 **4. Filter fusion**
 
@@ -39,7 +39,5 @@ A terminal `.select(cols)` is pinned as the last node and its column set is prop
 
 After optimization, the executor picks one of two execution strategies per node:
 
-- **IO path** — used when selectivity is low (few results expected). The index is queried directly and the result is returned as a slice of the DataFrame. No Polars expression pipeline is involved.
-- **EXPR path** — used when selectivity is high. The spatial closure runs as a Polars `map_batches` plugin, processing the DataFrame in batches. Scalar filters run first inside the batch, then the spatial query runs on the surviving rows.
-
-The optimizer annotates each node with the chosen path based on the selectivity threshold from the cost model.
+- **IO path**: used when selectivity is low (few results expected). The index is queried directly and the result is returned as a slice of the DataFrame. No Polars expression pipeline is involved.
+- **EXPR path**: used when selectivity is high. The spatial closure runs as a Polars `map_batches` plugin, processing the DataFrame in batches. Scalar filters run first inside the batch, then the spatial query runs on the surviving rows.

docs/how-it-works/streaming.md

@@ -10,7 +10,7 @@ The probe side of any join is sliced into fixed-size chunks called morsels:
 MORSEL_ROWS = 262_144  # 256K rows per morsel
 ```
 
-Morsels are produced via `iter_slices` — a zero-copy operation that yields views into the probe DataFrame without copying data. Each morsel is joined independently against the full index, and its result is either yielded, accumulated, or written to disk depending on the collection method.
+Morsels are produced via `iter_slices`, a zero-copy operation that yields views into the probe DataFrame without copying data. Each morsel is joined independently against the full index, and its result is either yielded, accumulated, or written to disk depending on the collection method.
 
 ## collect()
 
@@ -39,7 +39,7 @@ sf.lazy().polygon_knn_join(trips, "lon", "lat", k=5).sink_parquet("result.parque
 
 ## lazy_source()
 
-Exposes the join result as a native Polars `LazyFrame` source. This lets you fuse spatial join output with downstream Polars operations — sorts, sinks, further filters — into a single spilling pipeline:
+Exposes the join result as a native Polars `LazyFrame` source. This lets you fuse spatial join output with downstream Polars operations (sorts, sinks, further filters) into a single spilling pipeline:
 
 ```python
 (
@@ -52,8 +52,8 @@ Exposes the join result as a native Polars `LazyFrame` source. This lets you fus
 )
 ```
 
-Polars handles spilling to disk for the sort if the result exceeds memory, so the entire pipeline — join, select, sort, write — never requires the full result to be in RAM at once.
+Polars handles spilling to disk for the sort if the result exceeds memory, so the entire pipeline (join, select, sort, write) never requires the full result to be in RAM at once.
 
 ## Aggregate-join streaming
 
-`.group_by(keys).agg(...)` reduces over the morsel stream using associative partial aggregations. Each morsel produces per-group partials (counts, sums, etc.) that are combined across morsels at the end. The full pair frame never materialises — only the per-group accumulators are held in memory, which are bounded by the number of unique groups rather than the number of join pairs.
+`.group_by(keys).agg(...)` reduces over the morsel stream using associative partial aggregations. Each morsel produces per-group partials (counts, sums, etc.) that are combined across morsels at the end. The full pair frame never materialises. Only the per-group accumulators are held in memory, bounded by the number of unique groups rather than the number of join pairs.

docs/index.md

@@ -4,7 +4,7 @@ A declarative spatial query layer for Polars. Rust core, Python API.
 
 ## What is PyCanopy
 
-PyCanopy brings spatial queries — range, kNN, joins, polygon containment — into the Polars ecosystem without leaving Python. You declare operations in any order; the query planner reorders, fuses, and pushes them down before execution. The index type (KD-tree, R-tree, grid, or brute force) is selected automatically by a cost model calibrated to your hardware.
+PyCanopy brings spatial queries (range, kNN, joins, polygon containment) into the Polars ecosystem without leaving Python. You declare operations in any order; the query planner reorders, fuses, and pushes them down before execution. The index type (KD-tree, R-tree, grid, or brute force) is selected automatically by a cost model calibrated to your hardware.
 
 ## Why PyCanopy
 

docs/quickstart.md

@@ -83,7 +83,7 @@ print(lf.explain())
 #     DF [N=100,000; path: EXPR]
 ```
 
-The optimizer flipped the declaration order — scalar filter runs first, spatial query runs on the smaller survivor set.
+The optimizer flipped the declaration order: scalar filter runs first, spatial query runs on the smaller survivor set.
 
 ## Streaming large results
 
@@ -115,7 +115,7 @@ sf = SpatialFrame(df, x_col="lon", y_col="lat", index_mode="auto")
 ```python
 import numpy as np
 
-# Append new points — visible to queries immediately, no index rebuild
+# Append new points, visible to queries immediately with no index rebuild
 sf.engine.append_delta(np.array([2.5]), np.array([48.9]))
 result = sf.lazy().range_query(-10.0, 35.0, 40.0, 70.0).collect()