backcaster 0.3.3__tar.gz → 0.3.4__tar.gz

{backcaster-0.3.3/src/backcaster.egg-info → backcaster-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.3
+Version: 0.3.4
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -17,7 +17,9 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
 Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -54,10 +56,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.3:
+To install a specific release, such as 0.3.4:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.3
+python -m pip install --upgrade backcaster==0.3.4
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -121,7 +123,8 @@ All projections use local Lahman CSVs. On Windows, the default directory is
 Set the `LAHMAN_DATA_DIR` environment variable to change the default, or pass
 `--data-dir` to override it for one command. No network requests or online
 fallbacks are made. The directory must contain `People.csv`, `Teams.csv`, and
-`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+`Batting.csv` or `Pitching.csv` for the selected kind. Batter projections also
+require `Appearances.csv` and a valid `birthYear` in `People.csv`. Filenames are matched
 without regard to case. The database is not bundled with Backcaster.
 
 For the default Windows directory, no additional flag is needed:
@@ -161,7 +164,10 @@ Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
 batters faced. Lahman player IDs keep different players with the same name separate;
 ambiguous name lookups report the matching IDs.
 
-Only qualified player-seasons enter projections and league regression baselines.
+Batter league regression and rebaselining use all non-pitcher player-seasons;
+qualification selects the displayed players. Pitching retains its qualified-only
+baseline. See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
+real-age adjustment, PA formula, and explicit rebaselining choices.
 Single-player projections require qualification in all three preceding seasons.
 Team and batch projections use each player's available qualified seasons within
 that window. For team selection, a traded player's full-season totals are assigned
@@ -292,6 +298,20 @@ Sonar consumes:
 
 ---
 
+## Acknowledgments
+
+Thank you to **Tom Tango** for developing and publishing the Marcel system, and
+to **Ben Dilday** for [marcelR](https://github.com/bdilday/marcelR), whose open R
+implementation provides a valuable methodological reference for our Python work.
+We document the reviewed formulas, source revision, and implementation differences
+in [our reference notes](docs/MARCELR_REFERENCE.md). The complete marcelR MIT
+notice is preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and shipped
+with our distributions.
+
+Thanks also to SABR, Sean Lahman, and the database contributors. See
+[Lahman attribution and licensing](docs/LAHMAN.md). These acknowledgments do not
+imply endorsement or exact agreement with another implementation's projections.
+
 ## Security and responsible use
 
 Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

{backcaster-0.3.3 → backcaster-0.3.4}/README.md

@@ -25,10 +25,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.3:
+To install a specific release, such as 0.3.4:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.3
+python -m pip install --upgrade backcaster==0.3.4
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -92,7 +92,8 @@ All projections use local Lahman CSVs. On Windows, the default directory is
 Set the `LAHMAN_DATA_DIR` environment variable to change the default, or pass
 `--data-dir` to override it for one command. No network requests or online
 fallbacks are made. The directory must contain `People.csv`, `Teams.csv`, and
-`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+`Batting.csv` or `Pitching.csv` for the selected kind. Batter projections also
+require `Appearances.csv` and a valid `birthYear` in `People.csv`. Filenames are matched
 without regard to case. The database is not bundled with Backcaster.
 
 For the default Windows directory, no additional flag is needed:
@@ -132,7 +133,10 @@ Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
 batters faced. Lahman player IDs keep different players with the same name separate;
 ambiguous name lookups report the matching IDs.
 
-Only qualified player-seasons enter projections and league regression baselines.
+Batter league regression and rebaselining use all non-pitcher player-seasons;
+qualification selects the displayed players. Pitching retains its qualified-only
+baseline. See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
+real-age adjustment, PA formula, and explicit rebaselining choices.
 Single-player projections require qualification in all three preceding seasons.
 Team and batch projections use each player's available qualified seasons within
 that window. For team selection, a traded player's full-season totals are assigned
@@ -263,6 +267,20 @@ Sonar consumes:
 
 ---
 
+## Acknowledgments
+
+Thank you to **Tom Tango** for developing and publishing the Marcel system, and
+to **Ben Dilday** for [marcelR](https://github.com/bdilday/marcelR), whose open R
+implementation provides a valuable methodological reference for our Python work.
+We document the reviewed formulas, source revision, and implementation differences
+in [our reference notes](docs/MARCELR_REFERENCE.md). The complete marcelR MIT
+notice is preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and shipped
+with our distributions.
+
+Thanks also to SABR, Sean Lahman, and the database contributors. See
+[Lahman attribution and licensing](docs/LAHMAN.md). These acknowledgments do not
+imply endorsement or exact agreement with another implementation's projections.
+
 ## Security and responsible use
 
 Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

backcaster-0.3.4/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party acknowledgments and notices
+
+## marcelR — Ben Dilday
+
+Backcaster is a Python implementation of Marcel-style baseball projections.
+[marcelR](https://github.com/bdilday/marcelR), by Ben Dilday, is an independent R
+implementation we reviewed as a methodological reference and source of inspiration.
+Thank you to Ben Dilday for sharing readable formulas, intermediate calculations,
+and historical comparison examples that help make this work reproducible.
+
+Reference revision: `13a1c7943f5a7317c9c812a28e299c2184060046` (March 1, 2020).
+See [reference and adaptation notes](docs/MARCELR_REFERENCE.md) for the files
+reviewed, formulas examined, current differences, and attribution practices.
+
+At the time this notice was added, marcelR source had been inspected, but no R
+source had been copied or translated into Backcaster, and its datasets had not
+been bundled. Backcaster does not depend on R or marcelR. The notice is retained
+for acknowledgment and to accompany future attributed adaptations. Neither the
+review nor the acknowledgment implies endorsement or verified numerical parity.
+
+The following is marcelR's MIT license notice, reproduced without changes:
+
+```text
+MIT License
+
+Copyright (c) 2017 Ben Dilday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Method and data credits
+
+Tom Tango developed the Marcel projection system. We thank him for publishing
+its methodology. SABR, Sean Lahman, and the contributors to the Lahman database
+provide the historical data on which local projections rely. The Lahman data
+license is separate; see [database attribution and caveats](docs/LAHMAN.md).

{backcaster-0.3.3 → backcaster-0.3.4}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Marcel-style MLB projection CLI using local Lahman CSV data"
 readme = "README.md"
 license = "MIT"
-license-files = ["LICENSE"]
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.13",
@@ -22,6 +22,7 @@ classifiers = [
 requires-python = ">=3.13"
 dependencies = [
   "pandas>=2.0",
+  "numpy>=2.0",
 ]
 
 [project.urls]

{backcaster-0.3.3 → backcaster-0.3.4}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.3.3"
+__version__ = "0.3.4"

backcaster-0.3.4/src/backcaster/batters.py

@@ -0,0 +1,118 @@
+"""Population-level batter projections; no projected-year statistics are read."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from backcaster.marcel import BATTING_COMPONENTS, ProjectionError
+
+EVENTS = ["1B", "2B", "3B", "HR", "BB", "HBP", "SO", "SH", "SF", "OUT"]
+
+
+def _events(frame: pd.DataFrame) -> pd.DataFrame:
+    events = frame.reindex(columns=EVENTS, fill_value=0).astype(float)
+    events["1B"] = frame["H"] - frame["2B"] - frame["3B"] - frame["HR"]
+    events["OUT"] = frame["AB"] - frame["H"] - frame["SO"]
+    if not np.isfinite(events.to_numpy()).all() or (events < 0).any().any():
+        raise ProjectionError(
+            "Batter counts must be finite and consistent (H <= AB, SO <= AB - H)."
+        )
+    return events
+
+
+def _rebaseline(events: pd.DataFrame, pa: pd.Series, target: pd.Series) -> pd.DataFrame:
+    """Rake mutually exclusive events to fixed player PA and league event totals."""
+    desired = target * float(pa.sum())
+    # Positive league outcomes must be reachable, including a historically absent
+    # event in the projected population. Seed only those cells, then rake.
+    values = events.clip(lower=1e-12).mul(desired.gt(0), axis=1)
+    for _ in range(200):
+        values = values.mul(desired.div(values.sum()).fillna(0), axis=1)
+        values = values.mul(pa.div(values.sum(axis=1)).fillna(0), axis=0)
+        if np.allclose(values.sum(), desired, rtol=1e-10, atol=1e-8):
+            return values
+    raise ProjectionError("Batter league rebaselining did not converge.")
+
+
+def project_batters(seasons: pd.DataFrame, year: int) -> pd.DataFrame:
+    """Use all non-pitcher seasons for both regression and rebaselining."""
+    history = seasons[seasons["Season"].isin([year - 1, year - 2, year - 3])].copy()
+    if history.empty:
+        raise ProjectionError("No non-pitcher batting history in the three prior seasons.")
+    history = history[history["PA"] > 0].copy()
+    counts = _events(history)
+    weights = history["Season"].map({year - 1: 5.0, year - 2: 4.0, year - 3: 3.0})
+    history["EvidencePA"] = history["PA"] * weights
+    league_counts = counts.groupby(history["Season"]).sum()
+    league_pa = history.groupby("Season")["PA"].sum()
+    if year - 1 not in league_pa:
+        raise ProjectionError("Latest completed season has no non-pitcher batting PA.")
+    league_rates = league_counts.div(league_pa, axis=0)
+    # Each player's exposure to each season determines their league average.
+    expected = (
+        league_rates.reindex(history["Season"])
+        .set_axis(history.index)
+        .mul(history["EvidencePA"], axis=0)
+    )
+    evidence = counts.mul(weights, axis=0).groupby(history["PlayerID"]).sum()
+    evidence_pa = history.groupby("PlayerID")["EvidencePA"].sum()
+    baseline = expected.groupby(history["PlayerID"]).sum().div(evidence_pa, axis=0)
+    rates = (evidence + 1200 * baseline).div(evidence_pa + 1200, axis=0)
+    prior_pa = (
+        history.pivot_table(index="PlayerID", columns="Season", values="PA", aggfunc="sum")
+        .reindex(columns=[year - 1, year - 2], fill_value=0)
+        .fillna(0)
+    )
+    pa = 0.5 * prior_pa[year - 1] + 0.1 * prior_pa[year - 2] + 200
+    people = (
+        history.sort_values("Season")
+        .drop_duplicates("PlayerID", keep="last")
+        .set_index("PlayerID")
+        .reindex(rates.index)
+    )
+    birth = pd.to_numeric(people["birthYear"], errors="coerce")
+    age = year - birth
+    if birth.isna().any() or not np.isfinite(age).all() or ((age < 15) | (age > 70)).any():
+        raise ProjectionError(
+            "Valid birthYear is required for every batter in the projection population."
+        )
+    adjustment = (age - 29) * np.where(age > 29, 0.003, 0.006)
+    rates[["1B", "2B", "3B", "HR", "BB", "HBP"]] = rates[["1B", "2B", "3B", "HR", "BB", "HBP"]].mul(
+        1 - adjustment, axis=0
+    )
+    rates[["SO", "OUT"]] = rates[["SO", "OUT"]].mul(1 + adjustment, axis=0)
+    rates = rates.div(rates.sum(axis=1), axis=0)
+    projected = _rebaseline(rates.mul(pa, axis=0), pa, league_rates.loc[[year - 1]].iloc[0])
+    out = projected.copy()
+    out["H"] = projected[["1B", "2B", "3B", "HR"]].sum(axis=1)
+    out["AB"] = out["H"] + projected["SO"] + projected["OUT"]
+    out["PA"] = pa
+    out["AVG"] = out["H"] / out["AB"].replace(0, np.nan)
+    out["OBP"] = (out["H"] + out["BB"] + out["HBP"]) / (
+        out["AB"] + out["BB"] + out["HBP"] + out["SF"]
+    ).replace(0, np.nan)
+    out["SLG"] = (projected["1B"] + 2 * out["2B"] + 3 * out["3B"] + 4 * out["HR"]) / out[
+        "AB"
+    ].replace(0, np.nan)
+    out["OPS"] = out["OBP"] + out["SLG"]
+    out["Reliability"] = evidence_pa / (evidence_pa + 1200)
+    out["Age"] = age
+    out["Name"] = people["Name"]
+    out["Year"] = year
+    out = out.fillna(0).drop(columns=["1B", "OUT"]).reset_index()
+    return out[
+        [
+            "PlayerID",
+            *BATTING_COMPONENTS,
+            "SH",
+            "AVG",
+            "OBP",
+            "SLG",
+            "OPS",
+            "Reliability",
+            "Age",
+            "Name",
+            "Year",
+        ]
+    ]

{backcaster-0.3.3 → backcaster-0.3.4}/src/backcaster/lahman.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 import pandas as pd
 
+from backcaster.batters import project_batters
 from backcaster.data import DataFetchError, PlayerLookupError
 from backcaster.marcel import ProjectionError, project_player, project_team
 
@@ -37,7 +38,7 @@ class LahmanSource:
             )
         return frame
 
-    def season(self, year: int, kind: str) -> pd.DataFrame:
+    def season(self, year: int, kind: str, *, qualified: bool = True) -> pd.DataFrame:
         if kind not in {"batting", "pitching"}:
             raise DataFetchError(f"Invalid kind {kind!r}.")
         name = "Batting" if kind == "batting" else "Pitching"
@@ -75,11 +76,13 @@ class LahmanSource:
         if kind == "batting":
             totals["PA"] = totals[["AB", "BB", "HBP", "SF", "SH"]].sum(axis=1)
             minimum_pa = int(3.1 * games + 0.5)
-            totals = totals[totals["PA"] >= minimum_pa]
+            totals["Qualified"] = totals["PA"] >= minimum_pa
         else:
             totals["IP"] = totals["IPouts"] / 3
             totals["BF"] = totals["BFP"]
-            totals = totals[totals["IPouts"] >= 3 * games]
+            totals["Qualified"] = totals["IPouts"] >= 3 * games
+        if qualified:
+            totals = totals[totals["Qualified"]]
         if totals.empty:
             raise DataFetchError(f"No qualified {kind} players in Lahman for {year}.")
         totals = self._attach_names(totals)
@@ -101,7 +104,10 @@ class LahmanSource:
         ).str.strip()
         try:
             totals = totals.reset_index().merge(
-                people[["playerID", "Name"]], on="playerID", how="left", validate="many_to_one"
+                people[["playerID", "Name", *(["birthYear"] if "birthYear" in people else [])]],
+                on="playerID",
+                how="left",
+                validate="many_to_one",
             )
         except pd.errors.MergeError as exc:
             raise DataFetchError("Duplicate player IDs in Lahman People.csv.") from exc
@@ -114,25 +120,19 @@ class LahmanSource:
     def project(
         self, command: str, year: int, kind: str, name: str | None = None, team: str | None = None
     ) -> pd.DataFrame:
-        seasons = pd.concat(
-            [self.season(y, kind) for y in (year - 1, year - 2, year - 3)], ignore_index=True
-        )
+        batting = pd.DataFrame()
+        if kind == "batting":
+            seasons, batting = self._batting_population(year)
+        else:
+            seasons = pd.concat(
+                [self.season(y, kind) for y in (year - 1, year - 2, year - 3)], ignore_index=True
+            )
         if command == "player":
-            normalized = " ".join((name or "").casefold().split())
-            matches = seasons[
-                seasons["Name"].map(lambda value: " ".join(value.casefold().split())) == normalized
-            ]
-            ids = matches["PlayerID"].unique()
-            if len(ids) == 0:
-                raise PlayerLookupError(
-                    f"No qualified Lahman player found for '{name}' in the prior three seasons."
-                )
-            if len(ids) > 1:
-                raise PlayerLookupError(
-                    f"Ambiguous Lahman name '{name}'; matching player IDs: {', '.join(ids)}."
+            matches = self._player_seasons(seasons, name)
+            if kind == "batting":
+                return batting[batting["PlayerID"] == matches["PlayerID"].iloc[0]].reset_index(
+                    drop=True
                 )
-            if matches["Season"].nunique() != 3:
-                raise ProjectionError(f"Player '{name}' must qualify in all three prior seasons.")
             return project_player(
                 str(matches["Name"].iloc[0]), matches, kind, year, league_df=seasons
             )
@@ -143,4 +143,57 @@ class LahmanSource:
                 raise ProjectionError(
                     f"No qualified players for Lahman team ID '{team}' in the prior three seasons."
                 )
+        if kind == "batting":
+            return batting[batting["PlayerID"].isin(selected["PlayerID"])].reset_index(drop=True)
         return project_team(selected, kind, year, baseline_df=seasons)
+
+    def _batting_population(self, year: int) -> tuple[pd.DataFrame, pd.DataFrame]:
+        self.read("People", {"playerID", "nameFirst", "nameLast", "birthYear"})
+        seasons = pd.concat(
+            [self.season(y, "batting", qualified=False) for y in (year - 1, year - 2, year - 3)],
+            ignore_index=True,
+        )
+        appearances = self.read("Appearances", {"playerID", "yearID", "G_all", "G_p"})
+        appearances = appearances[appearances["yearID"].isin([year - 1, year - 2, year - 3])].copy()
+        try:
+            appearances[["G_all", "G_p"]] = appearances[["G_all", "G_p"]].apply(
+                pd.to_numeric, errors="raise"
+            )
+        except (ValueError, TypeError) as exc:
+            raise DataFetchError("Invalid game counts in Lahman Appearances.csv.") from exc
+        counts = appearances[["G_all", "G_p"]]
+        invalid = counts.replace([float("inf"), -float("inf")], float("nan")).isna() | (counts < 0)
+        if invalid.any().any() or (appearances["G_p"] > appearances["G_all"]).any():
+            raise DataFetchError("Invalid game counts in Lahman Appearances.csv.")
+        games = appearances.groupby(["playerID", "yearID"])[["G_all", "G_p"]].sum(min_count=1)
+        seasons = seasons.merge(games, left_on=["PlayerID", "Season"], right_index=True, how="left")
+        if seasons[["G_all", "G_p"]].isna().any().any():
+            raise DataFetchError(
+                "Appearances.csv must cover every batting player-season with game counts."
+            )
+        # A primary pitcher appears as pitcher in more than half of their games.
+        # Retain two-way hitters whose batting appearances outnumber pitching games.
+        seasons = seasons[seasons["G_p"] <= seasons["G_all"] / 2].copy()
+        projected = project_batters(seasons, year)
+        qualified = seasons[seasons["Qualified"]]
+        if qualified.empty:
+            raise ProjectionError("No qualified non-pitcher batters in the prior three seasons.")
+        return qualified, projected
+
+    def _player_seasons(self, seasons: pd.DataFrame, name: str | None) -> pd.DataFrame:
+        normalized = " ".join((name or "").casefold().split())
+        matches = seasons[
+            seasons["Name"].map(lambda value: " ".join(value.casefold().split())) == normalized
+        ]
+        ids = matches["PlayerID"].unique()
+        if len(ids) == 0:
+            raise PlayerLookupError(
+                f"No qualified Lahman player found for '{name}' in the prior three seasons."
+            )
+        if len(ids) > 1:
+            raise PlayerLookupError(
+                f"Ambiguous Lahman name '{name}'; matching player IDs: {', '.join(ids)}."
+            )
+        if matches["Season"].nunique() != 3:
+            raise ProjectionError(f"Player '{name}' must qualify in all three prior seasons.")
+        return matches

{backcaster-0.3.3 → backcaster-0.3.4/src/backcaster.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.3
+Version: 0.3.4
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -17,7 +17,9 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
 Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -54,10 +56,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.3:
+To install a specific release, such as 0.3.4:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.3
+python -m pip install --upgrade backcaster==0.3.4
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -121,7 +123,8 @@ All projections use local Lahman CSVs. On Windows, the default directory is
 Set the `LAHMAN_DATA_DIR` environment variable to change the default, or pass
 `--data-dir` to override it for one command. No network requests or online
 fallbacks are made. The directory must contain `People.csv`, `Teams.csv`, and
-`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+`Batting.csv` or `Pitching.csv` for the selected kind. Batter projections also
+require `Appearances.csv` and a valid `birthYear` in `People.csv`. Filenames are matched
 without regard to case. The database is not bundled with Backcaster.
 
 For the default Windows directory, no additional flag is needed:
@@ -161,7 +164,10 @@ Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
 batters faced. Lahman player IDs keep different players with the same name separate;
 ambiguous name lookups report the matching IDs.
 
-Only qualified player-seasons enter projections and league regression baselines.
+Batter league regression and rebaselining use all non-pitcher player-seasons;
+qualification selects the displayed players. Pitching retains its qualified-only
+baseline. See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
+real-age adjustment, PA formula, and explicit rebaselining choices.
 Single-player projections require qualification in all three preceding seasons.
 Team and batch projections use each player's available qualified seasons within
 that window. For team selection, a traded player's full-season totals are assigned
@@ -292,6 +298,20 @@ Sonar consumes:
 
 ---
 
+## Acknowledgments
+
+Thank you to **Tom Tango** for developing and publishing the Marcel system, and
+to **Ben Dilday** for [marcelR](https://github.com/bdilday/marcelR), whose open R
+implementation provides a valuable methodological reference for our Python work.
+We document the reviewed formulas, source revision, and implementation differences
+in [our reference notes](docs/MARCELR_REFERENCE.md). The complete marcelR MIT
+notice is preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and shipped
+with our distributions.
+
+Thanks also to SABR, Sean Lahman, and the database contributors. See
+[Lahman attribution and licensing](docs/LAHMAN.md). These acknowledgments do not
+imply endorsement or exact agreement with another implementation's projections.
+
 ## Security and responsible use
 
 Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

{backcaster-0.3.3 → backcaster-0.3.4}/src/backcaster.egg-info/SOURCES.txt

@@ -1,7 +1,9 @@
 LICENSE
 README.md
+THIRD_PARTY_NOTICES.md
 pyproject.toml
 src/backcaster/__init__.py
+src/backcaster/batters.py
 src/backcaster/cli.py
 src/backcaster/data.py
 src/backcaster/lahman.py
@@ -15,6 +17,7 @@ src/backcaster.egg-info/dependency_links.txt
 src/backcaster.egg-info/entry_points.txt
 src/backcaster.egg-info/requires.txt
 src/backcaster.egg-info/top_level.txt
+tests/test_batters.py
 tests/test_cli.py
 tests/test_lahman.py
 tests/test_marcel_math.py

{backcaster-0.3.3 → backcaster-0.3.4}/src/backcaster.egg-info/requires.txt

@@ -1,4 +1,5 @@
 pandas>=2.0
+numpy>=2.0
 
 [dev]
 pytest>=8.0

backcaster-0.3.4/tests/test_batters.py

@@ -0,0 +1,120 @@
+import numpy as np
+import pandas as pd
+import pytest
+
+from backcaster import batters
+from backcaster.batters import EVENTS, _events, _rebaseline, project_batters
+from backcaster.marcel import ProjectionError
+
+
+def history() -> pd.DataFrame:
+    rows = []
+    for year, pa, hr in [(2024, 600, 60), (2023, 300, 30), (2022, 100, 0)]:
+        for player, exposure, homers in [("A", pa, hr), ("B", 1000 - pa, 0)]:
+            rows.append(
+                dict(
+                    PlayerID=player,
+                    Name=player,
+                    Season=year,
+                    PA=exposure,
+                    AB=exposure,
+                    H=exposure * 0.25,
+                    SO=exposure * 0.2,
+                    HR=homers,
+                    **{"2B": exposure * 0.05, "3B": 0},
+                    BB=0,
+                    HBP=0,
+                    SF=0,
+                    SH=0,
+                    birthYear=1996,
+                )
+            )
+    return pd.DataFrame(rows)
+
+
+def test_exposure_weighted_league_and_playing_time(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(batters, "_rebaseline", lambda events, pa, target: events)
+    result = project_batters(history(), 2025).set_index("PlayerID")
+    assert result.loc["A", "PA"] == 530
+    # Weighted player PA=4,500; HR=420; league HR/PA=.06/.03/0.
+    # Player-specific baseline=(3000*.06+1200*.03+300*0)/4500=.048.
+    assert result.loc["A", "HR"] == pytest.approx(530 * (420 + 1200 * 0.048) / 5700)
+    assert result.loc["A", "Reliability"] == pytest.approx(4500 / 5700)
+    assert result.loc["A", "Age"] == 29
+
+
+def test_rebaselining_conserves_player_pa_and_league_rates() -> None:
+    data = history()
+    result = project_batters(data, 2025)
+    target = _events(data[data.Season == 2024]).sum() / 1000
+    actual = _events(result).sum() / result.PA.sum()
+    np.testing.assert_allclose(actual, target, atol=1e-10)
+    np.testing.assert_allclose(_events(result).sum(axis=1), result.PA)
+    assert (result[EVENTS[1:-1]] >= 0).all().all()
+
+
+def test_age_changes_skills_without_changing_pa(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(batters, "_rebaseline", lambda events, pa, target: events)
+    data = history()
+    neutral = project_batters(data, 2025).set_index("PlayerID")
+    data.loc[data.PlayerID == "A", "birthYear"] = 1993  # Age 32.
+    data.loc[data.PlayerID == "B", "birthYear"] = 2000  # Age 25.
+    adjusted = project_batters(data, 2025).set_index("PlayerID")
+    assert adjusted.loc["A", "AVG"] < neutral.loc["A", "AVG"]
+    assert adjusted.loc["B", "AVG"] > neutral.loc["B", "AVG"]
+    pd.testing.assert_series_equal(adjusted.PA, neutral.PA)
+
+
+def test_calendar_weights_missing_season_and_no_future_leakage(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(batters, "_rebaseline", lambda events, pa, target: events)
+    data = history()
+    data = data[~((data.PlayerID == "A") & (data.Season == 2023))]
+    future = data[data.Season == 2024].assign(Season=2025, HR=9999)
+    result = project_batters(pd.concat([data, future]), 2025).set_index("PlayerID")
+    assert result.loc["A", "PA"] == 500
+    assert result.loc["A", "Reliability"] == pytest.approx(3300 / 4500)
+
+
+@pytest.mark.parametrize(
+    "case, message",
+    [
+        ("empty", "No non-pitcher"),
+        ("latest", "Latest completed"),
+        ("counts", "finite and consistent"),
+        ("birth", "birthYear"),
+    ],
+)
+def test_bad_history(case: str, message: str) -> None:
+    data = history()
+    if case == "empty":
+        data = data.iloc[:0]
+    elif case == "latest":
+        data = data[data.Season != 2024]
+    elif case == "counts":
+        data["H"] = -1
+    else:
+        data["birthYear"] = np.nan
+    with pytest.raises(ProjectionError, match=message):
+        project_batters(data, 2025)
+
+
+def test_zero_denominators_and_absent_events() -> None:
+    data = history()
+    data[["H", "2B", "HR", "SO"]] = 0
+    data["AB"] = 0
+    data["BB"] = data["PA"]
+    result = project_batters(data, 2025)
+    assert result.AVG.eq(0).all()
+    assert result.OBP.eq(1).all()
+    assert result.SLG.eq(0).all()
+
+
+def test_rebaseline_nonconvergence(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(batters.np, "allclose", lambda *args, **kwargs: False)
+    events = pd.DataFrame([{c: 1.0 for c in EVENTS}])
+    pa = pd.Series([10.0])
+    target = pd.Series({c: 0.1 for c in EVENTS})
+    with pytest.raises(ProjectionError, match="did not converge"):
+        _rebaseline(events, pa, target)

{backcaster-0.3.3 → backcaster-0.3.4}/tests/test_lahman.py

@@ -13,9 +13,9 @@ from backcaster.marcel import ProjectionError
 def lahman(tmp_path: Path) -> Path:
     pd.DataFrame(
         [
-            {"playerID": "star", "nameFirst": "Test", "nameLast": "Star"},
-            {"playerID": "other", "nameFirst": "Other", "nameLast": "Player"},
-            {"playerID": "minor", "nameFirst": "Brief", "nameLast": "Career"},
+            {"playerID": "star", "nameFirst": "Test", "nameLast": "Star", "birthYear": 1990},
+            {"playerID": "other", "nameFirst": "Other", "nameLast": "Player", "birthYear": 1993},
+            {"playerID": "minor", "nameFirst": "Brief", "nameLast": "Career", "birthYear": 1995},
         ]
     ).to_csv(tmp_path / "People.csv", index=False)
     batting, pitching, teams = [], [], []
@@ -29,11 +29,11 @@ def lahman(tmp_path: Path) -> Path:
                     stint=1,
                     teamID="BOS",
                     AB=ab,
-                    H=150,
-                    **{"2B": 30, "3B": 2},
-                    HR=20,
+                    H=150 if player != "minor" else 5,
+                    **{"2B": 30 if player != "minor" else 1, "3B": 2 if player != "minor" else 0},
+                    HR=20 if player != "minor" else 0,
                     BB=bb,
-                    SO=100,
+                    SO=100 if player != "minor" else 5,
                     HBP=5,
                     SF=5,
                     SH=1,
@@ -54,6 +54,13 @@ def lahman(tmp_path: Path) -> Path:
                     BFP=700,
                 )
             )
+    pd.DataFrame(
+        [
+            dict(playerID=p, yearID=y, G_all=100, G_p=0)
+            for p in ["star", "other", "minor"]
+            for y in (2019, 2020, 2021)
+        ]
+    ).to_csv(tmp_path / "Appearances.csv", index=False)
     pd.DataFrame(batting).to_csv(tmp_path / "Batting.csv", index=False)
     pd.DataFrame(pitching).to_csv(tmp_path / "Pitching.csv", index=False)
     pd.DataFrame(teams).to_csv(tmp_path / "Teams.csv", index=False)
@@ -90,6 +97,7 @@ def test_short_season_threshold(lahman: Path) -> None:
     path = lahman / "Batting.csv"
     frame = pd.read_csv(path)
     frame.loc[frame.playerID == "star", ["AB", "BB", "HBP", "SF", "SH"]] = [190, 0, 0, 0, 0]
+    frame.loc[frame.playerID == "star", ["H", "SO"]] = [60, 20]
     frame.to_csv(path, index=False)
     source = LahmanSource(str(lahman))
     assert "star" in set(source.season(2020, "batting").PlayerID)
@@ -221,7 +229,7 @@ def test_cli_missing_directory_returns_error(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     assert main(["batch", "--year", "2022", "--kind", "batting", "--data-dir", str(tmp_path)]) == 2
-    assert "Expected Batting.csv" in capsys.readouterr().err
+    assert "Expected People.csv" in capsys.readouterr().err
 
 
 def test_qualification_boundary(lahman: Path) -> None:
@@ -261,4 +269,71 @@ def test_missing_default_files_never_fall_back_to_network(
     monkeypatch.setattr("socket.socket.connect", forbidden)
     monkeypatch.setenv("LAHMAN_DATA_DIR", str(tmp_path))
     assert main(["player", "--name", "Test Star", "--year", "2022", "--kind", "batting"]) == 2
-    assert "Expected Batting.csv" in capsys.readouterr().err
+    assert "Expected People.csv" in capsys.readouterr().err
+
+
+def test_batter_commands_share_population_rebaseline(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    player = source.project("player", 2022, "batting", name="Test Star")
+    batch = source.project("batch", 2022, "batting")
+    team = source.project("team", 2022, "batting", team="BOS")
+    expected = batch[batch.PlayerID == "star"].reset_index(drop=True)
+    pd.testing.assert_frame_equal(player, expected)
+    pd.testing.assert_frame_equal(team, batch)
+    assert player.loc[0, "PA"] == pytest.approx(0.5 * 571 + 0.1 * 571 + 200)
+    assert player.loc[0, "Age"] == 32
+
+
+def test_pitcher_exclusion_and_unqualified_league_context(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    before = source.project("batch", 2022, "batting")
+    path = lahman / "Appearances.csv"
+    appearances = pd.read_csv(path)
+    appearances.loc[appearances.playerID == "minor", "G_p"] = 100
+    appearances.to_csv(path, index=False)
+    after = LahmanSource(str(lahman)).project("batch", 2022, "batting")
+    assert set(after.PlayerID) == {"star", "other"}
+    assert not before.HR.equals(after.HR)
+
+
+@pytest.mark.parametrize(
+    "case, message",
+    [
+        ("missing", "must cover"),
+        ("numeric", "Invalid game counts"),
+        ("no_qualified", "No qualified non-pitcher"),
+    ],
+)
+def test_batting_population_errors(lahman: Path, case: str, message: str) -> None:
+    path = lahman / "Appearances.csv"
+    frame = pd.read_csv(path)
+    if case == "missing":
+        frame = frame[frame.playerID != "star"]
+    elif case == "numeric":
+        frame["G_p"] = "invalid"
+    else:
+        # Only the unqualified player remains a non-pitcher.
+        frame.loc[frame.playerID != "minor", "G_p"] = 100
+    frame.to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    with pytest.raises((DataFetchError, ProjectionError), match=message):
+        source.project("batch", 2022, "batting")
+
+
+@pytest.mark.parametrize("bad", [-1, 101, float("inf"), float("nan")])
+def test_invalid_appearance_counts(lahman: Path, bad: float) -> None:
+    path = lahman / "Appearances.csv"
+    frame = pd.read_csv(path)
+    frame["G_p"] = bad
+    frame.to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match="Invalid game counts"):
+        source.project("batch", 2022, "batting")
+
+
+def test_missing_birth_year_column(lahman: Path) -> None:
+    path = lahman / "People.csv"
+    pd.read_csv(path).drop(columns="birthYear").to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match="birthYear"):
+        source.project("batch", 2022, "batting")