PART 6
從 run_all.sh 那一支腳本開始,一層一層往下讀,讀到作者把神經元方程式寫成程式的那個檔案為止。不教 Python 語法;教的是每一段在做什麼、為什麼要有這一段
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 節)。
下面每一段都會用到這些詞,先在這裡說一次,之後不再解釋。
setup_envs.sh、check.py、fruitfly_lab/,PART 2 第 1 節);跑完之後它的 fruitfly_lab/ 底下會多出 repo/(作者的程式)、logs/、results/。out/:本課自己實跑時收下來的結果,放在本課網站的程式倉庫裡,check.py 的標準答案 expected.json 就是從它抄的。fly 完整接線;scrambled 打亂接線、沿用完整接線的閾值;scrambled_cal 打亂接線、用自己校準的閾值;lesion 損毀 AOTU019 與 AOTU025;lesion025 只損毀 AOTU025;random 不用大腦、每格亂按;oracle 不用大腦、直接照遊戲回報的敵人方位轉向開火(PART 1 第 5 節)。每一段程式都照同一個格式:先用一段話說這段在做什麼、為什麼要有這一段,然後放程式,程式下面逐行解釋。程式區塊左邊的數字是原檔的行號,和你下載下來的檔案完全一致;底色標出的行是接下來要講的行;行號旁的 ①②③ 是解釋裡用的標記。下面拿 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 行B 的名字裡,之後要用那個環境的 Python 時只要寫 $B。這種「給一個東西取名字、之後用名字代替它」叫變數,程式裡到處都是。D。# 後面灰色的字是註解:寫給人看的說明,電腦跳過不執行。本課自己寫的六個檔案在下載包裡,這一頁只放講到的段落,沒講到的行跳過(行號照原檔,缺的行可以對照下載包)。作者 fruitfly-lab 的五個檔案,repo 沒有附授權檔(授權是什麼,見首頁〈出處〉),本課的規矩是不轉發它的任何檔案,所以這一頁只引講到的那幾行、標明 commit 與行號,請對照你自己 clone 下來的檔案讀(run_all.sh 第一次跑就會幫你 clone,在 fruitfly_lab/repo/ 底下)。
建三個 conda 環境
一鍵重跑:取得程式與資料、FF1–FF6、1.3.2 對照、E1–E4、驗收
驗收:把你的結果和本課實跑的結果逐項比對
FF1:數連線表的三個總數
E1–E3:50 局、各自校準、只讀 DNa02
E4:右眼子圖為什麼反應偏弱
FF2:從全腦切出子圖
FF3:子圖、打亂接線、全腦各刺激一次
FF4、FF5:校準、玩遊戲
FF6:七個條件的統計與 p 值
神經元方程式、載入子圖、打亂接線
行數由 scripts/make_code.py 數出,記在 out/code_meta.json;我們的六個檔案合計 423 行,作者的五個合計 673 行。本頁每一個程式區塊都由同一支程式從原檔照抄,make_code.py --check 會逐塊確認和原檔一致。
這支在做什麼。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 行set -e:之後任何一行失敗,整支腳本立刻停。沒有這一行,建環境失敗了腳本還會繼續往下裝套件,錯誤會被埋掉。CONDA_BASE。不寫死路徑,換一台電腦也能跑(PART 2 第 5 節的可攜測試就是在驗這件事)。PYTHONNOUSERSITE=1:叫 Python 不要去家目錄的 ~/.local 找套件。PART 2 第 6 節那個「悄悄改變結果的陷阱」就是靠這一行擋掉的:家目錄裡若另外裝過同名但不同版本的套件,Python 會先拿它,結果就不同,而且不會有任何警告。export 的意思是這個設定連同之後叫出來的每一個程式都生效。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 行mk 的函式:把「建一個環境」這件事打包,下面三個環境各叫一次就好。$1、$2 是叫它時給的第一、第二個值(環境名、Python 版本)。三個用 || 接起來的指令讀成「或者」:先看環境在不在(conda env list | grep),在就什麼都不做;不在就 conda create;連 create 都失敗,就加 --solver classic 再試一次。最後那個備案是可攜測試時撞到的:conda 預設的求解器在某些安裝裡會壞掉(PART 2 第 5 節)。${@:3} 是「第三個以後的所有值」,也就是下面每一行列的套件清單。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 行mk。每個套件後面的 == 是版本號,寫死的理由在 PART 2 第 4 節:換一個小版號,結果就對不上。第 10 行是 Brian2 那個環境(跑 FF3 的全腦模型與 FF2 的切子圖),第 11 行是和作者同版的 ViZDoom 1.3.0,第 12 行是對照用的 1.3.2。這支在做什麼。它就是 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 行HERE。這樣不管你在哪個資料夾打 bash .../run_all.sh,它都知道 ext/(本課自己寫的程式)、logs/(每一步印出的文字)、results/(算出來的結果檔)在哪。$B(Brian2)、$D(1.3.0)、$D2(1.3.2)。下面每一行前面的 $B、$D 就是在選環境。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 取。
[ -d repo ] || 讀成「如果 repo 這個資料夾還不存在,就」git clone:把 fruitfly-lab 整個 repo 複製下來,放進 repo/。第二次跑就跳過。8c27fe8(首頁〈出處〉解釋過 commit 是什麼)。沒有這一行,作者之後改了程式,你跑到的就不是本課重現的那一版。--depth 1 只拿最新版、不拿歷史,省下載量。放在 repo/Drosophila_brain_model/,因為作者的程式寫死去那裡找它。out/ 裡的數字檔都是它)先複製到 results/author_doom/ 留作對照。等一下作者的程式會把自己的輸出寫進同樣的位置,不先存一份,作者的數字就被蓋掉了。curl 下載 FlyWire 的神經元註解表(每顆神經元叫什麼型、在左半腦還是右半腦;連線表只有編號,名字要靠這張表)。作者的 extract.py 第 25 行要讀它,但 repo 裡沒附。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 檔的原文。
ff1_compare_conn.py,讀 Shiu 附的連線表,印三個總數成 JSON。最後那個 $FLYWIRE_FEATHER 平常是空的;設了才會做逐條比對(第 3 節)。extract.py 重切一次,再算一次 md5。兩份指紋檔之後由 check.py 比對,目的是確認你電腦上重切出來的子圖檔和作者附的一個位元都不差。validate.py。它會啟動 Shiu 的全腦模型,所以用 Brian2 環境,也是整支腳本最花時間的一步。跑完把輸出複製成 validation_local.json,和第 18 行存下來的作者版本並排。fly_doom.py --calibrate,量 17 個方位的反應、算出轉向與開火的兩個閾值(PART 1 第 4 節)。--calibrate 一次做兩種大腦:完整接線,與第 100 號打亂的接線(打亂的方式由一個種子決定,100 就是那個種子,見第 5 節),寫成兩個校準檔。校準只讓大腦看假想敵人、不經過遊戲,所以和 ViZDoom 的版本無關,只做這一次,之後固定不變。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 兩個值各跑一遍。
for v in 132 130; do … done:v 先是 132、再是 130,中間的幾行各做一次。先 1.3.2 後 1.3.0 是故意的:作者的程式把七個條件的 JSON 寫在 repo/doom/results/,最後跑的版本會留在那裡,讓它停在和作者相同的 1.3.0。不過第 29 行已經把兩版各複製一份,第 33 行又會把這個資料夾還原,所以順序只是保險,沒有功能上的差別;校準檔只有一份、不受版本影響。v 選環境:130 用 $D,否則用 $D2。analyze.py,把七個條件的 JSON 算成平均、信賴區間與 p 值。results/local_doom_vizdoom132/ 或 …130/,兩版才不會互相覆蓋。本課 out/fruitfly/ 底下同名的兩個資料夾就是從這裡收來的。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 行ff_extra.py,1.3.0 環境跑 E1、E2、E3 三項,1.3.2 環境只跑 E1(PART 4 第 2 節的兩版對照)。e4_asymmetry.py,要讀 FF3 全腦模型留下的放電紀錄,所以用 Brian2 環境。results/,repo 回到乾淨狀態。|| true 讓這一行就算失敗也不要觸發第 5 行的 set -e。check.py 驗收。PART 2 第 7 節那份 ✓/✗/△ 的清單就是它印的。ff1_compare_conn.py、ff_extra.py、e4_asymmetry.py、check.py,作者的 extract.py、validate.py、fly_doom.py、analyze.py。下面兩節照這個順序讀。
這四支都在下載包裡,講到的段落照原檔放。它們的共同原則寫在 PART 4 第 1 節:只匯入作者的程式,不修改它(匯入的意思見第 1 節的詞表);結果另外存,不蓋掉重現的輸出。
這支在做什麼。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 行import:把 Python 內建的三個套件接進來用。json 讀寫 JSON 檔(一種用大括號和冒號寫資料的文字格式,本課 out/ 裡的數字檔都是它),os 處理路徑,sys 讀指令列給的參數。第 1–4 行三個引號夾的是這支程式的說明文字,和註解一樣不執行。ROOT:這支程式自己所在的資料夾,和 run_all.sh 的 HERE 同一個想法。"fruitfly" 對到子資料夾名 "fruitfly_lab"。以前這支程式同時驗兩個專案,字典是那時留下的形狀,本課只用一組。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 行def get(…):定義一個函式,叫 get,工作是「打開一個檔,沿著一串鍵走進去,取出一個值」。括號裡是它收的四樣東西:檔案路徑、鍵的串列、可選的 pluck 與 mean。.json 結尾就當 JSON 解析,否則整個當文字讀進來(log 檔走這條)。for k in keys:對鍵的串列裡每一個鍵做一次 d = d[k],也就是一層一層往裡面走。例如 expected.json 寫 ["summary", "kills"],就是先進 summary 再取 kills。pluck:遇到「一串局」這種東西時,從每一局裡取同一個欄位,例如每一局的 kills,變成一串數字。mean:把那串數字取平均。E1 的 50 局平均就是這樣算出來比對的。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 行which 是 "fruitfly")。ROOT/fruitfly_lab。c)做一次下面的事;ok、bad、known 三個計數器從 0 開始。get 取值,存進 got。try 的意思是「試著做,失敗了跳到第 47 行」,檔案不存在也不會讓整支程式當掉,而是記成一項不符。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 讀成「如果是這種…否則如果是那種…都不是就…」。
exact:逐位相同,取到的值要和預期一模一樣。FF1 的三個總數、FF4 的閾值、FF5 的每一局擊殺數、E1–E3 的平均都用它。rel:相對誤差。abs(got − v) 是差距的絕對值,不能超過預期值乘上容許比例 tol。只用在 FF3 的全腦模型,因為它沒有固定種子(PART 3 第 1 節)。same:兩個檔案內容相同。FF2 只用這一種:重切之後的指紋檔(rerun)要和重切之前作者附的(committed)相同。contains:檔案裡要出現預期的那幾段文字。E4 用它確認結果檔存在、而且含右眼刺激的比較。md5_twice:同一支程式跑兩次,兩行 md5 要相同、而且等於預期。本課沒有一項用到它,是以前留下的判法。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 行known 的項目,本課實跑時就不符、頁面上已經說明(FF3 那一項 +22%,PART 3 第 5 節)。不符但有 known 就印 △ 並單獨計數,不算失敗;continue 是跳到下一項。這支在做什麼。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 行pandas:處理表格資料的第三方套件,取短名 pd。整頁後面每一支程式都用它讀表。Connectivity_783.parquet);parquet 是一種壓縮過的表格檔。Connectivity 這一欄加總(突觸總數)、兩欄 ID 合起來有幾個不同的值(神經元數)。這就是 PART 3 第 3 節那三個數:138,639 顆、15,091,983 條、54,492,922 個。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 行merge),outer 的意思是兩邊都保留,indicator 多一欄記每一列是只有左邊有、只有右邊有、還是兩邊都有。results/ff1_conn.json。這支在做什麼。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 行ROOT:作者的 repo 在哪(這支程式在 ext/,往上一層再進 repo/)。fly_doom.py,取短名 fd;之後 fd.play、fd.FlyBrain 全是作者的東西。FlyBrain 是作者程式裡的一顆模擬大腦,把接線、方程式、輸入編碼包成一個東西;本頁說「大腦」都是它。也從 lif.py 匯入 Circuit(第 5 節)。results/ext_vizdoom1.3.0/ 或 …1.3.2/。本課 out/fruitfly/ext_vizdoom1.3.0/ 就是它。第 23–24 行把作者校準出來的兩個閾值檔複製過來,因為作者的程式會去 RESULTS 底下找它們。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% 信賴區間。
d。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 暫時換成我們的,跑完再換回來。
policy_fn(怎麼決定按鍵)、一個名字、局數、種子。make_policy 存起來。lambda 是一行的小函式:不管作者的迴圈給什麼名字,都交給 policy_fn。finally:不管成功或出錯,最後一定換回作者原本的。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 行fd.play,50 局,種子從 0 開始,所以種子 0–9 就是作者那 10 局(PART 4 第 2 節)。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 行。
c、轉向訊號怎麼算 steer(預設用作者的)、開火讀哪兩顆 fire_keys(預設 AOTU019 左右)、要損毀哪些 silenced。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 行cal。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 行silence 給的那幾群神經元整場不放電;E3 的第二個條件給的是 AOTU019 左右。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 行E1 E2 E3、對 1.3.2 只給 E1。E1.json、E2.json、E3.json,就是 PART 4 每一節圖說引的檔案。這支在做什麼。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 行circuit/meta.json(第 4 節 extract.py 寫的)。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 行lif.py,載入子圖(第 5 節)。這四支是 fruitfly-lab 的核心,PART 1 講的四個零件(①連結體、②神經元方程式、③輸入編碼、④讀出規則)都在這裡變成程式。只放片段的理由見第 1 節;每一塊的圖說寫著行號,請打開你 fruitfly_lab/repo/ 底下的同一個檔案對著讀。四支之間的關係:extract.py 切出子圖、寫成兩個檔;validate.py 與 fly_doom.py 都讀那兩個檔、用 lif.py 讓它動起來;analyze.py 只讀 fly_doom.py 寫出來的結果。
這支在做什麼。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 每个突触的权重
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]
flycircuit/extract.py 第 31–33 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)S(起點)。T(終點)。strong。下面走路只走這些。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
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
flycircuit/extract.py 第 66–75 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)這段在做什麼。PART 1 第 3 節追問過的那件事:「AOTU019 負責視野中央、AOTU025 負責視野外圍」,分工的方向是論文來的,作者在這裡把它變成每顆 LC10a 的偏好位置。註解裡的「0–40°」是作者 README 的概括,論文沒有這個分界,而且論文是用每顆 LC10a 在小葉上的位置推估視野,不是這裡的突觸占比(見 PART 1 第 3 節的附註)。
w19 ÷ (w19 + w25) 存成 central:愈接近 1 愈偏中央。兩邊都是 0 的填 0.5。第 86 行把它寫進每顆神經元的描述,fly_doom.py 第 80 行再讀出來用。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())
flycircuit/extract.py 第 107–113 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)circuit/meta.json:神經元清單(型、側、座標、central)、分群、參數。circuit/edges.bin,一個二進位檔,三段接著放:每顆神經元的連結從第幾條開始(offsets)、每條連結連到誰(post)、每條的權重(weight)。第 5 節 lif.py 第 31–33 行用同樣的順序讀回來。這支在做什麼。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"]
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()}
flycircuit/validate.py 第 28–36 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)LIF 跑 10,000 步,種子 r 是 0 到 4;回來的是每顆神經元放了幾次電。種子固定,所以 PART 3 第 5 節說子圖的結果逐位相同。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"))
flycircuit/validate.py 第 45–49 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)run_exp 跑全腦(13 萬多顆)。本頁不追進去(第 6 節);它跑完會把每一顆的放電紀錄存成檔,E4 讀的就是這些檔。這一步沒有固定種子,所以 PART 3 第 1 節對它只要求在誤差範圍內。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
flycircuit/validate.py 第 57–65 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)circ.scrambled(seed=1),怎麼打亂見第 5 節。output/validation.json,run_all.sh 第 22 行把它複製成 validation_local.json。這支在做什麼。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"]
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))))
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"])
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)
doom/fly_doom.py 第 89–95 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)這段在做什麼。輸入編碼的核心:一個方位角變成每顆 LC10a 的刺激頻率。
pref_ecc = 1 − central)和敵人的偏心度愈接近,tune 愈接近 1;差得遠就趨近 0。這是一條鐘形曲線,寬度由 SIGMA 決定。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
doom/fly_doom.py 第 98–104 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)self.rate 就是 PART 5 播放台上那八條曲線。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)
doom/fly_doom.py 第 125–138 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)這段在做什麼。七個條件裡用到大腦的五個,差別全在這幾行:換不換接線、損毀誰、用哪組閾值。然後是讀出規則本身。
scrambled 開頭就用打亂的接線,打亂編號是種子加 100;PART 4 第 3 節「每一局不同的打亂」就是因為種子每局加 1。lesion 四群、lesion025 兩群、其他不損毀。scrambled_cal 用打亂接線自己校準的那組,其他全用完整接線的。PART 4 第 3 節指出的問題(閾值只在第 100 號打亂上校準)就在這一行與第 125 行的組合裡。int(…) 把真假變成 1 或 0。quiet_th,它不是校準出來的,是作者直接寫死的),固定按右轉去找敵人。這是人為設定,作者的註解自己標明了。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)
doom/fly_doom.py 第 187–198 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)這段在做什麼。遊戲迴圈,一局裡每一格都走一遍。
enemies 換算成敵人方位的清單。act。回來一組三個 0 或 1(左、右、開火)。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)
doom/fly_doom.py 第 240–244 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)這支在做什麼。讀七個條件的 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))
doom/analyze.py 第 18–23 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)perm_p 同一個算法;ff_extra.py 就是照這裡抄的。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])
doom/analyze.py 第 36–40 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)trace 是第 0 局全部的格,seen 是其中畫面上有敵人的格;這一行再從中挑出敵人在 ±6° 以外的格。第二層的四支作者程式裡,validate.py、fly_doom.py 和我們的 e4_asymmetry.py 都寫了 from lif import LIF, Circuit,ff_extra.py 只匯入 Circuit。這是作者自己寫的唯一一個被引用的檔案,裡面兩樣東西:Circuit 負責把 extract.py 寫出來的子圖讀進來(和打亂它),LIF 負責 PART 1 第 2 節那兩條方程式。
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()}
flycircuit/lif.py 第 27–35 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)meta.json:神經元清單、分群、參數。edges.bin 的三段,順序和 extract.py 第 111–113 行寫的時候一樣:每顆神經元的連結從第幾條開始、每條連到誰、每條的權重。權重讀進來乘 0.275 mV,變成「上游放一次電,下游的 g 加多少」(g 是下一段要講的「這顆神經元目前收到的輸入總量」)。"LC10a_L" 對到左眼那 115 顆的編號。validate.py 與 fly_doom.py 選要刺激、要讀的神經元,用的就是這個字典。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
flycircuit/lif.py 第 37–42 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)permutation),起點(offsets)和權重(w)都不動。所以每顆神經元送出幾條、每條多強、正負號,全部和原本一樣,只有「連到誰」變了。seed 決定重排的方式;同一個 seed 永遠得到同一種重排,這就是 PART 4 第 3 節說的打亂「編號」。這段在做什麼。先把 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"])
flycircuit/lif.py 第 86–91 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)a_v = 一步的長度 ÷ τm(0.1 ÷ 20)。第一式是 τm·dV/dt = −(V − Vrest) + g,Vrest 就是靜止電位;程式把它換成「每一步把 V 往目標移動 a_v 這個比例」。decay_g = e 的 (−0.1 ÷ 5) 次方:第二式每一步 g 要乘的那個「關回去」的係數。PART 1 第 2 節「每過 5 ms 剩約 37%」,就是這個係數連乘 50 步。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]
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
flycircuit/lif.py 第 105–109 行(commit 8c27fe8;repo 沒有授權檔,本頁只引片段,請對照你自己 clone 下來的檔案)stim_rates 那一段);零件④讀出規則在 fly_doom.py 第 133–135 行與校準的第 241–244 行。PART 1 第 6 節總表說「只有零件①來自資料」,對回程式就是:只有 edges.bin 的內容是從 FlyWire 的表算出來的;其餘三個零件在 lif.py 與 fly_doom.py 裡,參數除了 0.275 mV 之外都是人定的,兩個閾值則是校準程序算出來的,既不是人寫的也不是資料。
再往下就是別人寫的程式庫。本頁不展開它們的原始碼,只列出每一個被誰叫到、做什麼、吃什麼吐什麼。
| 套件或工具 | 誰叫它 | 做什麼 | 進去的是什麼、出來的是什麼 |
|---|---|---|---|
| conda、pip | setup_envs.sh | 建隔離的 Python 環境、裝指定版本的套件 | 進:環境名、Python 版本、套件清單;出:三個可以執行的 Python |
| git | run_all.sh 第 13–15、33 行 | 取得 fruitfly-lab 與 Shiu 的 repo、切到固定 commit、把改動過的檔案還原 | 進:網址與 commit;出:repo/ 資料夾 |
| curl、md5sum | run_all.sh 第 19、21 行 | 下載一個檔案;算檔案的指紋 | 進:網址或檔案;出:檔案或一行指紋 |
| pandas | 我們的 ff1、e4;作者的 extract | 讀表格檔、篩選、分組加總、兩表對接 | 進:parquet、tsv、feather;出:表格 |
| numpy | 幾乎每一支 | 一串數字的運算:相減、平均、隨機抽樣 | 進出都是數字陣列 |
| numba | lif.py 第 45–50 行 | 把核心那二十行編譯成機器碼,跑得快很多;沒裝也能跑,走第 115 行以後的純 numpy 版本 | 進:一個 Python 函式;出:同樣行為、更快的版本 |
| ViZDoom | fly_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、imageio | fly_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 行。
| 檔案 | 層 | 誰叫它 | 讀什麼 | 寫什麼(本課 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.py | E4_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、e4 | circuit/meta.json、circuit/edges.bin | 不寫檔;回傳每顆神經元的放電次數 |
行數與常數出自 out/code_meta.json(由 scripts/make_code.py 從原檔抓);頁面上每一個程式區塊由同一支程式產生,--check 逐塊對回原檔。