Skip to content

chadwickpy

Turn Retrosheet play-by-play files into data tables, with one pip install.

Retrosheet publishes every play of every MLB game as text files. They are compact but hard to read. The Chadwick tools are the standard way to turn them into tables a researcher can use. chadwickpy is those same six tools, rewritten in pure Python, so you can install them anywhere Python runs: no compiler, no C library, no dependencies.

  • Get started

    Install, download a season, and write your first table in a few minutes.

  • Guides

    The six tools, the columns they write, Python usage and worked recipes.

  • Reference

    Every option and field of every tool, generated from the tools themselves.

play,1,0,aybae001,12,CBCX,S9/F9S-
play,1,0,abreb001,12,C11FBS,K
play,1,0,huntt001,22,F1CBFB1X,8/F8LXD

"GAME_ID","INN_CT","BAT_HOME_ID","OUTS_CT","BAT_ID","PIT_ID","EVENT_TX","EVENT_CD"
"NYA201004130",1,0,0,"aybae001","petta001","S9/F9S-",20
"NYA201004130",1,0,0,"abreb001","petta001","K",3
"NYA201004130",1,0,1,"huntt001","petta001","8/F8LXD",2

Try it in a minute

pip install chadwickpy                  # or: uvx --from chadwickpy cwevent -h
curl -O https://www.retrosheet.org/events/2010seve.zip
unzip -q 2010seve.zip -d retro2010 && cd retro2010
cwevent -y 2010 -n -f 0,2,3,4,10,14,29,34 2010NYA.EVA > yankees_events.csv

That is every event (each pitch-ending play, steal, pickoff and so on) in the Yankees' 2010 home games, as a CSV file. Getting started explains each step.

What you get

Tool One row per Use it for
cwevent event (a play) pitch-by-pitch and play-by-play analysis, run expectancy, batted balls
cwgame game schedules, scores, parks, umpires, starting pitchers
cwdaily player per game game logs: batting, pitching and fielding lines
cwsub substitution pinch hitters, pitching changes, defensive swaps
cwcomment comment scorer notes and ejections
cwbox game text or XML box scores (SportsML is deprecated)

Why use it

  • Same answers as Chadwick. Its output was compared with the real tools on every season that has game data (1897 to 2025): no differences, for inputs where the C tools behave in a defined way. How it was checked.
  • Installs anywhere Python runs. A notebook, a CI job, a laptop with no compiler. Python 3.11 or newer (the automated tests run on Linux).
  • Same commands. cwevent, cwgame, cwdaily, cwsub, cwcomment and cwbox, with Chadwick's options, so existing tutorials and scripts work.
  • Usable from Python. Import the parser and the row generators directly. See the Python guide.

Is it for you?

See who it is for and how it compares with other tools.

What to know first

  • On one core it is about 10 to 40 times slower than the C tools, depending on the tool (a whole season takes 14 to 40 seconds). With several files it uses several cores by itself, which brings a season to a few seconds on a multi-core machine, and it respects CPU limits set by Docker or Kubernetes. See compared with Chadwick for the measured numbers and using several cores to control it.
  • It reads the data files; it does not download them. Get them from Retrosheet (see the credit notice on the FAQ).
  • It is a derivative of Chadwick and is licensed GPL-3.0-or-later, with credit to Chadwick.