Added KyTea active

tools/kytea-active/README-en

@@ -0,0 +1,73 @@
+Partial Annotation for Word Alignment Domain Adaptation using KyTea
+Graham Neubig and Shinsuke Mori
+2011-01-20
+
+~~~~~~ Introduction ~~~~~~
+
+This is a toolkit for using active learning and partial annotation to do efficient domain adaptation. If you have any questions, comments, or corrections, please send them to neubig@gmail.com.
+
+One of the most attractive points of KyTea is that it is able to be adapted to new domains easily. In particular, as KyTea can be learned form partial annotations, it is possible to achieve good results with less annotation than previous methods. Traditional full annotation for word annotation takes the following form:
+
+この 時期 の 中心 人物 は 、 風穴 延昭 で あ る 。
+
+It can be seen that a space is placed between all words (where a word boundary exists), and there is no space where no word boundary exists. However, in order to do this, a whole sentence must be annotated at a time, while in this sentence there is only one word that is difficult to segment: "風穴." When using partial annotation, we are able to annotate only this difficult word and skip the rest of the words: 
+
+こ の 時 期 の 中 心 人 物 は 、|風-穴|延 昭 で あ る 。
+
+Here, a pipe "|" indicates that a word boundary exists, a hyphen "-" indicates that word boundaries don't exist, while a space " " indicates a section that we have not yet annotated.
+
+~~~~~~ Getting Ready ~~~~~~
+
+Please take the following steps to get ready to start annotating. Note that all files should be in the UTF-8 encoding.
+
+0) Modify the following lines in makemodel.sh to link to the KyTea binaries.
+
+     KYTEA=$PATH_TO_KYTEA_BIN/kytea
+     TRAIN=$PATH_TO_KYTEA_BIN/train-kytea
+
+   If KyTea is installed in your default path (it can be run by just typing "kytea)" then there is no need to modify these lines.
+
+1) Choose your segmentation standard. There are a number of different segmentation standards that can be used, but the official version of KyTea uses the one on the following site:
+   http://plata.ar.media.kyoto-u.ac.jp/sasada/research/project/corpus/
+
+2) Next, move a general domain corpus to the "data/" folder and modify the "GEN_CORPORA" variable in makemodel.sh to point to this data. For example, if the name of the corpus is BCCWJ.word, we will set the line as follows:
+
+      GEN_CORPORA="-full data/BCCWJ.word"
+
+   Included in the package is a Wikipedia corpus, which we are able to distrubte under the Creative Commons License. However, it is extremely small, and the results were automatically generated and corrected very simply by hand, it cannot be considered 100% correct. We recommend that you replace this with any high-quality language resources that you have at your disposal. In particular, the "Balanced Corpus of Contemporary Written Japanese (BCCWJ)" has extremely high quality annotations over a fair number of domains, so we recommend it for use with KyTea.
+
+3) Move the corpus that you want to annotate to data/target-train.raw.
+
+4) If you have dictionaries that you would like to use, you can move them to the "data/" folder and modify the DICTS variable in makemodel.sh to include them. If we have two dictionaries named "dict-1.txt" and "dict-2.txt" we can set the variable as follows.
+
+     DICTS="-dict data/dict-1.txt -dict data/dict-2.txt"
+
+   There are several things to note here. First, if it is possible to use a large, high-quality dictionary that matches the segmentation standard (for example, UniDic), this will greatly improve the segmentation accuracy compared with when one is not used. Second, unlike previous methods for morphological analysis, KyTea is able to use other dictionaries that don't necessarily match the segmentation standard of the corpus without decreasing accuracy. For example, if you have an in-domain dictionary that includes compound words, this can still be used to improve accuracy.
+
+~~~~~ Annotation ~~~~~
+
+Once you have finished preparing, it is time to start annotation. If you follow the 3 steps below 5-50 times you will notice a large increase in accuracy on your target domain. Of course, more is better, but you will get diminishing returns.
+
+1) First, we create a model with the corpus and dictionaries that are currently annotated, and choose positions that need to be annotated using active learning.
+
+     [user@machine]$ ./makemodel.sh
+
+   * The file in work/XXX.mod (where XXX is a number) is the model trained using all the resources that you have finished annotating.
+   * This step takes approximately five minutes, but more or less depending on the size of the corpora that you are using.
+
+2) In the file that is created in work/XXX.annot, change all of the exclamation points into "|" or "-". Also, if there are mistaken word boundaries that surround the exclamation points, these should be corrected as well. The file you need to modify is the file with the largest number XXX. Also, if you are having trouble deciding about a particular point, you can skip it by inserting a "?" instead of "|" or "-" and move on.
+
+3) Save the new file.
+
+     [user@machine]$ ./saveannot.sh
+
+   * If you get an error such as 「Double boundary ' |' at XXX」 this means that you made a mistake annotating line XXX, so check to make sure that you inserted only one boundary character " ", "|" or "-" between each text character. saveannot.sh will need to be run one more time after this.
+   * Once this step is finished, return to step 1.
+
+After you have finished annotating, you can find the fruit of your labors in the save/ folder. The file XXX.wann with the highest number is the file containing all sections annotated in this process. You can use this for later KyTea training using the "-part save/XXX.wann" option.
+
+~~~~ Notes ~~~~
+
+o In the XXX.annot file, word boundaries "|" should not be added at the very beginning or end of any sentence.
+
+o The files "save/XXX.wann" and "work/XXX.wordprob" contain information about the entire input corpus, and are saved on every iteration. If the corpus is large and your disk is small, this has the potential to fill up your entire disk. To make sure that none of your files are deleted by accident, we are not deleting these files automatically, but if you run into problems, you can delete some of the older files by hand to free up space.

