lamindb

LaminDB

概述

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

核心价值主张：

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

何时使用此技能

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

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

核心功能

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

1. 核心概念和数据谱系

核心实体：

• Artifacts：带版本的数据集（DataFrame、AnnData、Parquet、Zarr 等）
• Records：实验实体（样本、扰动、仪器）
• Runs & Transforms：计算谱系追踪（哪些代码生成了哪些数据）
• Features：用于注释和查询的带类型元数据字段

关键工作流：

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

参考： references/core-concepts.md - 阅读本文，详细了解 artifacts、records、runs、transforms、features、版本控制和谱系追踪。

2. 数据管理和查询

查询功能：

• 使用自动补全探索和查找注册表
• 使用 get()、one()、one_or_none() 检索单条记录
• 使用比较运算符筛选（__gt、__lte、__contains、__startswith）
• 基于特征的查询（按已注释的元数据查询）
• 使用双下划线语法跨注册表遍历
• 跨注册表全文搜索
• 使用 Q 对象进行高级逻辑查询（AND、OR、NOT）
• 无需加载到内存即可流式处理大型数据集

关键工作流：

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

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

3. 注释与验证

整理流程：

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

架构类型：

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

支持的数据类型：

• DataFrames（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）
• 使用 DuckDB 对 Parquet 文件执行 SQL 查询

可视化：

• 使用 Vitessce 进行交互式空间/单细胞可视化

版本控制：

• 使用 Git 集成跟踪源代码

参考：references/integrations.md — 阅读此文，了解集成模式、代码示例以及第三方系统的故障排查方法。

6. 设置与部署

安装：

• 基础安装：uv pip install lamindb
• 安装额外组件：uv pip install 'lamindb[gcp,zarr,fcs]'
• 模块：bionty、wetlab、clinical

实例类型：

• 本地 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
cell_types = bt.CellType.from_values(adata.obs.cell_type)
artifact.feature_sets.add_ontology(cell_types)

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
    artifact.features.add_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.add_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 ... 初始化实例

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

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

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

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

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

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

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

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

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

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

核心原则

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

1. 跟踪一切：在每项分析开始时使用 ln.track()，自动捕获数据沿袭

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

3. 使用本体：利用公开的生物本体实现标准化注释

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

5. 优先查询元数据：先筛选和搜索，再加载大型文件

6. 使用版本管理，而非复制：修改时使用内置版本管理功能，而不是创建新键

7. 使用 feature 标注：为可查询的元数据定义类型化 feature

8. 详尽记录：为 artifacts、schema 和 transforms 添加描述

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

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

参考文件

此技能包含按功能整理的全面参考文档：

• references/core-concepts.md - Artifacts、records、runs、transforms、features、版本管理、数据沿袭
• references/data-management.md - 查询、筛选、搜索、流式处理和数据组织
• references/annotation-validation.md - schema 设计、整理工作流、验证策略
• 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