This space is defunct, here's the redirect

I have moved everything from here to a mediawiki install. My new homepage is here:
http://wiki.df.dreamhosters.com/wiki/Main_Page

The ricemaker in particular lives here:
http://wiki.df.dreamhosters.com/wiki/RiceMaker

You will be automatically redirected in 5 seconds.


What is RiceMaker?


Ricemaker is a python script that automates the vocabulary game on FreeRice to generate rice donations. In other words, it is a FreeRice bot.

It uses the BeautifulSoup HTML parsing module, and, of course, the python interpreter.

Major features


  • Automatically plays the FreeRice vocabulary game.
  • Achieves high accuracy by looking up words on WordNet and dict.org.
  • Builds an internal dictionary of correct responses, achieving 100% accuracy in short order.
  • Good starter dictionary available for those who don't want to start from scratch.
  • Session saver keeps track of total rice donated by you using ricemaker.
  • Capable of running multiple threads in parallel, all learning and sharing knowledge at the same time. (Note: to avoid triggering the site's bot detection, might want to run it with just one thread.)
  • Highly configurable through command-line options. Choose how many threads to run, the individual thread loop delay, and more.
  • Informative and detailed runtime output:
    • Questions, answers given, correct answers
    • Vocab level for each thread
    • Total rice donated for the session
    • Average accuracy for the session
    • Total rice donated over all recorded sessions
    • Questions answered per second, and rice donated per second

You can view the changelog for ricemaker here:

How do I start using RiceMaker?


A few simple steps is all it takes:
ricemakerrun.png
RiceMaker doing its job (click to enlarge).

  1. Download and install python for your platform
  2. Download the file and place it anywhere (into the same directory as BeautifulSoup.py, if you chose not to install that module system-wide)
  3. Download BeautifulSoup and either install it system-wide (instructions available on site) or simply put the BeautifulSoup.py file into the same directory as you put the ricemaker.py file.
  4. [Optional - if you don't want to wait for RiceMaker to generate a dictionary from scratch] Download the file and place it into the same directory as ricemaker.py. (This dictionary file contains just about all words on levels 49 and 50, and quite a few from the lower levels as well. Since the script is smart enough to get to 50 and stay there, this is really all you need. :))
  5. [Optional - only if you have WordNet installed on your system] Determine the location of the WordNet command-line executable, and add that information to the command-line option for wordnetpath. You may also change some other parameters there if you choose, but the defaults would normally be just fine (see these detailed usage instructions).
  6. Open up a terminal (or command prompt), cd to the directory where you put the ricemaker script, and run command
python ricemaker.py

Enjoy watching your rice counter go up! (see screenshot at right). You can also learn vocabulary by watching the script - the target word and the correct answer are printed for that purpose. :)

How do I stop the script?


Just hit Control-C in the terminal window. The script will dump the internal database to file, and exit cleanly.

How does it work?


The script downloads the FreeRice page, parses out the question word and the possible answer choices. Then RiceMaker does a multi-stage word lookup.

  1. Look up the word in the internal dictionary (read more about how it is built below). If this is successful, submit the answer and go on to the next question. If it fails, go to the second stage.
  2. Look up the question word in WordNet (if present on your system - edit the script to set the configuration variable for WordNet full path for this to work), and search the WordNet output for the presence of each of the four possible answer choices. When a match is found, that answer is chosen and submitted. If it fails, try the third stage.
  3. Look up the word on http://dict.org, and use the same matching principle. If this fails, use the fourth and final stage.
  4. Choose an answer at random. :)

Before the internal dictionary is built up, WordNet and dict.org together produce about a 90% correct answer rate playing the game. (For the curious: using just WordNet or just dict.org, the accuracy is about 80%.) But it gets better!

As we go through questions, ricemaker keeps track of what questions have been asked, and what the correct answers were, writing these to an internal dictionary. As it gets bigger, more and more matches are made from this internal dictionary. It takes about 600 questions for the dictionary to have almost all of the words in vocab level 50 (where the script will happily reside forevermore).

Once you have fleshed out the internal dictionary, the correct answer rate approaches 100%.