tools/kytea-active/README-ja

@@ -0,0 +1,127 @@
+KyTeaを使った単語分割のための部分的アノテーション
+Graham Neubig, 森 信介
+2011-01-20
+
+~~~~~~ はじめに ~~~~~~
+
+KyTea の最も大きな利点の１つは分野適応が簡単であることです。特に、部分
+的アノテーション(後述)を使った分野適応は有用です。従来手法では、辞書に
+単語を追加する以外には、フルアノテーションコーパスを準備する必要があり
+ました。フルアノテーションコーパスは、
+
+  「この 時期 の 中心 人物 は 、 風穴 延昭 で あ る 。」
+
+のように、全ての単語境界に空白を入れ、単語境界のないところに空白を入れ
+ないことで、すべての文字間の境界情報をアノテーションします。しかし、こ
+の文の中で、「風穴」以外、ほとんどの単語境界は自明であり、アノテーショ
+ンする必要はないため、時間の無駄が生じます。その代わり、部分的アノテー
+ションでは、以下のように「風穴」のところだけをアノテーションすることが
+できます。
+
+  「こ の 時 期 の 中 心 人 物 は 、|風-穴|延 昭 で あ る 。」
+
+ここで、縦棒「|」は「単語境界あり」、横棒「-」は「単語境界なし」を意味
+し、空白は「単語境界の有無はアノテーションされていない」ことを意味しま
+す。これにより、アノテーションが分野適応に有用な箇所のみに集中すること
+がでます。KyTea はこのような言語資源から学習することができるので、効率
+的なアノテーションを実現することができます。
+
+
+~~~~~~ 準備 ~~~~~~
+
+アノテーション作業を開始する前に以下の準備をしてください。テキストファ
+イルのエンコードはすべて UTF-8 にしてください。
+
+0) KyTea が動作することを確認し、必要があれば makemodel.sh を編集する。
+
+     KYTEA=$PATH_TO_KYTEA_BIN/kytea
+     TRAIN=$PATH_TO_KYTEA_BIN/train-kytea
+
+   なお、kytea [Enter] で動作する場合には、デフォルトのままでよいです。
+
+
+1) 単語分割の基準を決めます。様々な基準はありますが、KyTea に付属してい
+   るモデルは、以下に説明している基準を利用しています。
+   http://plata.ar.media.kyoto-u.ac.jp/sasada/research/project/corpus/
+
+2) まず、一般分野のフルアノテーションコーパスを data/ フォルダに移しま
+   す。次に、makemodel.sh を編集して GEN_CORPORA にこのコーパスのパスを
+   追加します。例えばコーパスが BCCWJ.word の場合以下のようになります。
+
+      GEN_CORPORA="-full data/BCCWJ.word"
+
+   配布時には Creative Commons License の基に再配布可能なWikipedia デー
+   タを入れていますが、非常に少量であり、自動解析結果を人手で簡単に修正
+   しただけなので、単語の分割境界情報は100%信頼できるとは言えなません。
+   このため、手元に利用可能な言語資源があれば、それで置き換えることをお
+   すすめします。特に、日本語書き言葉均衡コーパス(BCCWJ) は様々な分野の
+   テキストに対して非常に精度の高いアノテーションを行ってあるため、
+   KyTea の学習に適しています。
+
+3) アノテーションしたい生コーパスを data/target-train.raw に移します。
+
+4) 辞書(複数可)がある場合は、それらの辞書ファイル(ここでは dict-1.txt
+   と dict-2.txt とする) を data/ フォルダに移し、makemodel.sh を編集し
+   て DICTS 変数にこの辞書のパスを追加します。この例では、以下のよ
+   うになります。
+
+     GEN_DICTS="-dict data/dict-1.txt -dict data/dict-2.txt"
+
+   ここで　注意すべき点はいくつかあります。１つ目は、UniDic などの単語
+   コーパスの単語分割基準に合った網羅的な辞書があれば、単語分割の精度が
+   ない場合に比べて非常に高くなります。手に入れば利用をおすすめします。
+   また、従来の形態素解析と違って、辞書は必ずしもコーパスの単語分割基準
+   に沿っていなくても精度は落ちません。分野内の複合語の辞書を利用すれば
+   さらなる精度向上が実現可能となります。ただし、２つの異なる辞書を利用
+   する場合、１つのファイルとしてではなく、以上の例のように個別に読み込
+   むほうが精度が高くなります。
+
+
+~~~~ アノテーション ~~~~~
+
+準備ができたら実際のアノテーションに移ります。以下の３ステップを数十回
+繰り返すと、適応分野における分割精度はかなり上がります。
+
+1) 現在持っている言語資源(コーパスと辞書)でモデルを作成し、アノテーショ
+   ンすべき箇所を選択します。
+
+     [user@machine]$ ./makemodel.sh
+
+   ※この結果得られる work/XXX.mod (XXX は数字)が、各繰り返し時点での
+     KyTea のモデルファイルです。つまり、最も大きい数字のファイルが最良
+     のモデルです。
+   ※言語資源の量によりますが、おおよそ5分ぐらいかかります。
+
+
+2) work/XXX.annotにできるファイルの中の「!」を「|」や「-」 に書き換え
+   、「!」の周りに間違った単語境界があればそれも直します。ここで XXX
+   は数字であり、最も大きい数字のファイルをアノテーションして下さい。
+   アノテーションが困難な箇所があれば、 「|」と「-」の代わりに「?」を
+   入れてアノテーションされていないままにすることもできます。
+
+3) 新しいファイルを保存します。
+
+     [user@machine]$ ./saveannot.sh
+
+   ※「Double boundary ' |' at XXX」のようなエラーが起こった場合はXXX
+    行目にアノテーションの形式が誤っている（具体的には、空白を消さずに
+    単語境界「|」を入れている）ので、 アノテーションファイルを直して、
+    もう一度./saveannot.shを直してください。
+   ※この後 1) に戻ります。
+
+アノテーションが終わったら、部分的アノテーションされたコーパスは
+save/XXX.wannとして保存されます。新たにKyTeaを学習する場合、"-part 
+save/XXX.wann"のオプションを指定すると、部分的アノテーションされた資源
+を利用してモデルを学習することができます。
+
+~~~~ 注意すべきこと ~~~~
+
+o XXX.annot ファイルの中で、文の最初の文字の前や最後の文字の後ろに「|」
+  や「-」を入れないでください。
+
+o 「save/XXX.wann」と「work/XXX.wordprob」ファイルは毎回保存されるため
+  、もとの生コーパスが大きい場合、ディスクの容量がかかります。アノテー
+  ションされた物が誤って消去されるのを防ぐため自動では消しておりません
+  が、容量が足りない場合は古いものを手動で消してください。
+
+以上