系統樹

系統樹について

系統樹（フィログラムまたはクラドグラムとも呼ばれる）は、種・遺伝子・配列のグループの推定された進化史を示します。内部ノードは仮想的な共通祖先を表し、先端（チップ）は観察された分類群を表します。枝の長さは進化的距離または分岐時間をエンコードします。進化生物学者・分子生態学者・臨床微生物学者が、生命の歴史の再構築、病原体のアウトブレーク追跡、遺伝子ファミリーの進化の理解に系統樹を使用します。

Schematex は**Newick フォーマットを受け付けます — PAUP*、IQ-TREE、RAxML、BEAST、およびほぼすべての系統解析プログラムが使用する普遍的な交換標準であり、ブートストラップ値とクレードメタデータのためのNHX アノテーション**で拡張されています。手書きのツリーのためのインデントベースの DSL もサポートされています。このページでは、現在パーサーが受け付ける構文を説明します。

1. はじめての系統樹

最小限の実用的なツリー：4つの分類群、2つのクレード。

以下の3つのルールで利用の80%をカバーできます。

1. phylo で始め、オプションで引用符付きタイトルとブラケットの props を続けます。
2. newick: フォーマットでツリートポロジーを提供します — 標準 Newick 文字列を引用符で囲み、1行に記述します。末尾の ; はオプションです。
3. オプションで、newick 行の下にクレードハイライトグループとスケールラベルを定義します。

コメントは単独行で # で始める必要があります。末尾インラインコメントはサポートされていません。

2. 入力フォーマット

2.1 Newick フォーマット

Newick が主要な入力です。完全な文法は以下の通りです。

(A,B,(C,D));                         # topology only
(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);    # with branch lengths
((A:0.1,B:0.2):0.05[&&NHX:B=98],(C,D):0.08);  # NHX bootstrap
('Homo sapiens':0.1,'Mus musculus':0.2);        # quoted names with spaces

枝の長さはコロンの後のノード名に続きます。内部ノードのサポート値はプレーンブラケット [95] または NHX [&&NHX:B=95] として表示できます。

パーサーが受け付ける Newick のルール：

2.2 インデント DSL

手書きまたは小さなツリーには、生の Newick より読みやすく編集しやすいインデントベースの代替手段を提供します。

インデント DSL のルール：

スペースなしで : で終わる最初の行がインデントツリーモードをトリガーします（例：root:）。コロンの前の名前がルートラベルになり、その下のすべてのインデント行が子になります。

3. レイアウト

ヘッダーブラケットでレイアウトを設定します：phylo "Title" [layout: rectangular]。

[unrooted] を単独フラグとして使うと [layout: unrooted] と同等です。

円形 — ルートが中心、先端が外側に広がります。クレードハイライトを持つ多分類群ツリーで最も視覚的に印象的です。

矩形 — L字形の枝。ルートが左、先端が右。発表用図のための古典的なフィログラム形式です。

斜め — 親から子への斜線。矩形よりコンパクトで、同じ左から右への読み方向です。

無根 — 等角放射状レイアウト。ルートを重視せず、すべての分類群間のペアワイズ距離を強調します。

4. モード

ヘッダーで [mode: …] を使って設定します（または本文の任意の場所に style [mode: …] 行を置きます）。

クロノグラムには、時間単位の枝の長さと、ヘッダーに [mrsd: "YYYY"]（最新サンプリング日）が必要です。レンダラーが先端を現在に整列させるために使用します。

phylo "SARS-CoV-2 variants" [mode: chronogram, mrsd: "2023"]
  newick: "((Alpha:0.5,Delta:0.4):0.3,Omicron:0.8);"
  scale "years"

デンドログラム — 階層的凝集クラスタリングの標準的な出力であり、進化ではありません。各内部ノードはその融合高さ（2つの子クラスターが融合するコフェネティック距離）に配置され、すべての葉が共通のベースラインに整列し、枝は矩形のエルボーコネクターです。高さ軸が描画されるため、任意の2つの葉が最初にクラスターを共有する距離を読み取れます。同じ Newick/インデントツリーが系統ではなくクラスタリング結果を説明する場合に使用してください。たとえば、遺伝子発現クラスター、サンプル類似度、調査回答グループなどです。

cut <value> 行を追加すると、選択した高さでツリーを切断します。融合高さがしきい値を下回るすべてのサブツリーが1つのフラットクラスターになり、それぞれが異なる色で着色され、その高さに破線のしきい値ラインが描画されます。これは scipy の fcluster に相当するデンドログラムの操作 — 連続ツリーを離散グループのセットに変換します。

cut を省略すると、フラットクラスターの着色なしの純粋なデンドログラムが表示されます。

5. クレードのハイライト

clade 行は単系統群を色、オプションのラベル、オプションのハイライトモードでマークします。

clade ID = (member1, member2, ...) [color: "#hex", label: "text", highlight: mode]

メンバーは Newick 文字列からの先端（葉）の ID です。レンダラーはリストされた先端の MRCA を計算し、そこをルートとするサブツリー全体をハイライトします。

6. スケールバーとアウトグループ

スケールバー： scale "label" — 下部にバーを追加します。ラベルは単位を説明します（例："substitutions/site"、"Mya"）。枝の長さに意味がないクラドグラムモードでは省略してください。

アウトグループ： outgroup: taxonId — ドキュメント用にアウトグループを記録します。レンダラーがアウトグループの分類群を視覚的にマークするために使用することがあります。

