Command-line tools

Chadwick provides the following command-line programs for extracting information from Retrosheet play-by-play event files:

• cwevent, an expanded event descriptor, which replaces and extends the DiamondWare program BEVENT.
• cwgame, a game information extractor, which replaces and extends the DiamondWare program BGAME.
• cwbox, a boxscore generator, which replaces and extends the DiamondWare program BOX.
• cwsub, which extracts information about in-game player substitutions. This program is unique to Chadwick.
• cwcomment, which extracts comment fields from event files. This program is unique to Chadwick.

Before reading the documentation specific to each tool, you may want to consult:

• The summary of command-line options which control the operation of each program.
• The documentation at Retrosheet summarizing the contents of play-by-play files, and documenting the DiamondWare versions of these tools.

The Chadwick documentation focuses on filling in the gaps in the Retrosheet documentation, and documenting Chadwick-specific extensions to the toolset.

cwevent: Expanded event descriptor

cwevent is a command-line tool which extracts detailed information about individual events (plays) in the data file. These are grouped into two categories. There are 97 fields which are compatible with the Retrosheet BEVENT event extractor tool. These are specified using the -f command-line flag. In addition, cwevent offers over 50 “extended” fields which expand upon or give more detailed information not easily accessed via the standard fields. These are are specified using the -x command-line flag.

cwevent standard field numbers

Field number	Description	Header
0	Game ID	GAME_ID
1	Visiting team	AWAY_TEAM_ID
2	Inning	INN_CT
3	Batting team	BAT_HOME_ID
4	Outs	OUTS_CT
5	Balls	BALLS_CT
6	Strikes	STRIKES_CT
7	Pitch sequence	PITCH_SEQ_TX
8	Visitor score	AWAY_SCORE_CT
9	Home score	HOME_SCORE_CT
10	Batter	BAT_ID
11	Batter hand	BAT_HAND_CD
12	Result batter	RESP_BAT_ID
13	Result batter hand	RESP_BAT_HAND_CD
14	Pitcher	PIT_ID
15	Pitcher hand	PIT_HAND_CD
16	Result pitcher	RESP_PIT_ID
17	Result pitcher hand	RESP_PIT_HAND_CD
18	Catcher	POS2_FLD_ID
19	First baseman	POS3_FLD_ID
20	Second baseman	POS4_FLD_ID
21	Third baseman	POS5_FLD_ID
22	Shortstop	POS6_FLD_ID
23	Left fielder	POS7_FLD_ID
24	Center fielder	POS8_FLD_ID
25	Right fielder	POS9_FLD_ID
26	Runner on first	BASE1_RUN_ID
27	Runner on second	BASE2_RUN_ID
28	Runner on third	BASE3_RUN_ID
29	Event text	EVENT_TX
30	Leadoff flag	LEADOFF_FL
31	Pinch-hit flag	PH_FL
32	Defensive position	BAT_FLD_CD
33	Lineup position	BAT_LINEUP_ID
34	Event type	EVENT_CD
35	Batter event flag	BAT_EVENT_FL
36	Official time at bat flag	AB_FL
37	Hit value	H_FL
38	Sacrifice hit flag	SH_FL
39	Sacrifice fly flag	SF_FL
40	Outs on play	EVENT_OUTS_CT
41	Double play flag	DP_FL
42	Triple play flag	TP_FL
43	RBI on play	RBI_CT
44	Wild pitch flag	WP_FL
45	Passed ball flag	PB_FL
46	Fielded by	FLD_CD
47	Batted ball type	BATTEDBALL_CD
48	Bunt flag	BUNT_FL
49	Foul flag	FOUL_FL
50	Hit location	BATTEDBALL_LOC_TX
51	Number of errors	ERR_CT
52	1st error player	ERR1_FLD_CD
53	1st error type	ERR1_CD
54	2nd error player	ERR2_FLD_CD
55	2nd error type	ERR2_CD
56	3rd error player	ERR3_FLD_CD
57	3rd error type	ERR3_CD
58	Batter destination	BAT_DEST_ID
59	Runner on first destination	RUN1_DEST_ID
60	Runner on second destination	RUN2_DEST_ID
61	Runner on third destination	RUN3_DEST_ID
62	Play on batter	BAT_PLAY_TX
63	Play on runner on first	RUN1_PLAY_TX
64	Play on runner on second	RUN2_PLAY_TX
65	Play on runner on third	RUN3_PLAY_TX
66	Stolen base for runner on first	RUN1_SB_FL
67	Stolen base for runner on second	RUN2_SB_FL
68	Stolen base for runner on third	RUN3_SB_FL
69	Caught stealing for runner on first	RUN1_CS_FL
70	Caught stealing for runner on second	RUN2_CS_FL
71	Caught stealing for runner on third	RUN3_CS_FL
72	Pickoff of runner on first	RUN1_PK_FL
73	Pickoff of runner on second	RUN2_PK_FL
74	Pickoff of runner on third	RUN3_PK_FL
75	Pitcher charged with runner on first	RUN1_RESP_PIT_ID
76	Pitcher charged with runner on second	RUN2_RESP_PIT_ID
77	Pitcher charged with runner on third	RUN3_RESP_PIT_ID
78	New game flag	GAME_NEW_FL
79	End game flag	GAME_END_FL
80	Pinch-runner on first	PR_RUN1_FL
81	Pinch-runner on second	PR_RUN2_FL
82	Pinch-runner on third	PR_RUN3_FL
83	Runner removed for pinch-runner on first	REMOVED_FOR_PR_RUN1_ID
84	Runner removed for pinch-runner on second	REMOVED_FOR_PR_RUN2_ID
85	Runner removed for pinch-runner on third	REMOVED_FOR_PR_RUN3_ID
86	Batter removed for pinch-hitter	REMOVED_FOR_PH_BAT_ID
87	Position of batter removed for pinch-hitter	REMOVED_FOR_PH_BAT_FLD_CD
88	Fielder with first putout	PO1_FLD_CD
89	Fielder with second putout	PO2_FLD_CD
90	Fielder with third putout	PO3_FLD_CD
91	Fielder with first assist	ASS1_FLD_CD
92	Fielder with second assist	ASS2_FLD_CD
93	Fielder with third assist	ASS3_FLD_CD
94	Fielder with fourth assist	ASS4_FLD_CD
95	Fielder with fifth assist	ASS5_FLD_CD
96	Event number	EVENT_ID

