lamindb

lamindb 是做什麼的？

概述

LaminDB 是一個開源、基於譜系的生物數據湖倉。它讓數據集與模型具備可查詢性、可追溯性、可驗證性、可重現性，並符合 FAIR（可尋找、可存取、可互通、可重複使用）原則，同時將數據儲存在開放格式中，支援本地檔案系統、S3、GCS、Hugging Face、SQLite 和 Postgres。

核心價值主張：

• 可查詢性：搜尋與過濾工件、記錄、執行、特徵、schema 與集合
• 可追溯性：追蹤筆記本、腳本、函數與管線的輸入、輸出、參數、原始碼與環境
• 可驗證性：使用 schema 策展 DataFrame、AnnData、SpatialData、TileDB-SOMA、Parquet、Zarr 及其他生物格式
• FAIR 合規性：使用 Bionty 支援的 ontology 與自訂註冊表標準化註釋
• 變更管理：使用專案、分支、空間、集合以及儲存的筆記或計畫來組織工作

何時使用此技能

在以下情況使用此技能：

• 管理生物資料集：scRNA-seq、bulk RNA-seq、空間轉錄體學、流式細胞術、多模態資料、EHR 資料
• 追蹤計算工作流程：筆記本、腳本、函數、shell 腳本與管線執行（Nextflow、Snakemake、Redun）
• 策展與驗證資料：Schema 驗證、標準化、基於 ontology 的註釋
• 處理生物 ontology：基因、蛋白質、細胞類型、組織、疾病、路徑（透過 Bionty）
• 建構資料湖倉：跨多個資料集的統一查詢介面
• 確保可重現性：自動版本控制、譜系追蹤、環境擷取
• 整合 ML 管線：與 Weights & Biases、MLflow、Hugging Face、Lightning、scVI-tools 連接
• 部署資料基礎架構：設定本地或基於雲端的資料管理系統
• 協作處理資料集：共用經過策展、註釋且具有標準化元數據的資料

核心能力

LaminDB 提供六個相互關聯的能力領域，每個領域在參考資料資料夾中都有詳細文件。

1. 核心概念與資料譜系

核心實體：

• 工件 (Artifacts)：版本化的資料集（DataFrame、AnnData、Parquet、Zarr 等）
• 記錄與 ULabels：實驗實體、型別化記錄與簡單標籤
• 集合 (Collections)：版本化、不可變的工件集合
• 執行與轉換 (Runs & Transforms)：計算譜系追蹤（什麼程式碼產生了什麼資料）
• 特徵 (Features)：用於註釋與查詢的型別化元數據欄位
• 專案、分支與空間 (Projects, Branches & Spaces)：專案分組、變更管理與存取邊界

關鍵工作流程：

• 從檔案或 Python 物件建立工件並進行版本控制
• 使用 ln.track() 和 ln.finish() 追蹤筆記本/腳本執行
• 使用 @ln.flow() 和 @ln.step() 追蹤函數工作流程
• 使用記錄、ulabels、專案與型別化特徵註釋工件
• 使用 artifact.view_lineage() 視覺化資料譜系圖
• 依來源查詢（尋找特定程式碼/輸入的所有輸出）

參考資料： references/core-concepts.md - 閱讀此文件以取得有關工件、記錄、執行、轉換、特徵、版本控制與譜系追蹤的詳細資訊。

2. 資料管理與查詢

查詢能力：

• 註冊表探索與查詢（含自動完成）
• 使用 get()、one()、one_or_none() 擷取單一記錄
• 使用比較運算符 (__gt、__lte、__contains、__startswith) 進行過濾
• 基於特徵的查詢，包括使用 Feature 物件的表達式風格查詢
• 使用雙底線語法進行跨註冊表遍歷
• 跨註冊表的全文搜尋
• 使用 ln.Q 物件進行進階邏輯查詢（AND、OR、NOT）
• 串流大型資料集而不載入記憶體

關鍵工作流程：

• 使用過濾與排序瀏覽工件
• 依特徵、建立日期、建立者、大小等查詢
• 分塊或使用陣列切片串流大型檔案
• 使用階層式鍵組織資料
• 將工件分組為集合

參考資料： references/data-management.md - 閱讀此文件以取得全面的查詢模式、過濾範例、串流策略與資料組織最佳實踐。

3. 註釋與驗證

策展流程：

1. 驗證：確認資料集符合預期的 schema
2. 標準化：修正錯字，將同義詞對應到標準術語
3. 註釋：將資料集連結到元資料實體以實現可查詢性

Schema 類型：

