How lblommesteyn/canada_basketball_fiba works
Project type and purpose
• This is a data-analysis pipeline (an open-source tool) that ingests FIBA play-by-play CSVs, runs a series of models (win-probability, Δ-WPA), a Monte Carlo analysis, and produces figures and CSV outputs.
• It’s invoked via a CLI (timeout_pipeline.py) and configured with config.json and the CSVs in data/.
File structure
• Top-level:
• data/ – raw input CSV files
• timeout_pipeline.py (aka timeout_analysis_pipeline.py) – the orchestration entry point
• requirements.txt – Python dependencies
• config.json – pipeline parameters
• old_analysis_and_testing/ – exploratory notebooks and scripts (archival)
• README.md, Summary.md, technotes_and_hiccups.md – documentation
• No “frontend” or “backend” per se—this is a batch pipeline with modular stages.
README for additional insights
• Describes 5 key steps:
1. ETL (load & clean)
2. Win-Probability logistic model
3. Δ-WPA Gradient-Boosting regressor
4. Monte Carlo “traffic lights”
5. Figures (heat-map, charts, cumulative gain)
• Outputs go to an outputs/ directory at runtime.
Main components and interactions
a. Data Store
• Raw CSVs in data/
• Config in config.json
b. ETL Module
• Reads CSVs with pandas, cleans and normalizes events
• Produces a master DataFrame passed downstream
c. Win-Prob Model Module
• Fits or loads a logistic regression on score_diff, time_remaining, period_num
• Appends wp (win probability) column
d. Δ-WPA Regressor Module
• Uses gradient boosting (e.g., XGBoost or sklearn’s GBM) to predict changes in win probability given context features (runs, timeouts left)
e. Monte Carlo Module
• Bootstraps residuals of Δ-WPA model to assign green/yellow/red flags
f. Visualization / Reporting Module
• Generates heat-map, situational bar charts, cumulative gain plots (matplotlib/seaborn)
g. Outputs
• Final CSVs and figures land in outputs/
Architectural patterns and design principles
• Modular pipeline: each stage is its own Python function or class
• Single orchestration script (CLI) that wires modules together
• Configuration-driven (via config.json) rather than hard‐coded
• Clear separation of “analysis experiments” (old_analysis_and_testing/) vs. “production pipeline”
Important reminders
• Be very detailed: break the Δ-WPA stage into “feature engineering” vs. “model training vs. prediction” if desired
• Configuration inputs (CLI args, config.json)
• Do not overthink: maximize clarity by showing every discrete component and its connections