wam - WAM library module for perl
use wam;
このモジュール (以下，WAM モジュール) は汎用連想計算エンジン GETA が提 供する C 言語ライブラリを Perl 言語から使うためのものである。
WAM モジュールでは以下の関数が提供されている。
WAM モジュールを初期化する。 $projectroot には GETA 環境がインストールされているディレクトリの絶 対パス名を指定する。 $projectroot に空文字列を指定した場合は，環境変数 GETAROOT の値が使 用される。 初期化に成功した場合は 0，失敗した場合は -1 を返す。
ハンドルが $handle である WAM をオープンし，その識別子 (正の整数) を返す。 オープン後，ユーザはこの識別子を用いて WAM にアクセスすることができる。 オープンに失敗した場合は 0 を返す。 ハンドルの代わりにショートネームを使ってもよい。
識別子 $d に関連付けられた WAM をクローズする。
識別子 $d に関連付けられた WAM (厳密には列 CW) の修正時間を
1970年 1月 1日 00:00:00(GMT) からの経過秒数として返す。
CW は WAM の構成要素の一つで，行や列を表す ID とその綴りである name と の対応表であり，行 CW と列 CW から成る。 CW の詳細については cw(3) を参照のこと。
識別子 $d に関連付けられた CW のうち，$mode で指定された側 (行ま たは列) の要素数を返す。
$mode に &wam::WAM_ROW を指定すると WAM の行数を，&wam::WAM_COL を 指定すると WAM の列数を知ることができる。
識別子 $d に関連付けられた WAM (厳密には CW) のうち，$mode で指 定された側の対応表 (行 CW または列 CW) を引き，与えられた ID $id に 対応する name を返す。 対応する name がない場合は空文字列を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には CW) のうち，$mode で指 定された側の対応表 (行 CW または列 CW) を引き，与えられた name $name に対応する ID を返す。 対応する ID がない場合は 0 を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
wam::id2name の配列対応版。 ID の配列へのリファレンス $idl をうけとり，それぞれの ID に対応する name を要素としてもつ配列へのリファレンスを返す。 対応する name がない ID に対しては空文字列が割り当てられる。
$d と $mode は wam::id2name と同じ意味である。
wam::name2id の配列対応版。 name の配列へのリファレンス $namel をうけとり，それぞれの name に対 応する ID を要素としてもつ配列へのリファレンスを返す。 対応する ID がない name に対しては 0 が割り当てられる。
$d と $mode は wam::name2id と同じ意味である。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) の要素数を返す。
$mode に &wam::WAM_ROW を指定すると WAM の行数を，&wam::WAM_COL を 指定すると WAM の列数を知ることができる。
XR は WAM の構成要素の一つで，WAM を行方向に圧縮した行 XR と，列方向に 圧縮した列 XR から成る。 XR の詳細については xr(3) を参照のこと。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) の $id 行 (列) ベクタの要素の値の総和を返す。 存在しない ID を与えた場合は -1 を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) のすべての行 (列) ベクタの要素の値の総和を返す。 すなわち，識別子 $d に関連付けられた WAM (厳密には XR) に含まれる要 素の値の総和を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) の $id 行 (列) ベクタ中の 0 でない要素数を 返す。 存在しない ID を与えた場合は -1 を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) の 行 (列) ベクタ中の 0 でない要素数の最大値を 返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) のすべての行 (列) ベクタ中の 0 でない要素数の 総和を返す。 すなわち，識別子 $D に関連付けられた WAM (厳密には XR) に含まれる 0 でない要素数を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
識別子 $d に関連付けられた WAM (厳密には XR) のうち，$mode で指 定された側 (行または列) の $id 行 (列) ベクタ を返す。
戻り値は，id, freq, name の 3 つのキーをもつ連想配列へのリファレンスの 配列へのリファレンスである。 存在しない ID を与えた場合は空文字列を返す。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
与えられた文字列 $text を，パス名が $path である形態素解析器で単 語分割する。 その結果を name であるとして，識別子 $d に関連付けられた WAM (厳密 には CW) のうち，$mode で指定された側の対応表 (行 CW または列 CW) を引き，その name に対応する ID を割り当てる。 対応する ID がない単語は無視される。
戻り値は，name, id, TF, TD_d, weight の 5 つのキーをもつ連想配列へのリ ファレンスの配列へのリファレンスである。 対応する ID をもつ単語がひとつもない場合は，長さ 0 の配列へのリファレ ンスが返される。
TF には，その ID の全体での TF (term frequency) がセットされる。 TF_d には，その ID の検索要求 $text 中での TF がセットされる。 weight には，0.0 がセットされる。
$mode には， &wam::WAM_ROW (行) または &wam::WAM_COL (列) を指定す る。
連想検索を行なう。 検索要求 $r 中の ID (行 ID または列 ID) に対応するベクタに現れる ID (列 ID または行 ID) を最大 $max 個集め，その結果を id, TF, TF_d, DF, DF_d, weight, name の 7 つのキーをもつ連想配列へのリファレンスの配 列へのリファレンスとして返す。 id，TF，TF_d，DF，DF_d，weight は syminfo 型の同名のメンバに対応してい る。 詳しくは wsh(3) を参照のこと。
結果は，類似度 $weight_type を用いて計算された weight の値の高い順 に配列に格納される。 使用可能な類似度のリストは wam::get_weight_types で得ることができる。
検索要求 $r が行 ID の場合は $mode に &wam::WAM_ROW (行) を指定 し，列 ID の場合は &wam::WAM_COL (列) を指定する。
識別子 $d1 には検索要求 $r が含まれる WAM を示す識別子を指定する。 識別子 $d2 には検索対象となる WAM を示す識別子を指定する。 同一文書内で連想検索を行なう場合は $d1 == $d2，異文書間で行なう 場合は $d1 != $d2 である。
$limit に正の整数を指定すると，検索要求 $r 中の ID のうち，識別 子 $d2 に関連付けられた WAM における TF 値が $limit 以上の ID を連想計算に使用しない。 0 を指定すると検索要求中のすべての ID を連想計算に使用する。 この値を適切に設定することで検索結果が膨大な数になるのを防ぐことができ る。
検索要求 $r が単語リストの場合は結果として文書リストが得られ，文書 リストの場合は単語リストが得られる。
検索要求 $r は name, id, TF, TD_d, weight, attr の 6 つのキーをもつ 連想配列へのリファレンスの配列へのリファレンスである。
name キーは特に指定する必要はなく，指定しても無視される。 id キーを省略した場合は，0 を指定したものとして解釈される。 TF キー，TF_d キー，weight キーを省略した場合は，それぞれ，0, 0, 0.0 を指定したものとして解釈され，こららの値を使用する類似度を使用している 場合は所望の結果を得ることができない。
attr には WSH_OR，WSH_AND，WSH_NOT を指定することができ，それぞれ，ブー リアン検索における OR, AND, NOT と同じ意味で用いる。 attr に WSH_AND がセットされている ID は必須要素となり，それらの ID の うち一つでも欠くものは集められない。 attr に WSH_NOT がセットされている ID は除外要素となり，それらの ID を 一つでも含むものは集められない。 attr キーを省略した場合は WSH_OR を指定したものとして解釈される。
wam::wsh の AND 検索版。 各引数は wam::wsh と同じ意味である。 検索要求 $r に含まれるすべての ID が含まれる検索結果を $max 個返 す。 WAM 中をすべて検索するのではなく，検索結果が $max に達した時点で検 索をやめ，その結果を返す。
類似した検索方法に wam::wsh において，類似度に &wam::WT_AND を指定 した場合と，wam::wsh において，検索要求中のすべての ID に対して，そ の attr キーに WSH_AND を指定した場合があるが，それぞれ以下の点で異な る。
前者では，WAM 中をすべて検索し，その結果を類似度 &wam::WT_AND を用いて ソートした結果を返す。 後者では，WAM 中をすべて検索し，その結果を指定された類似度を用いてソー トした結果を返す。
補助ファイル $file (タイトルファイルなど) をアクセスし，与えられた ID $id に対応する値を返す。 失敗した場合は空文字列を返す。
libae で定義されている類似度の名前の一覧を返す。 $GETAROOT/include/geta/weight_types.h に定義されている文字列の配列 weight_types の要素を perl の配列に順にセットし，その配列へのリファレ ンスを戻り値として返す。
ハンドルが $handle である WAM の属性 $attr の値を返す。 失敗した場合は空文字列を返す。 ハンドルの代わりにショートネームを使ってもよい。
wam::wsh または wam::wsa で連想検索された ID の総数を返す。
以下，技術的な詳細について補足説明しておく。
Perl では C 言語のような構造体を扱うことができない。 そのため，WAM モジュールでは連想配列とリファレンスを組み合わせて構造体 に相当するデータ構造を表現している。
libwam で用いられている xr_vec 型に対応するデータ構造は WAM モジュール にはない。
libwam で用いられている xr_elem 型は id, freq, name の 3 つのキーをも つ連想配列として表現される。 id と freq は xr_elem 構造体の同名メンバに対応する。 name には，その連想配列の id に対応する name が 割り当てられる。
libae で用いられている syminfo 型に対応するデータ構造は id, TF, TF_d, DF, DF_d, weight, name の 7 つのキーをもつ連想配列である。 id，TF，TF_d，DF，DF_d，weight は syminfo 型の同名のメンバに対応する。 name には，その連想配列の id に対応する name が 割り当てられる。
WAMモジュールが提供する関数と C 言語ライブラリが提供する関数の対応関係 は以下のとおりである。
WAMモジュール C 言語ライブラリ wam::init wam_init wam::open wam_open wam::close wam_close wam::ctime cw_mtime wam::cw_size wam_cw_size wam::id2name wam_id2name wam::name2id wam_name2id wam::idl2namel --- wam::namel2idl --- wam::size wam_size wam::freq_sum wam_freq_sum wam::total_freq_sum wam_total_freq_sum wam::elem_num wam_elem_num wam::max_elem_num wam_max_elem_num wam::total_elem_num wam_total_elem_num wam::get_vec wam_get_vec wam::wstem wstem wam::wsh wsh wam::wsa wsa wam::getaux getaux wam::get_weight_types --- wam::ci_value ci_value wam::get_last_nd ---
以下，対応する関数間で仕様が異なるものに関して補足説明をする。
wam_open は WAM * 型のポインタを返すのに対し，wam::openは小さい 正の整数を返す。
wam_get_vec では xr_vec 型の構造体を用いて行 (列) ベクタを表現して いるのに対し，wam::get_vec では ID で示される行 (列) ベクタのベ クタ部分だけ (xr_vec 型の構造体のメンバである xr_elem 型の要素に相当) を id, freq, name の 3 つのキーをもつ連想配列として表現している。 詳しくは xr_get_vec(3) を参照のこと。
wstem は syminfo 型へのポインタを返すのに対し，wam::wstem は name, id, TF, TD_d, weight の 5 つのキーをもつ連想配列へのリファレンス の配列へのリファレンスを返す。
wstem は結果の配列の要素数も返すが，wam::wstem は返さない。
wsh では，検索要求と検索結果のいずれも syminfo 型へのポインタである のに対し，wam::wsh では，検索要求が name, id, TF, TD_d, weight, attr の 6 つのキーをもつ連想配列へのリファレンスの配列へのリファレンス， 検索結果が id, TF, TF_d, DF, DF_d, weight, name の 7 つのキーをもつ連 想配列へのリファレンスの配列へのリファレンスとなっている。
wshでは検索要求の長さを渡す必要があるが，wam::wsh ではその必要が ない。
wshは検索結果の配列の要素数も返すが，wam::wsh は返さない。
wshでは，cookie を指定することができるが，wam::wsh ではできない (内部的には NULL で固定)。
getaux はデータの格納領域へのポインタを返すのに対し，wam::getaux は，そのポインタが指す文字列を SV に変換したものを返す。
WAM モジュールを利用するためには Perl version 5.005_03 以降が必要であ る。
wam(3), xr(3), cw(3)
今一 修 <imaichi@harl.hitachi.co.jp> 西岡 真吾 <nis@harl.hitachi.co.jp>