pybaseball

Python中的棒球数据抓取和分析工具

概述

pybaseball是一个用于棒球数据分析的Python包。该包抓取Baseball Reference、Baseball Savant和FanGraphs的数据，省去了您手动抓取的麻烦。该包可以获取Statcast数据、投球统计、打击统计、联盟排名/球队战绩、奖项数据等。数据可以精确到单次投球级别，也可以按赛季或自定义时间段进行汇总。有关数据获取函数的完整列表，请参阅文档。

安装

可以通过pip安装Pybaseball：

pip install pybaseball

或者从代码仓库安装（可能更新）：

git clone https://github.com/jldbc/pybaseball
cd pybaseball
pip install -e .

我们会尝试通过"releases"和PyPI CI定期发布更新，但有时可能会滞后。

社区

关于pybaseball的使用和开发讨论在我们的Discord群组中进行，注册链接在这里。代码问题仍应在GitHub上提出和解决。

文档

有关可用函数及其参数的完整文档以及示例位于docs文件夹中。本节简要概述了该库的主要功能。

Statcast：从美国职业棒球大联盟的Statcast系统中提取高级指标

Statcast数据包含投球级别的信息，从baseballsavant.com获取。

>>> from pybaseball import statcast
>>> statcast(start_dt="2019-06-24", end_dt="2019-06-25").columns
Index(['pitch_type', 'game_date', 'release_speed', 'release_pos_x',
       'release_pos_z', 'player_name', 'batter', 'pitcher', 'events',
       'description', 'spin_dir', 'spin_rate_deprecated',
       'break_angle_deprecated', 'break_length_deprecated', 'zone', 'des',
       'game_type', 'stand', 'p_throws', 'home_team', 'away_team', 'type',
       'hit_location', 'bb_type', 'balls', 'strikes', 'game_year', 'pfx_x',
       'pfx_z', 'plate_x', 'plate_z', 'on_3b', 'on_2b', 'on_1b',
       'outs_when_up', 'inning', 'inning_topbot', 'hc_x', 'hc_y',
       'tfs_deprecated', 'tfs_zulu_deprecated', 'fielder_2', 'umpire', 'sv_id',
       'vx0', 'vy0', 'vz0', 'ax', 'ay', 'az', 'sz_top', 'sz_bot',
       'hit_distance_sc', 'launch_speed', 'launch_angle', 'effective_speed',
       'release_spin_rate', 'release_extension', 'game_pk', 'pitcher.1',
       'fielder_2.1', 'fielder_3', 'fielder_4', 'fielder_5', 'fielder_6',
       'fielder_7', 'fielder_8', 'fielder_9', 'release_pos_y',
       'estimated_ba_using_speedangle', 'estimated_woba_using_speedangle',
       'woba_value', 'woba_denom', 'babip_value', 'iso_value',
       'launch_speed_angle', 'at_bat_number', 'pitch_number', 'pitch_name',
       'home_score', 'away_score', 'bat_score', 'fld_score', 'post_away_score',
       'post_home_score', 'post_bat_score', 'post_fld_score',
       'if_fielding_alignment', 'of_fielding_alignment', 'spin_axis',
       'delta_home_win_exp', 'delta_run_exp'],
      dtype='object')

有关这些列定义的文档，请参阅Statcast Search CSV文档。

如果提供了start_dt和end_dt，它将返回这两个日期之间的所有Statcast数据。如果没有提供，它将返回昨天的数据。可选参数verbose将控制库在拉取数据时是否更新进度。

特定球员查询

对于特定球员的Statcast查询，可以使用statcast_pitcher和statcast_batter函数拉取投球或打击数据。这些函数与statcast函数采用相同的start_dt和end_dt参数，以及一个player_id参数。这个ID来自MLB Advanced Media，可以使用playerid_lookup函数获取。返回的列与上面的集合相匹配，但仅限于该特定投手或击球手的行。完整示例：

# 查找Clayton Kershaw的球员ID
from pybaseball import  playerid_lookup
from pybaseball import  statcast_pitcher
playerid_lookup('kershaw', 'clayton')
  name_last name_first  key_mlbam key_retro  key_bbref  key_fangraphs  mlb_played_first  mlb_played_last
0   kershaw    clayton     477132  kersc001  kershcl01           2036            2008.0           2022.0

# 他的MLBAM ID是477132，所以我们将其作为player_id参数传递给以下函数
kershaw_stats = statcast_pitcher('2017-06-01', '2017-07-01', 477132)
kershaw_stats.groupby("pitch_type").release_speed.agg("mean")
pitch_type
CH    86.725000
CU    73.133333
FF    92.844622
SI    94.515385
SL    87.962381
Name: release_speed, dtype: float64

关于Statcast数据的说明

Statcast数据可能会发生变化（即使是往季数据）：

