Retrosheet


Working with Event Files

Retrosheet provides two pieces of software to help work with event files, BEVENT and BGAME. These files can be downloaded here. The event files themselves are described in detail here.
BEVENT, and BGAME have small help screens which can be displayed by typing the program name followed by a space and the characters "-h" from a command prompt. These help screens are useful when you cannot remember the correct syntax for each program or when you want to quickly display the switch options available for each program.

Both of these utility programs must have the year specified after the -y switch on the command line. Sample syntax for use:

BEVENT -y 1967 1967BOS.EVA > 1967BOS.BEV
This would execute BEVENT on the file '1967BOS.EVA' and return its output to the file '1967BOS.BEV'. Team and roster files for 1967 would need to be in the same directory as '1967BOS.EVA'.

These programs can also work with the standard wildcards "*" and "?" in the names of the input files.

BEVENT

The purpose of BEVENT is to prepare a report of a game in a format that is suitable for importing into a data base or spreadsheet. It would be reasonable to think of BEVENT functioning as a parser to extract information from the event file and report the game state after each play. BEVENT functions by converting each play of a game into a record that contains several items of situational information such as number of outs, score of game, identity of pitcher, handedness of batter and pitcher, identity of any runners, etc., along with the play results. In order to run the BEVENT program, you must have the "team" and the appropriate roster files in the same directory with the BEVENT program and the event files.

There are 96 different fields which may be created for each BEVENT record. You have the ability to control which of these fields is created. The list of all possible fields may be obtained by typing the command "BEVENT -d". If you do not specify which fields you want BEVENT to create, it will default to the fields noted by the help screen (type "BEVENT -h"). These default fields are also noted with an asterisk in the list generated by "BEVENT -d".

There are several other switches which may be used with BEVENT. To obtain a list of these options, enter the command "BEVENT -h". The output of any BEVENT command may be directed to a printer or to a new file.

