Backcaster

Backcaster is a Python CLI that produces Marcel-style MLB projections from the prior three seasons of data using local Lahman CSV files and pandas.

It supports:

• Single player projections (player)
• Single team projections (team)
• League-wide projections (hitters, pitchers, or batch)
• Output as terminal table, CSV, or HTML

Installation

Requirements

• Python 3.13+
• An extracted Lahman CSV database covering the three prior seasons
• Internet access for package installation only; projections run offline

Update an installed package

Upgrade to the latest release available on PyPI:

python -m pip install --upgrade backcaster

To install a specific release, such as 0.4.0:

python -m pip install --upgrade backcaster==0.4.0

Run the command using the same Python environment where you run Backcaster. If you use a virtual environment, activate it first. Check the installed version with:

python -m pip show backcaster

Install from source (recommended for contributors)

# from repo root
uv sync

This installs runtime dependencies and the backcaster CLI entrypoint defined in pyproject.toml.

Install in editable/dev mode

uv sync --extra dev

This adds test/lint/type-check/build tooling (pytest, pytest-cov, ruff, mypy, pandas-stubs, build).

Build/install as a package

python -m build
pip install dist/backcaster-*.whl

Quickstart CLI usage

All commands require --year, the target projection year. 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
• team requires --team
• batch, hitters, and pitchers require no player or team option

backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
backcaster <hitters|pitchers> --year <YEAR> [--data-dir PATH] [--format cli|csv|html] [--out PATH]

Pre-offseason league projections

Once the latest regular season is present in your local Lahman files, generate both populations without roster updates or team filters. For terminal output:

backcaster hitters --year 2026
backcaster pitchers --year 2026

To save files for comparison with Baseball Reference:

backcaster hitters --year 2026 --format csv --out hitters_2026.csv
backcaster pitchers --year 2026 --format csv --out pitchers_2026.csv

--year 2026 projects 2026 from 2023–2025; it never reads 2026 statistics. 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.

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 roster; pitchers who never reach the qualifying innings threshold (including most relievers) remain excluded. Qualification selects players without removing their other seasons from the calculation. Trades are combined into one player-season before qualification, and all teams' statistics contribute once. The output is one row per selected player, ready for comparison with reference projections.

1) Player projection

backcaster player --name "Mookie Betts" --year 2026 --kind batting

Offline projections with Lahman CSVs

All projections use local Lahman CSVs. On Windows, the default directory is C:\Baseball\lahman; on other systems it is ~/Baseball/lahman. 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. Both kinds require valid birthYear values in People.csv; batters additionally require Appearances.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:

backcaster player --name "Mookie Betts" --year 2024 --kind batting

See Lahman database notes for the supplied 1871–2025 edition's coverage, attribution, license, and historical-data caveats, with its original README.

backcaster player --name "Mookie Betts" --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
backcaster team --team LAN --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --format csv --out pitchers.csv

Use Lahman's teamID values, such as LAN for the Dodgers (rather than the FanGraphs abbreviation LAD). A projection year needs the preceding three seasons: 2022 requires 2019–2021. Missing seasons produce an error explaining which year is unavailable. If the directory or required files are missing, the command reports the missing file and directory; it never attempts an online fetch.

Offline qualification uses a consistent modern rule across historical seasons: at least 3.1 PA per game for hitters and one inning per game for pitchers. The season's game count is the maximum G in that year's Teams.csv records, so shortened seasons have lower thresholds. The PA threshold is rounded to the nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a reconstruction of historical award eligibility or batting-title exceptions. Relievers generally do not qualify under this pitching rule.

Player stints are summed before qualification. Plate appearances are calculated as AB + BB + HBP + SF + SH; missing/blank HBP, SF, and SH values count as zero. 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.