<div> <blockquote class="twitter-tweet"> <p lang="en" dir="ltr"> 每个赛季有超过700,000次投球，数据可能会更新。您应该相应地编写代码。 </p>&mdash; Tangotiger (@tangotiger) <a href="https://twitter.com/tangotiger/status/1362064972025634821?ref_src=twsrc%5Etfw">2021年2月17日</a> </blockquote> </div>

汇总统计

对于全联盟赛季级别的投球数据，使用函数pitching_stats(start_season, end_season)。这将为每个球员每个赛季返回一行数据，并提供FanGraphs提供的所有指标。

对于固定范围，pitching_stats_range(start_dt, end_dt)从Baseball Reference拉取特定时间间隔的数据。注意，所有日期应采用YYYY-MM-DD格式。

from pybaseball import pitching_stats
data = pitching_stats(2014,2016)
data.columns
Index(['IDfg', 'Season', 'Name', 'Team', 'Age', 'W', 'L', 'WAR', 'ERA', 'G',
       ...
       'LA', 'Barrels', 'Barrel%', 'maxEV', 'HardHit', 'HardHit%', 'Events',
       'CStr%', 'CSW%', 'xERA'],
      dtype='object', length=334)

打击数据的获取方式类似。获取赛季级别统计数据的函数调用是batting_stats(start_season, end_season)，而获取特定时间范围数据的函数是batting_stats_range(start_dt, end_dt)。Baseball Reference的赛季级数据对应函数是batting_stats_bref(season)。

（对于赛季级查询，如果你更喜欢Baseball Reference而不是FanGraphs，还有第三个选项pitching_stats_bref(season)。它的工作方式与pitching_stats相同，但从Baseball Reference获取数据。然而，不推荐使用这个选项，因为Baseball Reference查询目前每次请求只能检索一个赛季的数据。）

逐场比赛结果和赛程

schedule_and_record函数返回给定赛季某支球队的逐场比赛结果。该函数只有两个参数：season和team，其中team是球队的缩写（例如，NYY代表纽约洋基队）。

# 示例：假设我们想知道1927年洋基队5月16日的战绩
from pybaseball import schedule_and_record
data = schedule_and_record(1927, 'NYY')
data.loc[data.Date.str.contains("May 16"), :]
              Date   Tm Home_Away  Opp W/L    R   RA  Inn   W-L  Rank      GB      Win      Loss   Save  Time D/N  Attendance   cLI  Streak Orig. Scheduled
28  Monday, May 16  NYY         @  DET   W  6.0  2.0  9.0  19-8   1.0  up 3.0  Ruether  Holloway  Moore  2:28   D      4000.0  5.15       5            None

排名：最新或历史分区排名，胜负记录

standings(season)函数给出指定赛季的分区排名。如果选择当前赛季，它将给出最新的排名。否则，它将给出所选赛季每个分区的赛季末排名。这个函数返回一个数据框列表。每个数据框是MLB六个分区之一的排名。

>>> from pybaseball import standings
>>> data = standings(2016)[4]
>>> print(data)
                    Tm    W   L  W-L%    GB
1         Chicago Cubs  103  58  .640    --
2  St. Louis Cardinals   86  76  .531  17.5
3   Pittsburgh Pirates   78  83  .484  25.0
4    Milwaukee Brewers   73  89  .451  30.5
5      Cincinnati Reds   68  94  .420  35.5

缓存

为了加快重复调用的数据检索速度，可以使用本地数据缓存来保存请求数据的本地副本。默认情况下，缓存是禁用的，以尊重用户可能不希望在未经许可的情况下使用其硬盘空间的意愿。然而，启用缓存很简单。

可以通过包含pybaseball.cache模块并启用缓存选项来开启缓存，如下所示：

from pybaseball import cache

cache.enable()

常见问题

过时的缓存

如果你调用statcast方法获取未来日期的数据，缓存会为这些日期记录空数据集。如果你没有得到预期的某个日期的结果，首先尝试清除缓存：

from pybaseball import cache
cache.purge()

多进程处理

如果你遇到concurrent.futures.process.BrokenProcessPool错误，请将你的调用包装在一个主函数中，例如：

if __name__ == '__main__':
    stats = statcast()

这在使用基于spawn的进程的系统（通常是Windows和OSX）上可能是必要的。

对于其他问题，请提交一个issue。

贡献

请参阅contributing.md了解为这个库贡献的指南。

---

致谢

这个包由James LeDoux开发，并由Moshe Schorr维护。

这个包的灵感来自Bill Petti出色的R包baseballr，在这个包开发时还没有Python等价物。我们希望通过这个包填补这个空白。

Lahman数据来自Sean Lahman的棒球数据库。

所有其他数据来自FanGraphs、Baseball Reference、Chadwick Bureau、Retrosheet和Baseball Savant。