BSC 專題課程 / LPU 專題課程 / PART 5

PART 5

讀懂 AI 寫出來的程式

十六支散落的程式整合成三個檔案,然後用五個問題把它讀完

← PART 4 真的讓 AI Agent 跑一遍 回首頁 →
PART 4 交出了十六支程式、740 行。這一頁不是逐行講解那 740 行——沒有人會逐行讀程式,AI 寫的更不會。這一頁做兩件事:先把十六支整理成三個帶得走的檔案,再示範專業的讀法。
讀程式不等於看懂每一行。整合後的四個檔案合計 2,124 行。真正決定結論的,是其中十四個數字;真正需要盯住的,是五個地方。這一頁就是那五個地方。

開場先講四個詞

這一頁會反覆出現四個字眼。先各給一句話,之後不再解釋。

函式function

一段有名字的程式,吃進幾樣東西、吐出一個結果。hotspots(遮罩, 密度場, 75) 就是一個函式:給它三樣東西,它還你一批熱點體素。名字後面的括號就是「吃進什麼」。

類別class

把一批資料和處理那批資料的動作綁在一起的盒子。整條管線只有兩個:Config 裝所有參數,Brain 裝所有資料。

模組module

一個 .py 檔案。import lpu_lib 的意思是「把 lpu_lib.py 這個檔案裡的東西拿過來用」。

參數parameter

程式裡寫死的數字——門檻、比例、跑幾次。這一頁最重要的一個概念:換掉一個參數,結論就可能改變,但程式不會告訴你。

骨架五個問題

拿到一份 AI 寫出來的程式,不論它算的是果蠅腦、問卷資料還是影像,都可以問同樣五個問題。每一個問題只需要看程式的一小塊。

#問題要看哪裡為什麼是這一個
1哪些數字決定了結論?Config結論通常靠十幾個數字撐著,不是靠一千行
2資料是怎麼進來的?Brain讀錯資料的話,後面每一步都會很順利地算出錯的答案
3這一段在做哪一步?函式名 ↔ 步驟的對照表有對照表才能只讀你關心的那一段
4它怎麼證明自己沒寫錯?expected.json沒有這一塊,「跑完了」只代表沒當掉
5跑不出東西時會怎樣?會不會停下來最危險的不是報錯,是不報錯

1先看形狀:十六支變成三個檔案

PART 4 是一條指令一支程式跑出來的,所以留下十六支各自獨立的檔案。這樣的東西可以拿來看,但不能拿來用——它不能搬到別台機器,也很難讀。整合的第一件事不是改演算法,而是把重複的部分收成一份。

PART 4PART 5
檔案數16 支3 個(+一份驗收表)
行數740(16 支 .py)2,124(四個檔案合計)
程式敘述數(只算 .py)9361,298
會去載入分區標籤的檔案10 支1 處
自己寫一次體素編號換算的檔案9 支1 處
把資料路徑寫死的檔案14 支1 處(而且可以從命令列覆寫)
行數變多、檔案變少,這是正常的。多出來的是兩種東西:一種是 PART 4 沒有的周邊功能——檢查環境、核對驗收表、打包資料;另一種是後來補做的 STEP 7,從 SWC 的樹狀拓樸真正把神經束綁出來,那正是 PART 4 當時做不到、只能降級的一步。敘述數從 936 增為 1,298(多 39%),其中 230 個敘述來自 STEP 7。
為什麼「同一件事寫十次」是問題?把體素編號換算成座標這件事,在 PART 4 有九個版本。九個版本代表九個可能寫錯的地方,而且哪一個是對的,讀的人看不出來。收成一份之後,錯了就會全錯——聽起來更糟,其實更好:全錯很容易發現,只錯一個不會。

三個檔案的分工

run_lpu.sh
門

在終端機打的那一行。它只做四件事:檢查環境、跑、核對、列出產出。56 行,沒有任何計算。

run_lpu.py
順序

十四條指令收成十二個函式(指令 10+11、12+13 各併成一個)。它只管先做什麼、再做什麼、把什麼印出來,不管怎麼算。1,193 行。

lpu_lib.py
做法

參數、資料、七個步驟的演算法、畫圖。要改結論就改這裡。800 行。

這個切法有一個實際的用處:你想改什麼,就知道要打開哪一個檔案。想換一個參數重跑 → lpu_lib.py 最上面;想知道第 7 步在第 6 步之前還是之後 → run_lpu.py 最下面的順序表;想在別台機器跑 → 只碰 run_lpu.sh。

