Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Packet databases and other quizbowl sites, apps, or software should be discussed here.
Post Reply
User avatar
QuestionCactus
Lulu
Posts: 60
Joined: Sat Nov 17, 2018 9:55 pm

Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by QuestionCactus »

Users of qems2 will know that the tool provides the option of outputting a csv file. Using PacketBuilder, you can turn this csv file into a set of automatically randomized packets presented as beautiful LaTeX pdfs.

Image

Instructions

Download the repository. Add your qems output csv and update the settings.txt file to reflect your qems output filename and the name of your set. Install pandas and pdflatex. Run the Python script.

The program will generate pdf packet files but also the .tex files, which can be used to correct imperfections.

Sprinkling Algorithm

The script will generate p = q / 20 packets, where q is the number of tossups/bonuses.

The tossups are divided into categories based on the listed subcategories (e.g. "History - European") and into major categories (e.g. "History") based on the first word of their category. Any category with more than p tossups has 1 randomly selected tossup placed into each packet. This is repeated until all categories have fewer the p tossups, at which point the remaining tossups are pooled into major categories and shuffled. With this new list of "excess tossups," one tossup at a time is placed into each packet until all of the packets are full. This process is then repeated for bonuses.

Randomization Algorithm

Based on common principles of packetization, the tossups and bonuses within each packet are shuffled randomly until they fulfill the following criteria:
  1. No tossup has the same major category as the bonus at the same position.
  2. No major category should appear in two consecutive tossups or in two consecutive bonuses.
  3. The last tossup should not be geography, current events, or trash.
To avoid running forever, criterion 3 is abandoned after 1500 attempts, criterion 2 after 2000 attempts, and criterion 1 after 2500 attempts.

Thanks to Harris Bunker for letting me use a complete qems output file of his for testing (that's the sample file that appears in the repository).

Note that while the algorithm works, there will very likely be imperfections in the resulting packet pdfs and if you decide to try using this tool I would recommend closely checking over the result and having a rudimentary knowledge of LaTeX in order to make small adjustments as needed.

Github repo link: https://github.com/ArjunPanickssery/PacketBuilder
Last edited by QuestionCactus on Tue Aug 06, 2019 4:54 pm, edited 2 times in total.
Arjun Panickssery (he/his)
President, American Quizbowl League
User avatar
theMoMA
Forums Staff: Administrator
Posts: 5993
Joined: Mon Oct 23, 2006 2:00 am

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by theMoMA »

This is a welcome development, but I think it would be extremely helpful to have a program that outputs this to Word, which is a document format that most people are more familiar with and allows for quick editing in Word or Google docs. Also, I'm not sure whether the final output is in columns, as is shown here, but that would be a departure from how most tournaments are printed. (I've never seen packets formatted into columns before.)
Andrew Hart
Minnesota alum
User avatar
Mike Bentley
Sin
Posts: 6461
Joined: Fri Mar 31, 2006 11:03 pm
Location: Bellevue, WA
Contact:

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by Mike Bentley »

Am I missing the link to the tool? I scanned the post a few times and don't see it.

It sounds like you're taking the high-level category (i.e. Fine Arts) and then randomly choosing questions to put into the packet. While this will work decently for some categories, it won't work for a category like Fine Arts where you want to have a balanced set of art and music. You can work around this a bit with category names but I suspect it still will be challenging to create balanced packets.

That being said, if someone can make a great packetization algorithm, go for it. I've tried and haven't been able to come up with something that isn't very hard-coded to the specific set. And even then it's hard if you want to try to respect placement of questions ("place this question in the playoffs").
Mike Bentley
Treasurer, Partnership for Academic Competition Excellence
Adviser, Quizbowl Team at University of Washington
University of Maryland, Class of 2008
User avatar
QuestionCactus
Lulu
Posts: 60
Joined: Sat Nov 17, 2018 9:55 pm

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by QuestionCactus »

Mike Bentley wrote: Tue Aug 06, 2019 3:54 pm Am I missing the link to the tool? I scanned the post a few times and don't see it.
Good catch, thank you. I added it to the main post just now.
Mike Bentley wrote: Tue Aug 06, 2019 3:54 pm It sounds like you're taking the high-level category (i.e. Fine Arts) and then randomly choosing questions to put into the packet. While this will work decently for some categories, it won't work for a category like Fine Arts where you want to have a balanced set of art and music. You can work around this a bit with category names but I suspect it still will be challenging to create balanced packets.
Subcategories are considered first, before high-level categories.

As an example, suppose that these are the counts for every category in the file:

History - American: 15
History - European: 12
History - World: 3
Fine Arts - Auditory: 21
Fine Arts - Visual: 9

And suppose there are 6 packets of 10 tossups each to be filled.

The algorithm first considers these categories without dividing them, and sees if they can be sprinkled into the packets.

So first, "History - American" can have 2 groups of 6 sprinkled in, with 3 left over. "History - European" can have 2 groups of 6 sprinkled in with none left over. And so on.

After this step, each packet should have 2 History - American, 2 History - World, 3 Fine Arts - Auditory, and 1 Fine Arts - Visual.

These would be left over:

History - American: 3
History - European: 0
History - World: 3
Fine Arts - Auditory: 3
Fine Arts - Visual: 3

Now, since each individual category is too small, they're combined into major categories:

History: 6
Fine Arts: 6

