LaminDB 数据验证与注释实战Schema 设计、多模态数据策展与本体驱动的质量控制【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本指南聚焦 LaminDB 中「注释与验证Annotation Validation」这一核心能力如何通过 Schema 定义数据结构、用 Curator 对 DataFrame、AnnData、MuData、SpatialData 与 TileDB-SOMA 等生物数据集执行验证、标准化与本体注释最终让数据可查询、可溯源、符合 FAIR 原则。读完本文你将掌握三种 Schema 设计模式、完整的六步数据策展Curation工作流、基于 Bionty 本体如 CellType、Tissue的值校验与同义词映射技巧以及验证失败后的修复策略。一、为什么要验证和注释数据Validate → Standardize → AnnotateLaminDB 将数据策展Curation定义为三个环环相扣的步骤这也是 annotation-validation.md 贯穿全文的主线Validation验证确认数据集与期望的 Schema 结构、类型和取值规则一致Standardization标准化修复拼写错误、将同义词映射到规范术语如把 T lymphocyte 统一为 T cellAnnotation注释把数据集关联到元数据实体Feature、Bionty 本体记录、Artifact使其可被检索和查询。只有同时通过这三步的数据才具备可查询性Queryability与可追溯性Traceability。在 SKILL.md 中这套流程被列为六大能力域之一并明确支持 DataFrameParquet、CSV、AnnData单细胞基因组学、MuData多模态、SpatialData空间转录组与 TileDB-SOMA可扩展数组五类数据结构。二、Schema 设计三种模式与适用场景Schema 定义了数据的预期结构、类型和验证规则。LaminDB 通过ln.Schema提供三种递进的严格程度1. 灵活 SchemaFlexible Schema只校验那些与 Feature 注册表中名称匹配的列允许存在额外元数据列import lamindb as ln # 创建灵活 schema schema ln.Schema( namevalid_features, itypeln.Feature # 针对 Feature 注册表做验证 ).save() # 任何与 Feature 名称匹配的列都会被验证 # 其余列允许存在但不参与验证从源码结构看itypeln.Feature意味着该 Schema 面向 Feature 注册表记录验证逻辑只作用于可识别的特征列适合探索阶段、元数据尚不稳定的数据集。2. 最小必需 SchemaMinimal Required Schema指定必填列同时仍允许额外的元数据列# 定义必填 features required_features [ ln.Feature.get(namecell_type), ln.Feature.get(nametissue), ln.Feature.get(namedonor_id) ] # 创建带必填特征的 schema schema ln.Schema( nameminimal_immune_schema, featuresrequired_features, flexibleTrue # 允许额外列 ).save()flexibleTrue是关键开关它保证cell_type、tissue、donor_id三列必须存在且取值合法同时不阻塞研究者继续添加新的实验元数据列。3. 严格 SchemaStrict Schema对数据结构施加完全控制不允许 Schema 之外的任何列# 定义全部允许的特征 all_features [ ln.Feature.get(namecell_type), ln.Feature.get(nametissue), ln.Feature.get(namedonor_id), ln.Feature.get(namedisease) ] # 创建严格 schema schema ln.Schema( namestrict_immune_schema, featuresall_features, flexibleFalse # 不允许额外列 ).save()选择建议文档与 SKILL.md 的最佳实践一致——先用灵活 Schema 起步随着对数据结构的理解加深再逐步收紧到严格 Schema详见下文「最佳实践」第 3 条。三、DataFrame 策展工作流六步实战这是整个数据验证体系的经典流水线覆盖从原始 CSV 到带 Schema 链接的可查询 Artifact 的完整旅程。步骤 1–2加载数据并建立注册表import pandas as pd import lamindb as ln # 加载数据 df pd.read_csv(experiment.csv) # 定义并保存 features ln.Feature(namecell_type, dtypestr).save() ln.Feature(nametissue, dtypestr).save() ln.Feature(namegene_count, dtypeint).save() ln.Feature(nameexperiment_date, dtypedate).save() # 填充合法取值如果使用受控词表 import bionty as bt bt.CellType.import_source() bt.Tissue.import_source()要点Feature 注册表必须先于验证创建见 core-concepts.md 中 Feature 的定义dtype显式声明每列的数据类型bt.CellType.import_source()将 Cell OntologyCL、Uberon 等公开本体导入本地注册表为后续取值校验提供对照源。步骤 3创建 Schema# 将 features 链接到 schema features [ ln.Feature.get(namecell_type), ln.Feature.get(nametissue), ln.Feature.get(namegene_count), ln.Feature.get(nameexperiment_date) ] schema ln.Schema( nameexperiment_schema, featuresfeatures, flexibleTrue ).save()步骤 4初始化 Curator 并验证# 初始化 curator curator ln.curators.DataFrameCurator(df, schema) # 验证数据集 validation curator.validate() # 检查验证结果 if validation: print(✓ Validation passed) else: print(✗ Validation failed) curator.non_validated # 查看有问题的字段validate()返回布尔结果而curator.non_validated会暴露未通过校验的字段明细是定位问题的一手证据。步骤 5修复验证问题标准化取值Standardize Values# 修复分类列中的拼写错误和同义词 curator.cat.standardize(cell_type) curator.cat.standardize(tissue) # 查看标准化映射 curator.cat.inspect_standardize(cell_type)curator.cat是分类categorical列的操作入口。inspect_standardize()用于在真正执行前预览将要发生的映射符合「先检查后执行」的安全实践。映射到本体Map to Ontologies# 将取值映射到本体术语 curator.cat.add_ontology(cell_type, bt.CellType) curator.cat.add_ontology(tissue, bt.Tissue) # 对未映射术语查询公开本体 curator.cat.lookup(publicTrue).cell_type # 交互式查询add_ontology将列与 Bionty 注册表绑定使校验语义从「字符串类型」升级为「必须是合法的本体术语」lookup(publicTrue)则在不预先导入的前提下直接访问公开本体词条并支持 IDE 自动补全详见 ontologies.md 的 Public Ontology Lookup 一节。新增术语Add New Terms# 向注册表添加新的合法术语 curator.cat.add_new_from(cell_type) # 或手动创建记录 new_cell_type bt.CellType(namemy_novel_cell_type).save()当数据中出现本体未收录的新术语例如实验室自建细胞亚型时add_new_from将其批量注册手动创建则允许同时挂接父级关系与同义词扩展为自定义层级参考 ontologies.md 的「Managing Custom Terms and Hierarchies」。重命名列Rename Columns# 将列重命名为 feature 名称 df df.rename(columns{celltype: cell_type}) # 用修复后的 DataFrame 重新初始化 curator curator ln.curators.DataFrameCurator(df, schema)列名与 Feature 名称不一致是最常见的验证失败原因重命名后必须重建 Curator 实例再验证。步骤 6保存已策展的 Artifact# 带 schema 链接保存 artifact curator.save_artifact( keyexperiments/curated_data.parquet, descriptionValidated and annotated experimental data ) # 验证 artifact 带有 schema artifact.schema # 返回 schema 对象 artifact.describe() # 显示验证状态save_artifact是流水线收口产物以 Parquet 等开放格式落盘同时将 Schema 关联关系与验证状态写入元数据之后即可通过特征查询详见第七节。四、AnnData 策展用 Slots 验证复合结构单细胞数据AnnData由obs细胞注释、var基因、X表达矩阵等多个组件构成LaminDB 用slots槽位为不同组件分别定义 Schema定义 AnnData Schema# 为不同槽位创建 schemas obs_schema ln.Schema( namecell_metadata, features[ ln.Feature.get(namecell_type), ln.Feature.get(nametissue), ln.Feature.get(namedonor_id) ] ).save() var_schema ln.Schema( namegene_ids, features[ln.Feature.get(nameensembl_gene_id)] ).save() # 创建复合 AnnData schema anndata_schema ln.Schema( namescrna_schema, otypeAnnData, slots{ obs: obs_schema, var.T: var_schema # .T 表示转置 } ).save()注意var.T的写法由于验证器以行为单元工作对var这类基因在行的组件需要转置.T这是文档明确强调必须写清楚的细节。策展 AnnData 对象import anndata as ad # 加载 AnnData adata ad.read_h5ad(data.h5ad) # 初始化 curator curator ln.curators.AnnDataCurator(adata, anndata_schema) # 验证所有槽位 validation curator.validate() # 按槽位修复问题 curator.cat.standardize(obs, cell_type) curator.cat.add_ontology(obs, cell_type, bt.CellType) curator.cat.standardize(var.T, ensembl_gene_id) # 保存已策展的 artifact artifact curator.save_artifact( keyscrna/validated_data.h5ad, descriptionCurated single-cell RNA-seq data )AnnDataCurator的.cat操作比 DataFrame 版本多一个槽位参数如obs、var.T实现分槽验证与修复——这正是最佳实践中「对复合结构逐槽位增量验证」的落地方式。五、MuData、SpatialData 与 TileDB-SOMA 策展MuData多模态数据MuData 通过模态:槽位语法为每个模态定义独立 Schema# 为每个模态定义 schemas rna_obs_schema ln.Schema(namerna_obs_schema, features[...]).save() protein_obs_schema ln.Schema(nameprotein_obs_schema, features[...]).save() # 创建 MuData schema mudata_schema ln.Schema( namemultimodal_schema, otypeMuData, slots{ rna:obs: rna_obs_schema, protein:obs: protein_obs_schema } ).save() # 策展 curator ln.curators.MuDataCurator(mdata, mudata_schema) curator.validate()SpatialData空间转录组# 定义空间 schema spatial_schema ln.Schema( namespatial_schema, otypeSpatialData, slots{ tables:cell_metadata.obs: cell_schema, attrs:bio: bio_metadata_schema } ).save() # 策展 curator ln.curators.SpatialDataCurator(sdata, spatial_schema) curator.validate()空间数据中tables:xxx.obs指向特定表的观察元数据attrs:bio指向顶层属性slot 路径需要与 SpatialData 对象内部结构严格对应。TileDB-SOMA可扩展数组# 定义 SOMA schema soma_schema ln.Schema( namesoma_schema, otypetiledbsoma, slots{ obs: obs_schema, ms:RNA.T: var_schema # measurement:modality.T } ).save() # 策展 curator ln.curators.TiledbsomaExperimentCurator(soma_exp, soma_schema) curator.validate()ms:RNA.T遵循 SOMA 实验的命名约定ms表示 measurement 命名空间RNA为模态名.T同样表示转置。这类大规模数组数据可通过># 定义带类型的 features ln.Feature(nameage, dtypeint).save() ln.Feature(nameweight, dtypefloat).save() ln.Feature(nameis_treated, dtypebool).save() ln.Feature(namecollection_date, dtypedate).save() # 验证期间强制类型转换 ln.Feature(nameage_str, dtypeint, coerce_dtypeTrue).save() # 自动将字符串转为 intdtype支持int、float、bool、date、str等coerce_dtypeTrue允许在验证时自动做类型转换如字符串42→ 整数42但文档明确建议谨慎开启仅在确认转换安全时使用见最佳实践第 9 条。取值验证# 针对 Bionty CellType 注册表中的合法取值进行验证 cell_type_feature ln.Feature(namecell_type, dtypebt.CellType).save() # 现在验证将对照 CellType 注册表进行 curator ln.curators.DataFrameCurator(df, schema) curator.validate() # 若 cell_type 取值不在注册表中则报错当 Feature 的dtype直接指定为 Bionty 注册表类如bt.CellType时校验语义从类型合法跃升为取值必须是已收录的本体术语这是 ontologies.md 中bt.CellType.validate()机制在 Curator 层的自然延伸。七、标准化策略公开本体、同义词映射与自定义映射使用公开本体# 从公开来源查询标准术语 curator.cat.lookup(publicTrue).cell_type # 返回带自动补全的对象包含公开本体术语 # 用户可以交互式选择正确的术语同义词映射# 为记录添加同义词 t_cell bt.CellType.get(nameT cell) t_cell.add_synonym(T lymphocyte) t_cell.add_synonym(T-cell) # 现在标准化会自动映射同义词 curator.cat.standardize(cell_type) # T lymphocyte → T cell # T-cell → T cell这是最优雅的标准化方式一次注册同义词全库永久受益。底层机制可参考 ontologies.md——bt.CellType.standardize([HSC, blood stem cell])会基于已注册的 synonyms 返回规范名。自定义标准化# 手动映射 mapping { TCell: T cell, t cell: T cell, T-cells: T cell } # 应用映射 df[cell_type] df[cell_type].map(lambda x: mapping.get(x, x))适合一次性、局部性的数据清洗mapping.get(x, x)保证未命中的值原样保留。八、验证错误处理常见问题与解法速查问题解决方案列不在 Schema 中① 重命名列df.rename(columns{old_name: feature_name})② 把新列加入 Schema取值非法①curator.cat.standardize(column_name)②curator.cat.add_new_from(column_name)③curator.cat.add_ontology(column_name, bt.Registry)数据类型不匹配①df[column] df[column].astype(int)② 在 Feature 上开启coerce_dtype# 问题一列不在 schema 中 # 方案 1重命名列 df df.rename(columns{old_name: feature_name}) # 方案 2向 schema 添加 feature new_feature ln.Feature(namenew_column, dtypestr).save() schema.features.add(new_feature) # 问题二取值非法 # 方案 1标准化 curator.cat.standardize(column_name) # 方案 2添加新的合法取值 curator.cat.add_new_from(column_name) # 方案 3映射到本体 curator.cat.add_ontology(column_name, bt.Registry) # 问题三数据类型不匹配 # 方案 1转换数据类型 df[column] df[column].astype(int) # 方案 2在 feature 中启用类型强制转换 feature ln.Feature.get(namecolumn) feature.coerce_dtype True feature.save()九、Schema 版本化随时间演进的数据契约Schema 与其他记录一样支持版本化这保证数据契约的演进是可追溯的# 创建初始 schema schema_v1 ln.Schema(nameexperiment_schema, features[...]).save() # 用新 features 更新 schema schema_v2 ln.Schema( nameexperiment_schema, features[...], # 更新后的列表 version2 ).save() # 将 artifact 链接到特定 schema 版本 artifact.schema schema_v2 artifact.save()配合 setup-deployment.md 中的lamin migrate check / plan / deploySchema 版本化与数据库迁移共同构成数据基础设施演进的安全网。十、查询已验证数据让注释产生检索价值数据一旦完成验证与注释即可进入 LaminDB 的查询体系data-management.md 提供了完整的过滤与查询语法# 查找所有已验证的 artifacts ln.Artifact.filter(is_validTrue).to_dataframe() # 查找带特定 schema 的 artifacts ln.Artifact.filter(schemaschema).to_dataframe() # 按注释特征查询 ln.Artifact.filter(cell_typeT cell, tissueblood).to_dataframe() # 在结果中包含特征 ln.Artifact.filter(is_validTrue).to_dataframe(includefeatures)is_valid布尔字段标记验证状态includefeatures将注释特征展开为结果列。结合 ontologies.md 的层级查询如t_cell.query_children()ln.Artifact.filter(cell_types__int_cell_subtypes)甚至可以实现检索所有 T 细胞及其亚型相关数据集这类语义化查询。十一、最佳实践清单先定义 Features在策展之前就创建好 Feature 注册表使用公开本体借助bt.lookup(publicTrue)完成标准化从灵活开始初期使用灵活 Schema随理解加深再收紧文档化槽位在复合 Schema 中明确标注转置.T尽早标准化在验证之前修复拼写错误与同义词增量验证对复合结构逐槽位分别检查版本化 Schema追踪 Schema 的历时变更添加同义词注册常见变体以简化未来的策展谨慎强制类型仅在确认安全时启用 dtype 强制转换样本先行在完整数据集策展前先在小子集上验证。十二、进阶自定义验证器当内置 Schema 无法表达领域规则时可以编写自定义校验逻辑def validate_gene_expression(df): 基因表达值的自定义验证器。 # 检查非负 if (df 0).any().any(): return False, Negative expression values found # 检查合理范围 if (df 1e6).any().any(): return False, Unreasonably high expression values return True, Valid # 在策展过程中应用 is_valid, message validate_gene_expression(df) if not is_valid: print(fValidation failed: {message})该模式返回(bool, str)二元组可作为 Curator 之外的第二道防线用于表达数值区间、专业阈值等 Schema 难以描述的业务规则。十三、追踪策展溯源Curation Provenance策展过程本身也是一种计算活动应纳入 LaminDB 的血缘追踪体系# 已策展的 artifacts 会追踪策展血缘 ln.track() # 开始追踪 # 执行策展 curator ln.curators.DataFrameCurator(df, schema) curator.validate() curator.cat.standardize(cell_type) artifact curator.save_artifact(keycurated.parquet) ln.finish() # 完成追踪 # 查看策展血缘 artifact.run.describe() # 显示策展 transform artifact.view_lineage() # 可视化策展过程ln.track()/ln.finish()会自动捕获脚本/notebook 代码、Python 环境、输入输出 Artifact 与参数详见 core-concepts.md 的 Runs Transforms 一节配合artifact.view_lineage()生成的血缘图任何这份数据是怎么来的、由哪个 transform 生成、用了哪些输入都能一键回溯这正是本文开头那张架构图右侧view_lineage()模块所表达的 Query Lineage 闭环。附录在本仓库中继续探索annotation-validation.md本文对应的官方参考文档SKILL.mdLaminDB 技能总览含 scRNA-seq 本体验证、数据湖构建等完整用例core-concepts.mdArtifact、Feature、Runs/Transforms 与版本化基础ontologies.mdBionty 本体导入、标准化、层级与多物种支持data-management.md过滤、搜索、流式读取与ln.Q高级查询setup-deployment.md安装lamindb2.5.1、bionty2.4.0、lamin init与生产部署tests/skill-requirements.toml本仓库对 lamindb 技能声明的运行依赖lamindb、bionty、lamindb-wetlab。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考