資料 277 MB D03 分區 D06 骨架 程式 106 KB run_lpu.sh 檢查 → 跑 → 核對 → 列出產出 run_lpu.py 主程式 十四條指令,十二個函式 只管先做什麼、再做什麼 lpu_lib.py 函式庫 Config 所有參數集中在這裡 Brain  資料與座標換算 七個步驟的演算法+畫圖 產出 34 MB out/ 16 份 JSON、8 個中間檔 7 張圖、2 個 CSV expected.json 56 項驗收 核對
三個檔案、兩份資料、一個產出目錄。箭頭是「誰用到誰」:run_lpu.sh 叫起 run_lpu.py,主程式用 lpu_lib.py 裡的函式,函式庫去讀 D03 與 D06,結果寫進 out/,最後拿 expected.json 核對一次。程式 106 KB,資料 277 MB——要搬家的重量在左邊,不在中間。 示意圖。三個檔案在 part5/。

2問題一:哪些數字決定了結論

拿到一份程式,第一件事是找出所有寫死的數字。

不是看它怎麼算,是看它用了哪些門檻。散在一千行各處的話,你永遠不會知道結論靠什麼撐著。

整條管線的所有參數都在 lpu_lib.py 最上面的 Config 裡,而且刻意分成三組:

本頁的程式片段省略了型別標註(原始碼是 def hotspots(mask: np.ndarray, v: np.ndarray, q: float) -> np.ndarray:,這裡寫成 def hotspots(mask, v, q):),其餘一律逐字照抄;終端輸出若有略去的段落,會在該處註明。

@dataclass
class Config:
    # ── 資料在哪。換一台機器時,通常只要改這三行 ──
    d03: Path = Path("/home/wanjuli/claude_linux/BSC_plan/D03")
    d06: Path = Path("/home/wanjuli/claude_linux/BSC_plan/D06")
    out: Path = Path("out")

    # ── 論文明確給定的參數 ──
    quartile: float = 75.0          # STEP 2:取上四分位當熱點
    smooth_size: int = 3            # STEP 1:3x3x3 移動平均
    min_cluster_frac: float = 0.01  # STEP 3:群要大於腦區體積的 1%
    overlap: float = 0.50           # STEP 4:重疊超過 50% 才招募
    core_frac: float = 0.80         # STEP 6:中心 80% 對周邊 20%
    c_threshold: float = 2.0        # STEP 6:c > 2 才算 LPU

    # ── 論文沒給、我們自己決定的(PART 4 結論五)──
    f_ln: float = 0.80              # 指令 2:多少比例的分枝待在同一區才算 LN    bin_factor: int = 4             # 指令 4:幾格併成一個分析體素    n_shuffle: int = 9              # 指令 7:打亂體素順序重跑幾次    grow: int = 4                   # 指令 9:招募時撐大幾格(2 格招不到任何一顆)    depth_cut: int = 10             # 指令 10:離本體幾格以內視為初級神經突    min_ln_to_cluster: int = 10     # 指令 14:LN 少於幾顆就不分群    min_vox_touch: int = 5          # 指令 12:碰到幾個體素才算「碰到」這一區    term_min: int = 5               # STEP 7:一個腦區至少幾個終端,才算這顆神經元連到它    tract_min_neurons: int = 3      # STEP 7:一條神經束至少幾顆神經元    cover_grow: int = 1             # STEP 4(固定靶讀法):把分群撐大幾個分析體素    cover_thr: float = 0.30         # STEP 4(固定靶讀法):覆蓋率門檻    rng_seed: int = 0               # 打亂順序用的亂數種子
    # 切割高度:論文沒給。掃 4 到 25,平台取 14–20。    cut_lo: float = 4.0    cut_hi: float = 26.0    cut_step: float = 1.0    plateau: tuple = (14.0, 20.0)

    # ── 資料格式常數(跟著 D03/D06 走,不要改)──
    d06_grid: int = 512             # D06 體素編號的 X、Y 邊長
    d06_step: int = 2               # 一個 D06 體素等於幾個 1 µm 標籤格
白話:這是一張設定表。每一行是「名字 = 數字 + 一句說明」。程式跑的時候,任何地方要用到「上四分位」,都是回來讀這張表的 quartile,不會自己寫一個 75。所以要改一個門檻,只要改這裡一個地方。
藍底標起來的那兩段,是論文沒給、由我們自己決定的參數:十七行程式碼、十四項決定。它跟 PART 4〈結論五〉那張表講的是同一件事——哪些數字是我們自己選的——只是那張表按「這一遍做了哪些決定」列(十項),這裡按程式裡的欄位列(十四項),兩邊不是逐項對應:term_min、tract_min_neurons、cover_grow、cover_thr 是後來補做 STEP 7 與固定靶讀法時才加上的。論文沒有給這些數字,是我們自己決定的。它們跟上面那組(論文給的)長得一模一樣、寫在同一個地方、用起來也沒有差別——而這正是最容易出事的地方。把它們分成兩組並註明來源,是為了讓讀的人一眼看出「哪幾個數字是有出處的,哪幾個是我們選的」。