cwevent extended field numbers

Field number	Description	Header
0	home team id	HOME_TEAM_ID
1	batting team id	BAT_TEAM_ID
2	fielding team id	FLD_TEAM_ID
3	half inning (differs from batting team if home team bats first)	BAT_LAST_ID
4	start of half inning flag	INN_NEW_FL
5	end of half inning flag	INN_END_FL
6	score for team on offense	START_BAT_SCORE_CT
7	score for team on defense	START_FLD_SCORE_CT
8	runs scored in this half inning	INN_RUNS_CT
9	number of plate appearances in game for team on offense	GAME_PA_CT
10	number of plate appearances in inning for team on offense	INN_PA_CT
11	start of plate appearance flag	PA_NEW_FL
12	truncated plate appearance flag	PA_TRUNC_FL
13	base state at start of play	START_BASES_CD
14	base state at end of play	END_BASES_CD
15	batter is starter flag	BAT_START_FL
16	result batter is starter flag	RESP_BAT_START_FL
17	pitcher is starter flag	PIT_START_FL
18	result pitcher is starter flag	RESP_PIT_START_FL
19	defensive position of runner on first	RUN1_FLD_CD
20	lineup position of runner on first	RUN1_LINEUP_CD
21	event number on which runner on first reached base	RUN1_ORIGIN_EVENT_ID
22	defensive position of runner on second	RUN2_FLD_CD
23	lineup position of runner on second	RUN2_LINEUP_CD
24	event number on which runner on second reached base	RUN2_ORIGIN_EVENT_ID
25	defensive position of runner on third	RUN3_FLD_CD
26	lineup position of runner on third	RUN3_LINEUP_CD
27	event number on which runner on third reached base	RUN3_ORIGIN_EVENT_ID
28	number of balls in plate appearance	PA_BALL_CT
29	number of intentional balls in plate appearance	PA_INTENT_BALL_CT
30	number of pitchouts in plate appearance	PA_PITCHOUT_BALL_CT
31	number of other balls in plate appearance	PA_OTHER_BALL_CT
32	number of strikes in plate appearance	PA_STRIKE_CT
33	number of called strikes in plate appearance	PA_CALLED_STRIKE_CT
34	number of swinging strikes in plate appearance	PA_SWINGMISS_STRIKE_CT
35	number of foul balls in plate appearance	PA_FOUL_STRIKE_CT
36	number of other strikes in plate appearance	PA_OTHER_STRIKE_CT
37	number of runs on play	EVENT_RUNS_CT
38	id of player fielding batted ball	FLD_ID
39	force play at second flag	BASE2_FORCE_FL
40	force play at third flag	BASE3_FORCE_FL
41	force play at home flag	BASE4_FORCE_FL
42	batter safe on error flag	BAT_SAFE_ERR_FL
43	fate of batter (base ultimately advanced to)	BAT_FATE_ID
44	fate of runner on first	RUN1_FATE_ID
45	fate of runner on second	RUN2_FATE_ID
46	fate of runner on third	RUN3_FATE_ID
47	runs scored in half inning after this eveng	FATE_RUNS_CT
48	fielder with sixth assist	ASS6_FLD_CD
49	fielder with seventh assist	ASS7_FLD_CD
50	fielder with eighth assist	ASS8_FLD_CD
51	fielder with ninth assist	ASS9_FLD_CD
52	fielder with tenth assist	ASS10_FLD_CD
53	unknown fielding credit flag	UNKNOWN_OUT_EXC_FL
54	uncertain play flag	UNCERTAIN_PLAY_EXC_FL

