Getting live statistics at regular intervals

One of the cool features of nflgame is its ability to seamlessly read statistics from games that are currently in play. The nflgame.live module provides a way to easily retrieve statistics from only the games being currently played at some regular interval.

What follows is a quick tutorial on how to use it to report live statistics.

Note that using this module effectively is a bit more advanced than simply filtering statistics, as you'll have to write your own function that gets executed every time there is a game update.

Also, the live module requires that pytz is installed. pytz is a library that handles timezone information, which is necessary for knowing whether a game that starts at 1PM in the US/Eastern time zone is actually playing even if you don't live in the US/Eastern timezone.

Also, you'll need at least version 1.0.5 of nflgame to use the live module.

Teaser

As I'm typing this, there are three preseason games currently being played in the fourth week of preseason of the 2012 season. If I'd like to simply see the score of the game at 15 second intervals, all I need is 5 lines of code:

>>> import nflgame.live
>>> def cb(active, completed, diffs):
...     for g in active:
...         h, sh, a, sa = g.home, g.score_home, g.away, g.score_away
...         print '%s :: %s (%d) vs. %s (%d)' % (g.time, h, sh, a, sa)
...         
...     
... 
>>> nflgame.live.run(cb)
Q4 08:14 :: SEA (21) vs. OAK (0)
Q4 11:27 :: SF (35) vs. SD (3)
Halftime :: ARI (7) vs. DEN (0)
# 15 seconds later...
Q4 08:14 :: SEA (21) vs. OAK (0)
Q4 11:27 :: SF (35) vs. SD (3)
Q3 15:00 :: ARI (7) vs. DEN (0)
# 15 seconds later...
Q4 08:08 :: SEA (21) vs. OAK (0)
Q4 10:58 :: SF (35) vs. SD (3)
Q3 15:00 :: ARI (7) vs. DEN (0)

If you're following along at home, simply press Ctrl-C on your keyboard to return to a prompt. Otherwise nflgame.live.run will run forever!

How does it work?

The live module only makes a single function available: run. run has one manadatory parameter: a callback function that is called every time game statistics are updated. The callback function must accept three parameters: a list of games that are active (which means they are currently being played or are about to start), a list of games that have just completed and a list of differences between games. A game can never be in both lists, and a game shows up in the completed list only once.

run also has three optional parameters. The optional parameters consist of an active and an inactive interval in seconds, and a time for which to stop polling NFL.com for data.

The active and inactive intervals specify the amount of time (in seconds) to wait between downloads of data from NFL.com. The active interval is applicable only when games are currently being played (and it should therefore be shorter), while the inactive interval is applicable only when there aren't any games being played (and is therefore longer).

For example, if we revisited the teaser example above, we can change the call to only update the statistics every minute (instead of the default 15 seconds). We can also tell it to stop at 3am on the next day:

import datetime
stoptime = datetime.datetime(2012, 08, 31, 3)
nflgame.live.run(cb, active_interval=60, stop=stoptime)

Since the stop time is not related to game times, you don't need to worry about timezone information—just working in your local time will work. (So long as the time on your computer is set correctly!)

If stop is not set, run will never terminate. (So you'll need to kill it with something like Ctrl-C.)

Example: doing something when a game is over

Continuing with our previous example, what if we wanted to print a message whenever a game is over?

>>> import nflgame.live
>>> def cb(active, completed, diffs):
>>>     for g in completed:
>>>       print '%s vs %s is over. %s wins!' % (g.home, g.away, g.winner)
...     for g in active:
...         h, sh, a, sa = g.home, g.score_home, g.away, g.score_away
...         print '%s :: %s (%d) vs. %s (%d)' % (g.time, h, sh, a, sa)
...         
...     
... 
>>> nflgame.live.run(cb)
SF vs SD is all over. SF wins!
Q3 03:28 :: ARI (10) vs. DEN (0)

Since a completed game is only in completed once, the message that SF won is only printed once.

Another example: printing the passing leaders

Believe it or not, we've already touched on all of the features of the live module. Now you can apply what you already know about collecting statistics to print out whatever you want about the games being played. For instance, printing the passing leaders:

import nflgame.live

def cb(active, completed, diffs):
    for game in active:
        # Remember, it is possible for an active game to have not started yet.
        # However, sometimes NFL.com provides some data before the game starts.
        # If you omit this check, things still work OK.
        if not game.playing():
            continue

        print '%s :: %s vs. %s' % (game.time(), game.home, game.away)
        for p in game.players.passing().sort("passing_yds"):
            print '\t%s %d %d %d %d' \
                    % (p, p.passing_cmp, p.passing_att,
                       p.passing_yds, p.passing_tds)

nflgame.live.run(cb)

Links

The live module is described in more technical depth in its API documentation.