backcaster 0.4.0__tar.gz → 0.4.2__tar.gz

{backcaster-0.4.0/src/backcaster.egg-info → backcaster-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.4.0
+Version: 0.4.2
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -18,7 +18,7 @@ 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: pandas>=2.2.2
 Requires-Dist: numpy>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -27,6 +27,9 @@ Requires-Dist: ruff>=0.11.0; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: pandas-stubs>=2.2; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
 # Backcaster
@@ -56,10 +59,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.4.0:
+To install a specific release, such as 0.4.2:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.0
+python -m pip install --upgrade backcaster==0.4.2
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -73,7 +76,7 @@ python -m pip show backcaster
 
 ```bash
 # from repo root
-uv sync
+uv sync --locked
 ```
 
 This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
@@ -81,10 +84,10 @@ This installs runtime dependencies and the `backcaster` CLI entrypoint defined i
 ### Install in editable/dev mode
 
 ```bash
-uv sync --extra dev
+uv sync --locked --extra dev
 ```
 
-This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`, `setuptools`, `wheel`, `twine`).
 
 ### Build/install as a package
 
@@ -102,7 +105,7 @@ The `player`, `team`, and `batch` commands also require `--kind batting|pitching
 The `hitters` and `pitchers` commands choose their kind automatically.
 
 Subcommand-specific required options:
-- `player` requires `--name`
+- `player` requires exactly one of `--name` or `--player-id`
 - `team` requires `--team`
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
@@ -133,7 +136,9 @@ Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
 For HTML, use `--format html --out hitters_2026.html` (or a pitcher output filename).
-File formats require `--out`; the CLI format prints to the terminal.
+File formats require `--out`; the CLI format prints to the terminal and rejects
+`--out`. Invalid output options fail before data is loaded. Unwritable output
+paths report an error on stderr and exit with status 2.
 
 Players qualify for selection by meeting the existing PA/IP threshold in at least
 one of those three seasons. This is a historical eligibility list, not an active
@@ -195,7 +200,15 @@ Blank numeric counting-stat cells are also treated as zero; use a dataset with
 complete records for the seasons you intend to project.
 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.
+ambiguous name lookups report the matching IDs. Select one with `--player-id`
+instead of `--name`, for example:
+
+```bash
+backcaster player --player-id bettsmo01 --year 2026 --kind batting
+```
+
+IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+rules as name lookups.
 
 Batter league regression and rebaselining use all non-pitcher player-seasons;
 qualification selects the displayed players. Pitching retains its qualified-only
@@ -226,7 +239,7 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv
 backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
-> `--out` is required for `csv` and `html` formats.
+> `--out` is required for `csv` and `html` formats and cannot be used with `cli`.
 
 ---
 
@@ -238,8 +251,8 @@ Selected columns from a 2025 Mookie Betts projection (actual output includes
 additional counting statistics, reliability, and age):
 
 ```text
- PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
-bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869
+        Name Year  PlayerID Age  PA  AB   H HR    BA   OBP   SLG   OPS
+Mookie Betts 2025 bettsmo01  33 527 461 128 24 0.278 0.362 0.507 0.869
 ```
 
 ### Number formatting and baseball innings
@@ -248,8 +261,13 @@ Terminal, CSV, and HTML outputs use the same display rules:
 
 - Counting statistics are rounded to the nearest whole number, with halves rounded
   up. Age and year are displayed as whole numbers too.
-- AVG, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
-- ERA and WHIP always show two decimal places, such as `3.46` and `1.23`.
+- BA, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
+  BA is the canonical batter output label (previously AVG).
+  Rates with zero denominators remain undefined (NaN) and display blank;
+  OPS is undefined when OBP or SLG is undefined.
+- ERA shows two decimals; WHIP shows three. W-L% shows a three-decimal
+  fraction, such as `0.524`. H9, HR9, BB9, and SO9 show one decimal; SO/W shows two.
+  W-L% without any decisions and SO/W without walks are undefined and display blank.
 - IP is rounded to the nearest out and displayed in baseball notation:
   `161.0` is 161 innings, `161.1` is 161 innings plus one out, and `161.2` is
   161 innings plus two outs. Three outs carry into the next whole inning.
@@ -257,13 +275,34 @@ Terminal, CSV, and HTML outputs use the same display rules:
 Calculations and Python projection DataFrames retain full precision. Rates are
 computed from unrounded totals, then formatted; they are not recalculated from
 rounded displayed counts. Independently rounded totals may therefore not add up
-exactly. Reliability formatting is unchanged.
+exactly. Reliability shows six decimal places in CLI, CSV, and HTML output.
 
 **CSV IP uses baseball notation too.** Convert `161.1` to `161 + 1/3` before doing
 arithmetic; treating it as 161.1 decimal innings gives incorrect results. Internally,
 Backcaster uses decimal innings (`IPouts / 3`), so ERA and WHIP calculations use
 true innings rather than the displayed notation.
 
+### Tracked statistics and order
+
+All outputs put available Name, Year, Player ID, and Age metadata first, followed
+by these statistics in order and then Reliability:
+
+```text
+Batters:  PA,AB,R,H,2B,3B,HR,RBI,SB,CS,BB,SO,BA,OBP,SLG,OPS,TB,GDP,HBP,SH,SF,IBB
+Pitchers: W,L,W-L%,ERA,SV,IP,H,R,ER,HR,BB,IBB,SO,HBP,BK,WP,BF,WHIP,H9,HR9,BB9,SO9,SO/W
+```
+
+Lahman's batting `GIDP` is exported as `GDP`. The expanded counting-stat columns
+must be present in the appropriate local CSVs; missing columns produce an error.
+TB is derived as `H + 2B + 2×3B + 3×HR`; stolen bases do not add total bases.
+BA is H/AB, SLG is TB/AB, OBP is `(H+BB+HBP)/(AB+BB+HBP+SF)`, and OPS is OBP+SLG.
+IBB is already part of BB and is never added again to OBP or PA. Runs, RBI, SB,
+CS, and GDP are contextual counts rather than additional PA outcomes.
+
+Pitcher per-nine rates use unrounded counts and decimal IP: `9 × count / IP`.
+SO/W is SO/BB; W-L% is W/(W+L). Runs allowed (`R`) and earned runs (`ER`) are
+separate projections; ERA uses ER, while WHIP uses H+BB without adding IBB again.
+
 ### CSV output (`--format csv`)
 A single-row CSV for `player`; multi-row CSV for `team`, `batch`, `hitters`, and `pitchers`.
 Both populations include `PlayerID` for matching records across files.
@@ -302,6 +341,13 @@ Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
+### Python data-loading errors
+
+Local data-loading and validation failures raise
+`backcaster.data.DataLoadError` (renamed from `DataFetchError`). Player lookup
+failures continue to raise `PlayerLookupError`. The CLI reports these failures
+and filesystem errors on stderr with exit status 2.
+
 ## Dependency notes
 
 Runtime dependencies are intentionally minimal:
@@ -315,7 +361,12 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
+installs the locked tools with `--no-install-project`, then installs Backcaster
+with `--no-build-isolation` to keep build dependencies pinned. CI builds
+without build isolation using the locked build tools; wheel smoke tests install
+hash-checked runtime dependencies exported from the same lockfile.
 
 Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
 
@@ -323,7 +374,8 @@ Release/source ZIP archives may not include `uv.lock`. If it is missing in your
 uv lock
 ```
 
-Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+Do not hand-edit `uv.lock`; run `uv lock` and commit the updated lockfile when
+dependencies change. To deliberately refresh all pins, run `uv lock --upgrade`.
 
 ---
 

{backcaster-0.4.0 → backcaster-0.4.2}/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.4.0:
+To install a specific release, such as 0.4.2:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.0
+python -m pip install --upgrade backcaster==0.4.2
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -42,7 +42,7 @@ python -m pip show backcaster
 
 ```bash
 # from repo root
-uv sync
+uv sync --locked
 ```
 
 This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
@@ -50,10 +50,10 @@ This installs runtime dependencies and the `backcaster` CLI entrypoint defined i
 ### Install in editable/dev mode
 
 ```bash
-uv sync --extra dev
+uv sync --locked --extra dev
 ```
 
-This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`, `setuptools`, `wheel`, `twine`).
 
 ### Build/install as a package
 
