Qué es
FutViz es un proyecto de ciencia de datos deportiva sobre las 5 grandes ligas europeas
de fútbol, temporada 2025/2026.
Arranca con un EDA (análisis exploratorio) a nivel de equipo y de jugador, con la idea
de ir subiendo en complejidad más adelante: desde exploración general hasta análisis más
específicos y la inclusión de Machine Learning.
Los datos son públicos y gratuitos (fbref para equipos,
Understat para jugadores), así que no traen estadísticas súper
avanzadas, pero sí lo suficiente para sacar insights reales con buen tratamiento visual.
Estructura del repo
data/ No se versiona: los términos de las fuentes no permiten redistribuir los
datos. Los scripts code/fetch_*.py los bajan y code/consolidate_data.py los junta
code/ Notebooks del EDA (laboratorio) + viz_theme.py (identidad visual compartida)
web/
charts/ Configuración de las vistas de "Análisis exploratorio" (jugadores y equipos) y
gráficos de los artículos de ML (Plotly)
build.py Genera el sitio estático completo en web/dist/
site_utils.py Plantillas de página (landing, secciones, gráficos individuales)
react/ Las vistas de "Análisis exploratorio" en React + MUI X (gráficas, filtros, tabla).
Se compila con Vite a react/build/
react_views.py Une Python con el bundle de React (tablas de datos + fragmentos + copia a dist/)
section_views.py Cascarón de la página con las vistas que cargan bajo demanda
dist/ Sitio generado — se commitea tal cual para el deploy
img/ Logo y assets de marca fuente (no versionado — se procesa en cada build)
Cómo correrlo
Notebooks (laboratorio de cada gráfico):
pip install pandas matplotlib plotly numpy pillow
jupyter notebook code/eda_teams.ipynb # o code/eda_players.ipynb
Sitio estático (regenera web/dist/ a partir de web/charts/):
cd web
python build.py
Actualización semanal (temporada en curso): code/actualizar.py baja solo los partidos nuevos
de Understat y refresca las páginas de fbref, comprueba que ninguna fuente retrocedió, consolida,
reconstruye web/dist/ y, con --publicar, hace commit + push de web/dist/ (Vercel despliega
solo). Si algo falla, no publica nada y restaura los datos desde la copia que hizo antes de
descargar. El log de cada corrida queda en logs/.
python code/actualizar.py # baja + consolida + construye, sin tocar git
python code/actualizar.py --publicar # además commit + push (exige árbol limpio y rama master)
Para que corra solo cada lunes a las 23:00 (hora de CDMX), en el Programador de tareas de Windows
(la PC tiene que estar encendida y con la sesión iniciada; registrar la tarea no la enciende):
powershell -ExecutionPolicy Bypass -File code\programar_tarea.ps1 # registrar
powershell -ExecutionPolicy Bypass -File code\programar_tarea.ps1 -Despertar # además despierta la PC suspendida
powershell -ExecutionPolicy Bypass -File code\programar_tarea.ps1 -Quitar # borrar
Cada agosto hay que agregar la temporada nueva a SEASONS (en consolidate_data.py y los
fetch_*.py) y su tamaño a EXPECTED_SIZES; mientras no esté, actualizar.py falla con ese aviso.
Vistas en React (solo si se toca web/react/src/; hace falta Node 20+). El bundle compilado
web/react/build/ se versiona, así que python build.py no necesita Node:
cd web/react
npm install # una vez
npm run build # genera build/futviz-react.js
cd .. && python build.py
Los textos de lectura de cada vista ("En lo que estás viendo") se calculan en el navegador con una
copia en JS de code/insights.py. Para comprobar que ambas dan lo mismo (1.328 combinaciones de
temporada, liga, posición, nivel y sub-21):
cd web/react
python test/gen_paridad.py # genera test/fixtures/ con la versión de Python
node test/paridad.mjs # compara contra la de JS
