Z-score multitag/centros: versión interactiva (Plotly) descargable

Junto al PNG/SVG, cada figura de z-score (triple_multitag y triple_centros)
genera un HTML autocontenido con Plotly: al pasar el mouse por un punto muestra
el equipo, el valor de la métrica (xG/tiros/acciones) y el z-score. Incluye los
puntos de todos los equipos (fondo) y el equipo analizado resaltado.

- bundle.FigureArtifact: nuevo campo html_path.
- triple_multitag: builders plotly_triple/plotly_centros + _save_plotly_html
(include_plotlyjs=True → offline). Falla suave: si no se puede, warning y sigue.
- routes_jobs: interactive_url, lookup html, ruta /figure/{name}.interactive.html,
y se agrega al ZIP.
- schemas.FigureSummary.interactive_url; home.html: link "Interactivo".
- pyproject: plotly>=5.18 (el Space lo instala vía pip install -e .).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
   "mplsoccer>=1.2.0",
   "scipy>=1.12.0",
   "openpyxl>=3.1.0",
+  "plotly>=5.18.0",
 ]
 
 [project.optional-dependencies]

src/racing_reports/api/routes_jobs.py

@@ -47,6 +47,10 @@ def _bundle_summary(job_id: str, report_type: str, bundle) -> BundleSummary:
                 section=f.section,
                 png_url=f"{base}/figure/{f.name}.png",
                 svg_url=f"{base}/figure/{f.name}.svg" if f.svg_path else None,
+                interactive_url=(
+                    f"{base}/figure/{f.name}.interactive.html"
+                    if getattr(f, "html_path", None) else None
+                ),
             )
             for f in bundle.figures
         ],
@@ -90,16 +94,17 @@ def status(job_id: str) -> JobStatus:
 
 
 def _find_artifact(job, report_type: str | None, kind: str, name: str) -> Path:
-    """Busca un artifact en los bundles del job. ``kind`` ∈ {png,svg,csv}."""
+    """Busca un artifact en los bundles del job. ``kind`` ∈ {png,svg,html,csv}."""
     candidates = job.bundles.values() if report_type is None else [job.bundles.get(report_type)]
     for bundle in candidates:
         if bundle is None:
             continue
-        if kind in ("png", "svg"):
+        if kind in ("png", "svg", "html"):
             for fig in bundle.figures:
                 if fig.name != name:
                     continue
-                path = fig.png_path if kind == "png" else fig.svg_path
+                path = {"png": fig.png_path, "svg": fig.svg_path,
+                        "html": getattr(fig, "html_path", None)}[kind]
                 if path is None:
                     raise HTTPException(status_code=404, detail=f"{name}.{kind} no disponible.")
                 return path
@@ -134,6 +139,19 @@ def figure_svg(job_id: str, name: str):
     return FileResponse(path, media_type="image/svg+xml", filename=f"{name}.svg")
 
 
