跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

pybaseball

Load MLB Statcast, batting, pitching, standings, and player lookup data directly with pybaseball. Use for bounded pitch-level pulls, season tables, schema checks, and user-owned baseball data artifacts.

WalrusQuant · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add WalrusQuant/sports-analytic-skills --skill pybaseball

技能说明


name: pybaseball description: > Load MLB Statcast, batting, pitching, standings, and player lookup data directly with pybaseball. Use for bounded pitch-level pulls, season tables, schema checks, and user-owned baseball data artifacts. license: MIT metadata: version: "0.12.0"

pybaseball

Outcome

Create a bounded, documented MLB artifact at pitch, player-season, team-season, or schedule grain. Record the function and arguments, package version, retrieval time, schema, coverage, natural key, qualifier rules, and transformations.

Pybaseball is especially useful for Statcast depth and public batting/pitching tables. Source convenience does not make every returned field legal for a pre-pitch or pregame model.

When to use this skill

Use for pitch-level Statcast analysis, player-specific pitch pulls, season batting and pitching tables, player identifier lookup, and selected team records. For a general full-league schedule panel, evaluate whether a schedule-oriented source is narrower and more stable. Use a multi-sport source for other leagues.

Installation

python -m pip install pybaseball pandas pyarrow

Public endpoints can be slow or change. Start small, cache successful pulls, record versions, and avoid aggressive retries.

Provider-health boundary

Pybaseball is a collection of clients and scrapers over multiple upstream providers, not one uniform service. A successful import proves nothing about FanGraphs, Baseball Savant, Baseball Reference, Chadwick, or Retrosheet health. Probe the exact function family required for the analysis and record the provider separately.

In particular, batting_stats and pitching_stats are FanGraphs-backed. The upstream project has reports of FanGraphs returning HTTP 403/CAPTCHA responses; see pybaseball issue #507. This is a provider/interface-health warning, not evidence that every pybaseball function is unavailable. Statcast uses Baseball Savant and must be probed independently. Do not bypass access controls or hammer retries. If the required provider is unhealthy, fail visibly, preserve the error and retrieval time, and use a documented licensed/official alternative or a previously verified snapshot rather than treating an empty frame as data.

Choose the correct loader

NeedDirect functionGrainImportant caveat
Player-season battingbatting_stats(start, end)player-seasonqualifiers and provider definitions
Player-season pitchingpitching_stats(start, end)player-seasoninnings/qualification filters
League pitch datastatcast(start_dt, end_dt)pitchpotentially large; bound dates
Batter-specific pitchesstatcast_batter(start_dt, end_dt, player_id)pitchuse stable MLBAM ID
Pitcher-specific pitchesstatcast_pitcher(start_dt, end_dt, player_id)pitchuse stable MLBAM ID
Player identifierplayerid_lookup(last, first)candidate person matchesresolve ambiguity explicitly
Team schedule/recordschedule_and_record(season, team)team-gamenot automatically a full-league panel

Read references/pull_patterns.md for concise season-table and Statcast call patterns. Read references/statcast_bounds.md before any multi-day, multi-player, or repeated Statcast acquisition.

Example loads

from pybaseball import batting_stats, pitching_stats, statcast

batters = batting_stats(2023, 2024, qual=100)
pitchers = pitching_stats(2024, 2024, qual=50)
pitches = statcast(start_dt="2024-04-01", end_dt="2024-04-07")

Use a short date window first. Inspect the returned schema and units before requesting a larger interval.

Acquisition workflow

  1. Lock the question, grain, date/season range, entity, and required fields.
  2. Define decision time if the artifact may feed a prospective model.
  3. Choose the narrowest direct function and stable identifiers.
  4. Probe one player, one season table, or a short date interval.
  5. Inspect rows, columns, dtypes, nulls, duplicates, units, and category values.
  6. For long intervals, define non-overlapping chunks with retry and stop rules.
  7. Save each successful immutable chunk before requesting the next.
  8. Check chunk coverage, overlap, schema consistency, and key uniqueness.
  9. Concatenate only validated chunks; retain raw artifacts separately.
  10. Save Parquet plus a manifest containing exact function arguments.

Statcast planning

Estimate scope before pulling:

date_start / date_end
league-wide or player-specific
expected active days
required columns
chunk interval
natural pitch key
retry/backoff limit
raw chunk naming
coverage and overlap check

Prefer days or weeks for exploration. A full season can contain hundreds of thousands of pitches and may be unnecessary. Do not loop player-by-player when a single bounded league-wide pull plus local filter answers the question.

Validation checks

All artifacts

  • observed dates or seasons match the request;
  • player IDs resolve to intended people;
  • natural keys are unique at declared grain or duplicates are explained;
  • package version, function, arguments, and retrieval time are recorded;
  • missing values are distinguished from structural zeroes;
  • source columns and any renamed fields have a mapping.

Statcast

  • pitch/game identifiers and event dates are plausible;
  • chunk boundaries have neither gaps nor overlapping duplicate rows;
  • handedness, coordinate systems, velocity/distance units, and event labels are understood;
  • pitch outcomes and plate-appearance outcomes are not mixed silently;
  • post-pitch or postgame variables are not treated as pre-pitch/pregame information.

Season tables

  • qualifier, minimum plate appearances/innings, and year semantics are recorded;
  • counting and rate statistics are not compared without opportunity context;
  • provider-specific
阅读完整来源 ↗