JLit トピックビューア 操作マニュアル

Step 8「トピックモデル（LDA / MALLET）」で作るトピックビューアの使い方。 画面の各欄の見出しにある ？ を押すと，このマニュアルの該当する節が開く。

1この道具で何をするか

MALLET で学習したトピックモデル（LDA）の結果を，読むための画面である。 トピックは「語の確率分布」なので，上位キーワードの一覧を眺めるだけでは，それが主題なのか， 1つの作品の登場人物名の束なのか，機能語の寄せ集めなのかが分からない。この画面では

• 上位キーワードを品詞・頻度帯で絞り，relevance λ で並べ替えて，トピックの中身を見分ける
• トピックごとに時代別の割合と，そのトピックを担う作品・作家を見る
• 選んだトピックと関連の強いトピックを，語分布の近さや共起から探す
• 学習の条件を変えた複数のモデルを切り替えて比べる

1枚の HTML で，サーバもネットワークも要らない。ブラウザで開くだけで使える。

2マニュアルを横に並べて使う

画面右上の 操作マニュアル ↗ と，各欄の ？ は， このマニュアルを別のウィンドウで開く。何度押しても同じウィンドウが使われ，該当する節まで送られる。

1. ビューアで 操作マニュアル ↗ を押す（別のウィンドウが開く）
2. macOS では，ウィンドウ左上の緑のボタンにポインタを載せ，出てくるメニューから 画面の左半分に並べる項目を選ぶ（macOS の版によって表記が違う）。もう一方のウィンドウを右半分に選ぶ
3. 大きなモニターや2台目のモニターがあれば，マニュアルのウィンドウをそちらへ移す

3作り方と開き方

ノートブックから（ふつうはこちら）

1. Step 8 で MALLET を実行し（本番と，語を選び直したもの）， 「トピックビューアを作る」のセルを実行する
2. macOS なら次のセルで既定のブラウザに開く。あるいは my_work/results/topic_viewer.html をブラウザで開く

このマニュアル（topic_viewer_manual.html）は，ビューアと同じフォルダに一緒に書き出される。 ビューアのファイルをほかの場所へ移すときは，マニュアルも一緒に移すこと。

ターミナルから

python3 scripts/19_topic_viewer.py \
    --model 名詞・動詞・形容詞=my_work/results/mallet_nva \
    --model 内容語すべて=my_work/results/mallet \
    --out my_work/results/topic_viewer.html

4画面の構成

5モデルを切り替える

見出しの モデル で，ビューアに入れたモデルを切り替える。 Step 8 のノートブックからは，「語を選び直したもの」と「本番（内容語すべて）」の2つが入る。 左の欄の下に，いま見ているモデルのトピック数・作品数・トークン数と，MALLET の出力ディレクトリが出る。

切り替えると，絞り込みの設定はそのままで，選んでいたトピックの詳細は閉じる （トピックの番号はモデルごとに別物なので，T05 と T05 は対応しない）。

6品詞で絞る

チェックを外した品詞の語を，カードと詳細の上位キーワードから隠す。語の色は品詞を表す。 右の数字は，そのモデルのトークンのうちその品詞が占める割合である。

7頻度帯で絞る

5つのつまみで，上位キーワードを頻度や散らばりの性質で絞る。つまみの右に今の値が出る。

頻度・割合・集中度・dp_in は 18_pos_select.py が書く語の表（lexicon）から来る。 語にポインタを載せると，UniDic の語彙素（外来語は原綴つき）と品詞が出る。

8並べ方（relevance λ）

上位キーワードの並べ方を relevance（Sievert & Shirley 2014）で決める。

relevance ＝ λ log p(w|t) ＋ (1−λ) log(p(w|t) / p(w))

• λ = 1：トピックの中での確率 p(w|t) の順。どのトピックにも出る高頻度語が上に来やすい
• λ を下げるほど，コーパス全体に比べてそのトピックに特有の語が上に来る。0.6 前後が目安
• λ を 0 近くまで下げると，ごくまれな語ばかりになる（全体の頻度のつまみと組み合わせる）

表示する語数（5〜50）で，カードに出す語の数を変える。

