Add descriptive statistics tool

.claude/CLAUDE.md

@@ -20,7 +20,7 @@ MatHud pairs a canvas with an AI assistant so users can sketch geometric scenes,
 2. Geometry primitives: create, edit, and relate points, segments, vectors, triangles, rectangles, circles, ellipses, and angles.
 3. Mathematics: evaluate expressions, solve equations, differentiate, integrate, work with complex numbers, and run statistical routines.
 4. Graph theory: create graphs, trees, DAGs; run analyses (shortest path, MST, topological sort, BFS/DFS).
-5. Statistics: plot probability distributions (normal, discrete) and bar charts.
+5. Statistics: plot probability distributions (normal, discrete) and bar charts; compute descriptive statistics (mean, median, mode, quartiles, etc.).
 6. Workspace operations: save, load, list, delete, import, and export named workspaces.
 
 ## Key References
@@ -353,6 +353,7 @@ For features that extend existing managers (e.g., `fit_regression` in `Statistic
 ## Statistics
 - `plot a continuous normal distribution with mean 0 and sigma 1, shade from -1 to 1`
 - `plot a bar chart with values [10, 20, 5] and labels ["A", "B", "C"]`
+- `compute descriptive statistics for [10, 20, 30, 40, 50]`
 
 ## Parametric Curves
 - `draw a parametric circle with x(t) = cos(t) and y(t) = sin(t)`

README.md

@@ -18,13 +18,14 @@ MatHud pairs an interactive drawing canvas with an AI assistant to help visualiz
 3. Plot functions, compare intersections, shade bounded regions, and translate/rotate objects to explore relationships visually.
 4. Plot statistics visualizations (probability distributions and bar charts).
 5. Fit regression models to data (linear, polynomial, exponential, logarithmic, power, logistic, sinusoidal) and visualize fitted curves with R² statistics.
-6. Create and analyze graph theory graphs (graphs, trees, DAGs).
-7. Save, list, load, and delete named workspaces so projects can be resumed or shared later.
-8. Share the current canvas with the assistant using Vision mode to get feedback grounded in your drawing.
-9. Attach images directly to chat messages for the AI to analyze alongside your prompts.
-10. Use slash commands (`/help`, `/vision`, `/model`, `/image`, etc.) for quick local operations without waiting for an AI response.
-11. Choose from multiple AI providers — OpenAI, Anthropic (Claude), and OpenRouter — with the model dropdown automatically filtered by which API keys you have configured.
-12. Trigger client-side tests from the UI or chat to verify canvas behavior without leaving the app.
+6. Compute descriptive statistics (mean, median, mode, standard deviation, variance, min, max, quartiles, IQR) for any dataset.
+7. Create and analyze graph theory graphs (graphs, trees, DAGs).
+8. Save, list, load, and delete named workspaces so projects can be resumed or shared later.
+9. Share the current canvas with the assistant using Vision mode to get feedback grounded in your drawing.
+10. Attach images directly to chat messages for the AI to analyze alongside your prompts.
+11. Use slash commands (`/help`, `/vision`, `/model`, `/image`, etc.) for quick local operations without waiting for an AI response.
+12. Choose from multiple AI providers — OpenAI, Anthropic (Claude), and OpenRouter — with the model dropdown automatically filtered by which API keys you have configured.
+13. Trigger client-side tests from the UI or chat to verify canvas behavior without leaving the app.
 
 ## 3. Architecture Overview
 
@@ -135,11 +136,12 @@ Developer utilities:
    8. `plot a normal distribution with mean 0 and sigma 1, continuous, shade from -1 to 1`
    9. `plot a bar chart with values [10,20,5] and labels ["A","B","C"]`
    10. `fit a linear regression to x_data=[1,2,3,4,5] and y_data=[2,4,6,8,10], show points and report R²`
-   11. `create an undirected weighted graph named G1 with vertices A,B,C,D and edges A-B (1), B-C (2), A-C (4), C-D (1)`
-   12. `on graph G1, find the shortest path from A to D and highlight the edges`
-   13. `create a DAG named D1 with vertices A,B,C,D and edges A->B, A->C, B->D, C->D; then topologically sort it`
-   14. `save workspace as "demo"` / `load workspace "demo"`
-   15. `run tests`
+   11. `compute descriptive statistics for [10, 20, 30, 40, 50]`
+   12. `create an undirected weighted graph named G1 with vertices A,B,C,D and edges A-B (1), B-C (2), A-C (4), C-D (1)`
+   13. `on graph G1, find the shortest path from A to D and highlight the edges`
+   14. `create a DAG named D1 with vertices A,B,C,D and edges A->B, A->C, B->D, C->D; then topologically sort it`
+   15. `save workspace as "demo"` / `load workspace "demo"`
+   16. `run tests`
 
 ### 6.3 Slash Commands
 

documentation/Example Prompts.txt

@@ -72,6 +72,11 @@ Shear the rectangle horizontally by factor 0.5 from the origin.
 Rotate triangle ABC by 45 degrees around point (2, 3).
 Rotate point A by 90 degrees around the origin.
 
+# Descriptive Statistics
+Compute descriptive statistics for the dataset [10, 20, 30, 40, 50].
+Give me the mean, median, and standard deviation of [3, 7, 7, 2, 9, 4, 1].
+What are the quartiles and IQR for the values [12, 15, 18, 22, 25, 30, 35, 40]?
+
 # Regression Analysis
 Fit a linear regression to x_data=[1,2,3,4,5] and y_data=[2.1,3.9,6.2,7.8,10.1]. Show the data points and fitted curve.
 Fit a quadratic polynomial (degree 2) to x_data=[0,1,2,3,4] and y_data=[0,1,4,9,16]. Report the R-squared value.

documentation/Reference Manual.txt

@@ -316,6 +316,7 @@ Attributes:
 - `plot_distribution(name=None, representation="continuous", distribution_type="normal", distribution_params=None, plot_bounds=None, shade_bounds=None, curve_color=None, fill_color=None, fill_opacity=None, bar_count=None)`: Plot a probability distribution. For representation="continuous", `plot_bounds` controls the curve domain, while `shade_bounds` controls the shaded interval under the curve (clamped into `plot_bounds`). For representation="discrete", `plot_bounds` controls the bar span and `shade_bounds` is ignored. Discrete distribution plots create a `DiscretePlot` composite plus derived `Bar` drawables for rendering; derived bars are regenerated on workspace load and may be omitted from serialized canvas state to keep prompts compact.
 - `plot_bars(name=None, values=None, labels_below=None, labels_above=None, bar_spacing=None, bar_width=None, stroke_color=None, fill_color=None, fill_opacity=None, x_start=None, y_base=None)`: Plot a bar chart (`BarsPlot` composite plus derived `Bar` drawables). Derived bars are regenerated on workspace load and may be omitted from serialized canvas state to keep prompts compact.
 - `fit_regression(name=None, x_data=None, y_data=None, model_type="linear", degree=None, plot_bounds=None, curve_color=None, show_points=True, point_color=None)`: Fit a regression model to data and plot the resulting curve. Supported model types: "linear" (y=mx+b), "polynomial" (y=a0+a1*x+...+an*x^n, requires `degree`), "exponential" (y=a*e^(bx), requires positive y), "logarithmic" (y=a+b*ln(x), requires positive x), "power" (y=a*x^b, requires positive x and y), "logistic" (y=L/(1+e^(-k(x-x0)))), and "sinusoidal" (y=a*sin(bx+c)+d, requires at least 4 points). Returns function_name, expression, coefficients, r_squared, model_type, bounds, and optionally point_names. Use `delete_function` to remove the curve; delete points individually.
+- `compute_descriptive_statistics(data)`: Compute descriptive statistics for a list of numbers. Returns a dictionary with: count, mean, median, mode (list of values; empty if no meaningful mode), standard_deviation (population), variance (population), min, max, q1 (first quartile), q3 (third quartile), iqr (interquartile range), and range. Quartiles use the median-of-halves (exclusive) method. All values must be finite (no Infinity or NaN).
 - `delete_plot(name)`: Delete a plot composite created by plot_distribution/plot_bars, including its derived components.
 - `zoom_to_bounds(left_bound, right_bound, top_bound, bottom_bound)`: Fit the viewport so the specified math-space rectangle is entirely visible while preserving aspect ratio
 - `create_colored_area(drawable1_name, drawable2_name=None, left_bound=None, right_bound=None, color="lightblue", opacity=0.3)`: Create a colored area between two objects
@@ -4507,6 +4508,27 @@ Key Features:
 
 ### Statistics Utilities
 
+#### Descriptive Statistics (`utils/statistics/descriptive.py`)
+
+```
+Descriptive statistics computation module.
+
+Key Features:
+    - Mean, median, mode computation
+    - Population standard deviation and variance
+    - Min, max, range
+    - Quartiles (Q1, Q3) via median-of-halves (exclusive) method
+    - Interquartile range (IQR)
+    - Input validation (non-empty, finite, numeric)
+    - No browser imports — fully testable with pytest
+```
+
+**Key Functions:**
+- `compute_descriptive_statistics(data)`: Compute all descriptive statistics for a list of numbers. Returns a `DescriptiveStatisticsResult` TypedDict with count, mean, median, mode, standard_deviation, variance, min, max, q1, q3, iqr, and range.
+
+**Key Types:**
+- `DescriptiveStatisticsResult(TypedDict)`: Result dict with fields: `count` (int), `mean` (float), `median` (float), `mode` (List[float]), `standard_deviation` (float), `variance` (float), `min` (float), `max` (float), `q1` (float), `q3` (float), `iqr` (float), `range` (float).
+
 #### Distribution Expressions (`utils/statistics/distributions.py`)
 
 ```
@@ -4545,13 +4567,14 @@ Key Features:
 #### Statistics Manager (`managers/statistics_manager.py`)
 
 ```
-Statistics manager for probability distributions and regression plots.
+Statistics manager for probability distributions, regression plots, and descriptive statistics.
 
 Key Features:
     - Continuous distribution plots with PDF curves and shaded areas
     - Discrete distribution plots using bar elements
     - Custom bar chart creation with values and labels
     - Regression fitting (linear, polynomial, exponential, etc.)
+    - Descriptive statistics computation (mean, median, mode, std dev, quartiles, etc.)
     - Plot deletion with proper cleanup of constituent drawables
     - Workspace restore via plot materialization methods
 ```
@@ -4560,6 +4583,7 @@ Key Features:
 - `plot_distribution(name, representation, distribution_type, ...)`: Create continuous or discrete distribution plots
 - `plot_bars(name, values, labels_below, labels_above, ...)`: Create custom bar charts
 - `fit_regression(name, x_data, y_data, model_type, ...)`: Fit regression models to data
+- `compute_descriptive_statistics(data)`: Compute summary statistics (count, mean, median, mode, std dev, variance, min, max, Q1, Q3, IQR, range)
 - `delete_plot(name)`: Delete a plot and all its constituent drawables
 
 **Supported Regression Model Types:**