BSC 專題課程 / 果蠅玩 Doom / PART 6

PART 6

讀程式:一鍵重跑到底跑了什麼

從 run_all.sh 那一支腳本開始,一層一層往下讀,讀到作者把神經元方程式寫成程式的那個檔案為止。不教 Python 語法;教的是每一段在做什麼、為什麼要有這一段

← PART 5 逐格看迴路怎麼打 回課程首頁

1怎麼讀這一頁:三層、標記、哪些檔案只放片段

PART 2 要你貼兩個指令:bash setup_envs.sh 建環境,bash fruitfly_lab/run_all.sh 一鍵重跑。這一頁回答一個問題:那兩個指令按下去之後,電腦到底做了哪些事?做法是順著「誰叫了誰」往下讀:

層是什麼檔案
第一層你親手執行的兩支 shell script(shell script:一個文字檔,裡面是一行一行要在終端機裡執行的指令;終端機是什麼見 首頁)setup_envs.sh、run_all.sh
第二層run_all.sh 每一行叫到的 Python 程式。一半是本課自己寫的,一半是作者的我們的:check.py、ff1_compare_conn.py、ff_extra.py、e4_asymmetry.py;作者的:extract.py、validate.py、fly_doom.py、analyze.py
第三層第二層的程式再往下引用的檔案。作者的程式只引用一個自己寫的檔案,就是神經元方程式lif.py

第三層再往下就是第三方套件(別人寫好、裝進來直接用的程式庫,例如 numpy、ViZDoom)與 Shiu 等人的全腦模型。這一頁追到作者自己的檔案為止;套件只在被叫到的那一行說明它做什麼、吃什麼、吐什麼(第 6 節)。

先認識幾個詞

下面每一段都會用到這些詞,先在這裡說一次,之後不再解釋。

程式區塊怎麼看

每一段程式都照同一個格式:先用一段話說這段在做什麼、為什麼要有這一段,然後放程式,程式下面逐行解釋。程式區塊左邊的數字是原檔的行號,和你下載下來的檔案完全一致;底色標出的行是接下來要講的行;行號旁的 ①②③ 是解釋裡用的標記。下面拿 run_all.sh 的三行當例子:

  8①B=$ENVS/ffl_brian/bin/python      # Brian2 全腦模型、抽子圖  9②D=$ENVS/ffl_doom130/bin/python    # ViZDoom 1.3.0:與作者逐局相同 10 D2=$ENVS/ffl_doom/bin/python      # ViZDoom 1.3.2:版本對照
下載包的 fruitfly_lab/run_all.sh 第 8–10 行

哪些檔案全文放,哪些只放片段

本課自己寫的六個檔案在下載包裡,這一頁只放講到的段落,沒講到的行跳過(行號照原檔,缺的行可以對照下載包)。作者 fruitfly-lab 的五個檔案,repo 沒有附授權檔(授權是什麼,見首頁〈出處〉),本課的規矩是不轉發它的任何檔案,所以這一頁只引講到的那幾行、標明 commit 與行號,請對照你自己 clone 下來的檔案讀(run_all.sh 第一次跑就會幫你 clone,在 fruitfly_lab/repo/ 底下)。

setup_envs.sh第一層 我們的 13 行

建三個 conda 環境

run_all.sh第一層 我們的 34 行

一鍵重跑:取得程式與資料、FF1–FF6、1.3.2 對照、E1–E4、驗收

check.py第二層 我們的 63 行

驗收:把你的結果和本課實跑的結果逐項比對

ff1_compare_conn.py第二層 我們的 27 行

FF1:數連線表的三個總數

ff_extra.py第二層 我們的 144 行

E1–E3:50 局、各自校準、只讀 DNa02

e4_asymmetry.py第二層 我們的 142 行

E4:右眼子圖為什麼反應偏弱

extract.py第二層 作者的 118 行

FF2:從全腦切出子圖

validate.py第二層 作者的 72 行

FF3:子圖、打亂接線、全腦各刺激一次

fly_doom.py第二層 作者的 266 行

FF4、FF5:校準、玩遊戲

analyze.py第二層 作者的 78 行

FF6:七個條件的統計與 p 值

lif.py第三層 作者的 139 行

神經元方程式、載入子圖、打亂接線

行數由 scripts/make_code.py 數出,記在 out/code_meta.json;我們的六個檔案合計 423 行,作者的五個合計 673 行。本頁每一個程式區塊都由同一支程式從原檔照抄,make_code.py --check 會逐塊確認和原檔一致。

不會 Python 也讀得下去。會用到的語法只有幾種:變數(給東西取名)、函式(把幾行打包、取名、之後可以重複叫)、迴圈(同一段程式對一串東西各做一次)、條件(如果…就…)、串列與字典(一串值;一組「名字→值」)。每一種第一次出現時就地解釋,之後不再解釋。

2第一層:兩支 shell script

setup_envs.sh:建三個互不干擾的環境

這支在做什麼。PART 2 第 4 節說過為什麼要三個環境:Brian2 全腦模型、ViZDoom 1.3.0、ViZDoom 1.3.2 各要一組不同版本的套件,裝在一起會互相衝突。這支腳本把三個環境各建一次,套件版本寫死成本課實跑時的版本。

  1 #!/usr/bin/env bash
  2 # 建立重現 fruitfly-lab 需要的三個 conda 環境(只需做一次,需要網路)。用法:bash setup_envs.sh
  3 # 版本照本課實跑時的環境固定;ViZDoom 1.3.0 是 fruitfly-lab 作者用的版本,換版本遊戲隨機抽樣會不同。
  4①set -e  5②CONDA_BASE="$(conda info --base)"  6③export PYTHONNOUSERSITE=1        # 不讓使用者家目錄 ~/.local 裡的套件混進環境
下載包的 setup_envs.sh 第 1–6 行
  7 # conda 預設的 libmamba 求解器在某些安裝裡會壞掉(錯誤訊息含 libmambapy),失敗時改用 classic 求解器再試一次
  8①mk() { conda env list | grep -q "^$1 " || conda create -y -q -n "$1" "python=$2" || conda create -y -q --solver classic -n "$1" "python=$2"  9②       "$CONDA_BASE/envs/$1/bin/pip" install -q "${@:3}"; }
下載包的 setup_envs.sh 第 7–9 行
 10①mk ffl_brian   3.11 Brian2==2.9.0 numpy==1.26.4 pandas==2.3.3 pyarrow==17.0.0 joblib numba==0.68.0 11 mk ffl_doom130 3.12 vizdoom==1.3.0 numpy==2.5.4 pandas==3.0.6 pyarrow==26.0.0 numba==0.68.0 pillow
 12 mk ffl_doom    3.12 vizdoom==1.3.2 numpy==2.5.4 pandas==3.0.6 pyarrow==26.0.0 numba==0.68.0 pillow
 13②for e in ffl_brian ffl_doom130 ffl_doom; do "$CONDA_BASE/envs/$e/bin/python" -c "import sys; print('$e', sys.version.split()[0], 'OK')"; done
下載包的 setup_envs.sh 第 10–13 行

run_all.sh:一鍵重跑