@@ -71,7 +71,7 @@ The `player`, `team`, and `batch` commands also require `--kind batting|pitching
 The `hitters` and `pitchers` commands choose their kind automatically.
 
 Subcommand-specific required options:
-- `player` requires `--name`
+- `player` requires exactly one of `--name` or `--player-id`
 - `team` requires `--team`
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
@@ -102,7 +102,9 @@ Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
 For HTML, use `--format html --out hitters_2026.html` (or a pitcher output filename).
-File formats require `--out`; the CLI format prints to the terminal.
+File formats require `--out`; the CLI format prints to the terminal and rejects
+`--out`. Invalid output options fail before data is loaded. Unwritable output
+paths report an error on stderr and exit with status 2.
 
 Players qualify for selection by meeting the existing PA/IP threshold in at least
 one of those three seasons. This is a historical eligibility list, not an active
@@ -164,7 +166,15 @@ Blank numeric counting-stat cells are also treated as zero; use a dataset with
 complete records for the seasons you intend to project.
 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.
+ambiguous name lookups report the matching IDs. Select one with `--player-id`
+instead of `--name`, for example:
+
+```bash
+backcaster player --player-id bettsmo01 --year 2026 --kind batting
+```
+
+IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+rules as name lookups.
 
 Batter league regression and rebaselining use all non-pitcher player-seasons;
 qualification selects the displayed players. Pitching retains its qualified-only
@@ -195,7 +205,7 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv
 backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
-> `--out` is required for `csv` and `html` formats.
+> `--out` is required for `csv` and `html` formats and cannot be used with `cli`.
 
 ---
 
@@ -207,8 +217,8 @@ Selected columns from a 2025 Mookie Betts projection (actual output includes
 additional counting statistics, reliability, and age):
 
 ```text
- PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
-bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869
+        Name Year  PlayerID Age  PA  AB   H HR    BA   OBP   SLG   OPS
+Mookie Betts 2025 bettsmo01  33 527 461 128 24 0.278 0.362 0.507 0.869
 ```
 
 ### Number formatting and baseball innings
@@ -217,8 +227,13 @@ Terminal, CSV, and HTML outputs use the same display rules:
 
 - Counting statistics are rounded to the nearest whole number, with halves rounded
   up. Age and year are displayed as whole numbers too.
-- AVG, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
-- ERA and WHIP always show two decimal places, such as `3.46` and `1.23`.
+- BA, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
+  BA is the canonical batter output label (previously AVG).
+  Rates with zero denominators remain undefined (NaN) and display blank;
+  OPS is undefined when OBP or SLG is undefined.
+- ERA shows two decimals; WHIP shows three. W-L% shows a three-decimal
+  fraction, such as `0.524`. H9, HR9, BB9, and SO9 show one decimal; SO/W shows two.
+  W-L% without any decisions and SO/W without walks are undefined and display blank.
 - IP is rounded to the nearest out and displayed in baseball notation:
   `161.0` is 161 innings, `161.1` is 161 innings plus one out, and `161.2` is
   161 innings plus two outs. Three outs carry into the next whole inning.
@@ -226,13 +241,34 @@ Terminal, CSV, and HTML outputs use the same display rules:
 Calculations and Python projection DataFrames retain full precision. Rates are
 computed from unrounded totals, then formatted; they are not recalculated from
 rounded displayed counts. Independently rounded totals may therefore not add up
-exactly. Reliability formatting is unchanged.
+exactly. Reliability shows six decimal places in CLI, CSV, and HTML output.
 
 **CSV IP uses baseball notation too.** Convert `161.1` to `161 + 1/3` before doing
 arithmetic; treating it as 161.1 decimal innings gives incorrect results. Internally,
 Backcaster uses decimal innings (`IPouts / 3`), so ERA and WHIP calculations use
 true innings rather than the displayed notation.
 
+### Tracked statistics and order
+
+All outputs put available Name, Year, Player ID, and Age metadata first, followed
+by these statistics in order and then Reliability:
+
+```text
+Batters:  PA,AB,R,H,2B,3B,HR,RBI,SB,CS,BB,SO,BA,OBP,SLG,OPS,TB,GDP,HBP,SH,SF,IBB
+Pitchers: W,L,W-L%,ERA,SV,IP,H,R,ER,HR,BB,IBB,SO,HBP,BK,WP,BF,WHIP,H9,HR9,BB9,SO9,SO/W
+```
+
+Lahman's batting `GIDP` is exported as `GDP`. The expanded counting-stat columns
+must be present in the appropriate local CSVs; missing columns produce an error.
+TB is derived as `H + 2B + 2×3B + 3×HR`; stolen bases do not add total bases.
+BA is H/AB, SLG is TB/AB, OBP is `(H+BB+HBP)/(AB+BB+HBP+SF)`, and OPS is OBP+SLG.
+IBB is already part of BB and is never added again to OBP or PA. Runs, RBI, SB,
+CS, and GDP are contextual counts rather than additional PA outcomes.
+
+Pitcher per-nine rates use unrounded counts and decimal IP: `9 × count / IP`.
+SO/W is SO/BB; W-L% is W/(W+L). Runs allowed (`R`) and earned runs (`ER`) are
+separate projections; ERA uses ER, while WHIP uses H+BB without adding IBB again.
+
 ### CSV output (`--format csv`)
 A single-row CSV for `player`; multi-row CSV for `team`, `batch`, `hitters`, and `pitchers`.
 Both populations include `PlayerID` for matching records across files.
@@ -271,6 +307,13 @@ Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
+### Python data-loading errors
+
+Local data-loading and validation failures raise
+`backcaster.data.DataLoadError` (renamed from `DataFetchError`). Player lookup
+failures continue to raise `PlayerLookupError`. The CLI reports these failures
+and filesystem errors on stderr with exit status 2.
+
 ## Dependency notes
 
 Runtime dependencies are intentionally minimal:
@@ -284,7 +327,12 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
+installs the locked tools with `--no-install-project`, then installs Backcaster
+with `--no-build-isolation` to keep build dependencies pinned. CI builds
+without build isolation using the locked build tools; wheel smoke tests install
+hash-checked runtime dependencies exported from the same lockfile.
 
 Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
 
@@ -292,7 +340,8 @@ Release/source ZIP archives may not include `uv.lock`. If it is missing in your
 uv lock
 ```
 
-Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+Do not hand-edit `uv.lock`; run `uv lock` and commit the updated lockfile when
+dependencies change. To deliberately refresh all pins, run `uv lock --upgrade`.
 
 ---
 

{backcaster-0.4.0 → backcaster-0.4.2}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
 ]
 requires-python = ">=3.13"
 dependencies = [
-  "pandas>=2.0",
+  "pandas>=2.2.2",
   "numpy>=2.0",
 ]
 
@@ -38,6 +38,9 @@ dev = [
   "mypy>=1.10",
   "pandas-stubs>=2.2",
   "build>=1.2",
+  "setuptools>=77",
+  "wheel",
+  "twine",
 ]
 
 [project.scripts]

{backcaster-0.4.0 → backcaster-0.4.2}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.4.0"
+__version__ = "0.4.2"

backcaster-0.4.2/src/backcaster/batters.py

@@ -0,0 +1,175 @@
+"""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 ProjectionError
+from backcaster.normalize import safe_divide
+from backcaster.stat_columns import BATTING_STAT_COLUMNS, CONTEXT_STATS, IDENTITY_COLUMNS
+
+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 _context_counts(history: pd.DataFrame, events: pd.DataFrame) -> pd.DataFrame:
+    counts = history[list(CONTEXT_STATS)].astype(float)
+    if not np.isfinite(counts.to_numpy()).all() or (counts < 0).any().any():
+        raise ProjectionError("Contextual batter counts must be finite and nonnegative.")
+    if (counts["IBB"] > history["BB"]).any() or (counts["GDP"] > events["OUT"]).any():
+        raise ProjectionError(
+            "IBB must not exceed BB and GDP must not exceed non-strikeout AB outs."
+        )
+    return counts
+
+
+def _regress(
+    history: pd.DataFrame, counts: pd.DataFrame, year: int
+) -> tuple[pd.DataFrame, pd.Series, pd.DataFrame]:
+    weights = history["Season"].map({year - 1: 5.0, year - 2: 4.0, year - 3: 3.0})
+    exposure = history["PA"] * weights
+    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 = counts.groupby(history["Season"]).sum().div(league_pa, axis=0)
+    expected = league_rates.reindex(history["Season"]).set_axis(history.index).mul(exposure, axis=0)
+    evidence = counts.mul(weights, axis=0).groupby(history["PlayerID"]).sum()
+    evidence_pa = exposure.groupby(history["PlayerID"]).sum()
+    baseline = expected.groupby(history["PlayerID"]).sum().div(evidence_pa, axis=0)
+    return (evidence + 1200 * baseline).div(evidence_pa + 1200, axis=0), evidence_pa, league_rates
+
+
+def _playing_time(history: pd.DataFrame, year: int) -> pd.Series:
+    prior = (
+        history.pivot_table(index="PlayerID", columns="Season", values="PA", aggfunc="sum")
+        .reindex(columns=[year - 1, year - 2], fill_value=0)
+        .fillna(0)
+    )
+    return 0.5 * prior[year - 1] + 0.1 * prior[year - 2] + 200
+
+
+def _age_rates(
+    rates: pd.DataFrame, people: pd.DataFrame, year: int
+) -> tuple[pd.DataFrame, pd.Series]:
+    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)
+    aged = rates.copy()
+    positive = ["1B", "2B", "3B", "HR", "BB", "HBP", "R", "RBI", "SB", "IBB"]
+    negative = ["SO", "OUT", "CS", "GDP"]
+    aged[positive] = aged[positive].mul(1 - adjustment, axis=0)
+    aged[negative] = aged[negative].mul(1 + adjustment, axis=0)
+    return aged, age
+
+
+def _bounded_rebaseline(values: pd.Series, target: float, cap: pd.Series) -> pd.Series:
+    """Preserve a contextual league total while respecting per-player capacity."""
+    capacity = float(cap.sum())
+    tolerance = max(1e-8, capacity * 1e-9)
+    if target < 0 or target > capacity + tolerance:
+        raise ProjectionError("Contextual league target exceeds its available event capacity.")
+    if target == 0:
+        return values * 0
+    if target >= capacity:
+        return cap.copy()
+    # Normalize weights so target/smallest weight is a finite upper bound.
+    weights = np.maximum(values.to_numpy(dtype=float), 1e-12)
+    weights = weights / float(weights.max())
+    limits = cap.to_numpy(dtype=float)
+    low, high = 0.0, target / float(weights.min())
+    for _ in range(150):
+        scale = (low + high) / 2
+        result = np.minimum(weights * scale, limits)
+        if float(result.sum()) < target:
+            low = scale
+        else:
+            high = scale
+    return pd.Series(
+        np.minimum(weights * ((low + high) / 2), limits), index=values.index, name=values.name
+    )
+
+
+def _project_context(
+    rates: pd.DataFrame, pa: pd.Series, target: pd.Series, events: pd.DataFrame
+) -> pd.DataFrame:
+    projected = rates[list(CONTEXT_STATS)].mul(pa, axis=0)
+    desired = target[list(CONTEXT_STATS)] * float(pa.sum())
+    # Runs/RBI/baserunning are overlapping events, not extra PA outcomes.
+    for stat in ["R", "RBI", "SB", "CS"]:
+        projected[stat] *= safe_divide(float(desired[stat]), float(projected[stat].sum()))
+    projected["IBB"] = _bounded_rebaseline(projected["IBB"], float(desired["IBB"]), events["BB"])
+    projected["GDP"] = _bounded_rebaseline(projected["GDP"], float(desired["GDP"]), events["OUT"])
+    return projected
+
+
+def _summarize(projected: pd.DataFrame, pa: pd.Series) -> pd.DataFrame:
+    out = projected.copy()
+    out["H"] = out[["1B", "2B", "3B", "HR"]].sum(axis=1)
+    out["AB"] = out["H"] + out["SO"] + out["OUT"]
+    out["PA"] = pa
+    out["TB"] = out["H"] + out["2B"] + 2 * out["3B"] + 3 * out["HR"]
+    out["BA"] = out["H"] / out["AB"].replace(0, np.nan)
+    # BB includes IBB already. SB/CS/R/RBI/GDP do not add PA or total bases.
+    out["OBP"] = (out["H"] + out["BB"] + out["HBP"]) / (
+        out["AB"] + out["BB"] + out["HBP"] + out["SF"]
+    ).replace(0, np.nan)
+    out["SLG"] = out["TB"] / out["AB"].replace(0, np.nan)
+    out["OPS"] = out["OBP"] + out["SLG"]
+    return out
+
+
+def project_batters(seasons: pd.DataFrame, year: int) -> pd.DataFrame:
+    """Use all non-pitcher seasons for regression and population 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()
+    events = _events(history)
+    counts = events.join(_context_counts(history, events))
+    rates, evidence_pa, league_rates = _regress(history, counts, year)
+    pa = _playing_time(history, year)
+    people = (
+        history.sort_values("Season")
+        .drop_duplicates("PlayerID", keep="last")
+        .set_index("PlayerID")
+        .reindex(rates.index)
+    )
+    rates, age = _age_rates(rates, people, year)
+    event_rates = rates[EVENTS].div(rates[EVENTS].sum(axis=1), axis=0)
+    target = league_rates.loc[[year - 1]].iloc[0]
+    projected = _rebaseline(event_rates.mul(pa, axis=0), pa, target[EVENTS])
+    context = _project_context(rates, pa, target, projected)
+    out = _summarize(projected.join(context), pa)
+    out["Reliability"] = evidence_pa / (evidence_pa + 1200)
+    out["Age"], out["Name"], out["Year"] = age, people["Name"], year
+    out = out.reset_index()
+    return out[[*IDENTITY_COLUMNS, *BATTING_STAT_COLUMNS, "Reliability"]]

