SWord Warriors Dashboard ⚔️📝

A lightweight, interactive dashboard for analyzing word statistics, specifically focused on the relationship between Word Frequency and Scrabble Scores.

Built for GitHub Pages, this tool parses a CSV dataset to provide real-time statistical analysis, histograms, and random word sampling based on user-defined skill levels and word lengths.

Google Gemini used to support implmenting code. Human ideas, AI code.

🚀 Features

• Interactive Controls:
  • Length Slider: Filter words by character count (e.g., 2-15 letters).
  • Skill Level Slider: A "volume-style" slider that filters words by frequency. As you slide towards "Expert," it includes more obscure (lower frequency) words.
• Real-Time Statistics:
  • Calculates Mean, Standard Deviation, and Quartiles (25%/50%/75%) of Scrabble scores.
  • Identifies the highest possible Scrabble score in the selection.
• Data Visualization:
  • Interactive Histogram (powered by Plotly) showing the distribution of Scrabble scores.
• Word Discovery:
  • Random Sample: Pulls 30 random words from your current filter.
  • Rare Gems: Specifically targets the bottom 10% of frequency scores to find "Obscure" and "Unknown" words (max 25).

📂 Data Format

The dashboard expects a file named SWord_Warriors_Stats.csv in the root directory.

The CSV must contain the following headers:

Header	Type	Description
word	String	The actual word.
WordFreq_Score	Float	Frequency score (8.0 = Common, 0.0 = Rare).
Scrabble_Score	Integer	The calculated Scrabble score.
Length	Integer	The character count of the word.

Example CSV Content:

word,WordFreq_Score,Scrabble_Score,Length
AA,4.01,2,2
AAH,2.81,6,3
AAHED,0.0,9,5
ZYZYGY,0.0,25,6

## 🛠️ Installation & Usage

### Option 1: GitHub Pages (Recommended)

1. Fork or Clone this repository.
2. Ensure your `SWord_Warriors_Stats.csv` is in the main folder.
3. Go to **Settings** > **Pages**.
4. Under **Source**, select `Deploy from a branch` and choose `main` (or `master`).
5. Visit the provided URL.

### Option 2: Running Locally

Due to browser security policies (CORS), you cannot simply double-click `index.html` to load the CSV file. You must run a local server.

**Using Python:**

1. Open your terminal/command prompt in the project folder.
2. Run:
```bash
python -m http.server

3. Open your browser to http://localhost:8000.

Using VS Code:

1. Install the "Live Server" extension.
2. Right-click index.html and select "Open with Live Server".

🎚️ How the Skill Slider Works

The "Word Skill Level" slider controls the WordFreq_Score threshold. It operates inversely to frequency:

• Low (Slider at 0%): Sets threshold to ~8.0. Only allows extremely common words.
• Expert (Slider at 100%): Sets threshold to ~0.0. Allows all words, including the most obscure.

Legend:

• 8.0: Ubiquitous (Very Common)
• 6.0: Conversational
• 4.0: Literate
• 2.0: Obscure
• 0.0: Unknown (Very Rare)

🧰 Technologies Used

• HTML5 / CSS3: Responsive layout and styling.
• PapaParse: Fast in-browser CSV parsing.
• Plotly.js: Interactive charting and histograms.
• noUiSlider: Multi-handle range sliders.

Here is the Markdown section ready for your README.

---

Source File Generation

This project utilizes a Python utility script (scorer.py) to generate an enriched dataset from a raw list of words. The script ingests a simple CSV of words and appends metadata required for analysis and filtering, specifically word frequency, game score, and character length.

Data Origin

The raw dictionary file used to seed this generation process was sourced from the scrabble-buddy repository:

• Source: https://github.com/AdelBeit/scrabble-buddy/blob/main/scrabble-dictionary.csv

How It Works

The generation script performs the following operations on the input CSV:

1. Ingestion: Reads the raw input file (assuming the words are located in the first column).
2. Scoring & Metrics:

• WordFreq Score: Utilizes the wordfreq library to assign a Zipf frequency score (0.0–8.0), where higher numbers indicate more common usage in the English language.
• Scrabble Score: Calculates the point value of the word based on standard Scrabble rules (e.g., A=1, Q=10).
• Length: Computes the character count of the word.

3. Export: Generates a clean output CSV with exactly four columns:

• Word
• WordFreq_Score
• Scrabble_Score
• Length

Usage

To regenerate the source file, run the script from the terminal with the input and desired output filenames:

python scorer.py scrabble-dictionary.csv processed_dictionary.csv

Scrabble Point Reference

The scoring logic applies the following values per letter:

• 1 point: E, A, I, O, N, R, T, L, S, U
• 2 points: D, G
• 3 points: B, C, M, P
• 4 points: F, H, V, W, Y
• 5 points: K
• 8 points: J, X
• 10 points: Q, Z

📄 License

This project is open source. Feel free to modify and use it for your own word analysis projects.