gr-analytics 0.2.1__tar.gz → 0.3.0__tar.gz

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gr_analytics
-Version: 0.2.1
+Version: 0.3.0
 Summary: Scoring and salary calculation for GridRival fantasy F1
 Author: nce8
 License-Expression: MIT

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/gr_analytics/__init__.py

@@ -388,27 +388,62 @@ def score_event(scenario: pd.DataFrame, round: int = None) -> pd.DataFrame:
     """
     Score a Grand Prix event for drivers and constructors.
 
+    Merges ``scenario`` with the built-in ``driver_data.csv`` for the given
+    round to obtain starting salaries, team affiliations, eight-race
+    averages, and constructor rows. Then scores every driver and
+    constructor and computes post-event salary adjustments.
+
     Parameters
     ----------
-    scenario : DataFrame with columns:
-        driver_abbr, qualifying_position, race_position
-        completed_qualifying: 1 if driver completed qualifying, 0 if DNQ.
-            DNQ drivers get 0 qualifying points but overtake points still
-            use their official qualifying_position.
-        completed_pct (optional): fraction of race completed (0.0-1.0).
-            Used to calculate completion bonus (3 pts each at 25/50/75/90%).
-            Defaults to 1.0 (full completion) if column is absent.
+    scenario : DataFrame
+        One row per driver with the following columns:
+
+        - **driver_abbr** : str — three-letter driver code (e.g. "VER").
+        - **qualifying_position** : int — grid position (1–22).
+        - **race_position** : int — finishing position (1–22).
+        - **completed_qualifying** : int (0 or 1), optional — whether the
+          driver set a qualifying time. DNQ drivers (0) receive 0
+          qualifying points but overtake points still use their official
+          qualifying_position. Defaults to 1 if column is absent.
+        - **completed_pct** : float or "DNS", optional — fraction of race
+          distance completed (0.0–1.0), or the string "DNS" for drivers
+          who did not start. Used to calculate completion bonus (3 pts
+          each at 25%/50%/75%/90%). DNS drivers receive 0 for all
+          race-related points. Defaults to 1.0 (full completion) if
+          column is absent.
+
+        Qualifying and race positions must each be a complete 1…n
+        sequence with no duplicates.
+
     round : int, optional
-        Race round number. Defaults to the maximum round in driver_data.
+        Race round number used to look up driver/constructor data (salary,
+        eight-race average, team mapping). Defaults to the maximum round
+        in driver_data.
 
     Returns
     -------
-    DataFrame with scoring columns appended.
-    Drivers get: pts_qualifying, pts_race, pts_overtake, pts_improvement,
-                 pts_completion, pts_teammate, points_earned, salary_after_event,
-                 salary_change
-    Constructors get: pts_qualifying, pts_race, points_earned, salary_after_event,
-                salary_change
+    DataFrame
+        All driver and constructor rows with scoring columns appended.
+
+        **Drivers:** pts_qualifying, pts_race, pts_overtake,
+        pts_improvement, pts_completion, pts_teammate, points_earned,
+        salary_after_event, salary_change.
+
+        **Constructors:** pts_qualifying, pts_race, points_earned,
+        salary_after_event, salary_change (qualifying and race points
+        are the sum of constructor-specific point tables across both
+        drivers, not the driver tables).
+
+    Raises
+    ------
+    ValueError
+        If qualifying or race positions contain duplicates, gaps, or
+        out-of-range values.
+
+    Notes
+    -----
+    If the driver_data contains a ``held`` column with value 1, the
+    function prints the total points and salary change for held picks.
     """
     _validate_scenario(scenario)
 
@@ -420,6 +455,28 @@ def score_event(scenario: pd.DataFrame, round: int = None) -> pd.DataFrame:
     drivers_dd = dd[dd["type"] == "driver"].copy()
     teams_dd = dd[dd["type"] == "team"].copy()
 
