Tournakit: A Format and Toolkit

[cdcarter]

Hey all,

I hope quizbowl has been treating you well. I started a little project a few days ago after a conversation with Matt and Eric, and made some progress today. I wanted to share this with everyone to get feedback and get it into your minds.

Tournakit is format for describing results of mACF quizbowl games, as well as a reference implementation of that format. It's a (getting there...) strictly defined structured machine-readable "JSON" file that includes all the information on your standard scoresheet (and more!) The reference implementation is able to read in formatted games, act on them in some way, and/or write them out. You can import a tournament worth of games, and then calculate specific tossup or bonus conversion stats. Or you could import a tournament and normalize all player name or team names. As it is just an interchange format, it's extensible and anything you could conceive of doing with scoresheet data, you could do faster!

Currently the reference implementation can parse Tournakit JSON games, as well as Lily Chen's mACF Excel Scoresheets. An example of something you can do TODAY with the program is load an entire tournament's XLS scoresheets (and a whole tournament is provided in the data/ folder for your discover), and in seconds calculate the conversion statistics for every single tossup at that event. As soon as they are all parsed you can know exactly how many rooms converted Tossup 17 of Round 3 of 2010 GSAC at New Trier.

If you don't have XLS scoresheet data, you could conceivably enter data by hand too. But that'd probably suck.

My project for tomorrow is a SQBS import/export (both raw data files as well as Scoreboard.htm), but SQBS imports will be deficient compared to XLS imports, as SQBS doesn't track individual tossup conversion. But, once SQBS exporting exists (which is fairly straightforward and really I should have tomorrow), it will be very easy to just drop in a pile of XLS scoresheets and pump out a full SQBS file. This could be convenient for a lot of reasons.

Oh, it's probably worth noting that it's useful for the canonical format a game is saved in to have tossup data instead of just stat lines. That was the motivation of this project, after all.

If you're working on a quizbowl computer program, consider supporting Tournakit JSON as the go-to format for describing mACF games.

If you're intrigued by this and want to talk more, shoot me an email. Also, I'll be in IRC for the next few nights I think, if anyone wants to talk.

(and if you're wondering, does this mean we should probably have some database of canonical names for players, teams, and packets? yes. we should. let me know if you want to make one of those.)

and no, this won't ever let you get out of having a statkeeper or logistics person so don't even try.

[cdcarter]

Tournakit now supports outputting unbracketed SQBS files. In the code repo, the file "script/sqbs_out.rb" shows an example of how a folder of Lily Chen scoresheets can be parsed and a SQBS file automatically spit out.

Some other neat additions:

• "script/round_report.rb" -- which shows an example of serving up a round report with detailed tossup conversion stats
• "script/name_cleaner.rb" -- demonstrates how you could use Tournakit to quickly rename players from all the weird variations moderators use
• "script/event.rb" -- quickly see what rooms you have complete scoresheets from and what you're still missing
• "data/Example Tournament/*" -- a folder with a complete four team round-robin worth of scoresheets, tournakit data, SQBS data.

What's on deck?

• SQBS Importing
• Pretty HTML reports
• More versatile parser (including support for tiebreakers?)

Questions, comments, interest about how you can use this? Email me!

[Whiter Hydra]

I've made a script that takes the HTML files from the tournament database and parses them into Christian's JSON format. For a specific stat report, go to http://hdwhite.org/qb/stats/importmatch ... AAA&p=BBBB, where AAAA is the number of the tournament in the URL, and BBBB is the name of the stat report. So for example, to view the playoffs for ACF Fall at UVa, one would go to http://hdwhite.org/qb/stats/importmatch ... l_playoffs. I know this isn't the greatest UI in the history of mankind, but I'm not too sure that many people would be using this.

Let me know if you find any bugs. At the moment, it only supports tournaments with a 15/10/-5 or 10/-5 scoring system, and does not include bouncebacks. There's probably a few others, as HTML parsing with regular expressions is not the most elegant thing in the world.