Batter league regression and rebaselining use all non-pitcher player-seasons; qualification selects the displayed players. Pitching retains its qualified-only baseline, with real-age performance adjustments documented in the pitcher model. See the batter model for the six-stage calculation, real-age adjustment, PA formula, and explicit rebaselining choices. Eligibility means qualifying in at least one of the three preceding seasons. For every selected player, projections use all available seasons in that window, including nonqualified seasons and seasons spent with other teams. For team selection, a traded player's full-season totals are assigned to the team in their latest stint for that season; this is not a current-roster forecast.

2) Team projection

backcaster team --team LAN --year 2026 --kind pitching

3) Batch projection (all eligible players)

backcaster batch --year 2026 --kind batting

File outputs

backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv --out ./out/mookie_2026.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.

Output examples

CLI table output (--format cli, default)

Selected columns from a 2025 Mookie Betts projection (actual output includes additional counting statistics, reliability, and age):

 PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869

Number formatting and baseball innings

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.
• 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.

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.

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.

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.

HTML output (--format html)

A standalone report with embedded CSS and JavaScript, ready to open in a browser or share as one file. No server, CDN, fonts, or internet connection are required.

backcaster hitters --year 2025 --format html --out hitters_2025.html
backcaster pitchers --year 2025 --format html --out pitchers_2025.html

The first four columns are Name, Year, Player ID, Age, followed by counting statistics and batting/pitching rates in a consistent order. The report includes:

• A player-count, projection-year, and projection-type summary.
• Search across player names, IDs, and statistics.
• Sortable column headings, with numeric sorting for statistics.
• A sticky name column/header and horizontal scrolling on narrow screens.
• A reset control and print layout for browser printing or saving as PDF.

Your display precision rules apply, including baseball innings notation. Rates retain their trailing decimal places and OPS values above 1.000 display normally. Search filters the visible rows; printing respects that current view. Without JavaScript, the complete table is still readable. See HTML report customization for theme and column constants.

Local data updates

Backcaster reads the local CSV files for each command and does not use the old FanGraphs season cache. To refresh the data, replace the CSVs with a complete Lahman distribution from the same edition. Existing online caches are ignored.

Dependency notes

Runtime dependencies are intentionally minimal:

• pandas for tabular data processing and projection output
• numpy for numerical operations and rebaselining convergence checks

Development dependencies (--extra dev) include:

• pytest, pytest-cov
• ruff
• mypy, pandas-stubs

Lockfile policy (uv.lock)

uv.lock pins transitive versions for reproducible environments when working from a Git checkout.

Release/source ZIP archives may not include uv.lock. If it is missing in your environment, regenerate it locally:

uv lock

Do not hand-edit uv.lock; regenerate it when dependencies change.

What this projection does and does not claim

What it does

• Implements a Marcel-style weighted/regressed projection over prior seasons.
• Uses configurable reliability/regression/playing-time assumptions in code defaults.
• Produces transparent, table-based outputs for downstream analysis.

What it does not claim

• It is not an official MLB/club forecasting system.
• It does not model injuries, role changes, park effects, coaching strategy, or transaction context in a comprehensive way.
• It does not guarantee predictive superiority versus commercial/public projection systems.
• It should be treated as a baseline projection tool, not a betting or financial decision engine.

Development and quality checks

For release preparation and PyPI Trusted Publishing, see RELEASING.md. Changes for the next release are recorded in CHANGELOG.md.

Run tests

pytest

Coverage + JUnit reports

pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml

Lint and types

ruff check .
mypy

SonarScanner

sonar-scanner -Dsonar.projectVersion=$(PYTHONPATH=src python -c "from backcaster import __version__; print(__version__)")

Sonar consumes:

• coverage.xml
• pytest.xml

Acknowledgments

Thank you to Tom Tango for developing and publishing the Marcel system, and to Ben Dilday for 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. The complete marcelR MIT notice is preserved in THIRD_PARTY_NOTICES.md and shipped with our distributions.

Thanks also to SABR, Sean Lahman, and the database contributors. See Lahman attribution and licensing. 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.