• 彈性 schema：僅驗證已知欄位，允許額外的元資料
• 最小必要 schema：指定必要欄位，允許額外欄位
• 嚴格 schema：完全控制結構與值

支援的資料類型：

• DataFrame（Parquet、CSV）
• AnnData（單細胞基因組學）
• MuData（多模態）
• SpatialData（空間轉錄體學）
• TileDB-SOMA（可擴展陣列）

關鍵工作流程：

• 為資料驗證定義特徵與 schema
• 使用 DataFrameCurator、AnnDataCurator、SpatialDataCurator 或 TiledbsomaExperimentCurator 進行驗證
• 使用 .cat.standardize() 標準化數值
• 使用 .cat.add_ontology() 對應到 ontology
• 使用 schema 連結儲存策展的工件
• 依特徵查詢驗證過的資料集

參考資料： references/annotation-validation.md - 閱讀此文件以取得詳細的策展工作流程、schema 設計模式、處理驗證錯誤與最佳實踐。

4. 生物 Ontology

可用的 ontology（透過 Bionty）：

• 基因（Ensembl）、蛋白質（UniProt）
• 細胞類型（CL）、細胞株（CLO）
• 組織（Uberon）、疾病（Mondo、DOID）
• 表型（HPO）、路徑（GO）
• 實驗因素（EFO）、發育階段
• 生物體（NCBItaxon）、藥物（DrugBank）

關鍵工作流程：

• 使用 bt.CellType.import_source() 匯入公開 ontology
• 使用關鍵字或精確比對搜尋 ontology
• 使用同義詞對應標準化術語
• 探索階層關係（父項、子項、祖先）
• 根據 ontology 術語驗證資料
• 使用 ontology 記錄註釋資料集
• 建立自訂術語與階層
• 處理多生物體情境（人類、小鼠等）

參考資料： references/ontologies.md - 閱讀此文件以取得全面的 ontology 操作、標準化策略、階層導航與註釋工作流程。

5. 整合

工作流程管理工具：

• Nextflow：追蹤管線流程與輸出
• Snakemake：整合到 Snakemake 規則
• Redun：與 Redun 任務追蹤結合
• Lightning：持久化檢查點與訓練元資料

MLOps 平台：

• Weights & Biases：將實驗與資料工件連結
• MLflow：追蹤模型與實驗
• Hugging Face：追蹤模型微調
• scVI-tools：單細胞分析工作流程

儲存系統：

• 本地檔案系統、AWS S3、Google Cloud Storage
• 相容 S3 的系統（MinIO、Cloudflare R2）
• HTTP/HTTPS 端點（唯讀）
• HuggingFace 資料集

陣列儲存：

• TileDB-SOMA（支援 cellxgene）
• DuckDB 用於對 Parquet 檔案執行 SQL 查詢

視覺化：

• Vitessce 用於互動式空間/單細胞視覺化

版本控制：

• Git 整合用於原始碼追蹤

參考資料： references/integrations.md - 閱讀此文件以取得與第三方系統整合的模式、程式碼範例與故障排除。

6. 設定與部署

安裝：

• 目前穩定基準：lamindb==2.5.1（發布於 2026-06-01；Python >=3.10、<=3.14）
• 基本安裝：uv pip install 'lamindb==2.5.1'
• 含擴充功能：uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• 僅最小命名空間：uv pip install 'lamindb-core==2.5.1'
• Bionty 模組：包含在 LaminDB 文件中，可透過 uv pip install 'bionty==2.4.0' 安裝
• 選用模組：建議為濕實驗室或臨床 schema 模組固定已審查的版本，而非安裝浮動的最新版本

執行個體類型：

• 本地 SQLite（開發用途）
• 雲端儲存 + SQLite（小型團隊）
• 雲端儲存 + PostgreSQL（正式環境）

儲存選項：

• 本地檔案系統
• AWS S3（可設定區域與權限）
• Google Cloud Storage
• 相容 S3 的端點（MinIO、Cloudflare R2）

組態：

• 雲端檔案的快取管理
• 多使用者系統組態
• Git 儲存庫同步
• 用於憑證與連線 URL 的命名環境變數

部署模式：

• 本地開發 → 雲端正式環境遷移
• 多區域部署
• 共用儲存搭配個人執行個體

參考資料： references/setup-deployment.md - 閱讀此文件以取得詳細的安裝、組態、儲存設定、資料庫管理、安全最佳實踐與故障排除。

安全性與預設行為

在協助設定或整合 LaminDB 時：