Result batters and pitchers (fields 10-17)

In most cases, the pitcher and batter charged or credited with the event (when a batter event) are the ones in the game when the event occurs. However, Rules 10.17 and 10.18 have special clauses discussing how to charge walks to pitchers when a relief pitcher enters in the middle of the plate appearance, and how to charge strikeouts to batters when a pinch hitter enters in the middle of the plate appearance. The batter and pitcher fields always give the identity of the batter and pitcher in the game at the time of the event; the result batter and result pitcher give the batter and pitcher credited or charged with the event.

There is one known bug in the Retrosheet-provided tools regarding the result pitcher. When a relief pitcher enters the game, and then the next batter is retired on a fielder’s choice, the pitcher responsible for the runner put out is shown in the result pitcher field. While it is correct that the batter reaching base in this case would be charged to the former pitcher should he score, the purpose of the result pitcher field is to indicate the pitcher charged with the outcome of this particular event. In this case, for example, the relief pitcher is awarded one-third of an inning pitched; therefore, he should be the result pitcher, and then the previous pitcher should be (and is) listed in the responsible pitcher field for the batter in subsequent events.

In the case of switch-hitters, the batter hand and result batter hand fields are set to L or R, as appropriate, based upon the hand with which the pitcher throws. If the pitcher’s throwing hand is unknown, or if the batter’s batting hand is unknown, a question mark appears in these fields.

Pinch-hit flag (field 31)

This field is T if the batter is a pinch-hitter, and F if he is not. If a player enters the game as a pinch-hitter, and then bats again in the same inning because his team bats around, this field will be F for the player’s second plate appearance. To identify the cases where this occurs, consult the defensive position field (field 32), which will continue to be equal to 11 (or 12 for a pinch-runner) until that player assumes a defensive position.

Event type code (field 34)

All plays are categorized by their primary event type. Here is a list of all types and the corresponding codes used in this field. Codes marked “obsolete” are no longer used, or no longer appear in Retrosheet-produced play-by-play files.

cwevent extended field numbers

Code	Primary event
0	Unknown (obsolete)
1	None (obsolete)
2	Generic out
3	Strikeout
4	Stolen base
5	Defensive indifference
6	Caught stealing
7	Pickoff error (obsolete)
8	Pickoff
9	Wild pitch
10	Passed ball
11	Balk
12	Other advance/out advancing
13	Foul error
14	Walk
15	Intentional walk
16	Hit by pitch
17	Interference
18	Error
19	Fielder’s choice
20	Single
21	Double
22	Triple
23	Home run
24	Missing play (obsolete)

Sacrifice flags and eras (fields 36, 38, 39)

Chadwick in all cases applies the modern rules concerning the awarding of sacrifice hits, sacrifice flies, and official times at bat, regardless of the year indicated with the -y flag.

Plays on runners (fields 58-65)

Fields 58 through 65 give the destination of all runners, including the batter, as well as the fielding play made on them, if any. For the purposes of the destination fields, a code of 5 indicates the runner scored, and is charged as unearned, and a code of 6 indicates the runner scored, and is charged as unearned to the team, but earned to the pitcher. These codes only appear when the (NR) or (TUR) modifiers are explicitly used on the advancement code. There is no internal logic in Chadwick to ferret out which runs should be earned or unearned, as in many cases there is insufficient information, or the situation requires the judgment of the official scorer. Runners which are put out are reported as having an advancement of 0.

In most cases, the play on a runner indicates the fielding credits involved in putting him out. Chadwick also reports a fielding play on a runner when the runner is safe on a dropped throw, such as 3E1 or FC6.1X2(6E4).

