十一個 Widgets，一條龍的光譜鑑定流程
安裝後 Orange 工具箱會多一個 Spectra 分類。輸出的資料表採 Orange-Spectroscopy 慣例 （每一欄＝一個波數、每一列＝一條光譜），可直接接 PCA、PLS、階層式分群等 Orange 原生流程。
Import Spectrum URL
貼上 IRUG 編號（如 4119）、IRUG/SOPRANO 頁面網址，或 JCAMP-DX / CSV 直接網址——下載、畫圖、輸出資料表，一鍵完成。可連抓多條累積成一組。
Merge Spectra
把多個光譜來源疊在同一張圖，並輸出成一個合併資料表（每列一條光譜、共同波段），方便一次比對或接後續分析。
Load Spectra Files
一鍵吃整包光譜：資料夾或 .zip（免解壓）裡的 JCAMP-DX、CSV、矩陣 CSV、NetCDF .cdf 全部讀進來，輸出一個合併資料表。
Spectrometer
把「相機＋繞射光柵」拍到的光譜照片變成校準光譜：影像旋轉、取水平帶讀強度、峰值游標自動找峰對準、一鍵把已知譜線寫進校準表，把像素校準成波長（Theremino 分光儀的核心功能）。
Spectra Similarity
兩組光譜的逐對相似度：Pearson correlation、cosine、光譜角 SAM、Euclidean 距離。自動對齊重疊波段再比較。
Spectral Library
把參考譜收進光譜庫、存成 .speclib 檔（與 SpectraView 桌面版完全互通），未知譜對庫搜尋、輸出排名命中表與最佳匹配。
Mixture Analysis
混合光譜 ≈ Σ cᵢ·參考譜ᵢ 的非負最小平方（NNLS）分解：回報每個成分的係數、百分比與擬合 R²，並疊出擬合曲線與殘差。
Aquagram（水光譜學）
Aquaphotomics 分析：在水的 12 個特徵吸收帶（WAMACs）取正規化吸光度，畫成 12 軸雷達圖，比較不同樣品／擾動下水的氫鍵結構差異。
Peak Finder
自動偵測波峰並在圖上標記位置，量測峰位、峰高、半高寬（FWHM）、顯著度與面積，輸出峰表。門檻與平滑可調。
XRF Element ID
XRF 能譜（keV）自動尋峰並比對元素特徵譜線（Kα/Kβ/Lα/Lβ，Na–U 53 元素），圖上直接標出「Fe Kα1」等元素標籤。
PLS-DA
偏最小平方判別分析：依類別上色的分數圖、loadings 與 VIP 變數重要性，一眼看出哪些波段把類別分開。
安裝
▸ 桌面版 App（從 orangedatamining.com 下載的獨立程式，點圖示開）→ 走 方式 A。
▸ pip 版 Orange（自己
pip install orange3、用 python -m Orange.canvas 開）→ 走 方式 B。兩者的 Python 環境不同，裝錯環境 widgets 不會出現。
方式 A ── 桌面版 App（最推薦）
用 App 內建的 Add-ons 對話框，從 PyPI 依名稱安裝：
開 Add-ons
Orange 選單 Options ▸ Add-ons…
Add more… 輸入名稱
按右上 Add more…，輸入 orange-spectra（不是 git 網址——這個框只吃 PyPI 名稱），打勾後按 OK。套件已在
PyPI 上（目前 0.7.0）。
重啟 Orange
工具箱出現 Spectra 分類的 11 個 widgets。
…\Orange\python.exe）執行
python.exe -m pip install orange-spectra。方式 B ── pip 版 Orange
# 1) Orange 與 Qt 綁定（缺 PyQt5 會出現 "PyQt5 ... not available" 而開不了） pip install orange3 PyQt5 PyQtWebEngine # 2) orange-spectra widgets（從 PyPI 裝；要最新開發版才用 git 網址） pip install orange-spectra # 3) 啟動（用這個指令，不要點桌面 App 圖示——那是另一個環境） python -m Orange.canvas
▸
ImportError: PyQt5 … not available → 少裝 Qt，補
pip install PyQt5 PyQtWebEngine。▸ Add-ons 的 Add more… 貼 git 網址得到「packages were not found」→ 那個框只接受 PyPI 名稱，git 網址請走方式 B 的
pip install。▸ 只有要「更新」到新版時才需要重裝：
pip install --upgrade orange-spectra，
然後完全關掉 Orange 再重開。▸ 每個 widget 左上角都有 「ℹ 說明 How to use」盒子與 「📖 開啟線上教學」按鈕， 不會用時點一下就能學。
Widget 逐一教學
Import Spectrum URL — 從網址匯入光譜
- 在輸入框貼上來源，按 Fetch & add：
- IRUG 編號：
4119（＝http://www.irug.org/jcamp-details?id=4119，PB15 酞菁藍 Raman 譜） - SOPRANO 頁面網址（比利時 KIK-IRPA 顏料 Raman 資料庫）
- JCAMP-DX（AFFN）或兩欄 CSV 的直接網址
- IRUG 編號：
- 右側即時畫出光譜（IR/Raman 慣例：波數由高至低）。
- 重複 Fetch 可累積多條光譜；清單可移除單條或全部清空。多條光譜會自動重採樣到共同波段。
<script> 裡（"波數:強度" 配對）；SOPRANO 藏在 Dygraph 資料陣列；也支援 Plotly / Highcharts / Chart.js 等互動圖內嵌的 x/y 陣列（如 INFRA-ART 等資料庫）。widget 直接解析網頁原始碼還原數據。Spectrometer — 影像分光（相機＋繞射光柵）
- 按 Choose spectrum photo… 選一張相機＋繞射光柵拍到的光譜照片。若彩色條是直的（手機直拍很常見），用 Rotate 旋轉 轉 90°／270° 讓色散方向變水平——旋轉是無損的（只換軸、不內插）。
- Channel（luminance／R／G／B／sum）與 Strip centre / height 選要取的水平帶（上圖黃框）。
- Peak cursor 峰值游標：widget 會自動找峰（Min prominence / distance / Smoothing 可調），按「◀ 前一峰／下一峰 ▶」在峰之間跳，游標會吸附到 ±4 px 內的次像素峰位；左下角即時讀出 pixel、強度與 λ。
- 校準：游標對準一個認得的譜線 → 在 λ = 下拉選波長（內建日光燈特徵線 405.4／435.8／546.1 汞、611.6 銪，也可手動輸入）→ 按 寫進校準表 ↓。重複 2–3 條線後選 linear／quadratic 擬合；也可直接手填
像素=波長對。留空則 x 軸維持像素。 - 看 Status 的 R² 檢查校準品質：linear 擬合 R² 應接近 1（≥0.999），某點配錯譜線 R² 會明顯掉下來。注意「點數 = 次數+1」時 R²=1 是必然（exact fit 警告），不能當品質指標——加第 4 條線再看。
- 勾 Zoom plot to the calibrated range 只顯示校準區間（多項式在校準點外會發散，只影響顯示、不影響輸出）；輸出接 Similarity / Library / Peak Finder / Data Table。
Load Spectra Files — 批次載入光譜檔
- Add files… / Add folder… / Add .zip… 加入來源；資料夾會掃描所有光譜檔（可含子資料夾），.zip 免解壓直接讀。
- 支援：JCAMP-DX（AFFN）、兩欄 CSV/TSV、矩陣 CSV（SpectraView「合併匯出」兩種版面都行）、NetCDF .cdf/.nc（classic 格式——applewine 等 chemometrics 資料集、ANDI 層析匯出）。
- 右側疊圖預覽全部光譜；輸出接 Similarity / Library / PLS-DA / Data Table。
Merge Spectra — 多光譜疊圖合併
- 把多個來源接到 Spectra 輸入——多個 Import Spectrum URL、Orange 的 File、或任何欄名＝波數的 Table。
- 右側即時疊圖；Normalize each（none / max=1 / area=1 / SNV）讓不同強度的譜可比較，Stack offset 只把顯示往上錯開、不改數值。
- 輸出是一個合併 Table（每列一條光譜、共同重疊波段），可接 Similarity / Library / Mixture / PLS-DA。
Spectra Similarity — 光譜相似度
- 接上 Data 與 References：輸出 Data × References 每一對的四個指標。
- 只接 Data：改為 Data 內部兩兩互比（適合看一批樣品彼此像不像）。
- 排序依據可選 correlation / cosine（越大越像）或 SAM / Euclidean（越小越像）。
- Similarity Matrix 輸出（0.7.1 起）＝「Sort scores by」所選指標的 Data × References 寬矩陣（只接 Data 時為 n×n 對稱矩陣、對角線＝1）——接 Orange 原生 Heat Map widget 直接畫相似度熱圖，接 Data Table 看矩陣數字。
| 指標 | 意義 | 特性 |
|---|---|---|
| correlation | Pearson 相關係數 | 對位移與縮放都不敏感，鑑定最常用 |
| cosine | 向量夾角餘弦 | 對縮放不敏感 |
| SAM | 光譜角（弧度） | 遙測/高光譜常用，越小越像 |
| euclid | 單位化後歐氏距離 | 直觀的「形狀差多少」 |
Spectral Library — 光譜庫建立與比對
- 把參考譜接到 Spectra 輸入，按 Add input spectra to library 入庫。
- Save… 存成
.speclib；Load… 載入既有庫——檔案格式與 SpectraView 桌面版相同。 - Add built-in 一鍵載入內建庫（下拉選庫名→按鈕）：
▸ 糖類／食品添加物 NIR 庫（9 條；0.7.2 起隨套件內建、離線可用）——教學 Demo ②③ 用的就是這個庫。
▸ UCL 顏料拉曼庫（55 種，Bell, Clark & Gibbs 1997）——第一次按會直接向 UCL 官網下載（連不上時自動改抓 Internet Archive 存檔），之後讀本機快取、離線可用；因授權考量套件本身不含該資料。 - 未知譜接 Query：Hits 輸出每個 query 對每筆庫藏的排名與四個相似度指標，接 Data Table widget 即可檢視。
- Library 輸出把整個庫變成資料表——可以直接接 Mixture Analysis 當參考譜，或接 Spectra 檢視。
- 實例：硃砂樣品接 Query，最佳比對就是 Vermilion（HgS）。小訣竅：庫裡是未經基線校正的原始強度，未知譜先做基線校正（如 ALS）再查詢，correlation 會明顯拉開。發表時請引用 Bell, Clark & Gibbs, Spectrochim. Acta A 53 (1997) 2159。
Mixture Analysis — 混合光譜成分分析
- 混合譜接 Mixture、一組純物質參考譜接 References。
- 用非負最小平方（NNLS）解
mixture ≈ Σ cᵢ·refᵢ (+ offset)；係數強制 ≥ 0，符合物理意義。 - widget 內直接顯示成分表（係數、百分比）與 R²；圖上疊出混合譜、擬合線與殘差。
- Composition 輸出接 Data Table 或 Bar Plot 畫成分比例；Fit 輸出含 mixture / NNLS fit / residual 三列。
Aquagram — 水光譜學（aquaphotomics）雷達圖
Aquaphotomics（Tsenkova）用水在近紅外的 12 個特徵吸收帶（WAMACs，water matrix coordinates，約 1336–1522 nm）當「水的指紋」，把樣品在這 12 個座標的正規化吸光度畫成雷達圖，比較不同狀態（溫度、濃度、品種…擾動）下水的氫鍵結構變化。做法參考 NIRPY Research 的 aquagram 教學。
- 接上 NIR 光譜（可先用 Import Spectrum URL / File 載入，或接 Orange-Spectroscopy 的前處理）。
- 選正規化方式：
- raw：直接取 12 個波段的吸光度。
- snv：先對每條光譜做 SNV（標準常態變量），再取值。
- aquagram（預設，經典正規化）：SNV 後，對整組樣品在每個波段做標準化 (值−均值)/標準差——0 就是這組的平均水譜，往外 = 該波段吸光度高於平均、往內 = 低於平均。
- 右側即時畫出 12 軸雷達圖，每條光譜一條線；WAMACs 波段可在輸入框自訂（預設標準 12 帶）。
- Aquagram Coordinates 輸出是 n×12 的資料表，可再接 PCA、分群或 Data Table 做量化比較。
Peak Finder — 波峰偵測與標記
- 接上光譜，圖上立刻以三角形＋數字標出每個峰的位置。
- Min height / Min prominence（都是訊號全幅的 %）調高可濾掉雜訊小峰；Min distance（x 單位）避免相鄰的重複峰。
- Smoothing window（Savitzky-Golay 點數，0＝關）只影響偵測——峰高仍讀原始訊號，不會被平滑壓低。
- Peaks 輸出接 Data Table：每列一個峰（所屬光譜、峰位、峰高、FWHM、顯著度、高斯估計面積）。
XRF Element ID — XRF 光譜元素標記
- 接上已校正能量軸（keV）的 XRF 譜；widget 自動尋峰。
- 每個峰在容差（Energy tolerance，預設 0.10 keV）內比對特徵譜線資料庫——Kα1/Kβ1/Lα1/Lβ1（X-ray Data Booklet 參考值，Na–U 共 53 個元素）。
- 圖上直接標「Fe Kα1」「Pb Lα1」等；比不到的峰標「?」。Lines 選單可限定只比 K 線或 L 線。
- Elements 輸出表列出每峰的所有候選（峰能量、譜線能量、Δ、峰高、元素、譜線名）——接 Data Table 檢視。
PLS-DA — 偏最小平方判別分析
- 資料要有類別變數：File/Datasets 載入後，用 Select Columns 把類別欄拖到 Target 再接進來。
- widget 把類別 one-hot 編碼後做 PLS2（NIPALS 演算法），分數圖依類別上色；標題顯示訓練準確率，狀態欄有混淆矩陣。
- Components 調潛在變數數目（太多會過擬合——準確率永遠 100% 就是警訊）。
- VIP 輸出（已排序）：VIP > 1 常視為重要變數——這就是「哪些波數把類別分開」的答案。
- Predictions 輸出＝原資料表＋預測類別 meta，可接 Orange 原生評估 widget。
用內建範例資料實際跑一遍
下面所有圖與數字都是用真實範例資料（9 種糖類／添加物的 NIR 光譜——0.7.2 起
用 Spectral Library 的 Add built-in 一鍵載入，亦即 repo 的 examples/sugars_nir.speclib）
與真實玉米 NIR，實際用這些 widgets 的演算法跑出來的，不是示意圖。你在自己電腦照做會得到一樣的結果。
① Import Spectrum URL → 一次載入一組光譜
把 9 條糖類 NIR 參考譜載進來、疊在同一張圖（每列一條光譜的 Table）。
② Spectra Similarity → 9×9 相關係數熱圖
對 9 條糖譜兩兩算 correlation。化學上合理：蔗糖 vs 果糖 ≈ 0.99（蔗糖＝葡萄糖＋果糖）， 糖類 vs 咖啡因 ≈ 0.71 明顯拉開。
Heat Map 設定：Clustering 的 Rows/Columns 選 (None)（本圖是字母序；開 Clustering 也很有教學價值——糖類自動聚成一群、咖啡因自己一群）、 Row Annotations 選 spectrum（列名顯示光譜名）、Color 挑一個紅黃綠系色盤（Orange 沒有與 matplotlib 一模一樣的配色）。 Heat Map 不會在格內印數字——把 Similarity Matrix 再接一個 Data Table 就能看到每格的相關係數。
③ Spectral Library → 未知糖比對排名
拿 unknown_glucose.csv 對 9 種糖的庫搜尋，第一名正確命中 glucose（correlation = 1.0000）。
| 排名 | 命中 | correlation |
|---|---|---|
| 1 | glucose ✅ | 1.0000 |
| 2 | sucrose | 0.9562 |
| 3 | fructose | 0.9533 |
| … | … | … |
| 9 | caffeine | 0.7078 |
④ Mixture Analysis → NNLS 拆解真實 CGL NIR 混合譜
用 Eigenvector 的 CGL 三成分 NIR 混合設計 （casein／glucose／lactate，1104–2496 nm）：先用校正集以古典最小平方（CLS）估出三成分的純光譜， 再對一條真實測試混合譜做 NNLS 拆解。擬合 R² = 1.0000，回推比例與參考 wt% 相當接近。
| 成分 | NNLS 回推比例 | 參考 wt% |
|---|---|---|
| casein | 31.3% | 31.3% |
| glucose | 33.9% | 37.6% |
| lactate | 34.7% | 31.1% |
examples/cgl_mixture_nnls.py
會產生這張圖，並輸出 cgl_components.speclib（3 條純成分參考譜）與
cgl_mixture.csv（一條混合譜）——用 Load Spectra Files 載入接
Mixture Analysis 的 References、載入混合譜接 Mixture，即可在 Orange 裡跑同一次 NNLS 拆解。
（純光譜是用 CLS 從真實資料估的近似值，所以回推比例與參考值有數 % 的合理差異；光譜擬合本身 R²≈1。）
⑤ Aquagram → 真實玉米 NIR 水光譜雷達圖
用真實玉米近紅外光譜（依水分含量分低/高兩組），在 12 個 WAMACs 取正規化吸光度畫成 aquagram（雷達圖）。
三個課堂範例工作流
① 看譜：貼網址 → 光譜 → 資料表
最短路徑：一個 widget 就能「貼上網址看光譜」；再接 Orange-Spectroscopy 的 Spectra widget 或 Line Plot 可另行檢視。
② 鑑定：建庫 → 未知譜比對
未知譜從第二個來源（File widget 讀 CSV，或再開一個 Import URL）接到 Library 的
Query。.speclib 檔和 SpectraView 桌面版、教學範例庫完全互通。
③ 定量：混合譜成分分析
參考譜可以來自光譜庫的 Library 輸出——「建庫」與「拆混合物」自然銜接成一條流程。
與 SpectraView、Orange-Spectroscopy 的整合
| 互通點 | 說明 |
|---|---|
| .speclib 光譜庫 | Orange 裡存的庫，SpectraView 桌面版直接 Library ▸ Load library… 開啟；反之亦然（如 examples/sugars_nir.speclib）。 |
| 資料表格式 | 欄名＝波數、每列一條光譜——與 Orange-Spectroscopy 及 SpectraView 的「合併匯出 X-matrix」相同，匯出 CSV 可雙向載入。 |
| 演算法 | 相似度四指標與 NNLS 的定義和 SpectraView 完全一致，桌面版與 Orange 版結果可互相驗證。 |
| 下游分析 | Spectra 輸出可直接接 Orange 的 PCA、PLS（化學計量學）、距離矩陣、階層式分群等 widgets。 |
常見問題
桌面版 Add-ons 安裝失敗：UnicodeDecodeError: 'cp950' codec can't decode…？
這是 Orange 桌面版在繁體中文 Windows（系統代碼頁 cp950/Big5）上的已知問題：Add-ons 對話框讀取 pip 輸出時用 cp950 解碼，遇到 UTF-8 字元（如進度條「━」）就中斷。跟裝哪個套件無關。兩種解法：
- 用命令列裝進 App 環境（推薦、最快）——開「命令提示字元」執行：
"C:\Users\你的帳號\AppData\Local\Programs\Orange\python.exe" -m pip install orange-spectra
跑完完全關閉再重開 Orange 即可。更新版本同理加--upgrade。 - 讓 Python 走 UTF-8——「編輯系統環境變數 ▸ 環境變數 ▸（使用者變數）新增」：名稱
PYTHONUTF8、值1；重開 Orange 後 Add-ons 對話框就能正常用。
要每次用都重新 pip 安裝嗎？
不用。安裝是一次性的——裝完之後每次開 Orange，Spectra 分類的 11 個 widgets 都在，直接用。
只有要更新到新版時才重裝（pip install --upgrade orange-spectra），
且重裝後要完全關掉 Orange 再重開才會生效。
Spectrometer：游標紅線為何對不到校準的紅色虛線？
紅色虛線畫在你「填進校準表的參考波長」上，游標紅線畫在「擬合後該像素換算的波長」上——兩者的間距就是擬合殘差。 差距明顯（如好幾 nm）通常代表某個 pixel=nm 配對錯了譜線：把 Fit 切回 linear 看 R²（應 ≥0.999）， 用峰值游標重新對準實際的峰再「寫進校準表」。另外「◀ 前一峰／下一峰 ▶」只在偵測到的峰之間跳； 太弱的譜線要先調低 Min prominence 才找得到。
不會用某個 widget，怎麼學？
每個 widget 左上角都有 「ℹ 說明 How to use」盒子（簡短中英說明）和 「📖 開啟線上教學」按鈕， 點按鈕就會開這頁對應段落。也可先看上面的 真實數據 Demo 看每個 widget 實際跑出什麼。
抓 IRUG 失敗（連線錯誤）怎麼辦？
先確認瀏覽器打得開該頁；校內網路有時擋外部站台。仍失敗時，可在瀏覽器用 SpectraView 桌面版的 File ▸ Import from URL / IRUG… 匯入後存成 CSV，再用 Orange 的 File widget 載入。
JCAMP-DX 檔抓下來是亂碼／解析失敗？
URL 匯入支援 AFFN（純數字）JCAMP；壓縮格式（SQZ/DIF/DUP）請用 SpectraView 開啟（它有完整解碼器）後匯出 CSV。
兩條光譜波段不同能比較嗎？
可以。相似度與 NNLS 都會先取重疊波段、內插到共同格點再計算；完全沒有重疊才會回報錯誤。
可以先做基線校正／平滑再比對嗎？
建議可以：接 Orange-Spectroscopy 的 Preprocess Spectra widget（含基線、SNV、Savitzky-Golay 等）在比對之前處理；或先在 SpectraView 做 airPLS 再匯出。
Getting started
第一次做光譜分析？先看這份教材
本頁是 11 個 widget 的參考手冊；如果你還不知道「扣基線、找峰、比對譜庫」在做什麼， 建議先走一遍入門教材，再回來查 widget 的細節。
📘 拉曼光譜顏料分析入門
寫給大一零基礎的教材，用真實顏料光譜資料把 扣基線 → 找峰 → 比對譜庫 → 混合物解混整條流程走一遍。 同一件事有三條路線可選：Python、R、以及用本頁的 widget 完全不寫程式。
- 第四篇專門講怎麼把本頁的 widget 串成分析流程：Load Spectra Files → Peak Finder → Spectra Similarity → Spectral Library → Mixture Analysis。
- 第五篇有三個真實案例，以及「自動化程式一定會犯的三種錯」—— 這是初學者最需要知道、卻最少人講的部分。