Ricemaker makes a random pause of 3-6 seconds [default values] between iterations, to avoid hammering the freerice server, and to avoid looking too much like a bot in the server logs. :)

Detailed usage instructions


RiceMaker's behavior is configurable through command-line options. For example, to configure WordNet location, you would run RiceMaker as follows (actual path to the WordNet command-line executable may be different on your system):
python ricemaker.py -w 'C:\Program Files\WordNet\wn.exe'

The defaults are pretty sane, so besides the WordNet path, you really don't have to change anything unless you are just curious to play around with it. :)

If you need any further help, please post your questions on the discussion page.

The following reproduces the detailed help message from running ricemaker with the -h (help) option:
Usage
=====
  python ricemaker.py [options]
 
RiceMaker will automatically play the vocabulary game on freerice.com to
generate rice donations. For a more detailed usage manual, see the project
homepage: http://smokyflavor.wikispaces.com/RiceMaker
 
Options
=======
--version               show program's version number and exit
--help, -h              show this help message and exit
--debug, -d             Debug mode (print some extra debug output). [default:
                        False]
--savesession, -s       Save session in a file. This will store a running
                        total of the rice generated by you, across multiple
                        runs of ricemaker. [default: True]
--wordnetpath=WORDNETPATH, -w WORDNETPATH
                        Full path to the WordNet commandline executable, if
                        installed. On Linux, something like '/usr/bin/wn'; on
                        Windows, something like 'C:\Program
                        Files\WordNet\wn.exe'. [default: /usr/bin/wn]
--useragent=USERAGENT, -u USERAGENT
                        The User-Agent string to use for the HTTP requests.
                        The default is the User-Agent from IE7 on WinXP SP2.
                        [default: Mozilla/4.0 (compatible; MSIE 7.0; Windows
                        NT 5.1)]
--sleeplowsec=SLEEPLOWSEC, -l SLEEPLOWSEC
                        Lower bound on the random number of seconds to sleep
                        between iterations. [default: 3]
--sleephighsec=SLEEPHIGHSEC, -m SLEEPHIGHSEC
                        Upper bound on the random number of seconds to sleep
                        between iterations. [default: 6]
--freericedictfilename=FREERICEDICTFILENAME, -f FREERICEDICTFILENAME
                        Filename for internally generated dictionary. You may
                        specify a full path here, otherwise it will just get
                        written to the same directory where this script
                        resides (default behavior). No need to change this
                        unless you really feel like it. [default:
                        freericewordlist.txt]
--iterationsbetweendumps=ITERATIONSBETWEENDUMPS, -i ITERATIONSBETWEENDUMPS
                        Number of iterations between dictionary dumps to file.
                        More often than 5 minutes is really unnecessary (Time
                        between dumps is iterationsbetweendumps * avgsleeptime
                        = time between dumps.) [default: 1000]
--threads=THREADS, -t THREADS
                        Number of simultaneous threads of RiceMaker to start.
                        Stick with 1 to reduce probability of being filtered
                        out as a bot. [default: 1]
--benchmark=BENCHMARK, -b BENCHMARK
                        For benchmarking or dictionary building purposes: do
                        you want to skip dict.org lookups and/or wordnet
                        and/or internal dictionary lookups ('dict.org' to skip
                        dict.org, 'wordnet' to skip wordnet, 'idict' to skip
                        internal dictionary). [default: []]

Ethical considerations


The source of the funds for the rice donations is the advertisers on the site. The script does not display the ads to the user, thus potentially "cheating" the advertisers out of the gains they expect to make from advertising. Can it be, then, that running a ricebot is detrimental to the whole idea? I argue that that is not the case.

Consider that the adverts are not trying to sell particular products, but just to associate the sponsor company's name with a noble humane cause, in the minds of the humans playing the game, in effect boosting the corporate image among potential purchasers of products in the future.

Few, if any, people will start running a ricebot without first playing the game for a quite a few iterations, until they get bored. Thus, they will have plenty of time to see the ads quite a few times. I argue that the first couple of hundred times that you see the ads basically max out any image-boosting effect in the mind of the viewing human, and that the marginal effect of any further viewing of the same company logo does not convey any further benefit to the advertisers. So, the "negative" effect of running a ricebot is approximately zero.