Fielding errors (fields 51-57)

Up to three errors can be indicated in cwevent output. Supported error types are F for generic fielding errors, and T for throwing errors; no distinction is made between bobbled batted balls, muffed throws or fly balls, and so forth.

Fielding credits (fields 88-95)

The order in which Chadwick and the Retrosheet-provided tools list putouts and assists may vary. The number of plays on which this occurs is quite few, and generally in cases where there is a putout in the primary event as well as one in the baserunning modifiers. The words “first”, “second” and so on do not necessarily indicate chronological order of the credits, though in most cases they do.

cwgame: Game information extractor

cwgame reports game-level information for each game.

The following table gives the contents of each of the 84 fields cwgame outputs.

cwgame standard field numbers

Field number	Description	Header
0	Game ID	GAME_ID
1	Date	GAME_DT
2	Game number	GAME_CT
3	Day of week	GAME_DY
4	Start time	START_GAME_TM
5	DH used flag	DH_FL
6	Day/night flag	DAYNIGHT_PARK_CD
7	Visiting team	AWAY_TEAM_ID
8	Home team	HOME_TEAM_ID
9	Game site	PARK_ID
10	Visitors starting pitcher	AWAY_START_PIT_ID
11	Home starting pitcher	HOME_START_PIT_ID
12	Home plate umpire	BASE4_UMP_ID
13	First base umpire	BASE1_UMP_ID
14	Second base umpire	BASE2_UMP_ID
15	Third base umpire	BASE3_UMP_ID
16	Left field umpire	LF_UMP_ID
17	Right field umpire	RF_UMP_ID
18	Attendance	ATTEND_PARK_CT
19	PS scorer	SCORER_RECORD_ID
20	Translator	TRANSLATOR_RECORD_ID
21	Inputter	INPUTTER_RECORD_ID
22	Input time	INPUT_RECORD_TS
23	Edit time	EDIT_RECORD_TS
24	How scored	METHOD_RECORD_CD
25	Pitches entered	PITCHES_RECORD_CD
26	Temperature	TEMP_PARK_CT
27	Wind direction	WIND_DIRECTION_PARK_CD
28	Wind speed	WIND_SPEED_PARK_CT
29	Field condition	FIELD_PARK_CD
30	Precipitation	PRECIP_PARK_CD
31	Sky	SKY_PARK_CD
32	Time of game	MINUTES_GAME_CT
33	Number of innings	INN_CT
34	Visitor final score	AWAY_SCORE_CT
35	Home final score	HOME_SCORE_CT
36	Visitor hits	AWAY_HITS_CT
37	Home hits	HOME_HITS_CT
38	Visitor errors	AWAY_ERR_CT
39	Home errors	HOME_ERR_CT
40	Visitor left on base	AWAY_LOB_CT
41	Home left on base	HOME_LOB_CT
42	Winning pitcher	WIN_PIT_ID
43	Losing pitcher	LOSE_PIT_ID
44	Save	SAVE_PIT_ID
45	Game-winning RBI	GWRBI_BAT_ID
46	Visitor batter 1	AWAY_LINEUP1_BAT_ID
47	Visitor batter 1 position	AWAY_LINEUP1_FLD_CD
48	Visitor batter 2	AWAY_LINEUP2_BAT_ID
49	Visitor batter 2 position	AWAY_LINEUP2_FLD_CD
50	Visitor batter 3	AWAY_LINEUP3_BAT_ID
51	Visitor batter 3 position	AWAY_LINEUP3_FLD_CD
52	Visitor batter 4	AWAY_LINEUP4_BAT_ID
53	Visitor batter 4 position	AWAY_LINEUP4_FLD_CD
54	Visitor batter 5	AWAY_LINEUP5_BAT_ID
55	Visitor batter 5 position	AWAY_LINEUP5_FLD_CD
56	Visitor batter 6	AWAY_LINEUP6_BAT_ID
57	Visitor batter 6 position	AWAY_LINEUP6_FLD_CD
58	Visitor batter 7	AWAY_LINEUP7_BAT_ID
59	Visitor batter 7 position	AWAY_LINEUP7_FLD_CD
60	Visitor batter 8	AWAY_LINEUP8_BAT_ID
61	Visitor batter 8 position	AWAY_LINEUP8_FLD_CD
62	Visitor batter 9	AWAY_LINEUP9_BAT_ID
63	Visitor batter 9 position	AWAY_LINEUP9_FLD_CD
64	Home batter 1	HOME_LINEUP1_BAT_ID
65	Home batter 1 position	HOME_LINEUP1_FLD_CD
66	Home batter 2	HOME_LINEUP2_BAT_ID
67	Home batter 2 position	HOME_LINEUP2_FLD_CD
68	Home batter 3	HOME_LINEUP3_BAT_ID
69	Home batter 3 position	HOME_LINEUP3_FLD_CD
70	Home batter 4	HOME_LINEUP4_BAT_ID
71	Home batter 4 position	HOME_LINEUP4_FLD_CD
72	Home batter 5	HOME_LINEUP5_BAT_ID
73	Home batter 5 position	HOME_LINEUP5_FLD_CD
74	Home batter 6	HOME_LINEUP6_BAT_ID
75	Home batter 6 position	HOME_LINEUP6_FLD_CD
76	Home batter 7	HOME_LINEUP7_BAT_ID
77	Home batter 7 position	HOME_LINEUP7_FLD_CD
78	Home batter 8	HOME_LINEUP8_BAT_ID
79	Home batter 8 position	HOME_LINEUP8_FLD_CD
80	Home batter 9	HOME_LINEUP9_BAT_ID
81	Home batter 9 position	HOME_LINEUP9_FLD_CD
82	Visitor finishing pitcher	AWAY_FINISH_PIT_ID
83	Home finishing pitcher	HOME_FINISH_PIT_ID

