スコアリングの計算方法・アルゴリズム・パラメータ解説

1. 全体像

RCS は単一の入力テキスト（例: Subthalamic nucleus、Left basolateral amygdala (BLA)、LC）を HOMBA オントロジーのエントリと照合し、適合度スコア付きで候補リストを返します。

スコアは 0〜1 の浮動小数点数です。出力時は min(score, 1.0) を 小数第 6 位で四捨五入します。

2. 具体例（詳細 walkthrough）

alias 展開 · abbrev 展開 · laterality 除去 · 修飾語が同時に働く複合例は、 クエリバリアント全件・バリアント別 fuzzy ヒット・候補リストなどの詳細データを 別ページに分離しています。

修飾語の加点・減点だけを短く追う例は §16 例 D、前処理の一般説明は §3 を参照してください。

3. 前処理とクエリバリアント

3-1. テキスト正規化（normalize_text）

1. Unicode NFKC 正規化
2. & → and、/ → スペース
3. アポストロフィ（' ` ´）を除去
4. ハイフン・アンダースコアをスペースに変換
5. 英数字以外を除去、連続スペースを 1 つに縮小
6. 小文字化

例: Broca's area → broca s area（所有格のアポストロフィは削除）

3-2. クエリバリアント（query_variants）

1 つの入力から複数の検索用文字列を生成し、表記ゆれに対応します。生成は次の順序で行われ、最後に unique_preserve_order() で正規化キーの重複を除去します。

1. ベース 4 形（入力 · laterality 除去 · 括弧除去 · excluding 除去）
2. 各ベース形に homba_alias_rules.csv を適用（単語置換・同義語追加）
3. 各形に homba_abbrev_rules.csv を適用（略語展開 · クエリ側のみ）
4. 正規化キーで重複除去 → 最終バリアントリスト

各段階のすべての中間文字列（重複含む）の実例は BLA walkthrough §2-2 を参照してください。

• 正規化テキスト本体
• laterality 語（left / right / bilateral 等）を除去した形
• 括弧部分を除去した形（括弧内は modifier_terms として別途保持）
• excluding / except / without 以降を除去した形
• homba_alias_rules.csv による同義語展開（クエリ側）
• homba_abbrev_rules.csv による略語展開（クエリ側のみ。例: lc → locus coeruleus）

3-3. 修飾語抽出（extract_modifier_terms）

括弧内トークンと、homba_token_rules.csv で kind=modifier と定義された語を収集します。 これらは後述の修飾語一致率の計算に使われます。

3-4. トークン化（tokenize）

正規化後に空白分割し、kind=stopword の語を除去します（of、the、region 等）。 トークン Jaccard や BM25、fuzzy のインデックス絞り込みに使用します。

4. 三つの検索手法

同一 HOMBA エントリが複数手法でヒットした場合、エントリは 1 つに統合され、 各手法のスコアは 最大値 が保持されます（_add_candidate）。

generate() のデフォルト引数: top_k=10（返却件数）、per_method_k=40（各手法の上位候補数上限）。

5. 倒排インデックスと候補絞り込み

全別名（約 9,000 件）に毎回フルスキャンしないため、起動時に以下のインデックスを構築します。

Fuzzy: INTERSECTION（v0.3.1 以降）

1. クエリバリアントをトークン化
2. トークンが 3 個以上のとき、df が低い（レアな）2 トークン（rarest_limit=2）を選択
3. 選ばれたトークンの posting list の 積集合（INTERSECTION） だけを fuzzy 比較対象にする
4. 積集合が空 かつ 正規化バリアント長 > 5 のときのみ全別名スキャンにフォールバック

例: Subthalamic nucleus では subthalamic（df≈3）と nucleus（df≈1,400）の積集合 ≈ 3 件のみ比較。 旧 UNION 方式だと ≈ 1,400 件になっていた。

BM25: UNION

1. クエリバリアントの 全トークン の posting list を取得
2. posting list の 和集合（UNION） を BM25 比較対象（recall 重視）

6. Fuzzy スコア（string_similarity）

正規化後の 2 文字列を比較します。完全一致なら 1.0。

similarity = max(
  containment_bonus,
  0.35 × SequenceMatcher.ratio
+ 0.25 × bigram Dice
+ 0.20 × trigram Dice
+ 0.20 × token Jaccard
)