And then these groups of "excess tossups" would be split among the packets.
Mike Bentley wrote: Tue Aug 06, 2019 3:54 pm That being said, if someone can make a great packetization algorithm, go for it. I've tried and haven't been able to come up with something that isn't very hard-coded to the specific set. And even then it's hard if you want to try to respect placement of questions ("place this question in the playoffs").
Right, this algorithm will make a non-negligible number of feng shui violations, and the result will need a human eye to check it for sure.
theMoMA wrote: Tue Aug 06, 2019 3:49 pm This is a welcome development, but I think it would be extremely helpful to have a program that outputs this to Word, which is a document format that most people are more familiar with and allows for quick editing in Word or Google docs. Also, I'm not sure whether the final output is in columns, as is shown here, but that would be a departure from how most tournaments are printed. (I've never seen packets formatted into columns before.)
I can make one that converts to Word I guess. And the columns thing can be scrapped.

The origin of this project was in my making a LaTeX template for a packet I was writing, and then making a converter for individual packets. In my packet, I actually have the tossups on the left column and bonuses on the right. It proved difficult to make a general algorithm that does this accurately, so I put all the tossups first and the bonuses afterward in this program.

I think the LaTeX and the columns make the text both more readable and more space-efficient.
Last edited by QuestionCactus on Tue Apr 21, 2020 2:25 pm, edited 1 time in total.
Arjun Panickssery (he/his)
President, American Quizbowl League
User avatar
Ciorwrong
Tidus
Posts: 696
Joined: Fri Dec 20, 2013 8:24 pm

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by Ciorwrong »

theMoMA wrote: Tue Aug 06, 2019 3:49 pm This is a welcome development, but I think it would be extremely helpful to have a program that outputs this to Word, which is a document format that most people are more familiar with and allows for quick editing in Word or Google docs. Also, I'm not sure whether the final output is in columns, as is shown here, but that would be a departure from how most tournaments are printed. (I've never seen packets formatted into columns before.)
I started working on this before Arjun and brought him on to help with going from .txt - > LaTeX pdf. He decided to go start his own project. In my code, I produce .html files which are editable in Microsoft Word or a similar program. This is necessary because there will always be errors with formatting and slight packetization changes are inevitable. People also shouldn't need to learn TeX in order to make a quizbowl set in my opinion.

The reason my code has not been published yet is I'm working on a more thorough packetizing algorithm which actually accounts for sub categories and is more robust to some of the concerns mentioned. My preliminary code is available here. I plan to use my code for production of Michigan Winter Tournament and future events. I find .tex files very clunky to work with and html is more flexible and works in-browser. My hope in the future is that the .html files can work with stuff like Ophir stats and other advanced features.
Harris Bunker
Grosse Pointe North High School '15
Michigan State University '19
UC San Diego Economics 2019 -

at least semi-retired
User avatar
QuestionCactus
Lulu
Posts: 60
Joined: Sat Nov 17, 2018 9:55 pm

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by QuestionCactus »

Yep, Harris's tool will probably be more versatile and will output a more human-editable result that can be used in a variety of ways. My goal largely focused on being able to produce something reasonable in one shot and being able to look at pretty LaTeX pdfs.
Arjun Panickssery (he/his)
President, American Quizbowl League
User avatar
theMoMA
Forums Staff: Administrator
Posts: 5993
Joined: Mon Oct 23, 2006 2:00 am

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by theMoMA »

That sounds great, Harris. It would be excellent to cut down QEMS packetizing from a several-hour task to a several-minute one, especially if no special knowledge is required. Thanks to both of you for your work on this project!
Andrew Hart
Minnesota alum
User avatar
Ciorwrong
Tidus
Posts: 696
Joined: Fri Dec 20, 2013 8:24 pm

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by Ciorwrong »

theMoMA wrote: Tue Aug 06, 2019 6:47 pm That sounds great, Harris. It would be excellent to cut down QEMS packetizing from a several-hour task to a several-minute one, especially if no special knowledge is required. Thanks to both of you for your work on this project!
I timed it with the SHW csv, and it takes about a minute. Of course, someone still has to have their eyes ok each packet in case there are missing underlines and bold face, etc. I used regex for everything which has some drawbacks.
Harris Bunker
Grosse Pointe North High School '15
Michigan State University '19
UC San Diego Economics 2019 -

at least semi-retired
User avatar
Alejandro
Wakka
Posts: 226
Joined: Mon Jul 10, 2006 8:39 pm
Location: Seattle, WA

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by Alejandro »

QuestionCactus wrote: Tue Aug 06, 2019 4:10 pm Now, since each individual category is too small, they're concatenated into major categories:

History: 6
Fine Arts: 6

And then these groups of "excess tossups" would be split among the packets.
Does the packetizer respect minimum/maximum category and subcategory quotas? Like Mike, I've struggled with creating a good packetizer algorithm, and a big stumbling block is in generating packets that satisfy every quota.

It's good to see work being done on packetization, though, and your approach is clever.
Alejandro
Naperville Central '07
Harvey Mudd '11
University of Washington '17
User avatar
QuestionCactus
Lulu
Posts: 60
Joined: Sat Nov 17, 2018 9:55 pm

Re: Introducing QuizDroid PacketBuilder (qems csv --> packetized LaTeX pdfs)

Post by QuestionCactus »

Alejandro wrote: Fri Aug 16, 2019 3:32 am Does the packetizer respect minimum/maximum category and subcategory quotas? Like Mike, I've struggled with creating a good packetizer algorithm, and a big stumbling block is in generating packets that satisfy every quota.
No, it doesn't even read those columns. It doesn't read the columns where the packet of a given question is handpicked, either.
Arjun Panickssery (he/his)
President, American Quizbowl League
Post Reply