BSC 專題課程 / VFB 專題課程 / PART 9

PART 9

讀懂它寫出來的程式

把 PART 8 產出的三支程式讀完——不教 Python 語法,教的是「別人交給你一份程式,你要先看哪裡」

← PART 8 真的讓它跑一遍 回課程首頁

1先拿到它:三支程式與一份說明

PART 8 那一輪的產物是一包檔案。先下載下來,這一頁講的每一段都在裡面:

下載 vfb-recompute.zip(三支程式、說明,以及那一輪的全部輸出)

recompute.py主流程 618 行

取論文的靶、取 VFB 那一側、逐列比對

cross_check.py旁證 175 行

同一個數字問三條路

make_figure.py產圖 91 行

畫 PART 8 第 3 節那張圖

三個行數出自 out/recompute/run_meta.json 的 files;合計 884 行與其中 175 行註解出自同檔的 code_lines(註解用 tokenize、說明字串用 ast 數的,2026-09-15 實測)。

三支加起來 884 行,其中 175 行是註解或說明字串(20%)。這不是為了好看——指令 10 明寫「每個檔案開頭用註解寫清楚它做什麼」。一份研究用的程式,註解不是裝飾,是它唯一的說明書。
不會 Python 也讀得下去。這一頁不解釋 for 迴圈或字典是什麼。它要你看的是另一種東西:哪幾行代表一個決定。決定是看得懂的,語法可以跳過。

2第一個要看的地方:自己決定的參數

讀 recompute.py 的時候,第一眼不要看它怎麼抓資料。看開頭那一段。

# ══════════════════════════════════════════════════════════════════
# 自己決定的參數:全部集中在這裡。改動這一段就會改動結論。
# ══════════════════════════════════════════════════════════════════
PARAMS = {
    # 用 VFB 的哪一套資料。換一套,下面每個數字都會變。
    "vfb_dataset": "Nern2024",

    # 拿什麼當比對的鍵。兩個選擇實測命中率差很多:
    #   "instance" → 用神經元自己的標籤,取括號前那一段(例如 Dm20_R)
    #   "class"    → 用它所屬類別的標籤,取最後一個詞(例如 Tm3)
    # 預設用 instance;理由與兩者的命中率見 out/compare.json 的 key_choice。
    "match_key": "instance",

    # 「什麼算一個細胞型」:只算沒有下位類別的類別(末端類別)。
    # 設成 False 會把泛稱(例如「膽鹼性神經元」)也算成一個型,
    # 而那會讓型底下的顆數加總超過神經元總數。
    "leaf_classes_only": True,
}

三行。而 PART 7 第 3 節列的那六個「必須自己決定的事」,有三個就在這裡——①用哪一套資料、②什麼算一個細胞型、③拿什麼當比對的鍵。

改一個字,結論就變了——這不是比喻

把 match_key 從 instance 改成 class,其他完全不動,重跑一次:

instance(預設)class
名字對得上的753547
顆數也相同的732535
顆數不同的2112
只在論文那一側25185
只在 VFB 那一側184192

同一份資料、同一支程式、同一天跑的,結論從 732 變成 535。如果這份程式把這個選擇藏在第 180 行的某個判斷式裡,讀的人根本不會知道有這個選擇存在——他會以為 732 是資料告訴他的。

右欄五個數字出自 out/recompute/run_meta.json 的 match_key_class_variant(把參數改掉重跑一次存下來的);左欄出自 out/recompute/compare.json。2026-09-15。

順手抓到的一個真的毛病:參數表裡本來有第四個,而它根本沒被用到。
原本還有一個 page_size(「每頁取幾列」),看起來很重要,實際上這支程式走的是知識庫、一次就取完,從頭到尾沒有任何一行讀它。而 match_key 原本也只是註解——比對那一段寫死了用 instance,改它不會有任何效果。兩個都在寫這一頁的時候才發現:page_size 刪掉,match_key 補成真的會生效。
所以「檢查參數表」的第一步不是讀它寫什麼,是查每一個到底有沒有被用到。一個不生效的參數,比沒有這個參數更糟——它讓人以為自己控制得住某件事。

3讀主流程:三段,各解決一件事

recompute.py 跑起來會印五步。前三步是骨幹——就是 PART 8 第 2 節那些數字,這一節逐段讀的也是它們;④⑤ 是產給頁面用的(樹狀圖的實例、以及把論文原句逐字對回全文):

