pwquint24/org-babel-polyglot

多語言數據管線與 Org Babel 的互操作性

Org Babel 最強大的功能之一是語言無關的互操作性：數據可以在同一個文件中，在多種程式語言、Org 表格和公式之間無縫流動。

一個筆記本可以在 SQL 中查詢數據，在 Python 中轉換和清理，在 R 中進行統計建模，在 Shell 中執行系統命令，並在 Gnuplot 或 Matplotlib 中視覺化結果 — 而 Org Mode 則扮演通用數據匯流排的角色。

---

1. 通用數據傳遞機制：:var

:var 標頭參數在所有支援的語言中具有相同的語法：

:var VARIABLE_NAME=ASSIGNMENT
:var VARIABLE_NAME=FILE:REFERENCE

1.1 :var 支援的賦值類型

輸入來源	語法範例	備註
字面值	:var n=42 text="sample"	數字、布林值和字串。
具名 Org 表格	:var data=raw_measurements	將 2D 表格作為巢狀串列/資料框傳遞。
具名純串列	:var items=todo_list	將頂層串列項目作為陣列/向量傳遞。
無參數的程式碼區塊	:var stats=compute_stats()	執行 compute_stats 並傳遞其回傳值。
有參數的程式碼區塊	:var res=calc(rate=0.05, n=12)	使用指定參數評估目標區塊。
區塊內容 / 字面值	:var template=config_template[]	傳遞範例或程式碼區塊的逐字內容。
Emacs Lisp 評估	:var file=(buffer-file-name)	任何以 (, [, ' 或 ` 開頭的值都會被當作 Elisp 評估。
外部 Org 檔案	:var ext=other.org:data_table	解析外部檔案內的參考。

---

2. 傳遞和格式化 Org 表格

Org 表格會自動轉換為原生結構（Python 的串列串列、R 的資料框等）。標頭參數控制表格的預處理：

2.1 表格預處理參數

• :colnames yes | no | nil（預設：nil）：
  • 當為 nil 時：如果表格第 1 行下方有水平線，Babel 會移除標頭，轉換行，並將標頭重新套用於回傳的表格。
  • 當為 yes 時：明確將第一行視為欄位名稱/標頭。
  • 當為 no 時：將第一行視為普通數據。
• :rownames yes | no（預設：no）：
  • 當為 yes 時：在處理前移除第一欄，並在回傳時將其恢復為行名稱。
• :hlines yes | no（預設：no）：
  • 當為 no（建議）時：在將數據傳遞給直譯器之前，移除所有水平線 (|-...)。這可以防止類型錯誤（例如 None 或 'hline' 字串導致數值例程崩潰）。
  • 當為 yes 時：保留水平線作為 'hline 符號。

2.2 在 :var 中切片和索引表格

你可以在 :var 宣告中使用基於 0 的索引符號 [rows, columns] 直接對行和列進行切片：

#+NAME: full_dataset
| ID | Age | Score |
|----+-----+-------|
|  1 |  25 |  88.5 |
|  2 |  30 |  92.0 |
|  3 |  22 |  79.0 |
|  4 |  35 |  95.5 |

# 僅傳遞 'Score' 欄（欄索引 2，第 1 行到結尾）：
#+BEGIN_SRC python :var scores=full_dataset[1:, 2] :results value
  return sum(scores) / len(scores)
#+END_SRC

#+RESULTS:
: 88.75

• 索引語法：
  • data[0]：第一行。
  • data[,1]：所有行的第二欄。
  • data[1:3, :]：第 1 行到第 3 行，所有欄位（包含）。
  • data[-1]：最後一行。
  • data[*] 或 data[0:-1]：所有行。
• 重要： 索引操作發生在 :colnames 或 :hlines 移除之前。

---

3. 多語言管線模式：SQL -> Python -> R -> 圖形

這是一個完整的多語言數據工作流程：

#+TITLE: Multi-Language Pipeline

* Step 1: Database Query (SQLite)
提取原始事件計數：

#+NAME: raw_events
#+BEGIN_SRC sqlite :db telemetry.db :results table :colnames yes
  SELECT device_id, event_type, count(*) as count
  FROM events
  WHERE event_date >= '2025-01-01'
  GROUP BY device_id, event_type;
#+END_SRC

#+RESULTS: raw_events
| device_id | event_type | count |
|-----------+------------+-------|
| dev-01    | heartbeat  |  1420 |
| dev-01    | alert      |    12 |
| dev-02    | heartbeat  |  1380 |
| dev-02    | alert      |    45 |

* Step 2: 數據清理與標準化 (Python)
將 SQLite 表格載入 Python：

#+NAME: clean_telemetry
#+BEGIN_SRC python :var events=raw_events :colnames yes :results value table
  cleaned = []
  for row in events:
      dev_id, ev_type, count = row[0], row[1], int(row[2])
      rate = round(count / 1440.0, 4)  # events per minute
      cleaned.append([dev_id, ev_type, count, rate])
  return [["Device", "Event", "Count", "RatePerMin"]] + cleaned
#+END_SRC

#+RESULTS: clean_telemetry
| Device | Event     | Count | RatePerMin |
|--------+-----------+-------+------------|
| dev-01 | heartbeat |  1420 |     0.9861 |
| dev-01 | alert     |    12 |     0.0083 |
| dev-02 | heartbeat |  1380 |     0.9583 |
| dev-02 | alert     |    45 |     0.0313 |

* Step 3: 統計建模 (R)
將清理後的 Python 輸出載入 R：

#+NAME: r_stat_summary
#+BEGIN_SRC R :var df=clean_telemetry :colnames yes :results value table
  summary_df <- aggregate(RatePerMin ~ Event, data=df, FUN=mean)
  colnames(summary_df) <- c("Event", "AvgRatePerMin")
  summary_df
#+END_SRC

#+RESULTS: r_stat_summary
| Event     | AvgRatePerMin |
|-----------+---------------|
| alert     |        0.0198 |
| heartbeat |        0.9722 |

---

4. 程式化呼叫區塊：#+CALL: 與內聯 call_

你可以將任何具名區塊視為可重複使用的函數來呼叫，而無需重寫該區塊。

4.1 語法

# 區塊形式：
#+CALL: <name>[<inside_eval_headers>](<arguments>) <end_result_headers>

# 內聯形式：
... call_<name>[<inside_eval_headers>](<arguments>)[<end_result_headers>] ...

• <name>：目標區塊的 #+NAME:。
• <arguments>：函數風格的參數，例如 (n=5, metric="accuracy")。
• [<inside_eval_headers>]：在執行期間套用（例如 [:results output]）。
• [<end_result_headers>]：套用於格式化回傳結果（例如 :results raw）。

4.2 範例

#+NAME: power_calc
#+BEGIN_SRC python :var base=2 exp=3 :results value
  return base ** exp
#+END_SRC

# 使用自訂參數呼叫：
#+CALL: power_calc(base=3, exp=4)

#+RESULTS:
: 81

# 內聯呼叫：
The total capacity is call_power_calc(base=2, exp=8) units.

---

5. 反應式試算表：表格公式中的 Babel (org-sbe)

Org Mode 表格內建了試算表計算器 (#+TBLFM:)。org-sbe 巨集允許任何表格儲存格公式呼叫任意語言的 Babel 區塊：

(org-sbe "block-name" (param1 value1) (param2 value2))
;; 簡寫：
(sbe "block-name" (param1 value1))

範例：由 Python 與 R 公式驅動的表格

#+NAME: py_tax_rate
#+BEGIN_SRC python :var country="US" :results value
  rates = {"US": 0.08, "UK": 0.20, "DE": 0.19}
  return rates.get(country, 0.0)
#+END_SRC

#+NAME: invoice_table
| Item        | Country | Base Price | Tax Rate | Total Price |
|-------------+---------+------------+----------+-------------|
| Server Node | US      |       1200 |     0.08 |      1296.0 |
| Storage SAN | UK      |       3000 |      0.2 |      3600.0 |
| Gateway     | DE      |        800 |     0.19 |       952.0 |
#+TBLFM: $4='(org-sbe "py_tax_rate" (country $"$2")) :: $5=$3 * (1 + $4)

• 在表格中，在 #+TBLFM 行按下 C-u C-c C-c 會重新計算所有公式，為每一行動態評估 Python 區塊！
• $"$2" 將第 2 欄的值作為字串字面值傳遞。

---

6. 使用 :post 進行結果後處理

:post 標頭參數會將區塊的輸出先透過一個次要的格式化區塊處理，然後再插入到文件中。主區塊的輸出會綁定到 *this*：

# 後處理器區塊，用於新增自訂的 LaTeX 匯出屬性：
#+NAME: wrap_latex_figure
#+BEGIN_SRC emacs-lisp :var data="" caption="Figure"
  (format "#+CAPTION: %s\n#+ATTR_LATEX: :width 0.8\\textwidth\n%s" caption data)
#+END_SRC

# 使用 :post 的主要繪圖區塊：
#+BEGIN_SRC python :results file link :file figures/out.pdf :post wrap_latex_figure(caption="Model Accuracy", data=*this*)
  import matplotlib.pyplot as plt
  plt.plot([1, 2, 3], [4, 5, 6])
  plt.savefig("figures/out.pdf")
  plt.close()
  return "figures/out.pdf"
#+END_SRC

---

7. 巴別圖書館：共享的全域函式庫

巴別圖書館 (Library of Babel) 讓你可以將具名區塊匯入並共享到多個不同的 .org 檔案中，而無需重複編寫程式碼。

1. 建立一個共享的函式庫檔案（例如 ~/org/shared_babel.org），其中包含具名區塊。
2. 在 Emacs 工作階段中載入該函式庫：

   (org-babel-lob-ingest "~/org/shared_babel.org")
   

   或透過快捷鍵：C-c C-v i (org-babel-lob-ingest)。
3. 在任何緩衝區中使用 #+CALL: block_name(args) 來呼叫該檔案中的任何區塊！

---

8. 常見的多語言陷阱與最佳實踐

陷阱	後果	解決方案
欄位標頭不匹配	數值計算失敗，因為標頭字串被當作第 0 行數據讀取	在消費表格輸入的區塊上始終指定 :colnames yes。
表格水平線 (`	-`) 導致崩潰	Python/R 在需要數值的地方收到 'hline' 符號
:var 中使用了未具名的區塊	出現 Reference 'xyz' not found in buffer 錯誤	確保輸入區塊或表格的正上方有對應的 #+NAME: xyz 關鍵字。
在 org-sbe 中引用表格儲存格變數	未加引號的文字儲存格會被讀取為未定義的 Lisp 符號	將欄位引用包裹在字串中：(country $"$2")。
帶標頭時的索引順序	索引時 data[0] 會回傳標頭行	注意表格切片發生在 :colnames 移除之前。