跳至主要内容

Python 與 R 執行環境

在 Settings → Runtimes 選擇 Notebook 和代理可使用的 Python、R 環境。Ready 表示直譯器已檢測或準備就緒，Enable 開關單獨決定代理能否選擇該環境。

可以選擇應用管理的環境或已有直譯器。使用前核對路徑、版本、Ready 狀態和 Enable 開關。系統 R 與應用管理的 R 可以並存。

阅读平台
选择会在章节间保留。

為專案選擇執行環境​

記錄直譯器名稱、路徑和版本。首次 Python 分析可優先使用應用託管環境，避免修改其他研究依賴的環境。請求安裝軟體包前先在 Packages 中確認依賴是否已存在。檢視軟體包列表是隻讀操作，不會自動授予代理修改外部直譯器的權限。

執行失敗時，分別判斷直譯器不可用、缺少依賴、請求被拒絕或程式碼本身出錯。只有託管執行環境確實損壞時才考慮重灌，不能把所有分析錯誤都歸因於環境。復現結果時同時保留輸入版本、程式碼和執行環境資訊。

主頁面控制元件​

控制元件用途與邊界
Recheck重新發現直譯器並檢測狀態，更新最後檢查時間；衝突的安裝任務進行時不可用
Network settings開啟 Notebook 網路保護配置。提示條說明會話和包下載是否僅能訪問批准的域名
Let the Agent create environments控制代理是否可建立環境及準備缺失執行時；關閉後仍可由使用者主動安裝或修復
Add interpreter…開啟系統可執行檔案選擇器。選擇實際可執行檔案後，確認檢測到的路徑與 Ready 狀態
Download and set up環境缺失時，準備應用管理的環境
安裝期間的 Cancel請求取消安裝，等待狀態結束後再啟動其他操作
Retry setup解決錯誤原因後重試
Enable [environment]允許代理選擇該環境。禁用正在使用的環境時可能需要確認影響
Allow package install已啟用的外部 Python 或 R 環境提供的單獨安裝授權；R 授權限定在選定的個人庫。檢視包列表不需要安裝授權
Packages [count]開啟該直譯器的已安裝包清單
Reinstall在重建應用管理環境前開啟確認

安裝應用管理的環境​

安裝應用管理的 Python​

安裝 Python 前的執行時設定

  1. 找到 Python → App-managed environment。
  2. 選擇 Download and set up。
  3. 檢視進度並等待，安裝期間出現 Cancel。
  4. 成功後確認出現 conda: default-python、App-managed 與 Ready。
  5. 檢查直譯器路徑及 Enable conda: default-python 開關。

正在建立應用管理的 Python 環境

Python 安裝完成

確認 Ready、直譯器路徑和啟用狀態。包數量與版本隨安裝來源變化，不要把截圖中的臨時路徑用作長期環境位置。

安裝應用管理的 R​

  1. 開啟 Settings → Runtimes，滾動至 R。
  2. 在 App-managed environment 下選擇 Download and set up。本機已有系統 R 時，仍可安裝這個獨立環境。
  3. 等待下載和環境建立完成，期間保持應用開啟。如出現錯誤，先閱讀錯誤資訊再重試。
  4. 確認顯示 conda: default-r、App-managed、Ready，並已啟用。
  5. 開啟 Packages，在 Filter packages 輸入 r-base，核對 R 版本與渠道；清空篩選可檢視全部安裝包。

下載應用管理的 R 環境

應用管理的 R 已安裝並啟用

篩選 r-base 後，確認顯示已安裝 R 包及其版本、渠道。包總數取決於你的環境，可以與截圖不同。

檢查 R 包清單中的 r-base

接入已有直譯器​

使用本機已經安裝的 R​

選擇 Recheck，檢查發現的 R 路徑和版本。如果沒有出現目標直譯器，使用 Add interpreter… 選擇其可執行檔案。Ready 表示已檢測就緒，Enable 決定代理能否選擇該環境。

在 R Notebook 中檢查 R.home()，確認實際環境。需要安裝依賴時，按外部 R 包安裝步驟授權個人庫。

/opt/homebrew/bin/R 這類路徑表示系統安裝。