① 取論文的靶…
   778 列 732 個型 52,827 顆
② 取 VFB 那一側…
   53,402 顆 類別 844(泛稱 23、末端 821)
③ 逐列比對…
   鍵=instance  對得上 753/778 96.8% (分母:論文表的 instance 列(帶側別))
   鍵=class     對得上 547/732 74.7% (分母:論文表的 cell type(不帶側別))
   放到同一個分母(732 個型):instance 97.1% vs class 74.7% 差 22.4 個百分點
   顆數相同 732 不同 21(最大差 202)
   只在論文 25 只在 VFB 184
④ 取樹狀圖的實例…
   Dm3 與 Dm3a/Dm3b 的重疊:0 顆(分類學上位不會重複數)
   Dm3 直接 401 顆 / 這一叢共 1573 顆(樹狀圖上兩個都要寫)
⑤ 對論文原句…
   6 條全部逐字對得到

這是實際的執行輸出(python3 recompute.py,逐字貼回來的),每一個數字都同時寫進 out/recompute/target.json、out/recompute/vfb.json、out/recompute/compare.json、out/recompute/class_tree_examples.json、out/recompute/paper_quotes.json。2026-09-15。

① 取靶:一個 if 擋住了一整類災難

def paper_target() -> dict:
    """論文那一側:下載補充表,算出要比對的靶。

    **下載網址有坑**:PMC 那條路回 200 但只有 1.8 KB,是空殼。
    要從出版社的靜態內容站抓。抓到的東西太小就直接停,不要往下做。
    """
    import openpyxl
    req = urllib.request.Request(SUPP, headers={"User-Agent": UA})
    with urllib.request.urlopen(req, timeout=300) as r:
        blob = r.read()
    if len(blob) < 100_000:
        raise SystemExit(f"補充表只抓到 {len(blob)} 位元組,八成是空殼")

為什麼要有那兩行?

因為 HTTP 200 不代表你拿到了東西。PMC 那個網址回應正常、內容型態正常,檔案只有 1.8 KB——是一個空殼。沒有那兩行,程式會一路跑到解壓縮那一步才中斷,而錯誤訊息會指向壓縮檔壞了,完全看不出真正的問題是網址挑錯了。

這就是 PART 8 第 6 節說指令 1 要改的地方。那條指令只要求「說明你是從哪個網址拿到的」,沒要求看一眼檔案有多大。

② 取 VFB 那一側:「泛稱」是怎麼被找出來的

這一段解決的是那六個決定裡的第②個:什麼算一個細胞型。

    # 哪些類別是「泛稱」(底下還有別的類別,而那個別的類別也在這一組裡)
    lit = "[" + ",".join(f"'{c}'" for c in classes) + "]"
    # **只看這一組之內**:某個類別在整個 VFB 本體論裡還有下位,但那些下位
    # 在這套資料裡沒有神經元,它在這裡仍算末端。這是我們的選擇,不是資料說的。
    generic_rows = cypher(
        "MATCH (a:Class)<-[:SUBCLASSOF*1..8]-(b:Class) "
        "WHERE a.short_form IN %s AND b.short_form IN %s "
        "RETURN a.short_form, a.label, count(DISTINCT b) "
        "ORDER BY count(DISTINCT b) DESC" % (lit, lit))
    generic = {r[0] for r in generic_rows}
    leaf = {c: lab for c, lab in classes.items() if c not in generic}

這幾行在問什麼?

用白話講:「在我這一組類別裡,有誰的下面還站著另一個也在我這一組裡的類別?」——有的話,那個就是泛稱。SUBCLASSOF*1..8 是「往下找一到八層」。

結果是 844 個類別裡有 23 個是泛稱,821 個是末端。PART 2 第 3 節講的「VFB 查的是本體論裡的詞」,在這裡具體成了四行程式。

那個 1..8 是一個沒被寫進 PARAMS 的決定。為什麼是八層不是五層或二十層?沒有理由,就是夠深。這種數字在任何一份研究程式裡都找得到——它不影響這一次的結果(最深的鏈遠不到八層),但它是一個決定,而它躲在程式中間。讀別人的程式時,這種數字要逐一挑出來問一次。

③ 比對:兩個鍵都算,因為差距本身是結果

    # 這裡才是 PARAMS["match_key"] 真正生效的地方。
    # 選 class 的時候,論文那一側也要換成 cell type 欄,否則比的是兩種東西。
    if PARAMS["match_key"] == "instance":
        got = vfb["keys_instance"]
    else:
        got = vfb["keys_class"]
        ...