各成分の定義

7. BM25 スコア

エントリ内の複数別名それぞれに BM25 を計算し、最も高い別名のスコアをそのエントリの bm25 スコアとします。

パラメータ

IDF(t) = log(1 + (N - df(t) + 0.5) / (df(t) + 0.5))

BM25_raw = Σ_t  IDF(t) × (freq × (k1+1)) / (freq + k1 × (1 - b + b × doc_len / avg_len)) × query_count(t)

BM25_norm = BM25_raw / (BM25_raw + 4.0)

• N = 全別名エントリ数（alias_entries の件数）
• df(t) = トークン t を含む別名数
• avg_len = 別名の平均トークン長（起動時に計算）
• freq = 当該別名内のトークン出現回数
• query_count(t) = クエリ内のトークン出現回数

8. 最終スコアの合成（_score_candidate）

各候補について、クエリ全体と HOMBA 全別名の token Jaccard 最大値を token_score とします。

Step A — ベーススコア（base）

base = max(
  hierarchy_parent_score,   // 未設定なら 0
  exact_score,              // 未設定なら 0
  0.5 × fuzzy + 0.3 × bm25 + 0.2 × token_score,
  0.75 × fuzzy + 0.25 × token_score
)

• 4 項のうち 最大値 を採用（未ヒットの手法は 0 として扱う）
• exact が存在する場合: base = max(base, 0.96) — 完全一致候補の下限を引き上げ

Step B — 修飾語調整

Step C — 過細減点の順で適用します（次セクション参照）。

9. 修飾語（modifier）調整

modifier_match_score = 抽出した修飾語のうち、候補別名テキスト（正規化・連結）に 含まれる割合（0〜1）。修飾語がない場合は 1.0（調整なし）。

10. Specificity Penalty（過細候補の減点）

クエリに存在しない細分類語（inferior、lateral、core、shell、 molecular 等）が候補側の別名に含まれる場合、スコアを減点します。

適用条件（すべて満たすときのみ）

1. exact マッチがない
2. fuzzy または bm25 マッチがある
3. クエリに修飾語（modifier_terms）がない
4. 候補に親 ID（parent_id）がある

減点率

候補別名の specificity 語 \ クエリの specificity 語 が空でない
  → final_score × 0.86
それ以外
  → final_score × 1.0（減点なし）

specificity 語は homba_token_rules.csv の kind=modifier または kind=weak に該当するトークンです。

11. 階層親昇格（hierarchy_parent）

複数の子領域（兄弟）が同時に候補になったとき、共通の親エントリを追加します。 例: thalamus の複数サブリージョンが候補 → pulvinar of thalamus の親を昇格。

昇格条件

• クエリに修飾語がない
• 同一 parent_id を持つ子候補が 2 件以上
• 親エントリの別名とクエリトークンに token Jaccard 一致がある（> 0）

昇格スコア

hierarchy_parent_score = min(max(子候補の prelim_scores) + 0.08, 0.97)

prelim_scores は第 1 パスで算出した過細減点込みの暫定スコアです。 生の fuzzy スコア（例: 0.89）だけで親を昇格させると、ペナルティ後 0.77 の子を 0.97 の親が上回る「過昇格」が起きるため、暫定スコアを参照します。

12. 2-pass スコアリング（v0.3 以降）

親昇格スコアと子の final score の間に循環依存があるため、2 段階で処理します。

1. exact / fuzzy / bm25 で候補収集（手法別最大スコアを保持）
2. 第1パス: 全候補に _score_candidate() → prelim_scores（specificity_penalty 込み）
3. prelim_scores で _promote_common_parents() → hierarchy_parent 候補を追加
4. 第2パス: 昇格後の全候補を再度 _score_candidate() で最終スコア化
5. ソート → top_k 件を返却

13. ソートと出力

ソートキー（優先順）

1. score 降順
2. name 昇順（小文字化して比較）
3. homba_id 昇順

出力フィールド（主要）

14. レビューフラグ（rcs/review.py）

generate() の出力自体には含まれませんが、テスト・API 層では add_review_flags() により以下のフラグが付与されます。

15. パラメータ一覧（クイックリファレンス）

16. 計算例（概念的ウォークスルー）