這支在做什麼。它就是 PART 3 的 FF1–FF6 與 PART 4 的 E1–E4 排成一列。讀它的重點不是指令本身,而是每一步用哪個環境、輸出寫到哪裡;第二層要讀的程式,就是這支腳本一行一行叫出來的。

  1 #!/usr/bin/env bash
  2 # fruitfly-lab 一鍵重跑:FF1–FF6 + ViZDoom 1.3.2 對照 + 加做檢查 E1–E4。用法:bash run_all.sh(本課實測時間見 PART 2)
  3 # 需要先跑過上一層的 setup_envs.sh。下載約 400 MB(Shiu 全腦模型 repo + FlyWire 註解檔)。
  4 # 若另外下載了 FlyWire 的 proofread_connections_783.feather,可設 FLYWIRE_FEATHER=<路徑> 讓 FF1 逐條比對。
  5 set -e
  6①HERE="$(cd "$(dirname "$0")" && pwd)"  7②ENVS="$(conda info --base)/envs"  8 B=$ENVS/ffl_brian/bin/python      # Brian2 全腦模型、抽子圖
  9 D=$ENVS/ffl_doom130/bin/python    # ViZDoom 1.3.0:與作者逐局相同
 10 D2=$ENVS/ffl_doom/bin/python      # ViZDoom 1.3.2:版本對照
 11③export PYTHONNOUSERSITE=1 12④cd "$HERE"
