alterlab-lamindb

LaminDB

概述

LaminDB 是一个面向生物学的开源数据框架，旨在让数据可查询、可追溯、可复现，并符合 FAIR（可发现、可访问、可互操作、可复用）原则。它通过单一 Python API 提供统一平台，整合了湖仓架构、谱系跟踪、特征存储、生物学本体、LIMS（实验室信息管理系统）和 ELN（电子实验记录本）功能。

核心价值：

• 可查询性：按元数据、特征和本体术语搜索和筛选数据集
• 可追溯性：从原始数据到分析再到结果，自动跟踪谱系
• 可复现性：对数据、代码和环境进行版本控制
• 符合 FAIR 原则：使用生物学本体进行标准化注释

何时使用此技能

在以下情况下使用此技能：

• 管理生物学数据集：scRNA-seq、bulk RNA-seq、空间转录组学、流式细胞术、多模态数据、EHR 数据
• 跟踪计算工作流：笔记本、脚本、流水线执行（Nextflow、Snakemake、Redun）
• 整理和验证数据：模式验证、标准化、基于本体的注释
• 处理生物学本体：基因、蛋白质、细胞类型、组织、疾病、通路（通过 Bionty）
• 构建数据湖仓：跨多个数据集的统一查询接口
• 确保可复现性：自动版本管理、谱系跟踪、环境捕获
• 集成机器学习流水线：连接 Weights & Biases、MLflow、HuggingFace、scVI-tools
• 部署数据基础设施：搭建本地或基于云的数据管理系统
• 协作处理数据集：共享经过整理和注释、具有标准化元数据的数据

不适用的场景

场景	改用
分析 scRNA-seq AnnData（质量控制、聚类、差异表达），而不是注册它	alterlab-scanpy
整理 AnnData 对象本身（切片、拼接、h5ad/zarr 输入输出）	alterlab-anndata
从公共 CELLxGENE Census 获取参考细胞	alterlab-cellxgene
将实验室 ELN/LIMS（Benchling）用作记录系统	alterlab-benchling
将完成的数据集存入带有 DOI 的公共存储库	alterlab-open-science

核心功能

LaminDB 提供六个相互关联的功能领域，每个领域都在 references 文件夹中有详细说明。

1. 核心概念和数据谱系

核心实体：

• 制品：有版本的数据集（DataFrame、AnnData、Parquet、Zarr 等）
• 记录：实验实体（样本、扰动、仪器）
• 运行和转换：计算谱系跟踪（哪些代码生成了哪些数据）
• 特征：用于注释和查询的类型化元数据字段

关键工作流：

• 从文件或 Python 对象创建制品并进行版本管理
• 使用 ln.track() 和 ln.finish() 跟踪笔记本/脚本执行
• 使用类型化特征为制品添加注释
• 使用 artifact.view_lineage() 可视化数据谱系图
• 按来源查询（查找特定代码/输入生成的所有输出）

参考： references/core-concepts.md - 阅读此文档，详细了解制品、记录、运行、转换、特征、版本管理和谱系跟踪。

2. 数据管理与查询

已更改的 API 名称。 查询结果通过 .to_dataframe() 物化（旧方法为 .df()）， 使用 features.set_values({...}) / features.remove_values([...]) 为工件添加注释 （旧方法为 add_values），远程实例作为数据库对象打开——db = ln.DB("account/instance")，然后调用 db.Artifact.filter(...)——而不是导入其注册表。ln.track() / ln.finish() 和 ln.Artifact.from_dataframe / from_anndata 构造函数保持不变。

查询功能：

• 浏览注册表并查找记录，支持自动补全
• 使用 get()、one()、one_or_none() 获取单条记录
• 使用比较运算符筛选（__gt、__lte、__contains、__startswith）
• 基于特征查询（按带注释的元数据查询）
• 使用双下划线语法遍历多个注册表
• 跨注册表全文搜索
• 使用 Q 对象执行高级逻辑查询（AND、OR、NOT）
• 流式处理大型数据集，无需将其加载到内存

关键工作流：

• 使用筛选条件和排序浏览工件
• 按特征、创建日期、创建者、大小等查询
• 通过分块或数组切片流式处理大型文件
• 使用分层键组织数据
• 将工件整理到集合中

参考： references/data-management.md — 阅读此文以了解全面的查询模式、筛选示例、流式处理策略和数据组织最佳实践。