9語で探す

語を入れると，その語を上位（表示する語数以内）に持つトピックだけが濃く残り，ほかは薄くなる。 一致した語には色の帯が付く。見出しの行に，当たったトピックの数が出る。

語彙素（例：汽車）でも，外来語の片仮名だけ（例：テーブル）でも当たる。 絞り込みや λ で上位から外れた語は当たらない。

10トピックのカードと並べ替え

1枚のカードが1つのトピックである。

左の欄の 並べ替え で，トピック番号・割合の大きい順・ 絞り込み後に残る確率の大きい順（残存の順）に並べ替える。カードを押すと，下に詳細が出る。

11トピックの詳細

• 上位キーワード：λ の順に30語。棒の長さは p(w|t)。下に，MALLET が出した上位キーワード（絞り込み前）も出る
• 時代別の割合：時代区分ごとに，チャンクの中でこのトピックが占める割合の平均
• このトピックが多い作品：「作品内の割合」の大きい順に12作品
• このトピックを担う作家：「トピックに占める割合」の大きい順に8人

2つの割合を区別する

「A 高校の生徒の半分が野球部」と「野球部員の9割が A 高校」が両立するのと同じで， 向きが逆なので値は一致しない。どちらも語の絞り込みでは変わらない。

12関連の強いトピック

詳細のいちばん下に，選んだトピックと関連の強いトピックが並ぶ。 行を押すと，そのトピックに移る。各行の上位キーワードは，いまの絞り込みと λ で並べたもの。

上の4つは語分布の近さ（同じ語でできているか），相関は文書の中での共起 （同じチャンクに一緒に現れるか）を測る。語がほとんど重ならなくても， 同じ場面に続けて現れる2つのトピックは相関が高くなる。件数 で並べる数を変える。

13ネットワーク（トピック・作品）

画面上部の トピック一覧／トピックのネットワーク／作品のネットワーク／ 作品とトピックのネットワーク で表示を切り替える。ネットワークでは，近いものどうしをエッジ（辺）（エッジ）で結び， レイアウトで選んだ方法で配置する（既定は力学モデル。つながりの強いものが近くに集まる）。

画面を広く使う（ラップトップなど）

グラフの高さは，画面の残りの高さに合わせて自動で決まる（ウィンドウの大きさを変えると追従する）。 説明・凡例・操作の案内はグラフの上に重ねてあり，場所を取らない。

畳んだかどうかは覚えておかない。ビューアを開き直すと，いつもすべて広げた状態から始まる。 図の書き出し（SVG・PDF）には，畳んだかどうかにかかわらず凡例が付く。

操作

見やすくする

これらは配置を計算し直さずに変わる。色分けや指標を切り替えても，設定はそのまま残る。

エッジ（辺）の張り方

• 近い順に k 本：各ノードから，近い順に k 本（1〜5）のエッジを張る。k を増やすとつながりが密になる
• エッジを残す：近さの上位 N%：すべての組の近さを順位にし，上位 N% に入らないエッジを消す。 弱いつながりを消して，強いコミュニティだけを見るときに下げる。エッジの無いノードの数は説明の行に出る
• 線が太く濃いほど近い。太さは，その組の近さの順位（全組の中での位置）を，いま表示しているエッジの中で 細い〜太いに割り当てたもの。指標によって値の尺度が違うので，値そのものではなく順位にそろえてある。 線にポインタを載せると，2つのノードと指標の値，全組の中での位置が出る

レイアウト

操作欄の レイアウト で配置の方法を選ぶ。Fruchterman–Reingold は動きながら落ち着き， ほかは一度に計算して置く（ノードが千を超えると数秒かかる。計算にかかった時間が横に出る）。 乱数シードを固定してあるので，同じ条件なら同じ配置になる。

ForceAtlas2 と Yifan Hu は，つながっていない部分（連結成分）を別々に配置し，エッジの平均の長さをそろえてから大きい順に並べる。 Gephi の Scaling に当たる操作は，画面に合わせて自動で拡大縮小するため，下の Expansion／Contraction で代える。

補助の操作は，いまの配置に重ねて効く（レイアウトを選び直すか 配置し直す を押すと元に戻る）。

