	SPECIAL NOTES ON USING LAD IN AdaptFilter


Running the program:
--------------------

Assuming that all necessary input files are already prepared, it is
as simple as 
(PATH)/AdaptFilter filter_param > output.log

Refer to the instructions in README and the sample running
script, data/rocchio.sh, for more details.

Config file params:
-------------------

Look at the parameters with names beginning with LAD.* in the sample
config file, data/filterparam/filter_param. Most are documented there. 
More details can be found in the comments in include/LADParamManager.hpp.


Batch filtering vs. Adaptive filtering; Classifier update frequency:
--------------------------------------------------------------------

The parameter updateFreq controls how often the classifier will be
retrained. If updateFreq<0, the classifier will be trained only once:
on the TRAIN set; it will never be updated during the processing of
the TEST set. If updateFreq=N > 0 (by default, N=1), the classifier
the classifier for a query will be retrained after every N
update-worthy documents discovered in the TEST set and added to the
query's labeled set.

What is an "update-worthy" document? Normally (when thres.unjWt=0), a
document is considered update-worthy with respect to a query if it has
been sent to the Oracle with respect to this query, and the Oracle
responded with a P or N judgment. Moreover, if thres.unjWt > 0 (that
is, unjudged docs are treated as low-weight negative documents, rather
than ignored; this is done occasionally to make sure that the
classifier is penalized for sending too many docs to the Oracle), then
every document sent by the classifier to the Oracle will be considered
update-worthy.

With a LAD classifier, a classifier update can be one of the two
kinds. A "small update" causes only the update of the Rocchio model
coefficients and the classifier threshold, without changing the LAD
predicate set (that is, no LAD is run). A "big update" involves a LAD
re-run, with subsequent conversion of all labeled-set documents to the
new space coresponding to the new predicate set. In Madigan's terms,
the former is merely an exercise in classifier learning, without
affecting the representation, while the latter re-trains both the
representation and the classifier.

One can make each classifier update a big update, or one can have a
big update follow a given number of small updates. This is controlled
by the parameter LAD.retrainFreq.  If LAD.retrainFreq=-1, only small
updates are ever performed.  If LAD.retrainFreq=1, all updates are big
updates (expensive!). If LAD.retrainFreq=N>0, one update out of every
N will be a big update, and the rest will be small updates.


LAD Output files:
-----------------

The location of the LAD output files is specified by 
LAD.rundir in the config file.

Typical files produced by the program:

% wc *
     848    2544    8223 lad.train.dat       <-- training set (TF data) 
      21      43     178 lad.train.dat.txt   <-- converts LEMUR doc id (used in our program) to external doc ids
     519    1557    6304 lad.nam             <-- training set (term ID list)
     519    1039    5614 lad.nam.txt         <-- converts term IDs to term spellings
     575    1725    4752 lad.my-mcp          <-- MCP predicates, prefix notation, LEMUR term ids
      28      84     210 lad.my-cut          <-- CUT predicates, prefix notation, LEMUR term ids
      28      28     443 lad.my-cut-trad     <-- CUT predicates, traditional notation, term spellings
      43     434    1127 lad.my-pat          <-- patterns prefix notation, LEMUR term ids
      43      43    1958 lad.my-pat-trad     <-- patterns, traditional notation, term spellings

In the lad.my-cut-trad and lad.my-pat-trad files, each predicate is printed with its weight matrix, 
in the following format:
    NF PF NT PT
where
 NF = sum of weights of docs from F on which !P is true;
 PF = sum of weights of docs from F on which P is true;
 NT = sum of weights of docs from T on which !P is true;
 PT = sum of weights of docs from T on which P is true;

These values are sums of documents weights if LAD.useDocWt=1 (i.e., if
we use doc weights in all LAD calculations). If LAD.useDocWt=0 (i.e,
plain doc counts are used), then the 4 components of the predicate
weight matrix are simply document counts.



Only the last file for each topic is saved:
-------------------------------------------

The file names in the LAD run directory include the topic [query]
names (e.g, lad-R101.my-cut for topic R101). Therefore, you can
run adaptive filtering for several queries at once, and
then look at each query's own files. 

However, if a run involves several LAD retrainings (updateFreq >=1 and
LAD.retrainFreq>=1), the same file names are used for a particular
query throughout the run; therefore, at the end of the run only the
files from the last retraining will be found in the LAD run directory.



Pattern generation: 
-------------------

SPGen is run on several samples of @F (which corresponds to the
documents from P, since we generate negative patterns); the number and
size of samples is controlled by LAD.kft and LAD.qft.  On each run,
the target number of patterns produced is specified by
LAD.maxPatterns.  However, it should be understood that this number is
a target, rather than the exact number of patterns generated each
time. Actual number of patterns generated on each sample is reported
in the log file and may be greater or smaller than
LAD.maxPatterns. The size variation is due to the way the @PATTERNS
list size is adjusted during generation. Namely, when the list size
exceeds the target size, we find the pattern in the list whose
coverage of @T is smallest, and then remove that pattern and all other
patterns with the same value of coverage, and raise the CMIN; this may
reduce the curent list size significantly below LAD.maxPatterns. On
the other hand, if all patterns on the list have the same coverage, we
do not remove any of them, and the list size keeps growing beyond the
target size (LAD.maxPatterns).

List size adjustment is typically done in the fashion described above,
i.e. by raising CMIN rather than reducing DMAX. Only if all patterns
in the list already have the perfect coverage (i.e., are true on all
vectors from @T) and raising CMIN makes no sense, may we may reduce
DMAX instead; this may also make the remaining list very short.