Some BEVENT fields are numbers and some are strings (that is, non-numeric characters). In all cases, the strings are enclosed by double quotes so that the records can be correctly interpreted as numbers or strings when imported into spreadsheet and data base programs. Following are descriptions of each field.
     game id.  Game ID is a twelve-character ID of the form {TTT}{YYYY}{MM}{DD}{G}.
               The first three characters identify the home team). The next four are the year.
               The next two are the month followed by the day, both with leading zeroes as needed.
               The last digit indicates if this is a single game (0), or not (1,2).

     event num.  All events are numbered consecutively throughout
                 each game for easy reference.

     inning.  Inning in which this play took place. 

     batting team.  A one-character identification of the team at
                    bat ("0" for the visiting team and "1" for the
                    home team).

     outs.  Number of outs before this play. 

     balls, strikes, pitch sequence.  These three consecutive
            fields present the pitch information for this play.

     vis score.  Number of runs for the visiting team before this
                 play.

     home score.  Number of runs for the home team before this
                  play.

     batter.  Player ID code for the batter.

     batter hand.  One character which describes how the batter
                   batted for this event (L or R).

     res batter and res batter hand.  These fields are almost
             always the same as batter and batter hand.  They
             only differ if the batter is replaced during the
             time at bat and the final event is charged to the
             previous batter.  For example, if a pinch-hitter is
             inserted with two strikes and then takes strike three,
             the strikeout is charged to the first batter (the
             responsible batter)

     pitcher.  Player ID code for the pitcher.

     pitcher hand.  The hand with which the pitcher throws (L or
                    R).

     res pitcher and res pitcher hand.  Counterparts to res batter
             and res batter hand for those occasions when a pitcher
             is changed during an at-bat and the first pitcher is
             charged with the result.  For example, if a relief
             pitcher enters with a three-ball, no-strike count and
             throws ball four, then the walk is charged to the first
             pitcher.

     positions.  The next eight fields contain the Player ID codes
             for the players at each of the eight fielding positions,
             in numerical sequence by position number.

     first runner, second runner, third runner.  These three
             consecutive fields contain the Player ID codes for the
             runner at each base at the start of the play.
             If a base is not occupied, then the field has no width 
             and there will be a pair of double quotes with no space 
             between them.  For example, Bill
             Ripken on first as the only runner would look like this:

                "ripkb001","","",

             With Joe Orsulak on first and Cal Ripken on third, these
             fields would look like::

               "orsuj001","","ripkc001"

     event text.  The complete description of the play using the
             format described for the event files.

     leadoff flag.  A one character descriptor which is T for the
             first batter of each inning and F for all others.

     pinchhit flag.  Another one character flag which is T for
             pinch-hitters and F for all others.

     defensive position.  The defensive position currently being
             played by this batter.  It is pinch-hitter (position 11)
             for pinch-hitters.

     lineup position.  Position in the batting order for this
             batter.

     event type.  There are 25 different numeric codes to describe
             the type of event.  They are:

          Code Meaning

          0    Unknown event
          1    No event
          2    Generic out
          3    Strikeout
          4    Stolen base
          5    Defensive indifference
          6    Caught stealing
          7    Pickoff error
          8    Pickoff
          9    Wild pitch
          10   Passed ball
          11   Balk
          12   Other advance
          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


     batter event flag.  A one character indication of whether or
             not the event terminated the batter's appearance.
             T = yes, which is most common; F = no, meaning the
             same batter stayed at the plate, such as after a stolen base.

     ab flag.  A one character indication of whether batter was
             charged with at-bat (T = yes, F = no).

     hit value.  One number indicating value of hit (0 = no hit;
             1 = single; 2 = double; 3 = triple; 4 = home run).

     SH flag.  One character indicating sacrifice hit (T = yes;
             F = no).

     SF flag.  One character indicating sacrifice fly (T = yes;
             F = no).

     outs on play.  Number of outs recorded on this play.  

     double play flag.  One character field of DP or not. 

     triple play flag.  One character field of TP or not. 

     RBI on play.  Number of RBI credited to batter on this play. 

     wild pitch flag, passed ball flag.  Two records with
             indication of whether there was a WP or PB on this play.

     fielded by.  Fielding position (1-9) of the fielder who played 
             the ball. This is especially important for base hits 
             when no formal fielding credit is given.

     batted ball type.  Descriptor which is either F (fly ball), L
             (line drive), P (pop-up), or G (ground ball).

     bunt flag.  Descriptor for whether or not play was a bunt. 

     foul flag.  Descriptor for whether or not ball was played in
             foul ground.

     hit location.  The zone on the field where the ball was hit. 
             Refer to the Scoring System attachments for a
             diagram of all locations.

     num errors.  Number of errors on this play (a maximum of three
             is allowed).

     error players and types.  These are 6 consecutive fields which
             identify the player committing the 1st, 2nd or 3rd errors
             on the play and the type of error each was (throw or drop).

     batter dest.  The base which the batter reached at the
             conclusion of the play.  If he was out, the base is 0.

     runner dest.  The next three fields contain the base reached
             by each of the three runners at the conclusion of the
             play.  If there was no advance, then the base shown
             will be the one where the runner started.  Note that
             these runner fields are not updated on plays which end
             an inning, even if the inning-ending play would have
             resulted in an advance of one or more runners had it
             occurred earlier in the inning.

     plays.  The next four fields indicate the play (if any) made
             on the batter and each of the runners (if any).

     SB, CS, PO flags.  The next nine fields contain single
             character descriptors for each of the runners indicating
             whether he had a stolen base, was caught stealing or was
             picked off.

     responsible pitcher for runner.  The next three fields
             indicate which pitcher was responsible for the runners on each
             base, if any.  This assignment reflects responsbility should
             the runner score.

     new game and end game flags.  The next two fields set a flag
             if this is the first record of a new game or the last
             record of the game.

     pinchrunners.  The next three fields indicate if a pinchrunner
             has entered the game and at which base.

     removed runners.  The next three fields contain the player ID
             of the runner who was just run for, one field for each
             base.  If there is no pinchrunner at that base, the
             field contains the NULL string "".

     removed batter.  If there is a pinchhitter, this field
             contains the player ID of the batter removed. If there
             is no pinchhitter, this field contains the NULL string "".

     removed batter position.  If there is a pinchhitter, this
             field contains the fielding position of the removed batter.
             If there is no pinchhitter, this value is 0.

     fielder putouts.  The next three fields indicate the fielding positions
             (1-9) of the first, second, and third fielders credited with 
             putouts on the play.

     fielder assists.  The next five fields indicate the fielding positions
             (1-9) of any fielders who were credited with assists on the play
             (maximum of five fielders).

The following list presents all of the above options with the numbers to use with the -f option to specify them. Those marked with an asterisk are produced by the default option when the user specifies no fields.
number    field
------    -----
 0        game id*
 1        visiting team*
 2        inning*
 3        batting team*
 4        outs*
 5        balls*
 6        strikes*
 7        pitch sequence
 8        vis score*
 9        home score*