下載包的 fruitfly_lab/run_all.sh 第 1–12 行
 13①[ -d repo ] || git clone -q https://github.com/webergithub/fruitfly-lab.git repo 14②git -C repo checkout -q 8c27fe8e70903e09b1d87bae6989051d09161e92 15③[ -d repo/Drosophila_brain_model ] || git clone -q --depth 1 https://github.com/philshiu/Drosophila_brain_model.git repo/Drosophila_brain_model 16 mkdir -p logs results repo/data
 17 cd repo
 18④mkdir -p ../results/author_doom && cp doom/results/*.json ../results/author_doom/ && cp output/validation.json ../results/validation_author.json   # 作者附的結果,留作對照 19⑤[ -f data/flywire_annotations_783.tsv ] || curl -sL -o data/flywire_annotations_783.tsv https://raw.githubusercontent.com/flyconnectome/flywire_annotations/main/supplemental_files/Supplemental_file1_neuron_annotations.tsv
下載包的 fruitfly_lab/run_all.sh 第 13–19 行

這段在做什麼。把作者的程式、Shiu 的全腦模型、FlyWire 的註解檔三樣東西拿到手。下載包不附作者的程式(授權的事見第 1 節),所以是你的電腦自己去 GitHub 取。

 20①echo "FF1 資料核對";      $B ../ext/ff1_compare_conn.py Drosophila_brain_model/Connectivity_783.parquet $FLYWIRE_FEATHER > ../results/ff1_conn.json 2> ../logs/ff1_conn.log 21②echo "FF2 抽子圖";        md5sum circuit/* > ../logs/ff2_md5_committed.txt; $B flycircuit/extract.py > ../logs/ff2_extract.log 2>&1; md5sum circuit/* > ../logs/ff2_md5_rerun.txt 22③echo "FF3 子圖 vs 全腦(約 6 分鐘,會用滿 CPU)"; $B flycircuit/validate.py > ../logs/ff3_validate.log 2>&1; cp output/validation.json ../results/validation_local.json 23④echo "FF4 校準";          $D doom/fly_doom.py --calibrate > ../logs/ff4_calibrate.log 2>&1
下載包的 fruitfly_lab/run_all.sh 第 20–23 行

這段在做什麼。FF1 到 FF4,每一行一步。格式都一樣:echo 印出步驟名,然後用某個環境的 Python 跑一支程式,> 把它印出來的東西存進 logs/ 的一個檔案(2>&1 是把錯誤訊息也存進同一個檔)。PART 3 的終端機節錄就是這些 log 檔的原文。

 24①for v in 132 130; do       # 先跑 1.3.2 對照、最後跑 1.3.0,讓 doom/results/ 停在與作者相同的版本 25②  P=$([ $v = 130 ] && echo $D || echo $D2) 26   echo "FF5 七個條件 × 10 局(ViZDoom 1.3.${v#13})"
 27③  for p in fly scrambled scrambled_cal lesion lesion025 random oracle; do $P doom/fly_doom.py --policy $p --episodes 10 > ../logs/ff5_${p}_v$v.log 2>&1; done 28④  echo "FF6 統計";        $P doom/analyze.py > ../logs/ff6_analyze_v$v.log 2>&1 29⑤  mkdir -p ../results/local_doom_vizdoom$v && cp doom/results/*.json ../results/local_doom_vizdoom$v/ 30 done
下載包的 fruitfly_lab/run_all.sh 第 24–30 行

這段在做什麼。FF5 與 FF6 要跑兩次:一次用 ViZDoom 1.3.2 當對照(PART 3 第 8 節),一次用作者的 1.3.0。所以用一個迴圈:同一段程式對 132、130 兩個值各跑一遍。

 31①echo "E1–E3 加做檢查(ViZDoom 1.3.0 + 1.3.2)"; $D ../ext/ff_extra.py E1 E2 E3 > ../logs/ext_vizdoom130.log 2>&1; $D2 ../ext/ff_extra.py E1 > ../logs/ext_vizdoom132.log 2>&1 32②echo "E4 右側不對稱";     $B ../ext/e4_asymmetry.py > ../logs/e4_asymmetry.log 2>&1 33③git checkout -q _vizdoom.ini doom/results output 2>/dev/null || true   # 還原作者附的檔案;本機結果都在 ../results/ 34④cd "$HERE"; "$D" ../check.py fruitfly
下載包的 fruitfly_lab/run_all.sh 第 31–34 行
讀到這裡你已經有第二層的目錄。run_all.sh 總共叫了八支 Python 程式:我們的 ff1_compare_conn.py、ff_extra.py、e4_asymmetry.py、check.py,作者的 extract.py、validate.py、fly_doom.py、analyze.py。下面兩節照這個順序讀。

3第二層:我們自己寫的四支程式

這四支都在下載包裡,講到的段落照原檔放。它們的共同原則寫在 PART 4 第 1 節:只匯入作者的程式,不修改它(匯入的意思見第 1 節的詞表);結果另外存,不蓋掉重現的輸出。

check.py:驗收

這支在做什麼。run_all.sh 跑完的最後一步。它讀 expected.json(本課實跑的結果,每一項寫著「去哪個檔、取哪個值、用哪種標準比」),逐項去你的 results/ 與 logs/ 取值,比對後印 ✓、✗ 或 △。PART 3 第 1 節講的三種判定標準,在這裡變成五種程式判法。

  1 """驗收:把 run_all.sh 跑出來的數字跟 expected.json(本課實跑的結果)逐項比對。
  2 用法:python check.py fruitfly   (在 pack 根目錄或子資料夾都可以)
  3 判定有五種:exact(逐位相同)、rel(相對誤差在容許範圍內,用在沒有固定亂數種子的全腦模型)、
  4 same(兩個檔案內容相同)、contains(終端輸出裡出現預期的那幾行)、md5_twice(同一支程式跑兩次的 md5 相同且等於預期)。"""
  5①import json  6 import os  7 import sys  8 
  9②ROOT = os.path.dirname(os.path.abspath(__file__)) 10③SUB = {"fruitfly": "fruitfly_lab"}
下載包的 check.py 第 1–10 行
 13①def get(path, keys, pluck=None, mean=False): 14②    with open(path) as f: 15         d = json.load(f) if path.endswith(".json") else f.read() 16③    for k in keys: 17         d = d[k] 18④    if pluck:                      # 一串 dict 裡取同一個欄位,例如每一局的 kills 19         d = [x[pluck] for x in d] 20⑤    if mean: 21         d = round(sum(d) / len(d), 6) 22     return d
下載包的 check.py 第 13–22 行
 25 def main(which):
 26①    exp = json.load(open(os.path.join(ROOT, "expected.json")))[which] 27②    base = os.path.join(ROOT, SUB[which]) 28     ok = bad = known = 0
 29③    for c in exp: 30         try:
 31④            got = get(os.path.join(base, c["file"]), c.get("keys", []), c.get("pluck"), c.get("mean", False))
下載包的 check.py 第 25–31 行
 32①            if c["kind"] == "exact": 33                 good = got == c["value"]
 34②            elif c["kind"] == "rel": 35                 v = c["value"]
 36                 good = abs(got - v) <= c["tol"] * max(abs(v), 1e-9)
 37③            elif c["kind"] == "same": 38                 other = get(os.path.join(base, c["other"]), [])
 39                 good = got == other
 40④            elif c["kind"] == "contains": 41                 good = all(v in got for v in c["value"])
 42⑤            elif c["kind"] == "md5_twice":     # 同一支程式跑兩次,兩行 md5 相同且等於預期 43                 h = got.split()[0::2]
 44                 good = len(h) == 2 and h[0] == h[1] == c["value"]
 45             else:
 46                 good = False
 47⑥        except (OSError, KeyError, IndexError, ValueError) as e: 48             got, good = f"讀不到({type(e).__name__})", False
下載包的 check.py 第 32–48 行

這段在做什麼。五種判法。if … elif … else 讀成「如果是這種…否則如果是那種…都不是就…」。

 49①        if not good and c.get("known"):         # 本課實跑時就不符、頁面上已說明的項目 50             known += 1 51             print(f"△ {c['step']:6s} {c['what']} 本次 {got!r};已知:{c['known']}") 52             continue
 53         ok += good
 54         bad += not good
 55②        mark = "✓" if good else "✗" 56         print(f"{mark} {c['step']:6s} {c['what']}" + ("" if good else f" 本次 {got!r},預期 {c.get('value', c.get('other'))!r}")) 57     tail = f",{known} 項已知不符(△,本課實跑時也一樣)" if known else ""
 58③    print(f"\n{which}:{ok} 項通過,{bad} 項不符{tail}(共 {ok + bad + known} 項)") 59     return bad
下載包的 check.py 第 49–59 行

ff1_compare_conn.py:FF1,數連線表

這支在做什麼。FF1 要確認 Shiu 全腦模型附的那張連線表(每一對神經元之間幾個突觸)就是 FlyWire 官方的那一份。學員的電腦上只有 Shiu 這一份,所以程式平常只數它的三個總數;若另外下載了 FlyWire 的原檔,才逐條比對。

  1 """FF1:核對 Shiu 全腦模型附的 FlyWire 連線表(Connectivity_783.parquet)。
  2 只給一個檔案:印出神經元數、連結數、突觸總數。
  3 再給第二個檔案(另外下載的 FlyWire proofread_connections_783.feather):逐條比對兩份是否相同。"""
  4 import json
  5 import sys
  6 
  7①import pandas as pd  8 
  9②shiu = pd.read_parquet(sys.argv[1]) 10③out = {"shiu_edges": len(shiu), "shiu_synapses": int(shiu.Connectivity.sum()), 11        "shiu_neurons": int(pd.unique(pd.concat([shiu.Presynaptic_ID, shiu.Postsynaptic_ID])).size)}
下載包的 fruitfly_lab/ext/ff1_compare_conn.py 第 1–11 行
 12①if len(sys.argv) > 2: 13     loc = pd.read_feather(sys.argv[2])
 14     pre = [c for c in loc.columns if "pre" in c.lower() and "id" in c.lower()][0]
 15     post = [c for c in loc.columns if "post" in c.lower() and "id" in c.lower()][0]
 16     cnt = [c for c in loc.columns if "syn" in c.lower() and "count" in c.lower()][0]
 17②    agg = loc.groupby([pre, post])[cnt].sum().reset_index()      # 同一對神經元在不同神經氈的列合併 18     out.update({"local_rows": len(loc), "local_edges_after_neuropil_merge": len(agg),
 19                 "local_synapses": int(agg[cnt].sum()),
 20                 "local_neurons": int(pd.unique(pd.concat([agg[pre], agg[post]])).size)})
 21③    m = shiu.merge(agg, left_on=["Presynaptic_ID", "Postsynaptic_ID"], right_on=[pre, post], how="outer", indicator=True) 22     out["only_shiu"] = int((m._merge == "left_only").sum())
 23     out["only_local"] = int((m._merge == "right_only").sum())
 24     both = m[m._merge == "both"]
 25     out["both"] = len(both)
 26④    out["count_equal_frac"] = float((both.Connectivity == both[cnt]).mean()) 27⑤print(json.dumps(out, indent=1))
下載包的 fruitfly_lab/ext/ff1_compare_conn.py 第 12–27 行

ff_extra.py:E1、E2、E3

這支在做什麼。PART 4 的三項檢查。它不複製作者的程式,而是把作者的 fly_doom.py 整個匯入進來,借用它的遊戲迴圈、大腦與校準流程,只換掉需要換的那一小塊。這是「不改作者的模型」能成立的方法。先看開頭的說明與匯入:

  1 """計畫第 5 節:作者沒做、本輪加做的檢查(E1–E3)。不改作者程式碼:匯入 doom/fly_doom.py,
  2 把 RESULTS 指到 ../results/ext_vizdoom<版本>/,需要的新條件在這裡另外定義。
  3 在 repo/ 目錄下執行:ffl_doom 環境  python ../ext/ff_extra.py [E1|E2|E3 ...]
  4 
  5①  E1 加大樣本:fly / lesion025 / scrambled_cal / random 各 50 局(種子 0–49),重算配對置換 p  6②  E2 打亂對照逐一校準:作者 scrambled_cal 的閾值只在打亂種子 100 上校準,卻套用到每局不同的打亂;  7      這裡 10 組打亂各自校準,各跑 5 局
  8③  E3 拆開 lesion:作者的開火條件讀 AOTU019,靜音 AOTU019 就必然 0 殺。改用與 AOTU019 無關的讀出  9      (轉向 = DNa02 右減左;開火 = 兩側 DNa02 較小者 > 閾值,閾值同作者方法在 0° 校準),
 10      比較 fly_alt(完整迴路)與 lesion019_alt(靜音 AOTU019 左右),各 50 局
 11 """
下載包的 fruitfly_lab/ext/ff_extra.py 第 1–11 行
 12 import json, sys, shutil
 13 from pathlib import Path
 14 import numpy as np
 15 
 16①ROOT = Path(__file__).resolve().parent.parent / "repo" 17②sys.path.insert(0, str(ROOT / "doom")); sys.path.insert(0, str(ROOT / "flycircuit")) 18③import fly_doom as fd                                         # noqa: E402 19 from lif import Circuit                                        # noqa: E402 20 
 21 import vizdoom                                                 # noqa: E402
 22④EXT = ROOT.parent / "results" / f"ext_vizdoom{vizdoom.__version__}"; EXT.mkdir(parents=True, exist_ok=True) 23 for f in ["calibration_fly.json", "calibration_scrambled.json"]:
 24     shutil.copy(ROOT / "doom" / "results" / f, EXT / f) 25⑤fd.RESULTS = EXT 26 rng = np.random.default_rng(0)
下載包的 fruitfly_lab/ext/ff_extra.py 第 12–26 行
 29①def perm_p(a, b, n=20000): 30     d = np.asarray(a, float) - np.asarray(b, float) 31②    flips = rng.choice([-1, 1], size=(n, d.size)) 32③    return float(((np.abs((flips * d).mean(axis=1)) >= abs(d.mean()) - 1e-12).sum() + 1) / (n + 1)) 33 
 34 
 35 def kills(out):
 36     return [e["kills"] for e in out["episodes"]]
 37 
 38 
 39 def summary(k):
 40④    k = np.asarray(k, float); se = k.std(ddof=1) / np.sqrt(len(k)) 41     return dict(n=len(k), mean=round(float(k.mean()), 2), sd=round(float(k.std(ddof=1)), 2), 42                 ci95=[round(float(k.mean() - 1.96 * se), 2), round(float(k.mean() + 1.96 * se), 2)])
下載包的 fruitfly_lab/ext/ff_extra.py 第 29–42 行

這段在做什麼。三個小工具。perm_p 是 PART 3 第 7 節講的 p 值算法;summary 算平均、標準差和 95% 信賴區間。

 45①def play_with(policy_fn, tag, episodes, seed=0): 46     """借用 fd.play 的遊戲迴圈,只換 make_policy。"""
 47②    orig = fd.make_policy 48③    fd.make_policy = lambda name, circuit, s: policy_fn(circuit, s) 49     try:
 50④        return fd.play(tag, episodes, seed) 51     finally:
 52⑤        fd.make_policy = orig
下載包的 fruitfly_lab/ext/ff_extra.py 第 45–52 行

這段在做什麼。這八行是整支程式的中心思想。作者的 fd.play 是遊戲迴圈(開局、每一格問大腦要按什麼、記分),它在裡面叫 fd.make_policy 來拿「大腦+讀出」。我們想換讀出,但不想改作者的檔案,就在執行的時候把 fd.make_policy 暫時換成我們的,跑完再換回來。

 55 def e1():
 56     res = {}
 57①    for p in ["fly", "lesion025", "scrambled_cal", "random"]: 58②        res[p] = kills(fd.play(p, 50, 0)) 59     out = {p: summary(k) for p, k in res.items()}
 60     for p in res:
 61         if p != "fly":
 62③            out[p]["p_vs_fly"] = perm_p(res["fly"], res[p]) 63④    out["fly_first10_vs_lesion025_first10_p"] = perm_p(res["fly"][:10], res["lesion025"][:10]) 64     return dict(kills=res, summary=out)
下載包的 fruitfly_lab/ext/ff_extra.py 第 55–64 行
 67①def calibrate_circuit(c, steer=fd.steer_signal, fire_keys=("AOTU019_L", "AOTU019_R"), silenced=(), seed=0): 68     """逐行照抄 fd.calibrate 的方法(每個方位先跑 10 tic 暖機,再取 20 tic 平均;轉向閾值取 |steer| 在 0° 與 ±10° 較小者的中點;
 69     開火閾值取 0° 時 fire_keys 較小者的一半,下限 1),但可換電路、換讀出、可靜音,且不寫檔。"""
 70     by = {}
 71②    for az in fd.CAL_AZ: 72         brain = fd.FlyBrain(c, seed=seed, silenced=silenced) 73③        for _ in range(10): 74             brain.step([(float(az), 1.0)])
 75         acc = {k: 0.0 for k in fd.PANEL}
 76④        for _ in range(20): 77             r = brain.step([(float(az), 1.0)])
 78             for k in fd.PANEL:
 79                 acc[k] += r[k] / 20
 80         by[az] = acc
 81⑤    s0 = abs(steer(by[0])); s_off = min(abs(steer(by[-10])), abs(steer(by[10]))) 82     turn_th = (s0 + s_off) / 2 if s_off > s0 else max(1.1 * s0, 1.0) 83⑥    fire_th = max(0.5 * min(by[0][fire_keys[0]], by[0][fire_keys[1]]), 1.0) 84     return dict(turn_th=turn_th, fire_th=fire_th, quiet_th=5.0), by
下載包的 fruitfly_lab/ext/ff_extra.py 第 67–84 行

這段在做什麼。E2 與 E3 都要重新校準,但校準的對象不是作者的迴路(E2 換成打亂的接線,E3 換成讀 DNa02)。作者的 fd.calibrate 寫死了用完整迴路與作者的讀出,所以這裡照抄它的步驟,把「用哪個迴路、讀哪幾顆、算哪個訊號」改成可以指定的。PART 1 第 4 節的兩條閾值規則就是第 81–83 行。

 87 def e2():
 88     base = Circuit(); res = [] 89①    for k in range(10): 90②        c = base.scrambled(seed=100 + k) 91③        cal, _ = calibrate_circuit(c) 92 
 93         def pol(circuit, s, c=c, cal=cal):
 94             brain = fd.FlyBrain(c, seed=s)
 95 
 96             def act(targets):
 97④                r = brain.step(targets); st = fd.steer_signal(r) 98                 left, right = int(st < -cal["turn_th"]), int(st > cal["turn_th"]) 99                 fire = int(min(r["AOTU019_L"], r["AOTU019_R"]) > cal["fire_th"])100                 if not targets and sum(r.values()) < cal["quiet_th"]:
101                     left, right = 0, 1
102                 return [left, right, fire], dict(r)
103             return act, brain
104⑤        out = play_with(pol, f"scrambled_selfcal_{k}", 5, seed=1000 + 5 * k)105         res.append(dict(scramble_seed=100 + k, cal={a: round(float(b), 2) for a, b in cal.items()}, kills=kills(out)))
106     allk = [x for r in res for x in r["kills"]]107⑥    return dict(per_scramble=res, summary=summary(allk))
下載包的 fruitfly_lab/ext/ff_extra.py 第 87–107 行
110 def alt_readout(silence):
111     """與 AOTU019 無關的讀出:轉向 = DNa02 右減左;開火 = 兩側 DNa02 較小者 > 閾值。閾值在完整迴路上以作者同法校準。"""
112①    st = lambda r: r["DNa02_R"] - r["DNa02_L"]113②    cal, by = calibrate_circuit(Circuit(), steer=st, fire_keys=("DNa02_L", "DNa02_R"))114 
115     def pol(circuit, s):
116③        sil = [i for k in silence for i in circuit.groups[k]]117         brain = fd.FlyBrain(circuit, seed=s, silenced=sil)118 
119         def act(targets):
120④            r = brain.step(targets); d = st(r)121             left, right = int(d < -cal["turn_th"]), int(d > cal["turn_th"])122⑤            fire = int(min(r["DNa02_L"], r["DNa02_R"]) > cal["fire_th"])123             if not targets and sum(r.values()) < cal["quiet_th"]:
124                 left, right = 0, 1
125             return [left, right, fire], dict(r)
126         return act, brain
127     return pol, cal, {a: by[a] for a in (-10, 0, 10)}
下載包的 fruitfly_lab/ext/ff_extra.py 第 110–127 行
130 def e3():
131①    pol_f, cal, rows = alt_readout([])132     pol_l, _, _ = alt_readout(["AOTU019_L", "AOTU019_R"])133②    kf = kills(play_with(pol_f, "fly_alt", 50))134     kl = kills(play_with(pol_l, "lesion019_alt", 50))135     return dict(cal={a: round(float(b), 2) for a, b in cal.items()}, cal_rows={str(a): {k: round(v, 1) for k, v in r.items()} for a, r in rows.items()},
136                 fly_alt=summary(kf), lesion019_alt=summary(kl), p=perm_p(kf, kl), kills=dict(fly_alt=kf, lesion019_alt=kl))
137 
138 
139 if __name__ == "__main__":
140③    todo = sys.argv[1:] or ["E1", "E2", "E3"]141     for name in todo:142         r = {"E1": e1, "E2": e2, "E3": e3}[name]()143④        (EXT / f"{name}.json").write_text(json.dumps(r, indent=1))144         print(name, json.dumps({k: v for k, v in r.items() if k not in ("kills", "per_scramble", "cal_rows")}), flush=True)
下載包的 fruitfly_lab/ext/ff_extra.py 第 130–144 行

e4_asymmetry.py:E4,右眼的子圖為什麼反應偏弱

這支在做什麼。PART 3 第 5 節看到右眼刺激時,子圖的 DNa02 右只有 4.4 Hz、全腦 61.6 Hz。E4 想知道差距是不是切子圖時切掉了什麼輸入。做法:讀 FF3 全腦模擬留下的每一顆神經元的放電率,對 DNa02 的每一個上游神經元算「放電率 × 帶正負號的突觸數」(PART 4 第 5 節叫它驅動量),分成在子圖內、不在子圖內兩堆比大小。程式分三步,這裡讀前兩步。它最後的答案(PART 4 第 5 節):DNa02 的直接輸入幾乎全在子圖內,差距不是切掉了外面的輸入,而是子圖內的上游神經元本身在子圖裡放電比在全腦裡弱;第二步量的就是這個差。

 11 ROOT = Path(__file__).resolve().parent.parent / "repo"
 12 OUT = ROOT.parent / "results" / "E4_asymmetry.json"
 13①meta = json.loads((ROOT / "circuit/meta.json").read_text()) 14②sub_ids = {int(n["id"]) for n in meta["neurons"]} 15 groups = {k: [int(meta["neurons"][i]["id"]) for i in v] for k, v in meta["groups"].items()}
 16③ann = pd.read_csv(ROOT / "data/flywire_annotations_783.tsv", sep="\t", low_memory=False, 17                   usecols=["root_id", "cell_type", "hemibrain_type", "side"]).set_index("root_id")
 18④con = pd.read_parquet(ROOT / "Drosophila_brain_model/Connectivity_783.parquet", 19                       columns=["Presynaptic_ID", "Postsynaptic_ID", "Connectivity", "Excitatory x Connectivity"])
 20⑤THR = 5 21 strong = con[con.Connectivity >= THR] 22 lc = {s: set(groups[f"LC10a_{s}"]) for s in "LR"}
下載包的 fruitfly_lab/ext/e4_asymmetry.py 第 11–22 行
 44 def rates(stim):
 45①    df = pd.read_parquet(ROOT / f"Drosophila_brain_model/results/validate/{stim}.parquet") 46     n_run, t_run = df.trial.nunique() if "trial" in df else 5, 1.0
 47②    return (df.groupby("flywire_id").size() / (5 * t_run)).to_dict()
下載包的 fruitfly_lab/ext/e4_asymmetry.py 第 44–47 行
 50 res = {}
 51①for stim in ["LC10a_L", "LC10a_R"]: 52     r = rates(stim)
 53     side = stim[-1]
 54     res[stim] = {}
 55     for dn in ["DNa02_L", "DNa02_R"]: 56         tgt = groups[dn][0]
 57②        inp = con[con.Postsynaptic_ID == tgt].copy() 58③        inp["rate"] = inp.Presynaptic_ID.map(r).fillna(0.0) 59④        inp["drive"] = inp.rate * inp["Excitatory x Connectivity"] 60⑤        inp["in_sub"] = inp.Presynaptic_ID.isin(sub_ids) 61⑥        tot = inp.groupby("in_sub").drive.sum().to_dict() 62⑦        miss = inp[~inp.in_sub & (inp.drive != 0)].sort_values("drive", key=np.abs, ascending=False).head(12)
下載包的 fruitfly_lab/ext/e4_asymmetry.py 第 50–62 行
 78①# ---------- 第二步:DNa02 的輸入幾乎都來自子圖內,所以比較子圖內各突觸前神經元在「子圖模擬」與「全腦模擬」的放電率 79 import sys
 80 sys.path.insert(0, str(ROOT / "flycircuit")) 81②from lif import LIF, Circuit 82 circ = Circuit() 83 ids = np.array([int(n["id"]) for n in circ.meta["neurons"]])
 84 step2 = {}
 85 for stim in ["LC10a_L", "LC10a_R"]:
 86③    rr = np.zeros(circ.n); rates_in = np.zeros(circ.n); rates_in[circ.groups[stim]] = 100.0 87     for k in range(5): 88④        rr += LIF(circ, seed=k).run(10_000, rates_in) / 5.0           # 每秒放電次數
下載包的 fruitfly_lab/ext/e4_asymmetry.py 第 78–88 行

4第二層:作者的四支程式

這四支是 fruitfly-lab 的核心,PART 1 講的四個零件(①連結體、②神經元方程式、③輸入編碼、④讀出規則)都在這裡變成程式。只放片段的理由見第 1 節;每一塊的圖說寫著行號,請打開你 fruitfly_lab/repo/ 底下的同一個檔案對著讀。四支之間的關係:extract.py 切出子圖、寫成兩個檔;validate.py 與 fly_doom.py 都讀那兩個檔、用 lif.py 讓它動起來;analyze.py 只讀 fly_doom.py 寫出來的結果。

extract.py:FF2,從全腦切出子圖

這支在做什麼。PART 1 第 3 節講的切法:沿著突觸數 5 以上的連結,從 LC10a 往下游走 2 步、從轉向下行神經元往上游走 2 步,兩邊都走得到的留下。這支程式就是那段話。先看它開頭的幾個設定值:

 20①THR, DEPTH = 5, 2 21②SOURCE = ["LC10a"] 22③STEER = ["DNa01", "DNa02", "DNa03", "DNa04", "DNa11"] 23④W_SYN_MV = 0.275  # Shiu et al. 2024 每个突触的权重
fruitfly-lab 的 flycircuit/extract.py 第 20–23 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 31①S = set(ann.root_id[ann.cell_type.isin(SOURCE)]) 32②T = set(ann.root_id[ann.cell_type.isin(STEER)]) 33③strong = con[con.Connectivity >= THR]
fruitfly-lab 的 flycircuit/extract.py 第 31–33 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 36①def bfs(start, src_col, dst_col): 37     seen, frontier, dist = set(start), set(start), {n: 0 for n in start}
 38②    for d in range(1, DEPTH + 1): 39③        frontier = set(strong[dst_col][strong[src_col].isin(frontier)]) - seen 40         seen |= frontier
 41         dist.update({n: d for n in frontier})
 42     return seen, dist
 43 
 44 
 45④fwd, dist_fwd = bfs(S, "Presynaptic_ID", "Postsynaptic_ID") 46⑤bwd, _ = bfs(T, "Postsynaptic_ID", "Presynaptic_ID") 47⑥nodes = (fwd & bwd) | S | T
fruitfly-lab 的 flycircuit/extract.py 第 36–47 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。PART 1 白話框裡「從甲城出發兩站以內到得了、而且離乙城兩站以內」的走法,程式叫 bfs(一種從起點一圈一圈往外找的走法)。

 66 # LC10a 视野位置代理:更多连到 AOTU019(中央视野 0–40°)→ 偏中央;更多连到 AOTU025(外周 40–90°)→ 偏外周 67 lc = a.index[a.cell_type == "LC10a"]
 68 aotu = {(t, s): ann.root_id[(ann.cell_type == t) & (ann.side == s)].tolist() for t in ["AOTU019", "AOTU025"] for s in ["left", "right"]}
 69 central = {}
 70①for n in lc: 71     s = a.at[n, "side"]
 72②    out = con[con.Presynaptic_ID == n] 73③    w19 = out.Connectivity[out.Postsynaptic_ID.isin(aotu[("AOTU019", s)])].sum() 74     w25 = out.Connectivity[out.Postsynaptic_ID.isin(aotu[("AOTU025", s)])].sum() 75④    central[n] = float(w19 / (w19 + w25)) if w19 + w25 > 0 else 0.5
fruitfly-lab 的 flycircuit/extract.py 第 66–75 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。PART 1 第 3 節追問過的那件事:「AOTU019 負責視野中央、AOTU025 負責視野外圍」,分工的方向是論文來的,作者在這裡把它變成每顆 LC10a 的偏好位置。註解裡的「0–40°」是作者 README 的概括,論文沒有這個分界,而且論文是用每顆 LC10a 在小葉上的位置推估視野,不是這裡的突觸占比(見 PART 1 第 3 節的附註)。

107 OUT.mkdir(exist_ok=True)
108①(OUT / "meta.json").write_text(json.dumps(meta, ensure_ascii=False, separators=(",", ":")))109②w = e["Excitatory x Connectivity"].clip(-32768, 32767).to_numpy(np.int16)110③with open(OUT / "edges.bin", "wb") as f:111     f.write(offsets.tobytes())112     f.write(e.post.to_numpy(np.uint16).tobytes())113     f.write(w.tobytes())
fruitfly-lab 的 flycircuit/extract.py 第 107–113 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

validate.py:FF3,子圖、打亂接線、全腦各刺激一次

這支在做什麼。PART 3 第 5 節的驗證:刺激一側的 LC10a,看 DNa02 與 AOTU019 的放電率,三種模型各做一次。目的是確認子圖和全腦的反應方向一致(沒切錯),而打亂接線後方向就不一致(接線真的在做事)。

 21①RATE, N_RUN, STEPS = 100.0, 5, 10_000  # 100 Hz, 5 次, 1 s 22②READ = ["LC10a_L", "LC10a_R", "AOTU019_L", "AOTU019_R", "AOTU025_L", "AOTU025_R", 23         "DNa02_L", "DNa02_R", "DNa01_L", "DNa01_R", "DNa03_L", "DNa03_R", "DNa11_L", "DNa11_R"]
fruitfly-lab 的 flycircuit/validate.py 第 21–23 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 28 def run_sub(c, stim_group): 29     out = {k: [] for k in READ}
 30①    rates = np.zeros(c.n) 31     rates[circ.groups[stim_group]] = RATE 32     for r in range(N_RUN): 33②        cnt = LIF(c, seed=r).run(STEPS, rates) 34         for k in READ:
 35③            out[k].append(float(cnt[circ.groups[k]].mean())) 36④    return {k: round(float(np.mean(v)), 2) for k, v in out.items()}
fruitfly-lab 的 flycircuit/validate.py 第 28–36 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 45①    params = dict(default_params, n_run=N_RUN, t_run=1000 * ms, r_poi=RATE * Hz) 46②    stim_ids = [int(ids[i]) for i in circ.groups[stim_group]] 47③    run_exp(exp_name=stim_group, neu_exc=stim_ids, params=params, force_overwrite=True, n_proc=-1, 48             path_res=str(res), path_comp=str(ROOT / "Drosophila_brain_model/Completeness_783.csv"),
 49             path_con=str(ROOT / "Drosophila_brain_model/Connectivity_783.parquet"))
fruitfly-lab 的 flycircuit/validate.py 第 45–49 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 57①for stim in ["LC10a_L", "LC10a_R"]: 58②    for name, fn in [("subgraph", lambda s: run_sub(circ, s)), 59③                     ("scrambled", lambda s: run_sub(circ.scrambled(seed=1), s)), 60④                     ("full_brain", run_full)]: 61         t0 = time.time()
 62         r = fn(stim)
 63         r["_seconds"] = round(time.time() - t0, 1)
 64⑤        r["DNa02_R_minus_L"] = round(r["DNa02_R"] - r["DNa02_L"], 2) 65         results[f"{stim}/{name}"] = r
fruitfly-lab 的 flycircuit/validate.py 第 57–65 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

fly_doom.py:FF4 校準、FF5 玩遊戲

這支在做什麼。PART 1 第 4 節的兩個零件:輸入編碼(敵人方位 → LC10a 的刺激)與讀出規則(放電率 → 按鍵),加上遊戲迴圈和校準。266 行裡大約四分之一是畫錄影用的疊圖與指令列參數,這裡不讀。先看開頭的設定值:

 44 RESULTS = ROOT / "doom" / "results"
 45 DT = 1e-4
 46①STEPS_PER_TIC = round(1 / 35 / DT)  # 286 47②HALF_FOV_DOOM = 45.0                # Doom 水平视野 90° 48③FLY_SCALE = 2.0                     # 屏幕 ±45° → 果蝇视野 ±90° 49④BINO = 6.0                          # 双眼重叠区 ±6°(果蝇视野角),两侧 LC10a 同时受刺激 50⑤MAX_RATE = 150.0                    # LC10a 最大刺激频率 Hz 51 SIGMA = 0.3                         # LC10a 视野位置代理的调谐宽度
 52 TAU_S = 0.1                         # 放电率平滑时间常数
 53 PANEL = ["LC10a_L", "LC10a_R", "AOTU019_L", "AOTU019_R", "AOTU025_L", "AOTU025_R", "DNa02_L", "DNa02_R"]
 54⑥CAL_AZ = [-90, -75, -60, -45, -30, -20, -10, -5, 0, 5, 10, 20, 30, 45, 60, 75, 90] 55 POLICIES = ["fly", "scrambled", "scrambled_cal", "lesion", "lesion025", "random", "oracle"]
fruitfly-lab 的 doom/fly_doom.py 第 44–55 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 61     for lb in state.labels:
 62①        if lb.object_name == "DoomPlayer" or lb.height < 4 or lb.width > lb.height * 1.3: 63             continue
 64②        cx = lb.x + lb.width / 2 65③        az = (cx - 160) / 160 * HALF_FOV_DOOM * FLY_SCALE 66④        out.append((float(np.clip(az, -90, 90)), float(min(1.0, 0.35 + lb.height / 60))))
fruitfly-lab 的 doom/fly_doom.py 第 61–66 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。從遊戲回報的物體清單裡找出敵人、換算成方位角。PART 1 說「模型沒有看畫面的像素」,看的就是這份清單(每個物體在畫面上的位置與大小)。

 70 def steer_signal(r):
 71①    return (r["DNa02_R"] - r["DNa02_L"]) + (r["AOTU019_R"] - r["AOTU019_L"])
fruitfly-lab 的 doom/fly_doom.py 第 70–71 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 89         for az, strength in targets:
 90①            ecc = min(abs(az) / 90.0, 1.0) 91②            sides = ["L", "R"] if abs(az) < BINO else (["R"] if az > 0 else ["L"]) 92             for s in sides:
 93                 ids = self.lc[s] 94③                tune = np.exp(-((self.pref_ecc[ids] - ecc) ** 2) / (2 * SIGMA ** 2)) 95④                rates[ids] = np.minimum(MAX_RATE, rates[ids] + MAX_RATE * strength * tune)
fruitfly-lab 的 doom/fly_doom.py 第 89–95 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。輸入編碼的核心:一個方位角變成每顆 LC10a 的刺激頻率。

 98     def step(self, targets):
 99①        cnt = self.lif.run(STEPS_PER_TIC, self.stim_rates(targets))100         self.last_counts = cnt
101②        hz = cnt / (STEPS_PER_TIC * DT)102         for k, ids in self.idx.items():
103③            self.rate[k] = self.alpha * self.rate[k] + (1 - self.alpha) * float(hz[ids].mean())104         return self.rate
fruitfly-lab 的 doom/fly_doom.py 第 98–104 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
125①    c = circuit.scrambled(seed=seed + 100) if name.startswith("scrambled") else circuit126②    kill = {"lesion": ["AOTU019_L", "AOTU019_R", "AOTU025_L", "AOTU025_R"], "lesion025": ["AOTU025_L", "AOTU025_R"]}.get(name, [])127     silenced = [i for k in kill for i in circuit.groups[k]]128③    brain = FlyBrain(c, seed=seed, silenced=silenced)129④    cal = load_cal("scrambled" if name == "scrambled_cal" else "fly")130 
131     def act(targets):
132         r = brain.step(targets)
133⑤        s = steer_signal(r)134⑥        left, right = int(s < -cal["turn_th"]), int(s > cal["turn_th"])135⑦        fire = int(min(r["AOTU019_L"], r["AOTU019_R"]) > cal["fire_th"])136⑧        if not targets and sum(r.values()) < cal["quiet_th"]:137             left, right = 0, 1  # 没有视觉输入:向右搜索(与 oracle 相同的工程化行为)138         return [left, right, fire], dict(r)
fruitfly-lab 的 doom/fly_doom.py 第 125–138 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。七個條件裡用到大腦的五個,差別全在這幾行:換不換接線、損毀誰、用哪組閾值。然後是讀出規則本身。

187①        while not game.is_episode_finished():188②            st = game.get_state()189③            targets = enemies(st)190④            action, rates = act(targets)191             if ep == 0:
192                 near = min(targets, key=lambda t: abs(t[0]))[0] if targets else None
193                 trace.append({"az": None if near is None else round(near, 1), "a": action,
194                               **({k: round(v, 1) for k, v in rates.items()} if rates else {})})
195                 if record:
196                     frames.append(overlay(st.screen_buffer, rates, action, st.number,
197                                           int(game.get_game_variable(vzd.GameVariable.KILLCOUNT)), policy))
198⑤            game.make_action(action)
fruitfly-lab 的 doom/fly_doom.py 第 187–198 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。遊戲迴圈,一局裡每一格都走一遍。

240     by = {r["az"]: r for r in rows}
241①    s0 = abs(by[0]["steer"])242②    s_off = min(abs(by[-10]["steer"]), abs(by[10]["steer"]))243③    turn_th = (s0 + s_off) / 2 if s_off > s0 else max(1.1 * s0, 1.0)244④    fire_th = max(0.5 * min(by[0]["AOTU019_L"], by[0]["AOTU019_R"]), 1.0)
fruitfly-lab 的 doom/fly_doom.py 第 240–244 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

analyze.py:FF6,統計

這支在做什麼。讀七個條件的 JSON,算每個條件的平均、信賴區間、對 fly 的 p 值,以及第 0 局逐格紀錄的瞄準品質,寫成 analysis.json。PART 3 第 7 節那張表每一欄都從這裡來。

 18①def paired_perm_p(a, b, n=20000): 19     """同一组随机种子下的配对符号翻转置换检验(双侧)。"""
 20②    d = np.asarray(a, float) - np.asarray(b, float) 21     obs = abs(d.mean())
 22③    flips = rng.choice([-1, 1], size=(n, d.size)) 23④    return float(((np.abs((flips * d).mean(axis=1)) >= obs - 1e-12).sum() + 1) / (n + 1))
fruitfly-lab 的 doom/analyze.py 第 18–23 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 36①    off = [f for f in seen if abs(f["az"]) >= BINO] 37②    correct = sum(1 for f in off if (f["az"] > 0 and f["a"][1] and not f["a"][0]) or (f["az"] < 0 and f["a"][0] and not f["a"][1])) 38③    wrong = sum(1 for f in off if (f["az"] > 0 and f["a"][0] and not f["a"][1]) or (f["az"] < 0 and f["a"][1] and not f["a"][0])) 39④    fire_in = sum(1 for f in seen if f["a"][2] and abs(f["az"]) < BINO) 40     fire_all = sum(1 for f in trace if f["a"][2])
fruitfly-lab 的 doom/analyze.py 第 36–40 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

5第三層:lif.py,神經元方程式怎麼變成程式

第二層的四支作者程式裡,validate.py、fly_doom.py 和我們的 e4_asymmetry.py 都寫了 from lif import LIF, Circuit,ff_extra.py 只匯入 Circuit。這是作者自己寫的唯一一個被引用的檔案,裡面兩樣東西:Circuit 負責把 extract.py 寫出來的子圖讀進來(和打亂它),LIF 負責 PART 1 第 2 節那兩條方程式。

Circuit:讀子圖、打亂子圖

 27①        self.meta = json.loads((path / "meta.json").read_text()) 28         n, m = self.meta["n_neurons"], self.meta["n_edges"]
 29         raw = (path / "edges.bin").read_bytes()
 30         o = 4 * (n + 1)
 31②        self.offsets = np.frombuffer(raw, np.uint32, n + 1, 0).astype(np.int64) 32③        self.post = np.frombuffer(raw, np.uint16, m, o).astype(np.int64) 33④        self.w = np.frombuffer(raw, np.int16, m, o + 2 * m).astype(np.float64) * self.meta["w_syn_mv"] 34         self.n, self.m = n, m
 35⑤        self.groups = {k: np.array(v) for k, v in self.meta["groups"].items()}
fruitfly-lab 的 flycircuit/lif.py 第 27–35 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 37①    def scrambled(self, seed=0): 38         """度保持重连对照:每个神经元的出度、入度、正负号(Dale 定律)不变,只打乱"连给谁"。"""
 39         c = object.__new__(Circuit)
 40         c.__dict__.update(self.__dict__)
 41②        c.post = np.random.default_rng(seed).permutation(self.post) 42         return c
fruitfly-lab 的 flycircuit/lif.py 第 37–42 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

LIF:兩條方程式、一條放電規則

這段在做什麼。先把 PART 1 第 2 節的兩條方程式用三句話說一次:V 是神經元的電壓(白話叫水位),一直往「靜止電位(沒有任何輸入時電壓停住的地方,這裡是 −52 mV)加上目前的輸入」靠近,靠近得多快由 τm 決定,這是第一式;g 是它目前收到的輸入總量(水龍頭開度),自己會衰減,多快由 τsyn 決定,這是第二式;V 超過放電閾值就放電、拉回靜止電位。注意這裡的放電閾值是電壓,和前面轉向、開火的閾值(放電率)是兩回事。方程式用的是毫秒、毫伏;程式一步 0.1 ms,要先把每個參數換算成「一步要做的事」。

 86①        self.v0, self.vr, self.vth = float(p["v0"]), float(p["v_rst"]), float(p["v_th"]) 87②        self.a_v = dt * 1e3 / p["t_mbr_ms"] 88③        self.decay_g = float(np.exp(-dt * 1e3 / p["tau_ms"])) 89④        self.rfc_steps = int(round(p["t_rfc_ms"] * 1e-3 / dt)) 90⑤        self.dly = int(round(p["t_dly_ms"] * 1e-3 / dt)) 91⑥        self.kick = float(p["poisson_kick_mv"])
fruitfly-lab 的 flycircuit/lif.py 第 86–91 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
 58             for i in range(n):
 59①                g[i] += buf[slot, i] 60                 buf[slot, i] = 0.0 61                 if mute[i]:
 62                     v[i] = v0
 63                     g[i] = 0.0
 64                     continue
 65                 if rfc[i] <= 0: 66②                    v[i] += a_v * (v0 - v[i] + g[i]) 67③                    g[i] *= decay_g 68                 rfc[i] -= 1 69                 if p_spk[i] > 0.0 and np.random.random() < p_spk[i]: 70④                    v[i] += kick 71⑤                if v[i] > vth: 72⑥                    v[i] = vr 73                     g[i] = 0.0 74⑦                    rfc[i] = rfc_steps 75                     counts[i] += 1 76                     for k in range(offsets[i], offsets[i + 1]): 77⑧                        buf[dst, post[k]] += w[k]
fruitfly-lab 的 flycircuit/lif.py 第 58–77 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)

這段在做什麼。模擬的核心:每一步、每一顆神經元做的事。PART 1 第 2 節分成「隨時都在算」與「事件」兩組,這裡可以逐行對回去。

105①    def run(self, n_steps, rates_hz):106         """跑 n_steps 步,rates_hz 为每个神经元的泊松刺激频率(长度 n)。返回每个神经元的放电次数。"""
107         c = self.c
108②        counts = np.zeros(c.n, dtype=np.int64)109③        p_spk = np.asarray(rates_hz, dtype=np.float64) * self.dt
fruitfly-lab 的 flycircuit/lif.py 第 105–109 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)
讀到這裡,四個零件各在哪個檔案就清楚了。零件①連結體在 extract.py 切、edges.bin 存、Circuit 讀;零件②方程式在 LIF 的核心那二十行;零件③輸入編碼在 fly_doom.py 第 89–95 行(stim_rates 那一段);零件④讀出規則在 fly_doom.py 第 133–135 行與校準的第 241–244 行。PART 1 第 6 節總表說「只有零件①來自資料」,對回程式就是:只有 edges.bin 的內容是從 FlyWire 的表算出來的;其餘三個零件在 lif.py 與 fly_doom.py 裡,參數除了 0.275 mV 之外都是人定的,兩個閾值則是校準程序算出來的,既不是人寫的也不是資料。

6停在哪裡:第三方套件與 Shiu 的全腦模型

再往下就是別人寫的程式庫。本頁不展開它們的原始碼,只列出每一個被誰叫到、做什麼、吃什麼吐什麼。

套件或工具誰叫它做什麼進去的是什麼、出來的是什麼
conda、pipsetup_envs.sh建隔離的 Python 環境、裝指定版本的套件進:環境名、Python 版本、套件清單;出:三個可以執行的 Python
gitrun_all.sh 第 13–15、33 行取得 fruitfly-lab 與 Shiu 的 repo、切到固定 commit、把改動過的檔案還原進:網址與 commit;出:repo/ 資料夾
curl、md5sumrun_all.sh 第 19、21 行下載一個檔案;算檔案的指紋進:網址或檔案;出:檔案或一行指紋
pandas我們的 ff1、e4;作者的 extract讀表格檔、篩選、分組加總、兩表對接進:parquet、tsv、feather;出:表格
numpy幾乎每一支一串數字的運算:相減、平均、隨機抽樣進出都是數字陣列
numbalif.py 第 45–50 行把核心那二十行編譯成機器碼,跑得快很多;沒裝也能跑,走第 115 行以後的純 numpy 版本進:一個 Python 函式;出:同樣行為、更快的版本
ViZDoomfly_doom.py 第 142–152、187–198 行遊戲引擎:開一局 defend_the_center、每一格回報畫面與物體清單、接收按鍵、計分進:三個 0 或 1 的按鍵;出:畫面、物體位置、擊殺數。版本 1.3.0 與 1.3.2 回報的敵人位置不同(PART 3 第 8 節)
Brian2 與 Shiu 等人的程式validate.py 第 40–49 行;e4 讀它的輸出用同一組方程式模擬全腦 138,639 顆神經元。MIT 授權,程式在 repo/Drosophila_brain_model/進:要刺激的神經元 ID、頻率、次數、時間;出:每一顆神經元每一次放電的紀錄(parquet)。沒有固定種子
PIL、imageiofly_doom.py 的 overlay 與 --record把每一格的畫面疊上放電率畫成影片;只在錄影時用,重現不用進:畫面與八個放電率;出:mp4

表裡的行號對回各檔案的原檔(行數記在 out/code_meta.json);138,639 顆出自 PART 3 第 3 節 FF1 的核對(out/fruitfly/logs/ff1_conn.log);ViZDoom 的兩個版本號出自 setup_envs.sh 第 11、12 行。

7總表:每個檔案誰叫它、它產生什麼

檔案層誰叫它讀什麼寫什麼(本課 out/ 裡的對應)
setup_envs.sh一你—三個 conda 環境
run_all.sh一你—logs/ 每一步一個 log(out/fruitfly/logs/)、results/
ff1_compare_conn.py二run_all.sh 第 20 行Shiu 的連線表results/ff1_conn.json,check.py 的 FF1 三項就去這個檔取值(本課實跑時那一版的程式把同樣的 JSON 印在 log 裡,所以本課收在 out/fruitfly/logs/ff1_conn.log;只是存檔位置不同,數字相同)
extract.py二run_all.sh 第 21 行連線表、FlyWire 註解表circuit/meta.json、circuit/edges.bin(md5 在 out/fruitfly/logs/ff2_md5_*.txt)
validate.py二run_all.sh 第 22 行子圖兩檔;Shiu 的程式與資料output/validation.json(out/fruitfly/validation_local.json);Shiu 模型每顆神經元的放電紀錄
fly_doom.py二run_all.sh 第 23、27 行子圖兩檔;校準檔calibration_fly.json、calibration_scrambled.json、七個條件各一個 JSON 與第 0 局逐格紀錄(out/fruitfly/local_doom_vizdoom130/、…132/)
analyze.py二run_all.sh 第 28 行七個條件的 JSON、校準檔analysis.json(同上兩個資料夾)
ff_extra.py二run_all.sh 第 31 行作者的 fly_doom.py、lif.py、校準檔E1.json、E2.json、E3.json(out/fruitfly/ext_vizdoom1.3.0/、…1.3.2/)
e4_asymmetry.py二run_all.sh 第 32 行子圖、註解表、連線表、FF3 的放電紀錄、lif.pyE4_asymmetry.json(out/fruitfly/E4_asymmetry.json)
check.py二run_all.sh 第 34 行expected.json、上面所有輸出終端機上的 ✓/✗/△ 清單(out/fruitfly/runall_test.out)
lif.py三validate、fly_doom、ff_extra、e4circuit/meta.json、circuit/edges.bin不寫檔;回傳每顆神經元的放電次數

行數與常數出自 out/code_meta.json(由 scripts/make_code.py 從原檔抓);頁面上每一個程式區塊由同一支程式產生,--check 逐塊對回原檔。

← PART 5 逐格看迴路怎麼打 回課程首頁 →
BSC 腦空間體研究中心 · 專題課程 果蠅玩 Doom · 教材由 Claude Code 產生 · 回課程首頁