refactor: modularizar paquete, mejorar tests y corregir CI

Author: alvarosalinaso

.github/workflows/ci.yml

@@ -11,14 +11,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          pip install -e .
           pip install -r requirements.txt
+
       - name: Run tests
         run: |
           pytest -q

requirements.txt

@@ -1,8 +1,4 @@
 pandas
-pytest
 matplotlib
 seaborn
-
 pytest
-matplotlib
-seaborn

src/united_passing/analysis.py

@@ -1,37 +1,60 @@
-"""Módulo de análisis de datos."""
+"""Módulo de análisis de eficiencia de pases del Manchester United."""
 import pandas as pd
 
+
 def top_by_prog_ratio(df: pd.DataFrame, top_n: int = 10) -> pd.DataFrame:
     """
-    Obtiene el top N de jugadores ordenados por Prog_Ratio.
-    Calcula Prog_Ratio si no existe (Prog / Cmp).
+    Top N jugadores por Prog_Ratio (pases progresivos / completados).
+
+    Si Prog_Ratio no existe en el DataFrame, se calcula desde Prog y Cmp.
+    Si tampoco existen esas columnas, devuelve las primeras top_n filas.
+
+    Args:
+        df: DataFrame limpio con estadísticas de pases.
+        top_n: Número de jugadores a retornar.
+
+    Returns:
+        DataFrame ordenado por Prog_Ratio descendente.
     """
     df = df.copy()
