//////////////////////////////////////////////////////////////////////

□認識率算出ツール□
					       last update: 2003.10.01
//////////////////////////////////////////////////////////////////////

○変更履歴
===========
CSRC2000年度版
 ・初出

CSRC2003ベータ版(2003.07.01)：
 ・julius-3.3 の出力形式に対応．
 ・jperl を不要にした（通常の perl で動作）．
 ・バッチ処理するスクリプト "EVAL.sh" を追加した．

CSRC2003版(2003.10.01):
 ・julius-3.4 の出力形式に対応
 ・信頼度の出力に対応．しきい値ごとのFA, SErr, FRなどを算出
   (result_cm.pl)


○ファイルの内容
=================
動作には perl が必要です．

mkhyp.pl		Juliusの認識ログから認識結果の文仮説を抽出するフィルタ
align.pl		認識結果と文仮説のアラインメントを取るツール
score.pl		アラインメント結果から認識率などを算出するツール

EVAL.sh			上記を起動するスクリプト


○ Quick Start
==================

 Julius の認識結果の標準出力を記録したログと，正解ファイルを用意して，
以下のように実行することで認識率を算出できます．

	% ./EVAL.sh logfile reffile

ただし，logfile は Julius の認識結果の標準出力を記録したログ，reffile
は正解ファイルです．

以下に実行例を示します．ここでは単語認識率(%Correct) が 91.13, 単語認
識精度(Word Accuracy) が 89.35 と算出されています．"1st pass" とあるの
は第1パスのみの場合の結果です．

  % /cdrom/tools/scoring/EVAL.sh log_fast.male male20k.jdpr2_1-dic.ref
  log: /project/shikano-lab24/Work/ri/jnas/t/log_fast.male
  ref: male20k.jdpr2_1-dic.ref
  ----------------------------------------------------------------------------
            Snt      Corr      Acc      Sub      Del      Ins      Err   S.Err
  ----------------------------------------------------------------------------
  final (2pass)
  Sum/Avg   100     91.13    89.35     7.54     1.33     1.77    10.65   55.00
  ----------------------------------------------------------------------------
  1st pass
  Sum/Avg   100     82.94    80.91    13.19     3.87     2.03    19.09   78.00
  ----------------------------------------------------------------------------
  evaluation results saved to "./result.log_fast.male/"

なお，"EVAL.sh" は実際には，内部で他の３つのスクリプト (mkhyp.pl,
align.pl,score.pl) を起動して結果を表示するプログラムです．
処理の具体的な内容については，この文書の下方にある解説をご覧ください．


○正解文ファイルの作り方
=========================

正解ファイルは，以下のように，ファイル名に対応するIDと単語（形態素）で
分かち書きした正解文テキストの2行を一組として記述します．
----------------------------------------------------------------------
nm005-025
お+オ+39 年寄り+トシヨリ+2 から+カラ+58 の+ノ+67 注文+チューモン+17 に
+ニ+58 も+モ+62 備え+ソナエ+備える+44/6/5 、+、+75 二千+ニセン+19
個+コ+33 分+ブン+28 の+ノ+67 材料+ザイリョー+2 を+ヲ+58 確保+カクホ+17
。+。+74
----------------------------------------------------------------------
正解文の形態素が認識で用いる言語モデルの形態素と一致するように注意して
ください．

ファイル名と「ファイル名に対応するID」の変換規則は，このディレクトリに
あるスクリプト "mkhyp.pl" 内で定義します．詳細は以下をご覧ください．


//////////////////////////////////////////////////////////////////////
				解説
//////////////////////////////////////////////////////////////////////

○処理の流れ
============

Juliusのログから認識率を算出するための処理の流れを以下に示します．
EVAL.sh では実際に以下の手順で認識率を算出しています．
EVAL.sh の内容も併せてご覧ください．

Juliusログ
   |
(mkhyp.pl)
   |
   v
仮説ファイル(.hyp)	正解文ファイル(.ref)
(＋単語信頼度）
   |                               |
   --------------+------------------
                 |
             (align.pl)
                 |
                 v                                 
        アラインメントファイル(*.ali)
                 |
                 +---信頼度があれば---
                 |                   |
             (score.pl)        (result_cm.pl)
                 |                   |
                 v                   v
           集計結果が             CM_Histgram
           *.ali.scr/ 以下に
           生成される


○mkhyp.pl
===========

	使用法：
		% nkf -e julius.log | \
		  perl mkhyp.pl \
		  -p {1|2} \
		  > julius.hyp


  Juliusの認識結果ログから，音声サンプルのIDとその認識結果の組を抽出し
た仮説ファイル(*.hyp)を作成します．また確信度があれば，それも同時に
抽出します．

  オプション -p でどちらのパスの仮説ファイルを作成するかを指定します．



 ※注意１：

    "-quiet" "-demo" をJulius実行時につけた場合，正しく集計されません．
    （集計に必要な単語のN-gram形態素タグ情報が出力されないため）
    認識率を算出する際は上記のオプションを付けずに実行してください．


 ※注意２：

    仮説ファイルのIDと正解文ファイルのIDは，対応が取れている必要があり
    ます．本ツールでは入力としてJNASデータベースを仮定し，ファイル名を
    対応するJNASの話者IDと文番号に変換しています． 

	例：
		 ファイル名			サンプルID
	  /home/somewhere/nm006020.hs.mfc  ->  nm006-020

    JNAS以外の評価セットを使う場合は，正解文ファイルのIDと対応が取れる
    よう，本スクリプト末尾の "bunkai_id" を変更して使用してください．


○align.pl
===========

	    使用法：
		    % align.pl \
		          -u {morpheme|char} \
		          [-c] \
		          -f {kanji|kana} \
		          -r reference_file \
		      julius.hyp \
		      > julius.ali

  正解ファイル(*.ref)と仮説ファイル(*.hyp)に対して，DPを使って単語のア
ラインメントをとります．結果は標準出力に出力されます．

  オプション -u で単位(形態素or文字)を，オプション -f で表記(漢字かな
混じり or カタカナ)を指定します．
  また形態素単位でアラインメントを取る場合に，複合語処理を行なうかどう
かをオプション -c で指定します．

  正解ファイル(*.ref)はオプション -r で指定します．ファイルの書式は
仮説ファイル(*.hyp)と同じで，サンプルIDと正解文（形態素タグ付き）を
1行づつ交互に並べたものです．

  単語信頼度が仮説ファイルに含まれる場合，それはそのままアラインメント
  ファイルに出力されます．


○score.pl
===========

	    使用法：
		    % score.pl julius.ali

  アラインメントの結果を元に，認識率等を集計します．集計結果は
ディレクトリ“アラインメントファイル名.scr”の下に複数ファイルに分けて
出力されます．


 凡例：

    SPKR    話者ID
    Snt	    サンプル文数
    Corr    単語正解率(Word %Correct)
    Acc	    単語正解率(Word Accuracy)
    Sub	    置換誤り率
    Del	    削除誤り率
    Ins	    挿入誤り率
    Err	    誤り率（上記3つの計）
    S.Err   文誤り率


○result_cm.pl
===============

  アラインメント結果ファイルに単語信頼度が含まれている場合，そこから
しきい値ごとの False Acceptance, Slot Error, False Rejection などの評
価値を出力します．


								以上