{backcaster-0.4.0 → backcaster-0.4.2}/src/backcaster/cli.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 import pandas as pd
 
-from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.data import DataLoadError, PlayerLookupError
 from backcaster.lahman import LahmanSource
 from backcaster.marcel import ProjectionError
 from backcaster.outputs import to_cli_table, to_csv, to_html
@@ -25,12 +25,19 @@ def _default_data_dir() -> str:
     return os.environ.get("LAHMAN_DATA_DIR", default)
 
 
+def _validate_output_options(output_format: str, out: str | None) -> None:
+    if output_format == "cli" and out is not None:
+        raise ValueError("--out cannot be used with --format cli; choose --format csv or html")
+    if output_format in _FILE_RENDERERS and not out:
+        raise ValueError(f"--out is required for {output_format} output")
+
+
 def _render(df: pd.DataFrame, output_format: str, out: str | None) -> None:
+    _validate_output_options(output_format, out)
     if output_format == "cli":
         print(to_cli_table(df))
     elif output_format in _FILE_RENDERERS:
-        if not out:
-            raise ValueError(f"--out is required for {output_format} output")
+        assert out is not None
         _FILE_RENDERERS[output_format](df, out)
     else:
         raise ValueError(f"Unsupported format: {output_format}")
@@ -47,7 +54,7 @@ def build_parser() -> argparse.ArgumentParser:
         else:
             sp.set_defaults(kind=kind)
         sp.add_argument("--format", choices=_OUTPUT_FORMAT_CHOICES, default="cli")