3. 注释与验证

整理流程：

1. 验证：确认数据集符合预期的架构
2. 标准化：修正拼写错误，将同义词映射为规范术语
3. 注释：将数据集关联到元数据实体，以便进行查询

架构类型：

• 灵活架构：仅验证已知列，并允许添加其他元数据
• 最小必需架构：指定必要列，并允许添加其他列
• 严格架构：完全控制结构和值

支持的数据类型：

• DataFrame（Parquet、CSV）
• AnnData（单细胞基因组学）
• MuData（多模态）
• SpatialData（空间转录组学）
• TileDB-SOMA（可扩展数组）

关键工作流：

• 定义特征和架构以验证数据
• 使用 DataFrameCurator 或 AnnDataCurator 进行验证
• 使用 .cat.standardize() 标准化值
• 使用 .cat.add_ontology() 映射到本体
• 保存与架构关联的整理后工件
• 按特征查询通过验证的数据集

参考： references/annotation-validation.md — 阅读此文以了解详细的整理工作流、架构设计模式、验证错误处理方法和最佳实践。

4. 生物本体

可用本体（通过 Bionty）：

• 基因（Ensembl）、蛋白质（UniProt）
• 细胞类型（CL）、细胞系（CLO）
• 组织（Uberon）、疾病（Mondo、DOID）
• 表型（HPO）、通路（GO）
• 实验因素（EFO）、发育阶段
• 生物体（NCBItaxon）、药物（DrugBank）

关键工作流：

• 使用 bt.CellType.import_source() 导入公共本体
• 使用关键词或精确匹配搜索本体
• 使用同义词映射标准化术语
• 探索层级关系（父项、子项、祖先项）
• 根据本体术语验证数据
• 使用本体记录注释数据集
• 创建自定义术语和层级结构
• 处理多生物体场景（人类、小鼠等）

参考： references/ontologies.md — 阅读此文以了解全面的本体操作、标准化策略、层级导航和注释工作流。

5. 集成

工作流管理器：

• Nextflow：跟踪流水线进程和输出
• Snakemake：集成到 Snakemake 规则中
• Redun：结合 Redun 任务跟踪

MLOps 平台：

• Weights & Biases：将实验与数据制品关联
• MLflow：跟踪模型和实验
• HuggingFace：跟踪模型微调
• scVI-tools：单细胞分析工作流

存储系统：

• 本地文件系统、AWS S3、Google Cloud Storage
• 兼容 S3 的存储（MinIO、Cloudflare R2）
• HTTP/HTTPS 端点（只读）
• HuggingFace 数据集

数组存储：

• TileDB-SOMA（支持 cellxgene）
• 用于查询 Parquet 文件的 DuckDB SQL

可视化：

• 用于交互式空间/单细胞可视化的 Vitessce

版本控制：

• 用于跟踪源代码的 Git 集成

参考： references/integrations.md - 阅读此文档，了解第三方系统的集成模式、代码示例和故障排除。

6. 设置与部署

安装：

• 完整数据科学技术栈：uv pip install lamindb（截至 2026-09 为 2.10.x）
• 仅安装最小命名空间：uv pip install lamindb-core
• 附加组件：gcp、fcs、zarr-v2（现在默认使用 zarr v3——旧的裸 zarr 附加组件 已移除），例如：uv pip install 'lamindb[gcp,fcs]'
• 模块挂载在实例上，而不是通过 pip 安装： lamin init --storage ./mydata --modules bionty

实例类型：

• 本地 SQLite（开发）
• 云存储 + SQLite（小型团队）
• 云存储 + PostgreSQL（生产）

存储选项：

• 本地文件系统
• 支持可配置区域和权限的 AWS S3
• Google Cloud Storage
• 兼容 S3 的端点（MinIO、Cloudflare R2）

配置：

• 云文件缓存管理
• 多用户系统配置
• Git 仓库同步
• 环境变量

部署模式：

• 从本地开发迁移到云端生产
• 多区域部署
• 共享存储与个人实例

参考： references/setup-deployment.md - 阅读此文档，了解详细的安装、配置、存储设置、数据库管理、安全最佳实践和故障排除。

常见用例工作流

用例 1：通过本体验证进行单细胞 RNA-seq 分析

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

# Start tracking
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# Import cell type ontology
bt.CellType.import_source()