How scored (field 24)

This field outputs a numeric code corresponding to the medium by which the play-by-play account was recorded.

Numeric codes for how scored field

Code	Description
0	unknown
1	park
2	tv
3	radio

Pitches entered (field 25)

This field outputs a numeric code corresponding to the level of pitch detail in the file.

Numeric codes for pitches entered field

Code	Description
0	unknown
1	pitches
2	count
3	none

Note

This field reports the contents of the info,pitches field in the game file. Some games with partial pitch information will have this field set to none or count.

Temperature (field 26)

The game-time temperature, in degrees Fahrenheit. The value 0 is used when the temperature is unknown.

Wind direction (field 27)

This field outputs a numeric code corresponding to the direction of the wind.

Numeric codes for wind direction field

Code	Description
0	unknown
1	tolf
2	tocf
3	torf
4	ltor
5	fromlf
6	fromcf
7	fromrf
8	rtol

Wind speed (field 28)

The game time wind speed, in miles per hour. The value -1 is used when the wind speed is unknown.

Field condition (field 29)

This field outputs a numeric code corresponding to the condition of the field.

Numeric codes for field condition field

Code	Description
0	unknown
1	soaked
2	wet
3	damp
4	dry

Precipitation (field 30)

This field outputs a numeric code corresponding to the precipitation level.

Numeric codes for precipitation field

Code	Description
0	unknown
1	none
2	drizzle
3	showers
4	rain
5	snow

Sky (field 31)

This field outputs a numeric code corresponding to the sky conditions.

Numeric codes for sky field.

Numeric codes for sky field

Code	Description
0	unknown
1	sunny
2	cloudy
3	overcast
4	night
5	dome

cwsub: Player substitution descriptor

cwsub extracts information about in-game player substitutions. It is designed to be used in conjunction with cwevent to mitigate a blind spot in the existing tools.

cwsub outputs up to ten pieces of information about each substitution. All are included by default; which ones are generated is controlled by the -f switch.

cwevent standard field numbers

Field number	Description	Header
0	Game ID	GAME_ID
1	Inning	INN_CT
2	Batting team	BAT_HOME_ID
3	Substitute	SUB_ID
4	Team	SUB_HOME_ID
5	Lineup position	SUB_LINEUP_ID
6	Fielding position	SUB_FLD_CD
7	Removed player	REMOVED_ID
8	Position of removed player	REMOVED_FLD_CD
9	Event number	EVENT_ID

Command-line options

Each of the command-line tools shares a common set of options controlling their behavior. These are detailed in the following table.

Common command-line options and their effects

Switch	Description
-a	Generate ASCII comma-delimited files (default)
-d	Print a list of the available fields and descriptions (for use with -f)
-e mmdd	The latest date to process (inclusive)
-f flist	List of fields to output. The default list can be viewed with -h; the list of available fields can be viewed with -d
-ft	Generate FORTRAN format files.
-h	Prints description and usage information for the tool.
-i *gameid*	Only process the game with ID gameid
-n	If in ASCII mode (the default), the first row of the output is a comma-separated list of column headers.
-s mmdd	The earliest date to process (inclusive)
-y	Specifies the year to use (four digits)