演化樹

關於演化樹

演化樹（又稱系統發生樹、親緣樹或進化枝圖）展示一組物種、基因或序列的推斷演化史。內部節點代表假設的共同祖先；葉尖代表觀測到的分類群；分支長度編碼演化距離或分歧時間。演化生物學家、分子生態學家和臨床微生物學家使用演化樹來重建生命演化史、追蹤病原體疫情，以及了解基因家族的演化歷程。

Schematex 接受 **Newick 格式**的樹——這是 PAUP*、IQ-TREE、RAxML、BEAST 及幾乎所有系統發生學程式都使用的通用交換標準——並以 **NHX 標注**擴充支援自展值和進化枝元數據。對於手工編寫的樹，也支援基於縮排的 DSL。本頁說明解析器目前支援的語法。

1. 第一棵演化樹

最小可用的樹：四個分類群，兩個進化枝。

三條規則涵蓋了 80% 的使用情境：

1. 以 phylo 起頭，後面可選擇性加上引號標題和方括號屬性。
2. 以 newick: 格式提供樹的拓撲——標準 Newick 字串，加引號，放在同一行。結尾的 ; 可省略。
3. 可選擇在 newick 行下方定義clade 高亮群組和scale 標籤。

注解必須以 # 開頭並獨立成行。不支援行尾行內注解。

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

對於手工編寫或小型的樹，Schematex 提供一種基於縮排的替代格式，比原始 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"

樹狀圖 — 層次聚合分群的標準輸出，不用於演化。每個內部節點放置在其合併高度（兩個子集群融合的表型距離）處，所有葉節點對齊到共同基線，分支為直角折線連接器。旁邊繪製高度軸，讓你讀出任意兩個葉節點第一次共享集群的距離。當同一棵 Newick/縮排樹描述的是分群結果——基因表現量集群、樣本相似度、問卷回應分組——而非系統發生，請選用此模式。

加入 cut <value> 行，在選定高度切割樹：合併高度低於閾值的每棵子樹成為一個平坦集群，每個集群著以不同顏色，並在該高度處跨樹繪製一條虛線閾值線。這是 scipy 中 fcluster 的樹狀圖等價物——將連續樹轉換為離散群組集合。

省略 cut 可顯示不帶平坦集群著色的裸樹狀圖：

5. 進化枝高亮

clade 行為單系群（monophyletic group）標記顏色、可選標籤和可選高亮模式。

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

成員是 Newick 字串中的葉尖（葉節點）ID。渲染器計算列出葉尖的最近共同祖先（MRCA），並高亮以其為根的整個子樹。

6. 比例尺和外群

比例尺： scale "標籤" — 在底部加一條比例尺。標籤說明單位（如 "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. 標頭屬性參考

所有選項都放在 phylo 標頭行的 […] 中，或放在正文任意位置的 style […] 行中。

8. 標籤與注解

• 標題： phylo "Tree of Life" — 僅第一行。
• 比例尺標籤： scale "substitutions/site" — 每份文件一個。
• 進化枝標籤： 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= 欄位是目前唯一渲染的 NHX 欄位；其他所有欄位均被解析和儲存，但不顯示。

目前已實作的內容：

• ✅ 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=）。
• 糾纏圖（Tanglegram） — 並排顯示兩棵樹，並以連線連接對應的葉尖。

如果你迫切需要以上功能，歡迎在 GitHub issues 追蹤。