-----------------------------------
                                LRApy
                 -----------------------------------

Author: Max Jakob (max.jakob@web.de)
Version: 1.1

This program is free implementation of the Latent Relational Analysis,
that was developed by Dr. Peter Turney at the Institute for Information
Technology of the National Research Council Canada. It answers
multible-choice word-analogy questions, using the vector space model,
known from Information Retrieval.
For a detailed description of the algorithm see
  http://arxiv.org/abs/cs/0412024

For software requirements see INTALL. Also an indexed corpus is required
(see below).

You can call LRApy from command line:
  python src/lra.py <task_file> <corpus_directory>


Task file format
~~~~~~~~~~~~~~~~
<task_file> is a plain text file that contains all word-analogy questions,
that are to be answered.

Every line contains a case-insensitive word pair devided by a colon.
  word1:word2

The first line contains the stem. That is the word pair, whoms relation is
to be found in the multible choices.

The lines below the stem are the (multible) choices, from which the LRA
must choose the right one.
The one line marked with a '*' is the right choice.

The individual tasks are splited by a blank line ('\n\n').

Example:

  skulk : move      (stem)
  look : listen     (choice)
  blink : wink      (choice)
  shake : quiver    (choice)
  * peek : observe  (right choice)
  weep : grieve     (choice)

  tirade : anger        (stem)
  handshake : love      (choice)
  outburst : explosion  (choice)
  * lament : grief      (right choice)
  etc.


Corpus requirements
~~~~~~~~~~~~~~~~~~~
To prepare your corpus for retrieval run
  python /src/indexCorpus.py <corpus_directory>

That creates the indices that the corpus interface needs for context
searching in the corpus. The directoy can contain the following files:
  - Reuters Corpus XML-Files
  - any HTML-Pages
  - plain text files

Two files are created in the root directory:
'files.list' is a mapping of indices to full paths of a file,
'words.index' is a mapping of all words in the corpus to the files and
positions in which they occur.

If you have a big corpus and a limited amount of working memory, run
  python src/indexCorpus.py -big <corpus_directory>


CONSTANT VARIABLES
~~~~~~~~~~~~~~~~~~
The constant variables can be modified in 'lra.py', starting in line 23.

NUM_SIM       The number of synonyms to get from the thesaurus.
MAX_PHRASE    The scope in which the two words may appear, when counting
              synonym frequencies. In LRApy it is always MAX_INTER + 2,
              and does not need to be specified.
NUM_FILTER    The number of synynoms to keep (top in frequency).
MIN_INTER     Minimum number of intervening words when searching for phrases.
MAX_INTER     Maximum number of intervening words when searching for phrases.
NUM_PATTERNS  The number of patterns to keep (top in frequency).
k             The Number of columns to which is projected after SVD.

It is also optional if alternates should be included (USE_ALTERNATES),
entropy should be calculated (USE_ENTROPY) and if SVD should be applied
(USE_SVD). The values for this variables are boolean.