To compute the bogosity of a message, the Robinson-Fisher algorithm
uses several special numeric constants (robs, robx, min_dev,
spam_cutoff, and ham_cutoff).  File bogofilter-tuning.HOWTO, in
/usr/share/bogofilter/tuning describes these parameters and explains
how to tune the Robinson-Fisher algorithm so it gives optimal results.

This directory contains the scripts for running tests as described in
the HOWTO.  The scripts will suggest the optimal robs, min_dev, and
spam_cutoff values for _your_ email.  The scripts were created to
generate a file (named parms.tbl) giving test parameters and counts of
false negatives, which indicate how good the results are for the
current parameters.  The file can be used as input to the R
mathematical language (see file tuning.R) for generating graphs or
other analysis.

The best way to run a tuning test is to copy all the scripts from
/usr/share/bogofilter/tuning into a new, working directory.  The
scripts will need access from that directory to your messages.  You
can copy good.mbx and spam.mbx to the new directory or use symlinks.
Then switch to the new directory and run "tuning.sh".

After setting up the test files, tuning.sh will cycle through ranges
of values for robs and min_dev and print a line of output for each
combination.  This can be slow.  Depending on processor speed and the
amount of test data, each line may take a few seconds or a few minutes
or longer to complete.  The last number of each line is measure of how
well bogofilter did with the parameter combination being tested.  A
smaller value is better.  At the end of the whole test, the "Top 10
Results" are printed.

When you rerun the test with different test data, it's necessary to
delete the old training and test files, i.e. t.ns, t.sp,
r[0-2].ns/sp.*, and goodlist.db/spamlist.db.  If you're testing
different value ranges of robs and min_dev, the training and test
files can be used without problem.

How It Works:

Script bogolex.sh converts an email to a "msg-count" format which
contains the information needed by bogofilter to score the email.
A "msg-count" file contains tokens and their good and bad counts (from
the wordlists).  With formail, bogolex.sh can take a whole mbox file
and produce a msg-count file with an entry for each email in the mbox
file.  Using msg-count files during tuning moves the overhead of
looking up counts to a pre-processing pass at the beginning of a tuning
run.  Since bogofilter doesn't have to use BerkeleyDB during scoring,
it can process msg-count files approx 10 to 20 times faster than
regular files.

The first step tuning.sh takes is to run script "mkdb" to set up test
files.  Mailboxes good.mbx and spam.mbx are split up into training
data files (named t.ns and t.sp) and 3 test data sets (with files
named r0.ns, r0.sp, r1.ns, r1.sp, r2.ns, and r2.sp).  The training
data will be used to build wordlists (goodlist.db and spamlist.db).
To speed up the testing, the messages r in the test data sets will be
converted to msg-count format (in files r?.??.mc).

The computation of each results line involved scoring many messages.
First the non-spam messages in r0.ns.mc, r1.ns.mc, and r2.ns.mc are
scored.  Using these results and the value of "$target" (in
tuning.sh), a spam_cutoff is selected.  Then the spam messages in
r0.sp.mc, r1.sp.mc, and r2.sp.mc are scored.  For each of these files,
the number of false negatives is printed.  The last number of the line
is the total number of false negatives.

The results from each run are left in files results.MMDD.HHMM.txt and
parms.MMDD.HHMM.tbl.  This allows multiple sets of test results to be
saved, but may necessitate some house keeping from time to time.
(Note: If you have the R mathematical package installed, the
parms.MMDD.HHMM.tbl file can be used as input to script tuning.R to
generate a graph).

Enjoy!