註冊並使用外部 Python​

  1. 準備需要使用的 Python 環境。
  2. 選擇 Add interpreter…，選中 Python 可執行檔案，檢查 Ready、路徑和版本。
  3. 使用 Recheck 複查，再啟用該環境。
  4. 要求代理為 Notebook 明確選擇這個直譯器。
  5. 先輸出 sys.executable 和 Python 版本，確認實際環境後再使用依賴。

若 macOS 檔案選擇器無法選中符號連結直譯器，選擇目標環境的實際可執行檔案。繫結後檢查 sys.executable。使用穩定安裝路徑，不要沿用截圖中的臨時示例路徑。

包安裝授權與實際結果​

外部 Python 環境需要安裝新包時，先檢查 Allow package install 授權。允許安裝後，等待操作結束，並在同一環境中驗證匯入，再繼續分析。

安裝報告 403 Forbidden 或 destination resolves to a non-public network address 時，檢查受影響域名，按網路說明處理後再重試。這些錯誤屬於網路訪問問題，不能據此認定軟體包不存在。保持網路防護開啟。

禁用 Notebook 正在使用的環境​

切換 Enable 後，先閱讀活動與空閒核心數量再確認。禁用可能關閉核心；重新啟用後，仍需為會話選擇可用執行時。該配置提供啟用、禁用控制元件，沒有單獨的 Remove interpreter 操作。

在外部 R 環境安裝包​

已有 R 直譯器可以執行、但缺少依賴包時，使用這項功能。應用只授予一個已有個人庫的安裝權限，不授權系統庫或站點庫。

  1. 在 Settings → Runtimes 啟用目標外部 R 環境，確認路徑和版本。
  2. 在 Personal R package library 檢查檢測到的位置，或選擇合適的庫。沒有檢測結果時，使用 Advanced options → Choose library folder…，選擇該 R 直譯器可見且可寫的已有個人庫。此操作不會建立資料夾。
  3. 啟用 Allow package install。授權前核對路徑：其他專案如果也使用這個庫，會受到包安裝變化的影響。
  4. 透過應用的包管理操作請求安裝所需包，並明確指定該 R 環境。檢視安裝結果，按提示處理核心重啟。
  5. 在該環境執行 R.home()、.libPaths()、library(PACKAGE_NAME) 和 packageVersion("PACKAGE_NAME")，將包名佔位符替換為實際包名。確認使用預期的庫後，再繼續分析。

關閉 Allow package install 可撤銷後續安裝授權，但不會解除安裝已經寫入的包。需要更換庫時先撤銷授權。沒有符合條件的資料夾時，在應用外準備個人 R 庫，或使用應用管理的環境；不要選擇系統庫來繞過檢查。

根據捕獲的鎖檔案恢復依賴​

開啟已儲存結果的 Provenance → Environment，檢視捕獲的鎖檔案。有 Download bundle 時可下載恢復包，先閱讀包內說明和前置條件。

外部 R 需要可用的 renv 和受支援的 renv.lock；外部 Python 需要已有、受支援且固定雜湊的 requirements 鎖檔案。只有直譯器路徑或包名列表並不足夠。恢復環境必須滿足記錄的直譯器、平臺、架構和包管理器要求。

解壓恢復包，選擇自己擁有且可寫的新目標位置，按包內說明執行 restore-packages.py，傳入真實的直譯器與目標路徑。指令碼先核對前置條件和校驗值，再恢復包並檢查生效的版本與路徑。檢查失敗時應處理對應條件，不要修改鎖檔案來強行透過。Open-Science 不會接管或刪除這個外部目標位置。

這屬於有條件的依賴恢復，不是完整環境克隆。需要比較輸出時，重新開啟結果，在有受支援的捕獲執行過程時使用復現檢查。

檢查安裝包​

選擇目標 Python 卡片的 Packages。對話方塊顯示該環境的路徑、包來源與狀態。

在 Filter packages 輸入 numpy 等包名，檢查版本與渠道，清空篩選可恢復列表，點選 Close 返回。

篩選 Python 安裝包

列名為 Name、Version、Build、Channel。Build 中的橫線表示未顯示構建值。這個對話方塊用於檢視清單；沒有安裝或解除安裝包的按鈕，不應在這裡尋找 “Install package” 輸入框。