+@router.get(
+    "/{job_id}/figure/{name}.interactive.html",
+    response_class=HTMLResponse,
+    dependencies=[Depends(require_auth)],
+)
+def figure_interactive(job_id: str, name: str):
+    job = jobs_mod.get_job(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Job no encontrado.")
+    path = _find_artifact(job, None, "html", name)
+    return FileResponse(path, media_type="text/html", filename=f"{name}.html")
+
+
 @router.get(
     "/{job_id}/table/{name}.csv",
     dependencies=[Depends(require_auth)],
@@ -190,6 +208,8 @@ def zip_report(job_id: str, report: str):
             zf.write(fig.png_path, arcname=f"figures/{fig.name}.png")
             if fig.svg_path:
                 zf.write(fig.svg_path, arcname=f"figures/{fig.name}.svg")
+            if getattr(fig, "html_path", None):
+                zf.write(fig.html_path, arcname=f"figures/{fig.name}.interactive.html")
         for tbl in bundle.tables:
             zf.write(tbl.csv_path, arcname=f"tables/{tbl.name}.csv")
         if job.manifest_path:

src/racing_reports/api/schemas.py

@@ -28,6 +28,7 @@ class FigureSummary(BaseModel):
     section: str
     png_url: str
     svg_url: str | None = None
+    interactive_url: str | None = None
 
 
 class TableSummary(BaseModel):

src/racing_reports/reports/bundle.py

@@ -21,6 +21,7 @@ class FigureArtifact:
     section: str
     png_path: Path
     svg_path: Path | None = None
+    html_path: Path | None = None  # versión interactiva (Plotly, autocontenida)
     caption: str = ""
 
 

src/racing_reports/reports/triple_multitag.py

@@ -741,6 +741,106 @@ def plot_centros(detail_df: pd.DataFrame, team: str, side_label: str, title_team
     return fig
 
 
+# ── Versión interactiva (Plotly) ─────────────────────────────────────────────
+# Mismos datos que las figuras matplotlib pero con hover: equipo + valor + z-score.
+PLOTLY_METRIC = {
+    "xg": ("xG acumulado", METRIC_COLOR["xg"]),
+    "tiros": ("Tiros con tag", METRIC_COLOR["tiros"]),
+    "acc": ("Acciones totales", METRIC_COLOR["acc"]),
+}
+_METRIC_DY = {"xg": 0.22, "tiros": 0.0, "acc": -0.22}
+_HOVER = ("<b>%{customdata[0]}</b><br>%{customdata[3]}: %{customdata[1]}"
+          "<br>z = %{x:.2f}<br>%{customdata[2]}<extra></extra>")
+
+
+def _z_array(col: pd.Series) -> np.ndarray:
+    vals = col.to_numpy(dtype=float)
+    mu, sd = np.nanmean(vals), np.nanstd(vals)
+    if sd <= 1e-9:
+        return np.zeros(len(vals))
+    return (vals - mu) / sd
+
+
+def _fmt_val(metric: str, v: float) -> str:
+    return f"{v:.2f} xG" if metric == "xg" else f"{int(round(v))}"
+
+
+def _plotly_panel(fig, side_df: pd.DataFrame, tags: list[str], team: str, row: int, col: int,
+                  rng, show_legend: bool) -> None:
+    import plotly.graph_objects as go
+    n = len(tags)
+    ybase = {t: (n - 1 - i) for i, t in enumerate(tags)}
+    has_team = team in side_df.index
+    for metric, (mlabel, mcolor) in PLOTLY_METRIC.items():
+        bx, by, bcd = [], [], []
+        for tag in tags:
+            c = side_df[(tag, metric)]
+            z = _z_array(c)
+            yy = ybase[tag] + _METRIC_DY[metric]
+            jit = rng.uniform(-0.07, 0.07, len(z))
+            for tnm, zz, vv, jj in zip(c.index, z, c.to_numpy(dtype=float), jit):
+                bx.append(zz); by.append(yy + jj)
+                bcd.append([str(tnm), _fmt_val(metric, vv), tag, mlabel])
+        fig.add_trace(go.Scattergl(
+            x=bx, y=by, mode="markers", name=mlabel, legendgroup=mlabel,
+            showlegend=show_legend, marker=dict(size=6, color=mcolor, opacity=0.28),
+            customdata=bcd, hovertemplate=_HOVER), row=row, col=col)
+        if has_team:
+            hx, hy, hcd = [], [], []
+            for tag in tags:
+                c = side_df[(tag, metric)]
+                z = _z_array(c)
+                i = c.index.get_loc(team)
+                hx.append(z[i]); hy.append(ybase[tag] + _METRIC_DY[metric])
+                hcd.append([team, _fmt_val(metric, float(c.iloc[i])), tag, mlabel])
+            fig.add_trace(go.Scatter(
+                x=hx, y=hy, mode="markers", legendgroup=mlabel, showlegend=False,
+                marker=dict(size=13, color=mcolor, line=dict(width=1.6, color="#222")),
+                customdata=hcd, hovertemplate=_HOVER), row=row, col=col)
+    fig.add_vline(x=0, line_dash="dash", line_color="#888", line_width=1, row=row, col=col)
+    fig.update_yaxes(tickmode="array", tickvals=[ybase[t] for t in tags], ticktext=tags,
+                     range=[-0.7, n - 0.3], row=row, col=col)
+    fig.update_xaxes(title_text="Z-score (vs media de la liga)", range=[-4, 6.5],
+                     zeroline=False, row=row, col=col)
+
+
+def plotly_triple(side_df: pd.DataFrame, team: str, side_label: str, title_team: str, seed: int = 7):
+    from plotly.subplots import make_subplots
+    rng = np.random.default_rng(seed)
+    fig = make_subplots(rows=1, cols=1)
+    _plotly_panel(fig, side_df, TAGS, team, 1, 1, rng, show_legend=True)
+    fig.update_layout(template="plotly_white", hovermode="closest",
+                      height=max(620, 30 * len(TAGS)),
+                      title=f"Z-Score Multi-Tag — {side_label} — {title_team}",
+                      legend=dict(orientation="h", yanchor="bottom", y=1.02))
+    return fig
+
+
+def plotly_centros(detail_df: pd.DataFrame, team: str, side_label: str, title_team: str, seed: int = 7):
+    from plotly.subplots import make_subplots
+    rng = np.random.default_rng(seed)
+    grouped_df = _grouped_centros_df(detail_df)
+    fig = make_subplots(rows=1, cols=2, horizontal_spacing=0.16,
+                        subplot_titles=("Desglose por tipo · lado", "Vista agrupada"))
+    _plotly_panel(fig, detail_df, CENTROS_DETAIL, team, 1, 1, rng, show_legend=True)
+    _plotly_panel(fig, grouped_df, list(CENTROS_GROUPED), team, 1, 2, rng, show_legend=False)
+    fig.update_layout(template="plotly_white", hovermode="closest",
+                      height=max(620, 30 * len(CENTROS_DETAIL)),
+                      title=f"Z-Score Centros — {side_label} — {title_team}",
+                      legend=dict(orientation="h", yanchor="bottom", y=1.02))
+    return fig
+
+
+def _save_plotly_html(fig, out_dir, name: str):
+    """Guarda la figura Plotly como HTML autocontenido (plotly.js embebido)."""
+    from pathlib import Path
+    figs_dir = Path(out_dir) / "figures"
+    figs_dir.mkdir(parents=True, exist_ok=True)
+    html_path = figs_dir / f"{name}.interactive.html"
+    fig.write_html(str(html_path), include_plotlyjs=True, full_html=True)
+    return html_path
+
+
 # Columnas mínimas que necesita el análisis (del preprocessed).
 NEEDED_COLS = [
     "matchId", "teamId", "TeamName", "possessionId", "time_seconds",
@@ -764,9 +864,19 @@ def _build_report(out_path, report_type, title, plan, home_name, away_name):
         if team not in sdf.index and team not in seen:
             seen.add(team)
             warnings.append(f"{team} sin datos en la liga/temporada; figuras vacías.")
-        fig = plot_centros(sdf, team, side, team) if kind == "centros" else plot_triple(sdf, team, side, team)
+        is_centros = kind == "centros"
+        fig = plot_centros(sdf, team, side, team) if is_centros else plot_triple(sdf, team, side, team)
         png_path, svg_path = save_figure(fig, out_path.parent, name)
-        figures.append(FigureArtifact(name=name, title=fig_title, section=section, png_path=png_path, svg_path=svg_path))
+        plt.close(fig)
+        # Versión interactiva (Plotly, hover con equipo + valor); autocontenida.
+        html_path = None
+        try:
+            pfig = plotly_centros(sdf, team, side, team) if is_centros else plotly_triple(sdf, team, side, team)
+            html_path = _save_plotly_html(pfig, out_path.parent, name)
+        except Exception as exc:  # la interactiva es un extra: no romper el reporte
+            warnings.append(f"{name}: no se pudo generar la versión interactiva ({exc}).")
+        figures.append(FigureArtifact(name=name, title=fig_title, section=section,
+                                      png_path=png_path, svg_path=svg_path, html_path=html_path))
         imgs.append((fig_title, base64.b64encode(Path(png_path).read_bytes()).decode("ascii")))
     body = "\n".join(
         f'<h2>{t}</h2><img src="data:image/png;base64,{b}" style="width:100%;max-width:1100px"/>' for t, b in imgs

src/racing_reports/web/templates/home.html

@@ -245,6 +245,7 @@
                     <div class="flex gap-2 text-xs">
                       <a :href="fig.png_url" download class="text-racing-500 hover:underline">PNG</a>
                       <a :href="fig.svg_url" download class="text-racing-500 hover:underline" x-show="fig.svg_url">SVG</a>
+                      <a :href="fig.interactive_url" download class="text-racing-500 hover:underline" x-show="fig.interactive_url" title="HTML interactivo: hover muestra equipo y valor">Interactivo</a>
                     </div>
                   </figcaption>
                 </figure>