+    # Validate driver_abbr values before merging
+    dd_abbrs = set(drivers_dd["driver_abbr"])
+    scenario_abbrs = set(scenario["driver_abbr"])
+    missing_from_scenario = dd_abbrs - scenario_abbrs
+    missing_from_dd = scenario_abbrs - dd_abbrs
+    errors = []
+    if missing_from_scenario:
+        errors.append(
+            f"Drivers in driver_data (round {round}) but not in scenario: "
+            f"{sorted(missing_from_scenario)}"
+        )
+    if missing_from_dd:
+        errors.append(
+            f"Drivers in scenario but not in driver_data (round {round}): "
+            f"{sorted(missing_from_dd)}"
+        )
+    if errors:
+        raise ValueError(
+            "driver_abbr mismatch between scenario and driver_data:\n"
+            + "\n".join(f"  - {e}" for e in errors)
+        )
+
     drivers_merged = drivers_dd.merge(
         scenario,
         on="driver_abbr",
@@ -472,7 +529,7 @@ def score_my_team(
         (result["type"] == "driver") & (result["driver_abbr"].isin(drivers))
     ].copy()
     my_team = result[
-        (result["type"] == "team") & (result["driver_name"] == team)
+        (result["type"] == "team") & (result["driver_abbr"] == team)
     ].copy()
 
     my_picks = pd.concat([my_drivers, my_team])
@@ -490,7 +547,8 @@ def score_my_team(
 def optimal_lineup(
     scored: pd.DataFrame,
     locked_in: list = None,
-    optimize_for: str = "points",
+    locked_out: list = None,
+    optimize_for="points",
     budget: float = 100.0,
     star_salary_cap: float = 19.0,
 ) -> pd.DataFrame:
@@ -505,11 +563,17 @@ def optimal_lineup(
         driver_abbr values (drivers) or driver_name team codes (e.g. "MER")
         that must appear in the lineup. These count against the budget and
         the 5-driver / 1-constructor slot limits.
-    optimize_for : {"points", "salary_change"}
-        Objective to maximise. For "points", the star driver (who earns
-        double points) is chosen optimally across all candidates. For
-        "salary_change", the lineup maximises total salary change; no star
-        is designated since the star does not affect salary in GR.
+    locked_out : list of str, optional
+        driver_abbr values (drivers) or driver_name team codes that must
+        be excluded from the lineup. These are removed from the candidate
+        pool before optimisation.
+    optimize_for : {"points", "salary_change"} or float
+        Objective to maximise. ``"points"`` is equivalent to balance=1
+        (pure points with star doubling). ``"salary_change"`` is equivalent
+        to balance=0 (pure salary change). A float between 0 and 1 blends:
+        ``objective = (points_earned / 100) * balance + salary_change * (1 - balance)``
+        The star driver (whose points component is doubled) is chosen
+        optimally whenever balance > 0.
     budget : float
         Salary budget in £M available for non-locked-in picks (default 100).
         Locked-in drivers are treated as free (already under contract).
@@ -520,16 +584,35 @@ def optimal_lineup(
     Returns
     -------
     DataFrame with the 6 selected rows plus a `star` column (1 = starred
-    driver, only set when optimize_for="points").
+    driver, set when optimize_for="points" or a float balance > 0).
     """
     if locked_in is None:
         locked_in = []
-    if optimize_for not in ("points", "salary_change"):
-        raise ValueError("optimize_for must be 'points' or 'salary_change'")
-
-    obj_col = "points_earned" if optimize_for == "points" else "salary_change"
+    if locked_out is None:
+        locked_out = []
+
+    # Determine balance: 1.0 = pure points, 0.0 = pure salary_change
+    if isinstance(optimize_for, (int, float)) and not isinstance(optimize_for, bool):
+        balance = float(optimize_for)
+        if not 0.0 <= balance <= 1.0:
+            raise ValueError("optimize_for as a float must be between 0 and 1")
+    elif optimize_for == "points":
+        balance = 1.0
+    elif optimize_for == "salary_change":
+        balance = 0.0
+    else:
+        raise ValueError(
+            "optimize_for must be 'points', 'salary_change', or a float between 0 and 1"
+        )
 
     df = scored.copy()
+
+    # Remove locked-out entries from the pool entirely
+    _is_locked_out = df["driver_abbr"].isin(locked_out) | (
+        (df["type"] == "team") & df["driver_name"].isin(locked_out)
+    )
+    df = df[~_is_locked_out].copy()
+
     df["_locked"] = df["driver_abbr"].isin(locked_in) | (
         (df["type"] == "team") & df["driver_name"].isin(locked_in)
     )
@@ -554,7 +637,9 @@ def optimal_lineup(
     free = free.sort_values("type").reset_index(drop=True)
 
     salaries_arr = free["starting_salary"].values.astype(float)
-    obj_arr = free[obj_col].values.astype(float)
+    pts_arr = free["points_earned"].values.astype(float)
+    sal_arr = free["salary_change"].values.astype(float)
+    obj_arr = pts_arr / 100.0 * balance + sal_arr * (1.0 - balance)
 
     bounds = Bounds(0, 1)
     integrality = np.ones(len(free))
@@ -581,14 +666,16 @@ def optimal_lineup(
             raise RuntimeError(f"Optimization failed: {result.message}")
         return result
 
-    if optimize_for == "salary_change":
-        result = _run_milp(obj_arr)
-        picked = free[result.x.astype(bool)].copy()
-        full = pd.concat([picked, locked], ignore_index=True)
-        full["star"] = 0
-        return full.drop(columns=["_locked"])
+    # Locked contribution for total comparison
+    if not locked.empty:
+        locked_obj = (
+            locked["points_earned"].values.astype(float) / 100.0 * balance
+            + locked["salary_change"].values.astype(float) * (1.0 - balance)
+        ).sum()
+    else:
+        locked_obj = 0.0
 
-    # --- points optimization: loop over star candidates ---
+    # --- star optimization: loop over star candidates ---
     free_drivers = free[free["type"] == "driver"]
     if star_salary_cap is not None:
         free_drivers = free_drivers[free_drivers["starting_salary"] <= star_salary_cap]
@@ -602,7 +689,8 @@ def optimal_lineup(
     for i in star_candidates:
         obj_copy = obj_arr.copy()
         if i != -1:
-            obj_copy[i] *= 2
+            # Star doubles points_earned only → add the points component again
+            obj_copy[i] += pts_arr[i] / 100.0 * balance
 
         result = _run_milp(obj_copy)
         picked = free[result.x.astype(bool)].copy()
@@ -612,11 +700,8 @@ def optimal_lineup(
         if i != -1:
             star_abbr = free.at[i, "driver_abbr"]
             full.loc[full["driver_abbr"] == star_abbr, "star"] = 1
-            # total = doubled star pts + rest
-            star_pts = free.at[i, obj_col]
-            total = (
-                -result.fun + locked[obj_col].sum() + star_pts
-            )  # star_pts counted twice via obj_copy
+            star_bonus = pts_arr[i] / 100.0 * balance
+            total = -result.fun + locked_obj + star_bonus
         else:
             # Star is the highest-points locked_in driver (within salary cap)
             locked_drivers = locked[locked["type"] == "driver"]
@@ -625,12 +710,13 @@ def optimal_lineup(
                     locked_drivers["starting_salary"] <= star_salary_cap
                 ]
             if locked_drivers.empty:
-                total = -result.fun + locked[obj_col].sum()
+                total = -result.fun + locked_obj
             else:
-                best_row = locked_drivers.loc[locked_drivers[obj_col].idxmax()]
+                best_row = locked_drivers.loc[locked_drivers["points_earned"].idxmax()]
                 star_abbr = best_row["driver_abbr"]
                 full.loc[full["driver_abbr"] == star_abbr, "star"] = 1
-                total = -result.fun + locked[obj_col].sum() + best_row[obj_col]
+                star_bonus = best_row["points_earned"] / 100.0 * balance
+                total = -result.fun + locked_obj + star_bonus
 
         if total > best_total:
             best_total = total

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/gr_analytics/data/driver_data.csv

@@ -97,4 +97,37 @@ team,AMR,AMR,,2,15.7,,72
 team,WIL,WIL,,2,13.8,,78
 team,HAS,HAS,,2,11,,125
 team,AUD,AUD,,2,9.7,,80
-team,CAD,CAD,,2,9,,83
+team,CAD,CAD,,2,9,,83
+driver,RUS,G. Russell,MER,3,29.5,3,164
+driver,ANT,K. Antonelli,MER,3,28.7,4,173
+driver,LEC,C. Leclerc,FER,3,26.3,5,162
+driver,NOR,L. Norris,MCL,3,24.7,6,118
+driver,VER,M. Verstappen,RBR,3,24.6,5,133
+driver,PIA,O. Piastri,MCL,3,24.1,8,91
+driver,HAM,L. Hamilton,FER,3,23.4,7,158
+driver,GAS,P. Gasly,ALP,3,21.7,10,143
+driver,LAW,L. Lawson,RBS,3,18,12,140
+driver,HAD,I. Hadjar,RBR,3,17.7,11,117
+driver,ALO,F. Alonso,AMR,3,16.2,11,79
+driver,SAI,C. Sainz Jr,WIL,3,14.9,13,115
+driver,HUL,N. Hulkenberg,AUD,3,13.3,15,95
+driver,OCO,E. Ocon,HAS,3,12.7,16,130
+driver,BOR,G. Bortoleto,AUD,3,11.5,16,98
+driver,BEA,O. Bearman,HAS,3,11.2,15,142
+driver,STR,L. Stroll,AMR,3,11,14,69
+driver,ALB,A. Albon,WIL,3,9.9,16,70
+driver,LIN,A. Lindblad,RBS,3,9.7,17,131
+driver,COL,F. Colapinto,ALP,3,9,17,117
+driver,PER,S. Perez,CAD,3,7.5,18,97
+driver,BOT,V. Bottas,CAD,3,6.2,19,87
+team,MER,MER,,3,29.3,,175
+team,FER,FER,,3,24.6,,161
+team,MCL,MCL,,3,23.8,,106
+team,RBR,RBR,,3,21.8,,116
+team,ALP,ALP,,3,17.5,,120
+team,RBS,RBS,,3,17.3,,120
+team,AMR,AMR,,3,12.8,,69
+team,WIL,WIL,,3,12.7,,80
+team,HAS,HAS,,3,11.2,,114
+team,AUD,AUD,,3,10.8,,92
+team,CAD,CAD,,3,8.4,,80

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/gr_analytics.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gr_analytics
-Version: 0.2.1
+Version: 0.3.0
 Summary: Scoring and salary calculation for GridRival fantasy F1
 Author: nce8
 License-Expression: MIT

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/pyproject.toml

@@ -4,14 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gr_analytics"
-version = "0.2.1"
+version = "0.3.0"
 description = "Scoring and salary calculation for GridRival fantasy F1"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
-authors = [
-  {name = "nce8"},
-]
+authors = [{ name = "nce8" }]
 keywords = ["fantasy", "f1", "formula1", "gridrival", "motorsport"]
 classifiers = [
   "Programming Language :: Python :: 3",

{gr_analytics-0.2.1 → gr_analytics-0.3.0}/tests/test_scoring.py

@@ -333,6 +333,18 @@ class TestEdgeCases:
         result = _score_full(basic_race)
         assert result.loc[result.driver_name == "Russell", "pts_overtake"].iloc[0] == 0
 
+    def test_score_event_unknown_driver_abbr_raises(self):
+        """score_event raises ValueError when scenario contains a driver_abbr not in driver_data."""
+        scenario = pd.read_csv(_TESTS_DIR / "test_australia.csv")
+        # Replace one valid abbreviation with a bogus one
+        scenario.loc[scenario["driver_abbr"] == "VER", "driver_abbr"] = "ZZZ"
+        with pytest.raises(ValueError, match="driver_abbr mismatch") as exc_info:
+            score_event(scenario, round=0)
+        # Both directions should be reported
+        msg = str(exc_info.value)
+        assert "ZZZ" in msg, "error should mention the unknown abbreviation"
+        assert "VER" in msg, "error should mention the missing driver from driver_data"
+
 
 # ---------------------------------------------------------------------------
 # Australia 2026 round-0 integration test
@@ -534,6 +546,160 @@ class TestOptimalLineupStarCap:
         assert picked == {"drivera", "driverb", "driverc", "driverd", "driverf", "has"}
 
 
+# ---------------------------------------------------------------------------
+# locked_out tests
+# ---------------------------------------------------------------------------
+
+
+class TestLockedOut:
+
+    def test_locked_out_excludes_high_value_driver(self):
+        """A driver worth 999 points at cost 1 is excluded when locked_out."""
+        df = pd.DataFrame(
+            {
+                "type": [
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "team",
+                ],
+                "driver_abbr": ["GOD", "D1", "D2", "D3", "D4", "D5", None],
+                "driver_name": ["GOD", "D1", "D2", "D3", "D4", "D5", "TEAM"],
+                "starting_salary": [1.0, 15.0, 15.0, 15.0, 15.0, 15.0, 10.0],
+                "points_earned": [999.0, 50.0, 40.0, 30.0, 20.0, 10.0, 60.0],
+                "salary_change": [9.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
+            }
+        )
+        result = optimal_lineup(df, locked_out=["GOD"], star_salary_cap=None)
+        picked_abbrs = set(result["driver_abbr"].dropna())
+        assert "GOD" not in picked_abbrs
+
+    def test_locked_out_team_excluded(self):
+        """A constructor is excluded when its team code is in locked_out."""
+        df = pd.DataFrame(
+            {
+                "type": [
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "team",
+                    "team",
+                ],
+                "driver_abbr": ["D1", "D2", "D3", "D4", "D5", None, None],
+                "driver_name": ["D1", "D2", "D3", "D4", "D5", "GOOD", "BAD"],
+                "starting_salary": [15.0, 15.0, 15.0, 15.0, 15.0, 10.0, 1.0],
+                "points_earned": [50.0, 40.0, 30.0, 20.0, 10.0, 60.0, 999.0],
+                "salary_change": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9.0],
+            }
+        )
+        result = optimal_lineup(df, locked_out=["BAD"], star_salary_cap=None)
+        picked_teams = set(result.loc[result["type"] == "team", "driver_name"])
+        assert "BAD" not in picked_teams
+
+
+# ---------------------------------------------------------------------------
+# optimize_for balance (float) tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def balance_pool():
+    """
+    Pool where points-optimal and salary_change-optimal lineups differ.
+
+    D1: high points, low salary_change
+    D2: low points, high salary_change
+    D3–D5: filler
+    """
+    return pd.DataFrame(
+        {
+            "type": ["driver", "driver", "driver", "driver", "driver", "team"],
+            "driver_abbr": ["D1", "D2", "D3", "D4", "D5", None],
+            "driver_name": ["D1", "D2", "D3", "D4", "D5", "TEAM"],
+            "starting_salary": [18.0, 18.0, 10.0, 10.0, 10.0, 10.0],
+            "points_earned": [200.0, 50.0, 100.0, 100.0, 100.0, 100.0],
+            "salary_change": [0.0, 5.0, 1.0, 1.0, 1.0, 1.0],
+        }
+    )
+
+
+class TestOptimizeForBalance:
+
+    def test_balance_1_matches_points(self, balance_pool):
+        """optimize_for=1.0 should pick same drivers as optimize_for='points'."""
+        result_pts = optimal_lineup(balance_pool, optimize_for="points")
+        result_bal = optimal_lineup(balance_pool, optimize_for=1.0)
+        pts_abbrs = sorted(result_pts["driver_abbr"].dropna().tolist())
+        bal_abbrs = sorted(result_bal["driver_abbr"].dropna().tolist())
+        assert bal_abbrs == pts_abbrs
+
+    def test_balance_0_matches_salary_change(self, balance_pool):
+        """optimize_for=0.0 should pick same drivers as optimize_for='salary_change'."""
+        result_sal = optimal_lineup(balance_pool, optimize_for="salary_change")
+        result_bal = optimal_lineup(balance_pool, optimize_for=0.0)
+        sal_abbrs = sorted(result_sal["driver_abbr"].dropna().tolist())
+        bal_abbrs = sorted(result_bal["driver_abbr"].dropna().tolist())
+        assert bal_abbrs == sal_abbrs
+
+    def test_balance_star_assigned_when_balance_positive(self, balance_pool):
+        """When optimize_for is a positive float, a star driver should be assigned."""
+        result = optimal_lineup(balance_pool, optimize_for=0.5)
+        assert (result["star"] == 1).sum() == 1
+
+    def test_balance_0_star_has_no_effect(self, balance_pool):
+        """When optimize_for=0.0, a star may be set but has no impact on lineup choice."""
+        result_sal = optimal_lineup(balance_pool, optimize_for="salary_change")
+        result_bal = optimal_lineup(balance_pool, optimize_for=0.0)
+        sal_abbrs = sorted(result_sal["driver_abbr"].dropna().tolist())
+        bal_abbrs = sorted(result_bal["driver_abbr"].dropna().tolist())
+        assert bal_abbrs == sal_abbrs
+
+    def test_balance_out_of_range_raises(self, balance_pool):
+        """optimize_for outside [0, 1] should raise ValueError."""
+        with pytest.raises(ValueError, match="between 0 and 1"):
+            optimal_lineup(balance_pool, optimize_for=1.5)
+        with pytest.raises(ValueError, match="between 0 and 1"):
+            optimal_lineup(balance_pool, optimize_for=-0.1)
+
+    def test_balance_midpoint_blends_objectives(self):
+        """
+        At balance=0.5 the solver should prefer the candidate that best
+        combines normalised points and salary change.
+
+        D1: pts=200, sal_change=0 → obj = (200/100)*0.5 + 0*0.5 = 1.0
+        D2: pts=50,  sal_change=5 → obj = (50/100)*0.5 + 5*0.5  = 2.75
+        With budget=68 only one of D1/D2 fits alongside D3–D6+TEAM.
+        D2 has higher blended obj → solver picks D2 over D1.
+        """
+        df = pd.DataFrame(
+            {
+                "type": [
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "driver",
+                    "team",
+                ],
+                "driver_abbr": ["D1", "D2", "D3", "D4", "D5", "D6", None],
+                "driver_name": ["D1", "D2", "D3", "D4", "D5", "D6", "TEAM"],
+                "starting_salary": [18.0, 18.0, 10.0, 10.0, 10.0, 10.0, 10.0],
+                "points_earned": [200.0, 50.0, 100.0, 100.0, 100.0, 100.0, 100.0],
+                "salary_change": [0.0, 5.0, 1.0, 1.0, 1.0, 1.0, 1.0],
+            }
+        )
+        result = optimal_lineup(df, optimize_for=0.5, budget=68.0)
+        picked = set(result["driver_abbr"].dropna())
+        assert "D2" in picked
+        assert "D1" not in picked
+
+
 # ---------------------------------------------------------------------------
 # Pretty-print for manual inspection
 # ---------------------------------------------------------------------------