用真實分析驗證環境​

在所選環境執行小型計算，重新開啟輸出，與公共基準比較。執行與匯出步驟見 R Notebook。

資料質量工作流提供使用已有依賴的 Python 路線。計算成功不代表新增包安裝或核心重啟已經驗證。

成功的真實 Notebook 計算

匯入包失敗時，先檢查選中的執行環境及包清單。若下載因域名解析為保留地址而被拒絕，按網路處理。已有包能執行，不代表額外軟體包已經可以安裝。

其他分析前檢查所選環境是否包含所需包，必要時使用支援的包管理操作，閱讀真實結果，按要求重啟並驗證匯入。授權、進度卡片或 Ready 直譯器都不能代替匯入測試。

儲存結果的環境或執行證據不完整時，開啟 Provenance 檢視缺少的資訊。需要生成可用於復現檢查的新版本時，按環境準備步驟處理。數值匹配不會補齊缺失的來源證據。

確認實際使用的直譯器​

準備好 Python 或 R 後，在對應語言的 Notebook 中執行下面的命令，檢查實際版本與路徑。設定頁列出的環境可能不止一個，以本次執行的輸出為準。

Python：

import sys
print(sys.version)
print(sys.executable)

R：

R.version.string
R.home()

然後讀取一份專案中的小表格，檢查行數並儲存結果。重新開啟應用後如需繼續分析，再執行一次檢查；歷史報告可讀取，不代表上次的記憶體變數仍在。Notebook 操作見Notebook 與執行證據。

維護和修復環境​

取消安裝後重試​

在 Download and set up 期間選擇 Cancel，等待出現 Runtime setup cancelled。選擇 Retry setup，等到 Ready 後開啟 Packages 檢查環境。前一個操作尚未結束時不要重複發起安裝。

取消安裝與重試入口

重灌託管環境​

  1. 儲存需要保留的報告，記錄自行增加的依賴。
  2. 在目標託管環境選擇 Reinstall。
  3. 閱讀影響說明，再選擇 Reinstall runtime。
  4. 等待 Ready，檢查 Packages。
  5. 啟動新的 Notebook 單元，並重新開啟已有輸入和產出。

Notebook 會話中的重灌確認

重灌會刪除並重建環境，正在執行的單元可能被取消並顯示 Run cancelled: the runtime was stopped while this cell was executing. Notebook 歷史可保留，但舊名稱空間不會恢復。重灌後先執行直譯器檢查，再重新執行產生所需變數的程式碼，並開啟已儲存檔案確認可用。

核心停止後保留的 Notebook 歷史

檔案保留不等於記憶體變數保留。繼續分析前重新執行必要程式碼。後來新增的軟體包可能需要重灌，基礎環境恢復不能證明每個額外依賴也已恢復。

開發構建提示 micromamba not found​

原始碼開發版第一次安裝時，由於程序沒有找到 micromamba，在準備環境前失敗。

原始碼構建缺少 micromamba 的真實錯誤

正式安裝包包含該程式。開發構建可在啟動程序環境中，將 OPEN_SCIENCE_MICROMAMBA_BIN 指向有效的 micromamba 可執行檔案，然後重啟開發例項。確認程式可執行後再重試；不要修改已安裝應用的內部檔案。

這個環境變數屬於開發啟動配置，不是 Runtimes 頁面的輸入欄位。不要透過刪除環境目錄處理此發現錯誤。

在 Windows 安裝 Bioconductor 包​

Bioconda 不提供 Windows 包。在應用管理的 Windows R 環境中，請讓 Agent 使用 Notebook 包安裝器，選擇 installer="biocmanager"，保留 R 包名的大小寫，例如 DESeq2。批准安裝前確認目標環境。不要改成僅適用於 Linux 等平臺的 bioconductor-* Conda 包名，也不要裝進無關的系統 R 庫。

檢查安裝結果與該環境的 Packages 列表，再在同一個 R 環境中加載包。依賴或編譯錯誤仍需處理；選擇 BiocManager 不等於安裝成功。已有外部 R 環境繼續遵循其庫目錄權限。

最後於 更新