図を書き出す（SVG・PDF）

操作欄の 書き出し で，いま画面にある図をファイルにする。拡大縮小や移動の状態にかかわらず， ノードとラベルの全体が入るように切り出し，下に凡例を付ける。背景は白（画面が暗い配色でも白地の色にする）。 配置・色分け・線の色・文字の大きさ・不透過度・ノードを押したときの強調は，画面のとおりに写る。

条件を添える（再現のための注記）

条件を添える（初期値でオン）にしておくと，書き出した図の下縁（凡例の下）に，図を作った条件を小さな字で添える。 論文やスライドに図を載せたあとでも，同じ図を作り直せるようにするためである。

α と β は MALLET の topic-state.gz の先頭から読む（無ければ topic-keys.txt の α）。 反復回数・seed・ストップリストは MALLET の出力に残らないので，10_mallet.py train が学習のたびに train_params.json に書く。これより前に学習したモデルでは「記録なし」と出る（学習し直すと入る）。

欧文 で，書き出す図の英数字（ラベル・凡例・注記の中の数字，英字，欧文の記号）の書体を選ぶ。 初期値は Gill Sans（無ければ Gill Sans MT・Gill Sans Nova）で，和文はいつも和文の書体で書く。 「和文と同じ書体」にすると，英数字も和文の書体で書く。画面の表示は変わらない。

英数字の部分は，文字列を和文と欧文の連なりに分け，欧文の連なりだけに書体を指定している（SVG の <tspan>）。 書体を並べて指定するだけでは，最初の書体しか見ないソフト（Illustrator など）で和文が化けるためである。

トピックのネットワーク

指標は 12 関連の強いトピック の5つから選ぶ。円の大きさはトピックの割合。 色は「いちばん割合の高い時代区分」か「コミュニティ」。

作品のネットワーク

Delta は Step 4 の出力を --delta で渡すと入る（ノートブックは descriptive/freq_matrix_mfw.csv があれば自動で渡す）。 zスコアは，ビューアに入る作品の集合（Step 4 で数えた作品すべて）の平均と標準偏差（ddof=0）で作る。作品の集合を変えれば値も変わる。

色は時代区分・作家・ジャンル・文体・コミュニティから選ぶ。作家は作品の多い順に8人まで色を付け， 残りは灰色（凡例の「その他」にポインタを載せると名前が出る）。円の大きさは作品のチャンク数。 作品を押すと，近い作品の一覧に加えて，その作品で割合の高いトピックが出る（押すとトピックの詳細へ）。

作品とトピックのネットワーク

作品（丸）とトピック（濃い灰色の四角）を1枚に描き，作品のトピック構成（その作品のチャンクの θ の平均）で結ぶ。 どの作品がどのトピックでできているか，どのトピックがどの作品群に担われているか，複数のトピックにまたがる作品はどれかが見える。

線の太さは作品内の割合。四角の大きさはトピックの割合，丸の大きさは作品のチャンク数。トピックの四角は初めは作品に対して 60% の大きさで描く（大きさ：トピック で変えられる）。 トピックを押すと，そのトピックの割合が高い作品の一覧が出る。作品を押すと，その作品で割合の高いトピック（ラベルつき）の一覧が出る。 一覧の行を押すとその作品・トピックに移り，トピックをダブルクリックすると詳細へ移る。

コミュニティ

いま張られているエッジ（辺）から，互いに密につながるコミュニティを Louvain 法（Blondel et al. 2008）で求めて色分けする。 番号は大きいコミュニティから順に振る。

14ラベルづけ

トピックに名前を付けるのは，LDA でいちばん難しい作業の1つである（Lau et al. 2011）。 上位キーワードだけでは，それが主題なのか，1つの作品の登場人物名の束なのか，文体の偏りなのかが分からない。 上部の ラベルづけ のタブで，次の2通りのラベルを扱う。

