# -*- perl -*-
# $Id: sample-logic.pl,v 3.0 1998/11/19 07:12:10 tsuchiya Exp $

# This file is part of IREX tools.

# Please refer "Copyright file" at the root directory.
# (C) IREX committee IREX実行委員会. All rights reserved.  


#------------------------------------------------------------
#	What's this file ?
#------------------------------------------------------------

# IREX 結果統合ファイルから TREC 正解ファイルを生成する場合、複数の判定
# 者の判定結果から正解/不正解の2値を求めなければならない。
#
# irex-seikai-trec.perl には、そのための判定関数が幾つか既に書き込まれて
# いるが、コマンドラインオプションを用いてユーザーの作成した判定関数を用
# いるようにすることも出来る。
#
# 本ファイルは、判定関数と定義ファイルの形式について説明している。



#------------------------------------------------------------
# 	判定関数の条件
#------------------------------------------------------------
#
# 判定関数の引数は次の通り。
#
#     第1引数 = TOPIC-ID
#     第2引数 = Document Number
#     第3引数 = 各判定者のPIDをキー,判定結果を値とする連想配列
#
# 判定関数は、第1引数で指定された検索課題について、第2引数で指定された記
# 事を正解とするか否かを、第3引数として与えられる人手による判定結果に基
# づいて決定するための関数である。
#
# 本体のプログラムとの干渉を避けるために、関数内で使用する変数は全て、my
# または local を用いたローカル変数にしなければならない。また、判定関数
# の先頭では次のように引数をローカル変数にコピーする必要がある。
#
#     sub sample {
#         my( $topic_id,$docno,%judge )=@_;
#
# この場合、実際の値の例は次のようになる。
#
#      $topic_id = 1003
#      $docno    = 9410021234
#      %judge    = { {"1001","A?"}, {"1002","B"}, {"3001","A"}, {"9001","A"} }
#
# 判定関数は 1/0 の2値を返すように設計する。ただし、1が正解を表し、0が不
# 正解を表す。
#
# 正解とも不正解とも判断できないような場合は、1と0以外の値を返すようにす
# る。そのようなデータが発見されるとその時点で実行を中断するので、その関
# 数定義を見直すか、IREX 結果統合ファイルの内容を見直すか、どちらかの処
# 置が必要である。
    


# 最も PID の大きな判定者の判定結果と正解/不正解の2値を任意に結びつける関数
sub sample {
    # 引数をローカル変数にコピーする
    my( $topic_id, $docno, %judge )=@_;

    # 最も PID の大きな判定者を求める
    #     keys %judge は、%judge のキーのリストを返す。つまり、この記事を判定し
    #     ている全ての判定者の PID のリストである。そのリストを sort によって
    #     降順に並べかえたリストの最初の要素を取り出すと、最も大きな PID が得
    #     られる。
    my $pid = ( sort { $b <=> $a; } keys %judge )[$[];

    # 判定結果と返り値の関係を表現している連想配列
    my( %map )=( "A",  1,
		 "A?", 2,
		 "B",  1,
		 "B?", 2,
		 "C",  0,
		 "C?", 2 );

    # 従って、この関数は、最も PID の大きな判定者の判定結果が
    #     A または B の場合 -> 正解
    #     C の場合          -> 不正解
    #     A?, B?, C? の場合 -> 判断不能
    # という結果を返す関数となっている。
    $map{$judge{$pid}};
}



# 全ての Executive Judge の判定が A である場合に限って正解とする関数
sub sample_2 {
    # 引数をローカル変数にコピーする
    my( $topic_id, $docno, %judge )=@_;

    # 判定に参加している Executive Judge の PID を取り出す
    #     keys %judge は、%judge のキーのリストを返す。つまり、この記事を判定し
    #     ている全ての判定者の PID のリストである。そのリストから、PID の先頭の
    #     文字が 2 の要素のみを取り出すと、Executive Judge の PID のリストが作
    #     られる。
    my( @pid )= grep( /^2/,keys %judge );

    # @pid は Exective Judge の PID のリストになっている
    if( @pid != 0 ){
	# この記事を判定した Exectuvie Judge が一人以上いる場合
	for $pid ( @pid ){
	    # $pid には、@pid の1つの要素が代入されている状態でこのループの中に
	    # 入ってくる。よって、$judge{$pid} は、PID が $pid と等しい判定者の
	    # 判定結果である。従って、誰か一人でも A 以外の判定をした Executive
	    # Judge がいた場合は、即座に 0 を返し、不正解とする。
	    return 0 if $judge{$pid} ne "A";
	}
	# 全員が A と判定した場合に限って、for ループを終了して、ここに達する。
	# その場合は 1 を返して、正解とする。
        1;
    } else {
	# この記事を判定した Executive Judge が存在しない場合、判定できないので
	# 2 を返す。
        2;
    }
}



# ある特定の判定者の判定結果のみを利用して正解/不正解を決定する関数
sub sample_3 {
    # 引数をローカル変数にコピーする
    my( $topic_id, $docno, %judge )=@_;

    # 特定の判定者の PID
    my $pid = "1234";

    if( $judge{$pid} eq "A" ){
	# 特定の判定者の判定結果が A ならば 1 を返す -> 正解とする
	1;
    } elsif(( $judge{$pid} eq "B" )||( $judge{$pid} eq "C" )){
	# 特定の判定者の判定結果が B または C ならば 0 を返す -> 不正解とする
	0;
    } else {
	# それ以外の場合 2 を返す -> 判定不能
	2;
    }
}




#------------------------------------------------------------
#	判定関数の設定
#------------------------------------------------------------
#
# 利用したい判定関数の名前を irex-seikai-trec に対して通知するため、
# 判定関数へのリファレンス(ポインタ)を変数 $FUNC に代入する。
# irex-seikai-trec 本体は、記事毎に $FUNC によって指定された関数を
# 呼び出す。

$FUNC = \&sample;
# $FUNC = \&sample_2;
# $FUNC = \&sample_3;


# この 1; はファイルの最後に必ず必要である。
1;