phylo "Vertebrates"
  newick: "((Human:0.1,Chimp:0.08):0.03,Lamprey:0.8);"
  outgroup: Lamprey
  scale "substitutions/site"

7. ヘッダー props リファレンス

すべてのオプションは phylo ヘッダー行の […] 内、または本文の任意の場所の style […] 行に記述します。

8. ラベルとコメント

• タイトル： phylo "Tree of Life" — 最初の行のみ。
• スケールラベル： scale "substitutions/site" — ドキュメントごとに1つ。
• クレードラベル： clade 行内の [label: "Primates"]。
• コメント： 行頭（先頭スペースの後）の #。末尾インラインコメントはサポートされていません。

9. よくある間違い

10. 文法（EBNF）

document        = header (blank | comment | newick-line | scale-line
                    | outgroup-line | clade-line | style-line | cut-line | indent-line)*

header          = "phylo" ( WS quoted-string )? ( WS "[" props "]" )? NEWLINE
quoted-string   = '"' any-char-but-quote* '"'

newick-line     = "newick:" WS quoted-newick NEWLINE
scale-line      = "scale" ( WS quoted-string )? NEWLINE
outgroup-line   = "outgroup:" WS id NEWLINE
cut-line        = "cut" WS number NEWLINE       // dendrogram mode: flat-cluster threshold height
clade-line      = "clade" WS id WS "=" WS "(" id ("," id)* ")"
                    ( WS "[" clade-props "]" )? NEWLINE
style-line      = "style" WS "[" props "]" NEWLINE

// Indent tree — triggered by a line ending in ":" with no spaces
indent-tree     = root-line indent-node*
root-line       = id ":" NEWLINE
indent-node     = INDENT ( id ":" length | ":" length | id ) ( WS "[" number "]" )? NEWLINE

props           = prop ("," prop)*
prop            = "layout:" layout-value
                | "mode:" mode-value
                | "unrooted"
                | "branch-width:" number
                | "openAngle:" number
                | "mrsd:" quoted-string

clade-props     = clade-prop ("," clade-prop)*
clade-prop      = "color:" quoted-string
                | "label:" quoted-string
                | "highlight:" ( "branch" | "background" | "both" )

layout-value    = "rectangular" | "slanted" | "circular" | "unrooted"
mode-value      = "phylogram" | "cladogram" | "chronogram" | "dendrogram"

// Newick grammar (embedded, parsed separately)
newick          = subtree ";"?
subtree         = leaf | internal
internal        = "(" subtree ("," subtree)* ")" name? nhx? length?
leaf            = name nhx? length?
name            = unquoted-name | "'" single-quoted "'")
length          = ":" number
nhx             = "[" number "]"                     // plain bootstrap
                | "[&&NHX:" nhx-pair (":" nhx-pair)* "]"
nhx-pair        = key "=" value

id              = [a-zA-Z] [a-zA-Z0-9_-]*
number          = /[+-]?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/
comment         = INDENT "#" any NEWLINE

権威ある情報源：src/diagrams/phylo/parser.ts。このドキュメントとパーサーが乖離している場合、パーサーが優先されます。Issue を立ててください。

11. 標準準拠

Schematex の系統樹は、コアのツリーシリアライゼーションに**Newick フォーマット仕様（PHYLIP パッケージに記載）に従い、ブートストラップサポート値にはNHX（New Hampshire Extended）**の慣習を使用します。NHX ブラケットの B= フィールドのみが現在視覚的に描画されます。他のすべてのフィールドはパースされて格納されますが表示されません。

現在実装済みのもの：

• ✅ Newick トポロジー、枝の長さ、引用符付き名前、ポリトミー
• ✅ ブートストラップ値 — プレーン [95] と NHX [&&NHX:B=95]
• ✅ 矩形、斜め、円形、無根のレイアウト
• ✅ フィログラム、クラドグラム、クロノグラムのモード
• ✅ クレードハイライト（枝の色、背景シェーディング、両方）
• ✅ スケールバー
• ✅ インデント DSL の代替手段
• ⏳ 複数ツリードキュメント（フォレスト）— §12参照
• ⏳ クロノグラムの時間較正軸（地質スケール）
• ⏳ 先端ごとのアイコンまたは画像
• ⏳ B= 以外の NHX フィールド（種、分類、重複イベント）

参考文献：

• Felsenstein, J. (1986). The Newick tree format. PHYLIP documentation.
• Zmasek, C.M. & Eddy, S.R. (2001). ATV: Display and manipulation of annotated phylogenetic trees. Bioinformatics, 17(4), 383–384. (NHX specification)
• Felsenstein, J. (2004). Inferring Phylogenies. Sinauer Associates.

12. 関連サンプル

13. ロードマップ

計画中 — 現在はパース不可。 生成する DSL でこれらを使用しないでください。パーサーが拒否または無視します。

• 複数ツリードキュメント — 複数の newick: ブロックを持つ phylo ファイル（例：遺伝子ツリーと種ツリー）。
• クロノグラムの地質時間軸 — 平坦な数値スケールの代わりに、エポックラベル付きの X 軸（新生代/中生代など）。
• 先端ごとのメタデータ — クレード全体を宣言せずに個々の先端に形質や色付きマーカーを付ける（例：tip Ecoli [color: "#F00", shape: star]）。
• ブートストラップ以外の NHX フィールド — 種（S=）、重複（D=）、転移イベント（Tr=）を枝記号として描画。
• タングルグラム — 対応する先端を結ぶ接続線を持つ2つのツリーを並べて表示。

早急に必要な場合は GitHub の Issue でトラッキングしてください。