# Load data
adata = ad.read_h5ad("raw_counts.h5ad")

# Validate and standardize cell types
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# Curate with schema
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# Link ontology annotations (validated CellType records)
cell_types = bt.CellType.from_values(adata.obs.cell_type)
artifact.cell_types.add(cell_types)  # typed accessor: <registry-name-plural>.add(...)

ln.finish()

用例 2：构建可查询的数据湖仓

import lamindb as ln

# Register multiple experiments
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()

    # Annotate with features. Current API is set_values / remove_values
    # (add_values was renamed).
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Query across all experiments
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# Load specific datasets
for artifact in immune_datasets:
    adata = artifact.load()
    # Analyze

用例 3：集成 W&B 的 ML 流水线

import lamindb as ln
import wandb

# Initialize both systems
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# Load training data from LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Train model
model = train_model(train_data)

# Log to W&B
wandb.log({"accuracy": 0.95})

# Save model in LaminDB with W&B linkage
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 流水线集成

# In Nextflow process script
import lamindb as ln

ln.track()

# Load input artifact
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# Process (alignment, quantification, etc.)
# ... Nextflow process logic ...

# Save output
output_artifact = ln.Artifact(
    "counts.csv",
    key="processed/batch_${batch_id}_counts.csv"
).save()

ln.finish()

入门检查清单

要有效地开始使用 LaminDB：

1. 安装与设置（references/setup-deployment.md）

   • 安装 LaminDB 和所需的附加组件
   • 使用 lamin login 进行身份验证
   • 初始化实例：lamin init --storage ./mydata --modules bionty （对于由 Postgres 支持的实例，添加 --db postgresql://...）

2. 了解核心概念（references/core-concepts.md）

   • 了解 Artifacts、Records、Runs、Transforms
   • 练习创建和检索制品
   • 在工作流中实现 ln.track() 和 ln.finish()

3. 掌握查询（references/data-management.md）

   • 练习筛选和搜索注册表
   • 学习基于特征的查询
   • 尝试流式处理大型文件

4. 设置验证（references/annotation-validation.md）

   • 定义与研究领域相关的特征
   • 为数据类型创建架构
   • 练习整理工作流

5. 集成本体（references/ontologies.md）

   • 导入相关的生物本体（基因、细胞类型等）
   • 验证现有注释
   • 使用本体术语标准化元数据

6. 连接工具（references/integrations.md）

   • 与现有工作流管理器集成
   • 关联 ML 平台以跟踪实验
   • 配置云存储和计算

核心原则

使用 LaminDB 时，请遵循以下原则：

1. 跟踪所有内容：在每次分析开始时使用 ln.track()，自动捕获沿袭信息

2. 尽早验证：定义架构，并在开展大量分析之前验证数据

3. 使用本体：利用公共生物学本体进行标准化注释

4. 使用键组织数据：按层级结构组织工件键（例如，project/experiment/batch/file.h5ad）

5. 先查询元数据：在加载大型文件之前进行筛选和搜索

6. 创建版本，而非重复数据：修改数据时使用内置版本控制，不要创建新键

7. 使用特征进行注释：定义有类型的特征，以便查询元数据

8. 详尽记录：为工件、架构和转换添加描述

9. 利用沿袭信息：使用 view_lineage() 了解数据来源

10. 从本地开始，扩展到云端：使用 SQLite 在本地开发，使用 PostgreSQL 部署到云端

参考文件

此技能包含按功能组织的全面参考文档：

• references/core-concepts.md - 工件、记录、运行、转换、特征、版本控制、沿袭信息
• references/data-management.md - 查询、筛选、搜索、流式处理、数据组织
• references/annotation-validation.md - 架构设计、整理工作流、验证策略
• references/ontologies.md - 生物学本体管理、标准化、层级结构
• references/integrations.md - 工作流管理器、MLOps 平台、存储系统、工具
• references/setup-deployment.md - 安装、配置、部署、故障排查

请根据当前任务所需的 LaminDB 功能，阅读相关参考文件。

其他资源

• 官方文档：https://docs.lamin.ai
• API 参考：https://docs.lamin.ai/api
• GitHub 仓库：https://github.com/laminlabs/lamindb
• 教程：https://docs.lamin.ai/tutorial
• 常见问题：https://docs.lamin.ai/faq

属于 AlterLab Academic Skills 套件。