Rinklytics: Sports Data Analytics & Public Lakehouse

NHL Analytics (Rinklytics) is an end-to-end sports analytics platform and public open-data lakehouse. It collects, cleans, models, and visualizes National Hockey League (NHL) data, uncovering tactical behaviors, physical momentum, market odds efficiencies, and player career trajectories.

All deep-dive articles and analytical methodologies are published on Substack (rinklytics.substack.com).

---

🏛️ System Scope & Architecture

The platform operates across four coordinated environments:

┌────────────────────────────────────────────────────────────────────────┐
│                        NHL API & Data Sources                          │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │ Daily Automated Pulls (09:00 & 20:00 UTC)
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   GitHub Actions Automation & CI/CD                    │
│   • Scrapes raw box scores, odds, player logs, and play-by-play events │
│   • Commits incremental updates to latest/ repository files            │
│   • Deduplicates & synchronizes typed Parquet panels to Hugging Face   │
└──────────────────┬──────────────────────────────────┬──────────────────┘
                   │                                  │
                   ▼                                  ▼
┌──────────────────────────────────────┐  ┌──────────────────────────────┐
│  🤗 Hugging Face Public Datasets     │  │  ☁️ Databricks & Cloud Lake  │
│  (jjerlee/nhl-analytics)             │  │  • Large-scale out-of-core   │
│  • 14 seasons (2013–present)         │  │    data engineering (DuckDB) │
│  • Snappy-compressed Parquet tables  │  │  • Continuous-time SSM       │
│  • Games, Odds, Plays, Hits, Players │  │    Kalman Filter estimation  │
└──────────────────┬───────────────────┘  └──────────────────────────────┘
                   │
                   ▼ Fast Parquet Streaming
┌────────────────────────────────────────────────────────────────────────┐
│                     Rinklytics Web Application                         │
│   • Live Space: https://huggingface.co/spaces/jjerlee/rinklytics       │
│   • Local Testing Container: Docker on port 1901 (localhost:1901)      │
│   • Visualizes Game Scores, Betting Odds, Hit Momentum, & Shot Maps    │
└────────────────────────────────────────────────────────────────────────┘

Core Components

Domain	Platform / Endpoint	Description
Interactive Dashboard	Hugging Face Spaces (jjerlee/rinklytics)	Live Streamlit application streaming longitudinal data directly from Hugging Face Parquet tables with zero cold-start database overhead.
Public Data Lakehouse	Hugging Face Datasets (jjerlee/nhl-analytics)	Clean, typed multi-season panel datasets (2013–2026+) covering game box scores, US/CAN closing betting odds, player game appearances, play-by-play events, and physical hit sequences.
Big Data Engineering	Databricks Workspaces	Distributed compute and ML pipelines for processing multi-million play-by-play sequences, training PyTorch state-space models, and out-of-core analytics via DuckDB.
Pipeline Automation	GitHub Actions Workflows	Daily automated cron jobs that harvest NHL API endpoints, commit data to GitHub, and trigger atomic Parquet syncs to Hugging Face.

---

🛠️ Technology Stack

Layer	Tools & Technologies
Languages	Python 3.13, Julia
Cloud & Deployment	Databricks, Hugging Face Spaces & Datasets, GitHub Actions, Docker
Data Engine & Storage	DuckDB, Pandas, PyArrow, Parquet (Snappy), Unity Catalog
Machine Learning & Modeling	PyTorch (State-Space Models & Kalman Filtering), SciPy, Scikit-learn
Visualization & App	Streamlit, Plotly Express & Graph Objects, Folium, Matplotlib, Seaborn

---

🚀 Running Locally

The dashboard runs out of the box using the pre-compiled datasets included in latest/ or streamed directly from Hugging Face Datasets.

Option A: Native Execution

# Install dependencies
uv pip install -r src/requirements/requirements.txt

# Run the Streamlit app
uv run streamlit run app/app.py

Access the application at 👉 http://localhost:8501

Option B: Isolated Docker Container (Port 1901)

# Build and run container
docker build -t rinklytics:local -f deploy/local/Dockerfile .
docker run -d --name rinklytics-local -p 1901:1901 rinklytics:local

Access the container at 👉 http://localhost:1901
(See deploy/local/README.md for full Docker and Docker Compose instructions).

---

📚 Documentation & Deep-Dive Guides

For in-depth specifications, architectural details, and research notebooks, refer to the dedicated guides:

Guide / Resource	Description
deploy/README.md	Overview of deployment environments and container architecture.
deploy/huggingface/README.md	Complete guide to Hugging Face Spaces & Datasets synchronization engines and CI/CD triggers.
deploy/huggingface/huggingface_dataset.md	Official Dataset Card, column dictionaries, schemas, and PyArrow/Polars loading examples.
deploy/local/README.md	Docker & Docker Compose setup for local container testing on port 1901.
dev/decision_science/impact_of_hits/	Continuous-time State-Space Model and Kalman filter modeling the momentum effect of physical hits.
dev/player/player_draft/	Amateur draft lifecycle analysis, survival modeling, and NCAA prospect progression.
dev/team_success/	Pythagorean expectation, Corsi/Fenwick metrics, and Elo rating betting efficiency.

---

   ,
    -   \O                                     ,  .-.___
  -     /\                                   O/  /xx\XXX\
 -   __/\ `\                                 /\  |xx|XXX|
    `    \, \_ =                          _/` << |xx|XXX|
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""