而每一個比率都要把分母印出來。上面 ③ 那段輸出裡印比率的三行,753/778 的分母是列、547/732 的分母是型——兩個百分比的分母不一樣,並排看就會誤導。(這裡的 732 是論文的分型數,跟「顆數相同的 732 列」是兩件事,只是剛好相等——PART 8 第 2 節把它拆開過。)所以程式除了各自的比率,還會把兩者放到同一個分母再算一次(都降到型這一層)。一支會產出百分比的程式,最該檢查的就是它有沒有告訴你分母是什麼。

注意那句註解的後半:換鍵的時候,兩邊都要換。VFB 那側換成類別標籤,論文那側就得從 instance 欄換到 cell type 欄——不然一邊有左右(Dm15_R)、另一邊沒有(Dm15),比出來的命中率會低得莫名其妙,而且你會以為是資料的問題。

這種「成對的修改」是讀程式時最容易漏的東西。一個參數改了,通常有第二個地方要跟著改;而那第二個地方往往離得很遠。看到一個參數,先找它被讀到的每一個位置——這比讀懂它做什麼更要緊。

4讀旁證那一支 cross_check.py:程式怎麼證明自己

cross_check.py 存在的理由,整個寫在它的開頭:

"""cross_check.py — 同一個數字,換三條路各問一次。

  ① 知識庫 Cypher       pdb.virtualflybrain.org        recompute.py 用的就是這條
  ② REST 的 run_query   v3-cached.virtualflybrain.org  網站自己在用的那條
  ③ MCP 的 get_term_info vfb3-mcp.virtualflybrain.org  給 AI 工具用的那條

**這支程式的重點不是「確認三條一樣」,是把不一樣的地方攤開。**
"""

而它抓到的,是 PART 8 第 5 節那個矛盾:①③ 都說 53,402,② 說 60,002 而且在五萬列被截斷。查下去發現②數的是「(個體, 類別)配對」,不是神經元——一顆神經元同時屬於兩個類別,它就出現兩次。

    # 一顆神經元可以同時屬於好幾個類別(例如「Dm15」與「麩胺酸性神經元」)。
    # pairs 就是(個體, 類別)配對的數量——下面第二條路數的其實是這個。
    # 也確認一件事:一顆是不是只對到一個模板座標框(若不是,列數還有第二個來源)
    triples = ...

那個 triples 為什麼要算?

因為「找到一個解釋」跟「確認沒有第二個解釋」是兩件事。列數比顆數多,除了「一顆屬於多個類別」,還可能是「一顆有多個座標框的影像」。所以多算一次(個體, 類別, 模板)三元組——結果跟配對數一樣是 59,739,代表模板不是第二個來源。

而配對數 59,739 跟 ② 報的 60,002 還差 263。那 263 到現在沒解掉,就寫在輸出檔的 note 欄裡,一個字都不修飾。

三條路的回答、instanceof_pairs=59,739、三元組數與那句 note,全部出自 out/recompute/cross_check.json(cross_check.py 產生,2026-09-15)。

這是整包程式裡最值得學的一段——而它不是在算答案,是在挑自己的毛病。
一份研究程式如果只有「算出結果」的部分,你沒辦法判斷它對不對;有一段專門拿來反駁自己的,你才有東西可看。這件事跟用不用 AI 無關,PART 1 那兩批錯也是這樣抓出來的。

5讀畫圖那一支 make_figure.py:三個不寫出來就沒人知道的決定

make_figure.py 只有 91 行,但它做了三個會影響讀者怎麼看那張圖的決定,三個都寫在開頭那段 docstring 裡(節錄,原文前面還有檔案說明與產出清單):

**兩格都用對數軸**。理由:每型顆數從 1 跨到 4,000,線性軸會把九成的點
擠在左下角一團,看不出「絕大多數落在對角線上」這件事——而那正是結論。
對數軸畫不了 0,但這裡沒有 0(對得上的型兩邊都至少 1 顆),所以不用特別處理。

圖內不放文字說明,只留座標軸標籤,其餘寫在 HTML 的 figcaption 裡。
決定一:用對數軸and say why

不是為了好看。線性軸會讓「絕大多數點落在對角線上」這個結論看不見——而那是整張圖唯一要講的事。

決定二:講清楚 0 怎麼處理and confirm there are none