10        batter
11        batter hand
12        res batter*
13        res batter hand*
14        pitcher
15        pitcher hand
16        res pitcher*
17        res pitcher hand*
18        catcher
19        first base
20        second base
21        third base
22        shortstop
23        left field
24        center field
25        right field
26        first runner*
27        second runner*
28        third runner*
29        event text*
30        leadoff flag*
31        pinchhit flag*
32        defensive position*
33        lineup position*
34        event type*
35        batter event flag*
36        ab flag*
37        hit value*
38        SH flag*
39        SF flag*
40        outs on play*
41        double play flag
42        triple play flag
43        RBI on play*
44        wild pitch flag*
45        passed ball flag*
46        fielded by
47        batted ball type
48        bunt flag
49        foul flag
50        hit location
51        num errors*
52        1st error player
53        1st error type
54        2nd error player
55        2nd error type
56        3rd error player
57        3rd error type
58        batter dest* (5 if scores and unearned, 6 if team unearned)
59        runner on 1st dest* (5 if scores and unearned, 6 if team unearned)
60        runner on 2nd dest* (5 if scores and unearned, 6 if team unearned)
61        runner on 3rd dest* (5 if scores and unearned, 6 if team unearned)
62        play on batter
63        play on runner on 1st
64        play on runner on 2nd
65        play on runner on 3rd
66        SB for runner on 1st flag
67        SB for runner on 2nd flag
68        SB for runner on 3rd flag
69        CS for runner on 1st flag
70        CS for runner on 2nd flag
71        CS for runner on 3rd flag
72        PO for runner on 1st flag
73        PO for runner on 2nd flag
74        PO for runner on 3rd flag
75        Responsible pitcher for runner on 1st
76        Responsible pitcher for runner on 2nd
77        Responsible pitcher for runner on 3rd
78        New Game Flag
79        End Game Flag
80        Pinch-runner on 1st? (T/F)
81        Pinch-runner on 2nd? (T/F)
82        Pinch-runner on 3rd? (T/F)
83        ID of Runner removed for pinch-runner on 1st
84        ID of Runner removed for pinch-runner on 2nd
85        ID of Runner removed for pinch-runner on 3rd
86        ID of Batter removed for pinch-hitter
87        Fielding position of batter removed for pinch-hitter
88        Fielder with First Putout (0 if none)
89        Fielder with Second Putout (0 if none)
90        Fielder with Third Putout (0 if none)
91        Fielder with First Assist (0 if none)
92        Fielder with Second Assist (0 if none)
93        Fielder with Third Assist (0 if none)
94        Fielder with Fourth Assist (0 if none)
95        Fielder with Fifth Assist (0 if none)
96        event num

If you run BEVENT and generate all the possible fields, the output will be more than three times the size of the event file you specified to the program. It is suggested that you generate only a subset of all possible fields at any single time, since most studies will not need all of the information at one time. BEVENT may then be run again, specifying different fields for the output, for a subsequent study.
BGAME
The purpose of this program is to generate a summary of those items which are constant for each game, such as date, indication of day or night, identity of umpires, etc. The program also reports starting lineups as well as summary data of the game, such as the final score.

The output of BGAME may be coordinated with that from BEVENT since they use the same Game ID code. The use of this program is similar to BEVENT in that there are several switches to create the precise output desired. To see the options enter the command "BGAME -h"; for more general instructions on how to use BGAME to analyze play-by-play data, see the instructions for BEVENT.

The following list presents all of the options for BGAME with their numerical identification. The default for BGAME is that the first 81 fields are produced (all but 'gametype'). As with BEVENT, the -f can be used to output selected fields.
number    field
------    -----
 0        game id
 1        date
 2        game number (0 = no double header)
 3        day of week
 4        start time
 5        DH used flag
 6        day/night flag
 7        visiting team
 8        home team
 9        game site
10        visiting starting pitcher
11        home starting pitcher
12        home plate umpire
13        first base umpire
14        second base umpire
15        third base umpire
16        left field umpire
17        right field umpire
18        attendance
19        PS scorer
20        translator
21        inputter
22        input time
23        edit time
24        how scored
25        pitches entered?
26        temperature
27        wind direction
28        wind speed
29        field condition
30        precipitation
31        sky
32        time of game
33        number of innings
34        visitor final score
35        home final score
36        visitor hits
37        home hits
38        visitor errors
39        home errors
40        visitor left on base
41        home left on base
42        winning pitcher
43        losing pitcher
44        save for
45        GW RBI
46        visitor batter 1
47        visitor position 1
48        visitor batter 2
49        visitor position 2
50        visitor batter 3
51        visitor position 3
52        visitor batter 4
53        visitor position 4
54        visitor batter 5
55        visitor position 5
56        visitor batter 6
57        visitor position 6
58        visitor batter 7
59        visitor position 7
60        visitor batter 8
61        visitor position 8
62        visitor batter 9
63        visitor position 9
64        home batter 1
65        home position 1
66        home batter 2
67        home position 2
68        home batter 3
69        home position 3
70        home batter 4
71        home position 4
72        home batter 5
73        home position 5
74        home batter 6
75        home position 6
76        home batter 7
77        home position 7
78        home batter 8
79        home position 8
80        home batter 9
81        home position 9
82        gametype

Retrosheet website last updated September 18, 2024.
All data contained at this site is copyright 1996-2024 by Retrosheet. All Rights Reserved. Click here for information about the use of Retrosheet data

Send comments and suggestions to Tom Thress: tthress-ATsign-retrosheet.org.
Join the Retrosheet Discussion group here: RetroList
Retrosheet is an all-volunteer organization and a 501(c)(3) charitable organization. To volunteer, please e-mail Tom Thress. To make a donation, you can visit here: Donation Page