-        sp.add_argument("--out")
+        sp.add_argument("--out", help="Output path (required for csv/html; invalid with cli)")
         sp.add_argument(
             "--data-dir",
             default=_default_data_dir(),
@@ -56,7 +63,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     pp = sub.add_parser("player")
     add_common(pp)
-    pp.add_argument("--name", required=True)
+    player_selector = pp.add_mutually_exclusive_group(required=True)
+    player_selector.add_argument("--name", help="Player name (must identify one qualified player)")
+    player_selector.add_argument(
+        "--player-id", help="Exact Lahman player ID (for example, bettsmo01)"
+    )
 
     tp = sub.add_parser("team")
     add_common(tp)
@@ -75,16 +86,18 @@ def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
     try:
+        _validate_output_options(args.format, args.out)
         result = LahmanSource(args.data_dir).project(
             args.command,
             args.year,
             args.kind,
             name=getattr(args, "name", None),
             team=getattr(args, "team", None),
+            player_id=getattr(args, "player_id", None),
         )
         _render(result, args.format, args.out)
         return 0
-    except (DataFetchError, PlayerLookupError, ProjectionError, ValueError) as exc:
+    except (DataLoadError, PlayerLookupError, ProjectionError, ValueError, OSError) as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 2
 

{backcaster-0.4.0 → backcaster-0.4.2}/src/backcaster/data.py

@@ -1,8 +1,8 @@
 """Errors reported when local source data cannot be loaded or resolved."""
 
 
-class DataFetchError(RuntimeError):
-    pass
+class DataLoadError(RuntimeError):
+    """Local source files are missing, unreadable, or invalid."""
 
 
 class PlayerLookupError(RuntimeError):