對數軸畫不了 0,這是個真的坑。但這裡沒有 0——對得上的型兩邊都至少 1 顆。「沒有 0」是查過才敢寫的,不是假設的。

決定三:圖裡不放文字caption carries the words

圖上只有座標軸標籤。所有說明寫在圖說裡,因為圖裡的文字沒辦法被稽核程式檢查,圖說裡的可以。

這三個決定合起來,是「一張圖要能被別人檢查」的最低條件。而檢查的方式很具體:圖上落在對角線的點數,必須等於 compare.json 裡「顆數相同」的列數——兩個都是 732。對不上就代表圖跟數字來自不同的計算,那是嚴重的問題。這正是 指令 9 最後要求回報點數的原因。

「圖上落在對角線 732 點」出自 out/recompute/figure.json 的 on_diagonal;「顆數相同 732 列」出自 out/recompute/compare.json 的 same_count。2026-09-15。

6五個問題:拿到任何一份這種程式都先問

把前面幾節的讀法抽出來,就是五個問題。它們跟這篇論文、這個資料庫都沒有關係——不管是 AI 寫的、學生寫的、還是合作者寄來的,拿到就這樣問一次:

1
自己決定的東西在哪裡?有幾個? 集中在一處最好。散在程式各處,等於沒交代。找到之後,逐一問「這個真的有被用到嗎」——我們自己這一份就抓到一個沒用到的、一個寫了不生效的。
2
哪些數字是「決定」偽裝成的? SUBCLASSOF*1..8 的那個 8、「小於 100,000 位元組就停」的那個門檻——這些不在參數表裡,但它們都是決定。逐一挑出來問一次為什麼。
3
它有沒有一段是拿來反駁自己的? 沒有的話,你手上只有一個答案,沒有判斷它對不對的材料。有的話,先讀那一段。
4
它把「沒解決的事」寫在哪裡? 一份查不出任何問題的程式,通常不是沒問題,是沒查。找得到「這一條我不知道」的地方,這份程式才可信。
5
從空資料夾跑得起來嗎? 這是唯一一個不能用讀的、只能實際做的。解壓縮、刪掉輸出、重跑一次,看數字一不一樣。PART 8 第 7 節那一輪是 63 秒加 51 秒,7 個輸出檔逐位元組相同。

第 1、2 點提到的參數與門檻在 recompute/recompute.py 裡(PARAMS、SUBCLASSOF*1..8、len(blob) < 100_000);第 5 點的 63 秒、51 秒與「7 個輸出檔逐位元組相同」出自 out/recompute/run_meta.json 的 clean_run(由 recompute/run_meta.py --zip 真的解開重跑產生,2026-09-15 實測)。

五個問題裡,只有一個需要看得懂程式碼。其餘四個問的是「這份東西有沒有交代清楚」,而那件事跟語法無關——你在審一份研究計畫、一篇論文的方法段時問的,其實是同樣五件事。

7收尾:這門課到底在教什麼

從 PART 1 到這裡,表面上講的是 Virtual Fly Brain 怎麼用。但每一個部分真正卡住的地方,都不是操作:

表面上在講實際上卡住的地方
1模板與對位別人的資料憑什麼跟你的疊在一起
2搜尋框怎麼用同一個東西有三個名字,而你要數的是哪一種
3十支查詢它們為什麼不能相加
4八套連線資料你說的那個 N 是從哪一套、哪一版來的
5相似度分數它底下那份骨架到底是什麼
6三種問法三個答案不一樣,差別全在預設值
7怎麼寫指令給 AI你有哪六件事還沒想清楚
8實際跑一遍哪些數字是預先知道的,哪些不是
9讀程式哪幾行是決定,而它有沒有被寫出來
整門課只有一件事:把「你自己決定了什麼」講出來。
交給 AI 的時候要講(PART 7),跑完之後要講(PART 8),寫進程式裡也要講(這一頁)。而不講的代價一直是同一個:別人拿到你的數字,沒辦法判斷它對不對——包括三個月後的你自己。
這一整包裡還沒解掉的四條,列在 PART 8 第 7 節。它們留在那裡不是因為忘了處理,是因為第 4 個問題的答案要找得到地方放。
← PART 8 真的讓它跑一遍 回課程首頁
VFB 專題課程 PART 9 · 程式與輸出以 vfb-recompute.zip 提供 ·  論文為 Nern et al., 2025, Nature(CC-BY) · 數字於 2026-09-15 取得
回 BSC 專題課程首頁