• 切勿顯示、記錄或傳輸實際的 API 金鑰、雲端憑證、資料庫密碼或包含機密的完整連線字串。
• 偏好使用 IAM 角色、工作負載身份、機密管理工具或命名的環境變數，例如 LAMIN_DB_URL、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 GOOGLE_APPLICATION_CREDENTIALS；僅檢查命名變數是否存在，而非其值。
• 在儲存來自 REST API、外部資料庫或使用者提供檔案的內容之前，請使用明確的 schema 或策展工具進行驗證與清理。
• 為了可重現的安裝，請固定套件版本或使用鎖定檔案。僅在使用者明確需要最新上游版本時，才接受浮動安裝。

常見使用案例工作流程

使用案例 1：使用 Ontology 驗證的單細胞 RNA-seq 分析

import lamindb as ln
import bionty as bt
import anndata as ad

# 開始追蹤筆記本/腳本執行
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# 匯入細胞類型 ontology
bt.CellType.import_source()

# 載入資料
adata = ad.read_h5ad("raw_counts.h5ad")

# 驗證並標準化細胞類型
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# 使用 schema 策展
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# 連結 ontology 支援的註釋以實現可查詢性
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

使用案例 2：建構可查詢的資料湖倉

import lamindb as ln

# 註冊多個實驗
for i, file in enumerate(data_files):
    artifact = ln.Artifact.from_anndata(
        ad.read_h5ad(file),
        key=f"scrna/batch_{i}.h5ad",
        description=f"scRNA-seq batch {i}"
    ).save()

    # 使用特徵註釋
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# 依註釋的特徵查詢所有實驗
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# 載入特定資料集
for artifact in immune_datasets:
    adata = artifact.load()
    # 進行分析

使用案例 3：整合 W&B 的 ML 管線

import lamindb as ln
import wandb

# 初始化兩個系統
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# 從 LaminDB 載入訓練資料
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# 訓練模型
model = train_model(train_data)

# 記錄到 W&B
wandb.log({"accuracy": 0.95})

# 將模型儲存在 LaminDB 並連結 W&B
import joblib
joblib.dump(model, "model.pkl")
model_artifact = ln.Artifact("model.pkl", key="models/exp-42.pkl").save()
model_artifact.features.set_values({"wandb_run_id": wandb.run.id})

ln.finish()
wandb.finish()

使用案例 4：Nextflow 管線整合

# 在 Nextflow 流程腳本中
import lamindb as ln

ln.track()

# 載入輸入工件
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# 處理（比對、定量等）
# ... Nextflow 流程邏輯 ...

# 儲存輸出
output_artifact = ln.Artifact(
    "counts.csv",
    key="processed/batch_${batch_id}_counts.csv"
).save()

ln.finish()

對於原生 Nextflow 專案，建議在有可用時優先使用 nf-lamin 外掛與目前的 nextflow.config 模式；對於小型或自訂管線步驟，則使用內聯 Python 追蹤。

入門檢查清單

要有效使用 LaminDB：

1. 安裝與設定 (references/setup-deployment.md)

   • 安裝固定的 LaminDB 與所需的擴充功能
   • 使用 lamin login 進行身份驗證
   • 使用 lamin init --storage ... 初始化執行個體

2. 學習核心概念 (references/core-concepts.md)

   • 了解工件、記錄、執行、轉換
   • 練習建立與擷取工件
   • 在工作流程中實作 ln.track()/ln.finish() 或 @ln.flow()/@ln.step()

3. 精通查詢 (references/data-management.md)

   • 練習過濾與搜尋註冊表
   • 學習基於特徵的查詢與表達式風格的過濾器
   • 嘗試串流大型檔案

4. 設定驗證 (references/annotation-validation.md)

   • 定義與研究領域相關的特徵
   • 為資料類型建立 schema
   • 練習策展工作流程

5. 整合 Ontology (references/ontologies.md)

   • 匯入相關的生物 ontology（基因、細胞類型等）
   • 驗證現有註釋
   • 使用 ontology 術語標準化元資料

6. 連接工具 (references/integrations.md)

   • 與現有的工作流程管理工具整合
   • 連結 ML 平台以進行實驗追蹤
   • 設定雲端儲存與計算

關鍵原則

使用 LaminDB 時遵循這些原則：

1. 追蹤所有內容：在每個分析開始時使用 ln.track() 以自動擷取譜系

2. 及早驗證：在進行大量分析之前，定義 schema 並驗證資料

3. 使用 Ontology：利用公開的生物 ontology 進行標準化註釋

…

[因翻譯限制而截斷]