ラベルはカードの見出し・詳細の上・トピックのネットワークのノードに出る。 ラベルには作家名・作品名を入れない。どの作品や作家に偏っているかは，ネットワークの図と詳細を見れば分かる。 名前を入れると，ネットワークの図のラベルが長くなって読みにくくなる。作品指標・作家指標であることは種類（作品指標・作家指標）で示し， 作家名・作品名は根拠に書く。取り込んだラベルに作家名・作品名が入っていると，一覧に ⚠ が出るので手で直す。 ラベルは短いほどよい（図にそのまま載る）。プロンプトでは2〜8字を目安に10字以内を求めており，10字を超えると一覧に ⚠ が出る。

手順

1. 対象（すべて／ラベルの無いものだけ）と 1回に含めるトピック（5・10・20・すべて）を選ぶ。 無料プランでは長いプロンプトが途中で切れることがあるので，10 前後がよい。← 前・次 → で残りの回に進む
2. プロンプトをコピー を押し，生成 AI の入力欄に貼り付けて送る。 Claude・ChatGPT・Gemini・Copilot などの無料プランでよい（アカウントの登録は要る。API キーは要らない）
3. 返ってきた回答の JSON を「2.」の欄に貼り付け，使った AI を選んで 取り込む を押す。 説明文や ```json の囲みが付いていても，JSON の部分を探して読む
4. 「3.」の一覧で結果を確かめる。ラベル・種類・信頼度は手で直せる（直すと出典に「手で修正」と残る）
5. ラベルを書き出す で topic_labels.json を保存し，ビューアと同じフォルダ（my_work/results/）に置く。 次にビューアを作るとき自動で読み込まれる

診断資料（プロンプト）の中身

• 上位キーワード（トピック内の確率の順）と特有の語（λ=0.6 の順）を15語ずつ。品詞つき
• このトピックの割合が高い作品と，このトピックを担う作品（作家・初出年・時代区分・ジャンル・文体・2つの割合）
• 担う作家・時代区分ごとの割合・偏りの警告・語分布の近いトピック

プロンプトには，主題か指標か文体の偏りかを診断してから名前を付けること，根拠は資料の語と作品から挙げること （一般に知られた知識を使ったときはそう明記すること），ラベルに作家名・作品名を入れず内容で表すこと，回答の形（JSON）が書いてある。 本文そのものは送らない（上位キーワードと書誌だけ）。

15トピック表を書き出す

タブの トピック表 で，トピックと上位キーワードの表（主表）と，トピック診断表を書き出す。 論文に載せることを考えて，キャプションにコーパス名・テクストチャンク数・作品数・トークン数・語彙数・K・α・β・反復回数・optimize-interval・random-seed・上位キーワードの選び方を入れる。 論文の誌面では，主表を本文に，診断表を付録に置くとよい。

主表（トピックと上位キーワード）

トピック診断表

トピックごとに，ラベル・α・平均割合・トークン数（そのトピックに割り当てられたトークンの数）・coherence・exclusivity （MALLET の diagnostics.xml から。Mimno et al. 2011）・最多区分（平均割合が最も高い時代区分）・ラベルの種類・信頼度を並べる。 diagnostics.xml が無いモデルでは coherence と exclusivity の列を出さない。

書き出しの形式

どの形式にも，ビューアの名前・モデルの指紋・書き出した日時をコメントとして入れる（どのモデルから作った表かを後で確かめるため）。 下の表示 で選んだ形式が下の欄に出るので，コピー して論文のファイルに貼ってもよい。

16語を隠すことと，除いて学習し直すこと

ビューアで語を隠すことと，その語を除いて学習し直すことは違う。 隠した語もトピックの形成には寄与している。固有名詞が作ったトピックは， 固有名詞を隠しても「その作品のトピック」のままである。カードの「残存」が低いのはそのためである。

本当に除くには，18_pos_select.py で語を選び直して学習し直し， 両方のモデルをビューアに入れて 切り替えて 比べる。

17困ったとき

JLit_Corpus_2026 — トピックビューア操作マニュアル。 ビューアは scripts/19_topic_viewer.py が作り，このマニュアルは scripts/topic_viewer_manual.html から ビューアと同じフォルダに書き出される。用語の説明は docs/glossary.md の Step 8 にある。
JLit トピックビューア　© Tomoji Tabata (DH UOsaka)