Stop studying everything. Start studying what matters.
Score Impact Analyzer uses the official Digital SAT adaptive scoring model to simulate every "what if I had answered this correctly?" scenario — and ranks the results. In seconds, you know exactly which questions were worth the most points.
- Why This Tool
- How It Works
- Features
- Architecture
- Installation
- Configuration
- Usage
- Output Example
- Security & Privacy
- Roadmap
- Contributing
- License
The Digital SAT is adaptive: Module 1 performance determines whether a student gets the easy or hard Module 2 — and that single routing decision can swing the final score by 60+ points. Standard practice tools ignore this cascade effect entirely.
Score Impact Analyzer doesn't. It models the full adaptive pipeline so tutors and students can identify not just which questions a student missed, but which misses had systemic, score-multiplying consequences.
Student Attempt Data ──► Module 1 Analysis ──► Cascade Simulation
│ │
│ ┌────────────────────────────────── │
│ │ For each incorrect answer: │
▼ │ 1. Flip to correct │
Scoring Model │ 2. Recalculate M2 routing │
(DSAT v2 JSON) │ 3. Recompute scaled score │
│ │ 4. Record Δscore │
└──────────────┴──► Ranked Impact List ──► Output
| Feature | Description |
|---|---|
| 📊 Score Simulation | Simulates score changes for every missed question |
| 🔀 Cascade Detection | Identifies Module 1 misses that would change Module 2 routing |
| 🏆 Impact Ranking | Ranks questions by score-point upside |
| 📚 Dual-Subject Analysis | Separate pipelines for Math and Reading & Writing |
| 🎯 Topic Clustering | Groups high-impact questions by skill/topic |
| Feature | Description |
|---|---|
| 📄 Report Export | Save results as CSV or JSON for further analysis |
| 🔒 Secure Config | Environment-variable based secrets (no hardcoded credentials) |
| 🔁 Retry Logic | Exponential backoff for MongoDB connection failures |
| 🧪 Input Validation | Schema-validated JSON loading with descriptive errors |
| 🛡️ Privacy-Safe Logging | Student IDs are never logged in plaintext |
| 📈 Batch Processing | Analyze multiple students in a single run |
| ⚙️ Configurable Thresholds | Adjust adaptive routing thresholds without touching code |
| 📝 Structured Logging | JSON-formatted logs with severity levels |
score-impact-analyzer/
│
├── main.py # Entry point — orchestrates analysis pipeline
├── config.py # Centralised config (env vars + defaults)
├── analyzer/
│ ├── __init__.py
│ ├── adaptive.py # Adaptive/cascade scoring logic
│ ├── scorer.py # Raw → scaled score lookup
│ └── reporter.py # CSV / JSON export
├── db/
│ ├── __init__.py
│ └── mongo_client.py # Connection pooling + retry logic
├── utils/
│ ├── __init__.py
│ ├── logger.py # Structured logging setup
│ └── validators.py # JSON schema validation
│
├── data/ # (gitignored) — student attempt files go here
├── scoring_DSAT_v2.json # Official DSAT scoring model
│
├── requirements.txt # Pinned dependencies
├── .env.example # Environment variable template
├── .gitignore # Protects secrets and data files
├── SECURITY.md # Vulnerability reporting & security practices
└── README.md # You are here
- Python 3.8+
- MongoDB 6.0+ (local or Atlas)
piporpipenv
# 1. Clone
git clone https://github.com/PRATHAM777P/score-impact-analyzer.git
cd score-impact-analyzer
# 2. Create a virtual environment (strongly recommended)
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Set up environment variables
cp .env.example .env
# → Edit .env with your MongoDB URI and any custom settingsAll settings are loaded from environment variables. Copy .env.example to .env and fill in your values:
# .env.example — copy to .env, never commit .env to git
MONGO_URI=mongodb://localhost:27017/
MONGO_DB_NAME=sat_analysis
# Adaptive routing threshold (0.0 – 1.0, default 0.5)
ADAPTIVE_THRESHOLD=0.5
# Path to student attempt data directory
DATA_DIR=./data
# Log level: DEBUG | INFO | WARNING | ERROR
LOG_LEVEL=INFO
# Export format: csv | json | both | none
EXPORT_FORMAT=csv
EXPORT_DIR=./reports
⚠️ Never commit your.envfile. It is already in.gitignore.
python main.pypython main.py --student-id <your_student_id>python main.py --batchpython main.py --batch --export csv --output ./reportspython main.py --threshold 0.6usage: main.py [-h] [--student-id ID] [--batch] [--threshold FLOAT]
[--export {csv,json,both,none}] [--output DIR] [--log-level LEVEL]
optional arguments:
--student-id ID Analyze a single student by ID
--batch Analyze all student files in DATA_DIR
--threshold FLOAT Module 2 routing threshold (default: 0.5)
--export FORMAT Export results (csv | json | both | none)
--output DIR Directory for exported reports
--log-level LEVEL Logging verbosity (DEBUG | INFO | WARNING | ERROR)
╔══════════════════════════════════════════════════════╗
║ Score Impact Analyzer — v2.0 ║
╚══════════════════════════════════════════════════════╝
[Student: s***1] Subject: Reading & Writing
──────────────────────────────────────────────────────
Current Score : 650 │ Module 2 assigned : HARD
Top 5 High-Impact Module 1 Questions
┌─────┬──────────────────────────────────┬──────────┬──────────────────────┐
│ # │ Topic │ +Points │ Notes │
├─────┼──────────────────────────────────┼──────────┼──────────────────────┤
│ 1 │ Text structure and purpose │ +20 │ │
│ 2 │ Text structure and purpose │ +20 │ │
│ 3 │ Command of evidence (textual) │ +10 │ │
│ 4 │ Words in context │ +10 │ │
│ 5 │ Inferences │ +10 │ │
└─────┴──────────────────────────────────┴──────────┴──────────────────────┘
[Student: s***1] Subject: Math
──────────────────────────────────────────────────────
Current Score : 520 │ Module 2 assigned : EASY
Top 5 High-Impact Module 1 Questions
┌─────┬──────────────────────────────────┬──────────┬──────────────────────┐
│ # │ Topic │ +Points │ Notes │
├─────┼──────────────────────────────────┼──────────┼──────────────────────┤
│ 1 │ Advanced Math │ +60 │ ⚡ M2→HARD (cascade) │
│ 2 │ Nonlinear functions │ +20 │ │
│ 3 │ Linear equations (one var.) │ +10 │ │
│ 4 │ Systems of equations │ +10 │ │
│ 5 │ Ratios, rates & proportions │ +10 │ │
└─────┴──────────────────────────────────┴──────────┴──────────────────────┘
This project handles sensitive educational data. The following safeguards are built in:
- No hardcoded credentials — all secrets via environment variables
- Data directory is gitignored — student attempt files never reach version control
- Student IDs are masked in all log output (
s***1, not the raw ID) - Input validation — all JSON files are schema-validated before being inserted into MongoDB
- MongoDB connection uses a connection pool with configurable timeouts, not a raw persistent socket
- No telemetry — this tool makes zero outbound network calls except to your own MongoDB instance
For vulnerability reporting, see SECURITY.md.
- Web dashboard — Flask/FastAPI UI for non-technical tutors
- Module 2 analysis — extend impact ranking to Module 2 questions
- Topic heatmaps — visual breakdown of skill gaps
- Multi-test trend — track score trajectory across multiple practice tests
- PDF report generation — shareable one-page student summaries
- MongoDB Atlas support — plug-and-play cloud deployment
Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.
# Fork → clone → branch → change → test → PR
git checkout -b feature/your-feature-namePlease make sure your code passes flake8 and includes appropriate tests.
MIT © 2026 — Score Impact Analyzer contributors
Built for students. Powered by data. Designed for impact.
⭐ Star this repo if it helps your students!