跟 PART 3 的指令對得起來嗎

這份程式是照 PART 3 那 14 條指令跑出來的,所以值得逐項對一次。指令裡寫死的數值有十三個,其中十一個程式照做——LN 判準 80%、4×4×4 併格、打亂九次、上四分位、深度小於 10 丟掉、神經束 30 個體素與 60% 相似度、一條束至少三顆、c > 2、中心區 80%。

只有兩個不一樣,而且都是 PART 4 實跑之後改的:

參數PART 3 的指令說程式實際用為什麼改
grow
招募時撐大幾格
2 格4 格撐大 2 格時一顆都招募不到——重疊率過門檻的配對只有 5.9%。改成 4 格才啟動(53.4%),但啟動之後三輪吞下整池。PART 4〈發現一〉
plateau
切割高度
先用 8(指令自己註明「這是我隨便挑的,指令 7 會處理」)平台 14–20指令 7 本來就要求掃 4–25 並找出穩定區間,8 只是暫用值;掃完之後改用帶寬為 0 的那一段
這兩個改動沒有被藏起來,是這份程式最該學的地方。Config 的註解就寫著「# 指令 9:招募時撐大幾格(2 格招不到任何一顆)」與「# 切割高度:論文沒給。掃 4 到 25,平台取 14–20。」——把「為什麼是這個值」寫在值的旁邊,而不是寫在另一份文件裡。

它每一次跑都會把這組數字印出來

Config 裡有一個叫 describe() 的函式,作用只有一個:把「自己決定的」那一組印在螢幕上。每次執行都印,不管你要不要看。

論文沒有給、由我們自己決定的參數(換掉任何一個,結論就可能改變)
  f_ln               = 0.8      指令 2  LN 判準的比例門檻
  bin_factor         = 4        指令 4  幾格併成一個分析體素
  n_shuffle          = 9        指令 7  打亂順序重跑幾次
  cut range          = 4–25     指令 7  切割高度掃描範圍
  plateau            = 14–20    指令 7  取哪一段當平台
  grow               = 4        指令 9  招募時撐大幾格
  depth_cut          = 10       指令 10 深度小於此值視為初級神經突
  min_ln_to_cluster  = 10       指令 14 少於幾顆 LN 就不分群
  min_vox_touch      = 5        指令 12 碰到幾個體素才算碰到
  term_min           = 5        指令 12 幾個終端才算連到一個腦區
  tract_min_neurons  = 3        指令 12 一條神經束至少幾顆
  cover_grow         = 1        指令 9  固定靶讀法:分群撐大幾格
  cover_thr          = 0.3      指令 9  固定靶讀法:覆蓋率門檻
  rng_seed           = 0        亂數種子
為什麼要強迫自己看?因為半年後回來看 out/ 裡的結果,你不會記得當時 f_ln 設的是 0.8 還是 0.9。把它印在紀錄的最前面,等於每一份結果都自帶產生它的條件。

3問題二:資料是怎麼進來的

讀錯資料的程式不會當掉,它會很順利地算出錯的答案。

所以第二個要看的地方,是「檔案變成數字」的那一段——尤其是座標怎麼對上。

這條管線要同時用兩套座標:

D03 的標籤格D06 的骨架體素
是什麼每一格記著「這裡屬於哪個腦區」每一筆記著「某顆神經元經過這一格」
格子大小1 µm邊長 2 個標籤格
怎麼存一個 311 × 611 × 956 的三維陣列一個整數 vox,三個軸的位置編在一起

「編在一起」的意思是:一個整數同時記著三個軸的位置,要用的時候得拆開。Brain 在載入的當下就拆一次,之後全程共用:

G = cfg.d06_grid                          # 512
self.ix = (self.vox % G).astype(np.int64)         # ← 左右
self.iy = ((self.vox // G) % G).astype(np.int64)  # ← 背腹
self.iz = (self.vox // (G * G)).astype(np.int64)  # ← 前後
白話:這是「除法與餘數」而已。想像門牌號碼寫成 樓層 × 10000 + 排 × 100 + 號,要拆回來就是除一除、取餘數。% 是取餘數、// 是取商。整條管線只有這四行在做這件事,PART 4 有九份各自寫過一次。
右邊那三個註解是這一頁排版時加的(原始碼裡寫成上一行的一句話)。而重點正在這裡:ix 是左右、iy 是背腹、iz 是前後這件事,不是從檔案的標頭讀來的——標頭沒寫。它是 PART 4 的指令 1 用三組解剖關係反推出來的:兩側視葉的重心相差 668 格,而且幾乎只差在同一個軸上,那個軸就是左右。

這種「靠外部知識才能確定的事」,是讀 AI 寫的程式時最該停下來查的一類。程式把軸接反了也照樣跑得完,只是所有結果都左右顛倒,而且不會報錯。

後面所有步驟共用的那張表

Brain 算完座標之後,會做一張表 contact,它是後面好幾步的共同輸入:

@property
def contact(self) -> np.ndarray:
    """神經元 × 腦區的體素數矩陣 C。第 0 欄(腦區外)已歸零。"""
    if self._C is None:                     # 只算一次,算完存起來
        N, R = len(self.neurons), len(self.names)
        L = self.region_of_voxel
        C = np.bincount(self.nid.astype(np.int64) * R + L,
                        minlength=N * R).reshape(N, R)
        C[:, 0] = 0
        self._C = C
    return self._C
白話:C 是一張 28,573 列 × 76 欄的表。第 i 列第 j 欄的數字是「第 i 顆神經元有幾個體素落在第 j 個腦區裡」。LN 判準、神經束驗證、合併判斷,三步都只是在對這張表做算術。
if self._C is None 那一行是「算一次就好」的寫法。第一次有人要這張表時才算,算完存在 self._C 裡;第二次以後直接拿現成的。這張表要掃過 1,189 萬筆「某顆神經元經過某個體素」的紀錄,重算十次就是白白多花十倍時間。讀程式時看到這個形狀,就知道它下面那段是「貴」的。

4問題三:這一段在做哪一步

先建立對照表,再讀單一函式。

不要從第一行往下讀。先弄清楚「PART 2 的第幾步 = 哪一個函式」,然後只讀你關心的那一個。

PART 2 的步驟指令函式在哪個檔案
(不對應任何 STEP)1盤點資料、確認座標框與單位——收在 Brain 載入時的檢查lpu_lib.py
STEP 0 誰是 LN(前置)2、3ln_selection/ln_by_regionlpu_lib.py
STEP 1 密度場 v(r) 與 3×3×3 平滑4density_fieldlpu_lib.py
STEP 2 取上四分位當熱點5five_number/hotspotslpu_lib.py
STEP 3 UPGMA 分群與 1% 過濾6、7cluster_hotspots/cut_sweeplpu_lib.py
STEP 4 挑種子、招募
(論文的兩種讀法各一支)
8、9pick_seed/recruit(滾雪球)/recruit_regime/recruit_coverage(固定靶)lpu_lib.py
STEP 5 去初級神經突、抽等值面10depth_profilelpu_lib.py
STEP 6 算 c 值11c_valuelpu_lib.py
STEP 7 長程神經束驗證12read_swc/tree_path/scan_paths/bundle_tracts/tracts_in_bodylpu_lib.py
步驟以外 合併判斷13merge_gainlpu_lib.py
全腦跑一遍14step14run_lpu.py

這張表本身也寫在程式裡。run_lpu.py 最下面有一段就是它:

STEPS = {
    "1": ("盤點資料、確認座標框與單位", step01),
    "2": ("把目視判準翻成比例規則", step02),
    "3": ("全腦 LN 普查與 f 敏感度", step03),
    "4": (f"{REGION} 的密度場 v(r)", step04),
    ...
    "14": ("全腦逐區跑一遍", step14),
}
ORDER = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "12", "14"]
白話:這是一份目錄。左邊是編號、右邊是「這一步叫什麼、由哪個函式做」。下面那行 ORDER 是執行順序。要知道整支程式做了什麼,看這十幾行就夠了——這是整份程式最值得先讀的地方。

細讀之一:最短的那個函式

def hotspots(mask, v, q):
    """取上四分位以上的體素。

    佔比必然接近 25%,因為「上四分位」的定義就是排到 75% 的那個位置。
    這個 25% 不是資料的性質,是分位數定義的必然結果。
    """
    return mask & (v >= np.percentile(v[mask], q))
白話,一行拆成三件事:先 v[mask] 把腦區內的密度值挑出來;再 np.percentile(..., 75) 找出排到 75% 那個位置的值;最後 mask & (v >= 那個值) 選出「在腦區內、而且密度不低於那個值」的格子。一行程式就是 PART 2 的 STEP 2。
真正要讀的是那段說明文字。它講的不是「程式怎麼寫」,而是「不要把結果讀錯」——熱點永遠佔 25%,這不是果蠅腦的性質,是四分位這個定義造成的。看到跑出來的數字是 25.0% 就以為發現了什麼,是最容易犯的錯。

讀 AI 寫的註解時,值得先分類:這一句是在解釋程式(可以跳過),還是在解釋結果(一定要讀)。

細讀之二:為什麼一個迴圈要跑九次

def cut_sweep(P, thr, cfg, rng, detail=False):
    """掃切割高度,並把體素順序打亂重跑 n_shuffle 次。"""
    cuts = cfg.cuts
    runs, root = [], None
    for t in range(cfg.n_shuffle):                    # 跑九次
        Q = P if t == 0 else P[rng.permutation(len(P))]   # 第一次不打亂,之後都打亂
        D = pdist(Q)                                  # 兩兩距離
        Z = linkage(D, "average")                     # average linkage 就是 UPGMA
        runs.append([...每一個切割高度剪出幾群...])
        del D                                         # 用完立刻丟掉,這東西很大
    ...
白話:同一份資料,換九種排列順序,各分群一次,看答案一不一樣。如果九次的答案都相同,那個答案就可信;如果九次不一樣,那就不是「答案」,是「其中一種答案」。
為什麼順序會影響答案?AL_R 有 3,130 個熱點體素、4,896,885 對距離,但相異的距離值只有 557 種——體素排在整齊的格子上,距離大量重複。UPGMA 每一步要挑「最近的一對」,遇到平手時,選哪一對取決於它們在陣列裡的先後。順序一換,樹就不一樣。

實測:切割高度取 6 時,打亂九次得到 13、13、13、14、14、14、15、15、15 群。

if t == 0 這種分支,讀到就要停一下。它的意思永遠是「第一次跟其他次不一樣」。這裡是「第一次用原本的順序,其餘八次打亂」——所以九次裡有一次是原始答案,八次是對照。如果沒注意到這一行,會以為它跑了九次隨機、實際上是一次原始加八次隨機。

5問題四:它怎麼證明自己沒寫錯

「跑完了、沒報錯」只證明程式沒當掉,不證明它算對了。

要看的是:有沒有一份寫在程式外面的預期答案,跑完會自動核對。

PART 3 每一條指令後面都附了一張「怎麼確認它做對了」的表。這一版把那些表整份搬進 expected.json——不是文件,是程式會去讀的檔案:

{"指令": 1,  "說明": "神經元數",           "path": "c01/神經元數",   "want": 28573}
{"指令": 6,  "說明": "1% 門檻(分母是整個腦區)", "path": "c06/thr", "want": 125.11, "tol": 0.01}
{"指令": 9,  "說明": "20 種參數組合裡「只收一部分」的有幾個", "path": "c09/partial_cells", "want": 0}
{"指令": 14, "說明": "判定為單一 LPU",       "path": "c14/單一 LPU",   "want": 8}
{"指令": 12, "說明": "兩個候選共用的神經束(0 才算「各有自己的」)", "path": "c12_13/tract/sub/shared", "want": 0}
{"指令": 14, "說明": "判定為 hub(有束、無 LN 族群)", "path": "c14/hub", "want": 48}
白話:每一行是一項「應該是多少」。path 是「去產出的哪一份檔案、找哪一個欄位」,want 是應該得到的值,tol 是允許的誤差(小數才需要)。跑完之後 verify 會把 56 項逐一比對:
$ python3 run_lpu.py verify
核對 56 項:通過 56、不符 0、還沒跑 0
全部通過。
最有用的驗收項,是那幾條「預期它失敗」的。上面那條 partial_cells 的 want: 0 記的是「指令 9 照補充材料的滾雪球讀法應該找不到任何可用的參數組合」。如果哪天這一項變成不是 0,代表資料換了、或是招募那一步被改動過——而那正是最需要被通知的時候。

驗收表不只用來確認成功,也用來釘住已知的失敗。

為什麼要放在程式外面的一個檔案?因為它是「答案」,不是「作法」。放在外面,改答案不必動程式,改程式也不會順手把答案一起改掉。把預期值寫進程式裡自己跟自己比,等於沒有比。

6問題五:跑不出東西的時候會怎樣

最危險的不是報錯,是不報錯。

一支程式在資料撐不住的時候,可以選擇三件事之一。選哪一件,是寫程式的人的價值判斷,不是技術問題。

做法使用者看到什麼後果
照樣算下去一份完整、漂亮的結果最糟。看不出有問題,數字會被引用
印一行警告再算下去幾百行輸出裡的一行小字幾乎等於沒印。往下捲就看不到了
停下來沒有結果,只有一段說明為什麼停使用者必須自己決定要不要繼續

PART 4 的指令 9照補充材料的滾雪球寫法實作,而它在這份資料上跑不出中間結果:掃「撐大 2 到 5 格 × 重疊門檻 0.3 到 0.7」共 20 種組合,每一種的答案不是 1 顆(只有種子)就是 723 顆(整池)。這一版採取第三種做法:

「收一部分」=結果落在 2 到 722 之間的格子數:0 / 20

┌──────────────────────────────────────────────────────────────────────
│ 照補充材料的滾雪球讀法,這一步沒有可用的操作區間。
│ 20 種參數組合,每一種的結果不是 1(只有種子)就是 723(整池)。
│ 沒有任何一種設定收到「一部分」。
│
│ 這不是參數沒調好,是這個讀法本身的性質:每收一顆就把靶放大一次,
│ 所以它只有兩個終點——收不到任何一顆,或者一路收到底。
│ 論文對這一步還有另一種寫法(圖 S5D(e):靶是分群本身,固定不動),
│ 那一種的結果會隨門檻連續變化。這支程式實作的是補充材料那一種。
│
│ 主程式在這裡停下來,不往下產出看起來完整、其實沒有意義的結果。
│ 要繼續,請加上 --force-recruit:接下來的一切都建立在
│ 「撐大 4 格」這一種設定上,那是跑得動的設定,不是驗證過的。
└──────────────────────────────────────────────────────────────────────
白話:程式在這裡把選擇權交還給人。它把量到的事實(20 種組合、沒有一種收到一部分)、它的判讀(不是參數沒調好,是這個讀法的性質)、論文另一種寫法的存在、以及繼續下去的代價講完,然後停住。要往下跑,得自己打出 --force-recruit 這幾個字。
那個旗標的作用不是技術上的,是紀錄上的。它讓「我知道這一步沒有根據,但我還是要往下跑」變成一件必須打出來的事,而且會留在指令紀錄裡。沒有旗標的話,這個決定會消失得無影無蹤。

那另一種讀法呢?也在同一個函式庫裡。recruit_coverage() 實作的是圖 S5D(e) 的固定靶讀法,指令 12、13 用的就是它——AVLP_R 那兩個候選族群(11 顆與 138 顆)都是它招募出來的。論文對同一步的兩種寫法,程式裡是兩支函式;跑不動的那一支會停下來,跑得動的那一支繼續往下。

在自動化的腳本裡也一樣要看得見。run_lpu.sh 帶著這個旗標,而理由就寫在旗標旁邊,不是寫在另一份文件裡:

# --force-recruit 的意思:
#   指令 9 實作的是補充材料的滾雪球讀法,而它在這份資料上沒有可用的
#   操作區間——20 種參數組合,結果不是「只有種子 1 顆」就是「整池 723 顆」。
#   原因是這個讀法每收一顆就把靶放大一次,只有「收不到」與「全收」兩個終點。
#   主程式預設會在那裡停下來,不產出看起來完整、其實沒有意義的結果。
#   這裡加上旗標讓它往下走,是為了把後面幾步也跑出來;但要記得,
#   之後每一個數字都建立在「撐大 4 格」這一種設定上。
"$PY" run_lpu.py all --force-recruit
這是拿到 AI 寫的程式時最該檢查的一件事。問它:資料不夠、條件不成立的時候,你這支程式會怎麼做?如果答案是「照樣算完」,那它產出的每一份結果都需要你自己去判斷可不可信——而你多半沒有那個資訊。

7帶到另一台機器

整合成三個檔案的實際理由:可以搬。但搬家的重量不在程式——程式四個檔案加起來 106 KB,資料 277 MB。兩包都可以直接下載,連結在本節的〈下載:把這兩包拿走〉。

第一件事:先問機器夠不夠

run_lpu.py check 不載入任何資料、不算任何東西,只確認東西都在:

$ python3 run_lpu.py check
── 一、Python 與套件 ────────────────────────────────
   python      3.11.7
   numpy       1.26.4   (測過的下限 1.24)
   scipy       1.15.3   (測過的下限 1.10)
   matplotlib  3.8.0    (測過的下限 3.6)
── 二、資料檔 ───────────────────────────────────────
   [有]  labels_fc_1um.npy           173.2 MB   分區標籤體積
   (中間三個 KB 級的小檔略去)
   [有]  vox.npy                      45.4 MB   骨架體素編號
   [有]  nid.npy                      45.4 MB   每個體素屬於哪顆神經元
   [有]  dep.npy                      11.3 MB   每個體素離細胞本體多遠
   [有]  neurons.csv                   1.6 MB   28,573 顆神經元的名字
         合計                          277.0 MB
── 三、記憶體 ───────────────────────────────────────
   這條管線實測的峰值是 2.5 GB(指令 14 跑到 ME_L 的兩兩距離時)。
   其他每一步都在 1.1 GB 以下。
   目前可用約 16.3 GB → 夠
   (第四段「輸出目錄」與最後印出的參數表略去;參數表見上面〈它每一次跑都會把這組數字印出來〉)

結果:全部通過,可以跑 `python3 run_lpu.py all`
白話:這一步的價值在於「還沒開始算就知道會不會失敗」。不然的話,你會等三分鐘、載完 277 MB,然後在畫第一張圖的時候才發現 matplotlib 沒裝。

只有三個套件

套件測過的版本用在哪
numpy1.26.4全部。所有陣列運算
scipy1.15.3平滑、膨脹、距離轉換、兩兩距離、UPGMA
matplotlib3.8.0七張圖

沒有用到:pandas、scikit-learn、scikit-image、trimesh、PIL。整條管線是用 numpy 加 scipy 的基本功能做出來的。

套件少本身就是一種可讀性。每多一個套件,讀的人就多一份「這一段到底在做什麼」要查。而且套件愈多,兩年後裝不起來的機率愈高。

三件會咬人的事

要注意的為什麼
畫圖前要先設 Agg沒有螢幕的機器(伺服器、容器、ssh 連進去的工作站)直接畫圖會找不到顯示裝置而中斷。整條管線只有 setup_matplotlib() 一個地方在做這件事,所以只有一個地方需要對
圖裡不要放中文新機器不一定裝了中文字型。字型不在的時候 matplotlib 不會停,它照樣把圖存起來,只是每個中文字都變成空白方塊。七張圖的文字全部是英文,說明一律寫在網頁上
版本要鎖理由跟一般專案不同:這條管線的答案會被平手的處理方式影響(上面〈為什麼一個迴圈要跑九次〉那一節)。換一個 scipy 版本,如果分群的內部實作動過,同一份資料可能給出不同的群數

資料打包:277 MB 變 39 MB

$ python3 run_lpu.py pack --pack-to ~/lpu_data
   labels_fc_1um.npy           173.2 MB →     1.1 MB   分區標籤體積
   (中間三個 KB 級的小檔略去)
   vox.npy                      45.4 MB →     5.9 MB   骨架體素編號
   nid.npy                      45.4 MB →    21.0 MB   每個體素屬於哪顆神經元
   dep.npy                      11.3 MB →     9.1 MB   每個體素離細胞本體多遠
   合計                        277.0 MB →    38.6 MB   (14%)
白話:分區標籤壓到原本的 0.6%。那個檔案是 1.8 億個格子,絕大多數是「腦區外」的零,剩下的也是一大片一大片同樣的號碼——這種東西壓縮率極高。程式讀得懂壓縮檔,所以另一台機器不必先解開,代價是載入多花 0.4 秒。
可攜性是驗過的,不是宣稱的。把四個檔案(106 KB)複製到一個空目錄,只給它打包後的 39 MB再加一份 3.1 MB 的路徑快取,重跑一遍:16 份 JSON 與 7 張圖全部與原本逐位元組相同,56 項驗收全部通過。

那份 3.1 MB 是 STEP 7 的中間產物。神經束要從 FlyCircuit 的 SWC 原始檔算(28,573 個檔、842 MB),但掃完的結果會存成 out/c12_paths.csv——17,690 條跨兩區的路徑。下次跑到指令 12 時那個檔在,就不必再讀 SWC。所以搬家要搬的還是 39 MB + 3 MB,不是 39 MB + 842 MB。

下載:把這兩包拿走

上面講的東西都可以直接下載。分成兩包,因為它們的性質不一樣——程式 44 KB,跟著課程網站走;資料 38 MB,放在 GitHub 的發布頁,不進版本控制的歷史。

資料包的 38 MB 是八個資料檔(上面那張表的 38.6 MB)+ 那份 3.1 MB 的路徑檔,再一起壓成 zip;加了東西反而小一點,是因為 neurons.csv 與路徑檔都是純文字,zip 還能再壓掉約六成。

程式包 · 44 KB lpu-part5-code.zip

三個檔案 + 驗收表 + 說明:run_lpu.sh、run_lpu.py、lpu_lib.py、expected.json、README.md。

解開後是 lpu-part5/ · 內附 SHA256SUMS.txt

資料包 · 38 MB lpu-part5-data.zip

八個資料檔(D03 的分區標籤、D06 的骨架體素)壓成 .npz,外加 STEP 7 的路徑檔 out/c12_paths.csv。

解開後是 lpu-part5-data/ · 內含上面那八個檔 + 那份路徑檔

兩包都解開,把資料包裡的 out/ 複製到程式旁邊,然後跑:

$ unzip lpu-part5-code.zip && unzip lpu-part5-data.zip
$ cp -r lpu-part5-data/out lpu-part5/
$ cd lpu-part5 && ./run_lpu.sh ../lpu-part5-data/D03 ../lpu-part5-data/D06
白話:第二行是在省 842 MB。out/c12_paths.csv 是 STEP 7 掃 SWC 掃出來的結果。把它先放進 out/,指令 12 就會直接沿用,不必去讀那 28,573 個原始檔——那才是搬不動的部分。少了這一行程式也跑得完,只是跑到指令 12 會找不到 SWC 而停在那裡。

這兩包就是上面那張驗收表跑出 56 項全過的那份東西,不是另外整理的版本。在一台空目錄的機器上照上面三行跑完:170 秒、56 項全過,16 份 JSON 與 7 張圖與 part5/out/ 裡的成品逐位元組相同。

資料的出處要跟著走。資料包裡有一份 來源與出處.md,逐檔寫明來自哪裡: 兩包內各有一份 SHA256SUMS.txt,用 sha256sum -c SHA256SUMS.txt 核對。
106 KB
程式(四個檔案)
39 MB
打包後的資料
170 秒
整條跑完
2.5 GB
實測峰值記憶體
整條管線的瓶頸不是算力,是資料。全腦 75 區跑完只要 94 秒,而其中 54 區的 LN 候選少於十顆,根本沒有東西可以分群。換一台更快的機器,不會讓那 54 區變得可以分析。看到一份程式跑得很慢時值得先問:慢的是計算,還是根本在等一份不存在的資料?

收尾一張可以帶走的檢查清單

這五個問題跟果蠅腦沒有關係。任何一份 AI 寫給你的分析程式,都可以照這個順序問一遍。

#問題怎麼問答不出來代表什麼
1參數在哪裡「把所有寫死的門檻、比例、次數列給我,並標出哪些有出處、哪些是你自己決定的」你不知道結論靠什麼撐著
2資料怎麼進來「單位是什麼、座標軸誰是誰、這個判斷是從檔案讀來的還是你推的」可能整份結果左右顛倒,而且不會報錯
3哪一段做哪一步「給我一張表:我的第幾步 = 你的哪個函式」你只能整份接受或整份不信,無法逐段檢查
4怎麼證明沒寫錯「把預期值寫成一個獨立的檔案,跑完自動核對」「跑完了」只等於「沒當掉」
5撐不住時會怎樣「資料不夠、條件不成立的時候,你會停下來還是照樣算完」最危險的一項。你會拿到一份看不出有問題的結果
五個問題裡只有第四個在問「算得對不對」。其餘四個問的是參數的來源、資料的意義、能不能逐段對照、撐不住時怎麼處理——全部是「這份結果能不能拿去用」的問題。算法對不對,AI 通常比你會判斷;但這四件事只有你能判斷,因為只有你知道這份資料是怎麼來的、要拿去回答什麼問題。
回到這堂課的起點。PART 1 問「一個腦區的邊界該畫在哪裡」,PART 2 把它變成七個步驟,PART 3 把七個步驟變成十四條指令,PART 4 讓 AI 真的跑了一遍,這一頁把跑出來的東西整理成看得懂、帶得走的三個檔案。

五個部分裡,只有 PART 4 那一步是 AI 做的。其餘四步——決定要問什麼、把問題寫成步驟、把含糊的地方指定清楚、判斷跑出來的東西能不能用——都還在人這一邊。

← PART 4 真的讓 AI Agent 跑一遍 回首頁 →
BSC 腦空間體研究中心 · 專題課程 LPU · PART 5 | 程式在 part5/,三個檔案 + 一份驗收表;所有數字由 part5/run_lpu.py 實跑產生 · 回 BSC 專題課程首頁