Some may argue that the marginal effect of ad viewing is not so quickly decreasing, due to the value of "subliminal advertising". However, the evidence available shows that the effectiveness of subliminal messages is at best dubious.

Furthermore, without ricebots, most people will generate at most a few thousand grains of rice, before getting bored with the game and never showing up again. This means that the overall rice generation potential for the site will be relatively small, as the growth potential is limited by the number of "new" people that learn of the project. The presence of ricebots has the potential to increase the rice generation by several orders of magnitude, thus making the project much more newsworthy. More news coverage, mentioning the corporate sponsors in the context of charitable activity, actually confers a benefit on the advertisers.

Based on these arguments, it is hard to say that running a ricebot confers a net economic cost on the advertisers. It may very well be a net neutral, or even a net surplus.

That said, the FreeRice FAQ now includes a question about bots, which seems to discourage rice generation exclusively through bots.

But, ultimately, it is up to you to decide whether you feel comfortable running a bot to generate rice, for how long to run it, whether you want to supplement it with manual game playing or deliberate ad clicking and/or product-buying, etc.. You are your own moral compass.

Fun facts


Easter egg messages


Every 10,000 grains of rice, you get a "special" message. Look for the following ones in your output (only printed if you're running one thread):
You have donated 10000 grains of rice. Wow! Now THAT is impressive!
You have donated 20000 grains of rice. Wow! We're speechless!
You have donated 30000 grains of rice. Wow! We're STILL speechless!
You have donated 40000 grains of rice. Wow! We're STILL speechless!
You have donated 50000 grains of rice. Wow! We're STILL speechless!
You have donated 60000 grains of rice. Wow! We're STILL speechless!
You have donated 70000 grains of rice. Wow! We're STILL speechless!
You have donated 80000 grains of rice. Wow! We're STILL speechless!
You have donated 90000 grains of rice. Wow! We're STILL speechless!
You have donated 100000 grains of rice. May you have a lifetime of happiness...

Yes, it does look like they ran out of imagination between 30K and 90K rice grains... :)

What happens after 100,000 grains?


Counter restarts from 0 (that's what happens as of November 13, 2007). Rather anticlimactic... :)

What does all this rice translate to?


  • There are about 29,000 grains of rice in a pound of long-grain rice.
  • Current market price of Rough Rice, per 100 lbs, is about USD 12.5 (as of November 2007).
  • The "milled" yield from 100 pounds of rough rice is about 56 lbs of milled whole grains and 12 lbs of broken grains.
  • Does Freerice donate grains of Rough Rice, or grains of Milled Whole Grain Rice? They don't specify, but let's be charitable, and assume it is Milled Rice. This means that the price per 100 lbs of donation is about USD 22.3 (12.5 / 56 * 100).
  • How many grains does it take, then, to make a donation of USD 22.3? 100 lbs * 29,000 grains/lb = 2.9 Million grains.
  • Assuming you can answer one question per 3 seconds, 24 hours a day (as RiceMaker will enable you to do), it will take 2,900,000/(24*60*60.0*10/3) or 10 days to donate 100 lbs of rice (the equivalent of 22.3 USD).
  • A pound of brown rice cointains 1633 Calories. To convert rough rice to brown rice, the hulls - about 17 percent of the weight must be removed. Thus, a pound of rough rice contains about 1356 Calories. source
  • Based on a 2000-Calorie diet, and assuming rice as the only source of energy, a person needs 2000/1633 = 1.2 pounds of milled rice per day.
  • This translates to about 35,500 grains of rice (based on 29,000 grains per pound).
  • Thus, if you run RiceMaker 24/7, and don't change the loop delay settings from the default of 3 second average, you can feed about 60*60*24*10/3.0/35500 = 8.1 people per day.

Related links



Where can I ask more questions?


Please do let me know if the script stops working (which happens occasionally due to changes in the freerice site layout). Any comments or suggestions are also welcomed. You can post your comments in the discussion page.