-    
-    # Calcular Prog_Ratio si no está presente y tenemos las columnas necesarias
-    if 'Prog_Ratio' not in df.columns:
-        if 'Prog' in df.columns and 'Cmp' in df.columns:
-            # Evitar división por cero
-            df['Prog_Ratio'] = df.apply(
-                lambda x: x['Prog'] / x['Cmp'] if x['Cmp'] > 0 else 0, axis=1
+
+    if "Prog_Ratio" not in df.columns:
+        if {"Prog", "Cmp"}.issubset(df.columns):
+            df["Prog_Ratio"] = df.apply(
+                lambda r: round(r["Prog"] / r["Cmp"], 4) if r["Cmp"] > 0 else 0.0,
+                axis=1,
             )
         else:
-             # Si no podemos calcularlo y no está, devolvemos vacío o error
-             # Por compatibilidad con el script anterior, asumiremos que el input puede ser el 'reporte' que ya lo tenga
-             pass
+            return df.head(top_n)
+
+    return df.sort_values("Prog_Ratio", ascending=False).head(top_n).reset_index(drop=True)
 
-    if 'Prog_Ratio' in df.columns:
-        df_sorted = df.sort_values('Prog_Ratio', ascending=False)
-        return df_sorted.head(top_n)
-    else:
-        # Fallback si no hay métrica
-        return df.head(top_n)
 
 def filter_midfielders(df: pd.DataFrame) -> pd.DataFrame:
     """
-    Filtra jugadores que son mediocampistas (MF).
-    Asume columna 'Pos' con valores como 'MF', 'MFDF', etc.
+    Filtra filas cuya columna 'Pos' contenga 'MF'.
+
+    Args:
+        df: DataFrame con columna 'Pos'.
+
+    Returns:
+        DataFrame filtrado. Si no existe 'Pos', retorna el DataFrame original.
+    """
+    if "Pos" not in df.columns:
+        return df
+    return df[df["Pos"].str.contains("MF", na=False)].reset_index(drop=True)
+
+
+def resumen_estadisticas(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Tabla resumen con métricas clave por jugador.
+
+    Args:
+        df: DataFrame limpio de pases.
+
+    Returns:
+        DataFrame con Player, Cmp, Att, Cmp%, Prog, Prog_Ratio (si disponibles).
     """
-    if 'Pos' in df.columns:
-        return df[df['Pos'].str.contains('MF', na=False)]
-    return df
+    cols_deseadas = ["Player", "Pos", "90s", "Cmp", "Att", "Cmp%", "Prog", "Prog_Ratio", "KP", "xA"]
+    cols_presentes = [c for c in cols_deseadas if c in df.columns]
+    return df[cols_presentes].copy()

src/united_passing/data.py

@@ -1,38 +1,105 @@
-"""Módulo para carga y limpieza de datos."""
-import pandas as pd
+"""Módulo para carga y limpieza de datos de pases del Manchester United."""
 from pathlib import Path
+from typing import Optional, Tuple
+
+import pandas as pd
+
+# Columnas numéricas conocidas del dataset FBref
+_NUMERIC_COLS = [
+    "90s", "Cmp", "Att", "Cmp%", "TotDist", "PrgDist",
+    "Ast", "xA", "KP", "1/3", "PPA", "CrsPA", "Prog",
+]
+
+_PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+
+def _resolver_ruta(nombre: str) -> Path:
+    """Busca el archivo en CWD y en la raíz del proyecto."""
+    candidatos = [Path(nombre), Path.cwd() / nombre, _PROJECT_ROOT / nombre]
+    for c in candidatos:
+        if c.exists():
+            return c.resolve()
+    raise FileNotFoundError(
+        f"No se encontró '{nombre}'. Colócalo en la raíz del proyecto."
+    )
+
+
+def load_data(
+    passes_path: str = "passing.csv",
+    report_path: str = "reporte_mediocampo.csv",
+) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Carga los datos de pases y el reporte de mediocampo.
+
+    Args:
+        passes_path: Nombre/ruta del CSV de pases (FBref).
+        report_path: Nombre/ruta del CSV de reporte de mediocampo.
+
+    Returns:
+        Tupla (df_pases, df_reporte). df_reporte puede ser vacío
+        si el archivo no existe todavía.
+    """
+    df = pd.read_csv(_resolver_ruta(passes_path))
+
+    try:
+        report = pd.read_csv(_resolver_ruta(report_path))
+    except FileNotFoundError:
+        report = pd.DataFrame()
 
-def load_data(passes_path: str = 'passing.csv', report_path: str = 'reporte_mediocampo.csv') -> tuple:
-    """Carga los datos de pases y el reporte de mediocampo desde CSV."""
-    # Usar Path para mayor robustez, asumiendo ejecución desde la raíz o configurando paths relativos
-    base_path = Path.cwd()
-    p_path = base_path / passes_path
-    r_path = base_path / report_path
-    
-    if not p_path.exists():
-        raise FileNotFoundError(f"No se encontró el archivo: {p_path}")
-        
-    df = pd.read_csv(p_path)
-    
-    if r_path.exists():
-        report = pd.read_csv(r_path)
-    else:
-        report = pd.DataFrame() # Return empty if report doesn't exist yet
-        
     return df, report
 
+
 def clean_passes(df: pd.DataFrame) -> pd.DataFrame:
-    """Limpia el DataFrame de pases."""
+    """
+    Limpia el DataFrame de pases:
+      - Elimina columnas completamente vacías.
+      - Convierte strings vacíos a NaN.
+      - Coerce columnas numéricas conocidas.
+
+    Args:
+        df: DataFrame crudo de pases.
+
+    Returns:
+        DataFrame limpio.
+    """
     df = df.copy()
-    # Remover columnas completamente vacías
-    df.dropna(axis=1, how='all', inplace=True)
-    # Reemplazar cadenas vacías por NaN (usando forward fill para compatibilidad o pd.NA)
-    df = df.replace(r'^\s*$', pd.NA, regex=True)
-    
-    # Intentar convertir columnas numéricas conocidas
-    numeric_cols = ['90s', 'Cmp', 'Att', 'TotDist', 'PrgDist', 'Ast', 'xA', 'KP', '1/3', 'PPA', 'CrsPA', 'Prog']
-    for col in numeric_cols:
+
+    # Eliminar columnas 100% vacías
+    df.dropna(axis=1, how="all", inplace=True)
+
+    # Strings vacíos → NaN
+    df.replace(r"^\s*$", pd.NA, regex=True, inplace=True)
+
+    # Convertir numéricas conocidas
+    for col in _NUMERIC_COLS:
         if col in df.columns:
-            df[col] = pd.to_numeric(df[col], errors='coerce')
-            
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+
     return df
+
+
+def build_midfield_report(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Genera el reporte de mediocampo calculando Prog_Ratio y filtrando MF.
+
+    Args:
+        df: DataFrame limpio de pases.
+
+    Returns:
+        DataFrame con columna Prog_Ratio, ordenado descendente.
+    """
+    df = df.copy()
+
+    if "Prog" in df.columns and "Cmp" in df.columns:
+        df["Prog_Ratio"] = df.apply(
+            lambda r: round(r["Prog"] / r["Cmp"], 4) if r["Cmp"] and r["Cmp"] > 0 else 0.0,
+            axis=1,
+        )
+
+    if "Pos" in df.columns:
+        df = df[df["Pos"].str.contains("MF", na=False)].copy()
+
+    if "Prog_Ratio" in df.columns:
+        df.sort_values("Prog_Ratio", ascending=False, inplace=True)
+
+    return df.reset_index(drop=True)

src/united_passing/plot.py

@@ -1,32 +1,109 @@
-"""Módulo para visualización de datos."""
+"""Módulo de visualización de pases del Manchester United."""
+from pathlib import Path
+
 import matplotlib.pyplot as plt
+import matplotlib.ticker as mticker
 import pandas as pd
+
 try:
     import seaborn as sns
+    sns.set_theme(style="whitegrid", palette="muted")
     HAS_SEABORN = True
 except ImportError:
     HAS_SEABORN = False
 
-def plot_top_passers(df: pd.DataFrame, metric: str = 'Cmp', top_n: int = 10, out_path: str = 'grafico_pases_united.png'):
-    """Genera un gráfico de barras de los top N jugadores según una métrica."""
+_RED = "#c0392b"
+_DARK = "#2c3e50"
+
+
+def _guardar(fig: plt.Figure, out_path: str) -> str:
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    fig.savefig(out_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+    print(f"  ✅ Guardado: {out_path}")
+    return out_path
+
+
+def plot_top_passers(
+    df: pd.DataFrame,
+    metric: str = "Cmp",
+    top_n: int = 10,
+    out_path: str = "grafico_pases_united.png",
+) -> str:
+    """
+    Gráfico de barras horizontales con los top N jugadores según una métrica.
+
+    Args:
+        df: DataFrame limpio de pases.
+        metric: Columna a usar como métrica (ej. 'Cmp', 'Prog', 'xA').
+        top_n: Número de jugadores a mostrar.
+        out_path: Ruta de salida del gráfico.
+
+    Returns:
+        Ruta donde se guardó el gráfico.
+    """
     if metric not in df.columns:
-        raise KeyError(f'La columna {metric} no existe en los datos.')
-    
-    # Ordenar y seleccionar top
-    df_top = df.sort_values(metric, ascending=False).head(top_n)
-    
-    plt.figure(figsize=(10, 6))
-    
+        raise KeyError(f"La columna '{metric}' no existe en los datos.")
+    if "Player" not in df.columns:
+        raise KeyError("El DataFrame no tiene columna 'Player'.")
+
+    df_top = df.dropna(subset=[metric]).sort_values(metric, ascending=False).head(top_n)
+
+    fig, ax = plt.subplots(figsize=(10, 6))
+
+    colores = [_RED if i == 0 else _DARK for i in range(len(df_top))]
+
     if HAS_SEABORN:
-        sns.set_theme(style="whitegrid")
-        sns.barplot(x=metric, y='Player', data=df_top, palette='viridis')
+        sns.barplot(x=metric, y="Player", data=df_top, palette=colores, ax=ax)
     else:
-        # Fallback a matplotlib puro
-        plt.barh(df_top['Player'][::-1], df_top[metric][::-1])
-    
-    plt.xlabel(metric)
-    plt.title(f'Top {top_n} jugadores por {metric}')
-    plt.tight_layout()
-    plt.savefig(out_path)
-    plt.close()
-    return out_path
+        ax.barh(df_top["Player"][::-1], df_top[metric][::-1], color=colores[::-1])
+
+    ax.set_xlabel(metric, fontsize=11)
+    ax.set_ylabel("")
+    ax.set_title(f"Top {top_n} jugadores — {metric} | Man Utd 2024/25", fontweight="bold")
+    ax.axvline(df_top[metric].mean(), color="gray", linestyle="--", linewidth=0.8,
+               label=f"Media: {df_top[metric].mean():.1f}")
+    ax.legend(fontsize=8)
+
+    return _guardar(fig, out_path)
+
+
+def plot_prog_ratio_scatter(
+    df: pd.DataFrame,
+    out_path: str = "analisis_mediocampo_united.png",
+) -> str:
+    """
+    Scatter: Pases completados (volumen) vs Prog_Ratio (eficiencia progresiva).
+
+    Args:
+        df: DataFrame con columnas Cmp y Prog_Ratio.
+        out_path: Ruta de salida.
+
+    Returns:
+        Ruta donde se guardó el gráfico.
+    """
+    if "Prog_Ratio" not in df.columns or "Cmp" not in df.columns:
+        raise KeyError("Se necesitan columnas 'Prog_Ratio' y 'Cmp'.")
+
+    fig, ax = plt.subplots(figsize=(10, 7))
+
+    ax.scatter(df["Cmp"], df["Prog_Ratio"], color=_RED, s=100, edgecolors=_DARK,
+               linewidth=0.6, zorder=3)
+
+    if "Player" in df.columns:
+        for _, row in df.iterrows():
+            ax.annotate(row["Player"], xy=(row["Cmp"], row["Prog_Ratio"]),
+                        xytext=(4, 3), textcoords="offset points", fontsize=8)
+
+    ax.axhline(df["Prog_Ratio"].mean(), color="gray", linestyle="--", linewidth=0.8,
+               label=f"Media Prog_Ratio: {df['Prog_Ratio'].mean():.3f}")
+    ax.axvline(df["Cmp"].mean(), color="gray", linestyle=":", linewidth=0.8,
+               label=f"Media Cmp: {df['Cmp'].mean():.0f}")
+
+    ax.set_xlabel("Pases Completados (Cmp)", fontsize=11)
+    ax.set_ylabel("Ratio de Pases Progresivos (Prog/Cmp)", fontsize=11)
+    ax.set_title("Volumen vs Eficiencia Progresiva — Mediocampistas Man Utd", fontweight="bold")
+    ax.legend(fontsize=8)
+    ax.grid(True, alpha=0.2)
+
+    return _guardar(fig, out_path)