LOVD 莱顿开放变异数据库 — 软件与共享实例

LOVD 是「Leiden Open Variation Database」的缩写，中译莱顿开放变异数据库，由莱顿大学医学中心人类遗传学系维护。它的正身是一套开源软件：用 PHP 写成、数据存在 MySQL 或 MariaDB 里、遵循 GPL 许可，任何实验室都可以下载下来，为自己关心的基因建一个位点特异数据库（locus-specific database，LSDB）。用这套软件建起来的库遍布全球，数量以百计算。

但它的名字里又确实带着「数据库」三个字，而且在莱顿的服务器上，官方自己托管了一个规模很大的实例——Global Variome 共享实例。这个实例是可检索、可统计、可按基因取数的实体，当前挂着两万三千余个基因条目与两百五十余万条变异记录。所以讲 LOVD 要先分两层：作为软件，它是一套模具；作为共享实例，它是用这套模具铸出来的最大一件成品。本页按这个次序写，先写模具，再写成品，最后写它与同行的分工。

一屏速览见下表。

维度	内容
全称	Leiden Open Variation Database（莱顿开放变异数据库）
本体性质	基因变异数据库建库软件，非单一数据集
维护方	莱顿大学医学中心人类遗传学系
首发年份	2004 年前后投入运行，2007 年发布 2.0，2012 年底发布 3.0
软件许可	GPL，源码托管于 GitHub
技术栈	PHP + MySQL / MariaDB + Apache 等 HTTP 服务器，跨 Linux、Unix、Windows、macOS
共享实例规模	23051 个基因条目、两百五十余万条变异记录、四十八万上下唯一变异
全部注册实例	活跃的十几个实例合计约 468 万条变异、约 185 万个体
数据对象	基因、疾病、个体、表型、筛查、变异六类，以主键关联
发布版本	3.0 为当前主线，2.0 已停止维护
命名规范	遵循 HGVS，基因符号经 HGNC 校验
下载方式	单库「下载全部数据」、数据检索 API、整库 JSON 需申请
关键限制	禁止抓取，整库下载需许可，各库字段与分类口径不统一
定位一句话	全球策展型基因变异库的骨架，松散自治，非集中审校

§1 它要解决的具体麻烦

1.1 一个基因的变异，散落在几百篇论文的补充材料里

临床遗传学的日常工作是这样的：一个病人做了测序，拿到一个罕见变异，需要判断它是不是致病的。判断依赖两类信息，一类是变异本身在人群中的频率，另一类是别人报道过的、携带同一个变异的病人长什么样。后一类信息不集中在任何一个地方。它散在论文的表格里、散在诊断实验室的内部记录里、散在综述的附录里，而且每个实验室记录的方式都不一样。

在 LOVD 出现之前，关心某个基因的研究者通常做两件事：一是自己维护一个 Excel 表，二是等综述更新。Excel 表的寿命通常不超过一篇论文的周期，作者毕业之后就没人管了。这种「每个基因一个小本子」的模式在上世纪末非常普遍，结果是同一位点在不同本子里记着互相矛盾的观察，而且没有任何一份是完整可查的。

1.2 LOVD 的切入点：把「本子」做成可托管的软件

LOVD 选择的路线与集中式数据库相反。它不去建一个巨大的中央库，而是做一套「数据库开箱即用」的软件包，让每个基因的专家组自己建库、自己策展、自己决定公开哪些字段。这种做法在当时被称作 LSDB-in-a-Box。

这个选择有三个直接后果。第一，入门的成本落到策展人身上，而不是维护方身上，所以能覆盖的基因数量增长很快。第二，口径的差异被保留下来，因为每个库的策展人有自己的判断标准。第三，只有当某个基因没有专门团队时，官方才用共享实例来兜底。前面说的「两层」结构，本质上就是这个取舍的产物。

1.3 三条常见的错误期待

常见期待	实际情况
以为 LOVD 是一个像 ClinVar 那样有统一 ID、统一下载包的中央库	它是一个软件家族，共享实例只是其中最大的一个节点，同一变异可能同时存在于多个库里
以为下载了共享实例就拿到了全部 LOVD 数据	共享实例只覆盖官方托管的部分，各独立实例的数据不在其中，合并需要另外取
以为里面有现成的致病性分级可直接当标签	有分级，但分级的判据版本与用词因库而异，且大量条目根本没有分类

1.4 它给不了的几样东西

前面那张处境表列的是「它能帮什么」，这里反过来列「它帮不上什么」，四条都常见。

第一，它给不了统一的病原性分级。库里有分级列，但判据与用词由各库自定，跨库拼起来就不是同一把尺子。要统一标签只能去 ClinVar 一类集中审校的资源，或者自己按 ACMG/AMP 的五级重新裁一遍。

第二，它给不了治疗建议。六类对象里没有药物、剂量、随访指南这类字段，设计上就不承担这件事，也不会因为某个库想要而增设。

第三，它给不了全量的无条件下载。整库的病例级数据要申请许可，免费能拿到的只有单库导出与 API 的有限字段。

第四，它给不了可复现的定期快照。没有发布版本号，没有按月打包的全量文件，同一个库在两个月里查到的东西可能不同。

1.5 你的处境与它能帮到的事

你的处境	它能帮你什么	下一步该做什么
门诊遇到一个罕见变异，想知道有没有别人报道过携带者	全球查询入口能按位置把各实例的命中记录一并返回	先做命名校验，再打开来源库读病例细节
手上有一份几十个基因的清单，要逐个看病例	每个基因对应一个库，库首页即可看变异与个体列表	确认各库是否开启下载，逐库取数并保留来源列
实验室想给自己关心的基因建一个库	提供可部署的软件、角色体系与提交通道	先定公开范围与列集合，再导入数据
想把自家测序结果接进公共库	数据提交 API 支持从实验室信息系统自动上传	按 VarioML 格式对接，并指定目标基因库
要做跨基因的变异-表型统计	各库结构一致但字段不齐，需要人工对齐	先做分布检查，再决定合并哪些库
要给模型准备变异训练集	只提供病例背景，不提供统一分级	改用集中式资源的标签，LOVD 只作补充
想一次拉全量做离线分析	整库 JSON 需申请许可，抓取被禁	走许可申请，或退回到少数几个基因

这张表读下来会发现一件事：凡是围绕具体基因的问题，它都能较快给出答案；凡是围绕「全体」的问题，它都会把责任推回给使用者。这不是推诿，而是这个结构的必然结果——它没有中央编辑部，自然也就没有一份可以整体负责的全量表。

1.5 一句话判断

如果关心的是某一个具体基因、想看清所有已报道的病例细节，LOVD 里对应的基因库往往比任何集中式资源都深；如果需要的是跨基因、口径统一、可直接训练的大表，它的松散结构反而是负担。

1.6 不适合谁：四条边界

第一，不适合把它的分类当作金标准的人。每个基因库的策展人是独立的，判据不同，同一个词在不同库里的含义可以差很远。把它当成「经过统一审校的结论」会系统性高估一致性。

第二，不适合需要全量、可复现下载的人。官方对抓取的态度是明确禁止，整库下载需要申请许可。任何依赖「每个月自动拉一遍全量」的流水线，在这里都不成立。

第三，不适合需要临床决策依据的人。它记录的是「谁在什么地方携带了什么变异、表现如何」，不记录该变异应当如何处理。用药、随访、手术决策不在它的范围里。

第四，不适合做没有人工介入的自动化整合。各库启用的列不同，同一个语义可能落在不同的自定义列上，字段名相同的也可能语义不同。没有人工核对就直接拼表，错位几乎必然发生。

§2 数据构成与规格

2.1 两层结构：软件、实例、基因库

要讲清 LOVD 的规模，必须先把三层说清楚，混着讲就会得出互相矛盾的数字。

第一层是软件。它是一个可下载的代码包，版本号形如 3.0-30，本身没有数据量。世界各地的实验室下载它、部署它，就得到各自的实例。

第二层是实例。每个实例是一台服务器上跑起来的一套 LOVD，可以是机构自建，也可以是官方免费托管。论文给出的数字是全球约一百个实例，其中在官方页面登记为公开的曾为 56 个。官方页面的公开列表则是另一回事：只收录最近三个月内活跃、并且开启了「纳入全球列表」设置的实例，这个列表当前是十几个。

第三层是基因库。一个实例里可以挂很多个基因库，每个库对应一个或一组基因，有自己的策展人。共享实例一个实例里就挂着两万多个基因条目。

三层的数字口径完全不同，所以在任何场合引用规模都必须写明是哪一层。下文默认以共享实例为主要口径，因为它是唯一有稳定入口、可被外部核对的那一层。

2.2 共享实例的规模

共享实例的基因列表页当前显示 23051 个条目、231 页，这是按基因符号排列的目录，每一行给出基因符号、HGNC 编号、基因全名、染色体区带、转录本数、变异数、唯一变异数与最后更新日期，以及关联的疾病。

同一页面在总数行给出的变异记录是 2551947 条，唯一变异 480841 条。两个数的差距说明了一件事：同一个变异平均被记录在五个个体上。这是病例型数据库的常态，也是它与以变异为单位计数的数据库最大的差别——它的基本单元不是变异，是「个体与变异的组合」。

作为对照，官方公开列表里活跃实例的合计是 4679657 条变异、1850990 个个体。可见共享实例占了全部活跃实例变异记录的半数略多，其余分散在少数几个大型机构实例里。

2.3 六类对象与它们的关系

LOVD 3.0 的数据模型由六类对象构成，这是与 2.0 最大的架构差异。2.0 只有基因、个体、变异三类，一大批基因混在一个库里时，个体表的列会膨胀到无法使用。3.0 拆出疾病、表型、筛查三类之后，每个基因库可以配置自己需要的列。

对象	承载什么	关键关系
基因	基因符号、HGNC 编号、染色体区带、转录本集合	一对多到变异与疾病
疾病	疾病名、本体编号、关联基因	多对多到基因，一对多到个体
个体	去标识编号、性别、年龄、来源	一对多到变异、表型与筛查
表型	表型条目、本体编号、出现与否	多对一到一个体，可多次追加
筛查	筛查技术、结果、是否检出	多对一到一个体
变异	HGVS 描述、基因组坐标、各转录本上的效应	多对多到个体与基因

这套关系的核心设计在于「变异与个体分离」。同一条变异记录在多个个体上时，只存一份变异信息，个体侧只存引用。表型与筛查同理，都挂在个体而不是变异上。这样一来，一个个体带三个变异、做两次筛查、有五次随访表型，就能用六类对象的不同组合完整表达，而不需要在宽表里开一堆可空列。

2.4 字段分块

实际导出的宽表，列可以粗分为四块。第一块是基因与变异标识，包括基因符号、HGNC 编号、转录本号、HGVS 的基因组与转录本两级描述、基因组坐标、变异类型。第二块是个体与表型，包括个体编号、性别、年龄、表型条目及其本体编号、是否出现。第三块是筛查与家系，包括筛查技术、结果、家系关系。第四块是文献与元信息，包括参考文献、提交者、提交日期、该条提交声明的数据许可。

这四块的稳定性差别很大。第一块受 HGVS 规范约束，各库基本一致。第二块与第三块取决于库启用了哪些自定义列，差异最大。第四块里最难处理的是数据许可，因为它是按提交逐条声明的，同一张表里可能混着几种不同的许可。

论文提到 3.0 预置了 43 个自定义列，而共享实例上已经启用的列超过 200 个。这两个数字放在一起说明：自定义列体系是开放的，各库可以自己加，官方的预置只是一个起点。这正是「字段不统一」的技术根源——不是设计失误，而是设计目标。

2.5 一条记录的解剖

取一个个体在某个基因库中的样子，它在导出表里大致如下。字段名在各库间可能不同，下面的写法只表示语义位置。

#-- 一条病例型记录的典型组成，按四大块排列
基因与变异:  DMD | HGNC:2928 | NM_004006.3 | c.4375C>T | p.Arg1459Ter
             chrX:g.32517432G>A | 无义
个体与表型:  个体编号 00012345 | 男 | 8 岁 | 无义突变携带
             表型: 肌无力(HPO:0003324) 出现 | 心肌病(HPO:0001631) 未出现
筛查与家系:  技术 全外显子测序 | 检出 | 母亲为携带者
文献与元信息: PMID 23456789 | 提交者某诊断中心 | 许可 CC0

这条记录里值得注意的有三处。其一，同一个变异在基因组与转录本两级都有描述，3.0 强制两套都存，这是「以基因组为中心」的直接体现。其二，表型既有出现也有未出现的记录，后者对判断表型谱边界同样有用，但只有部分库录入。其三，许可是逐条写的，说明同一库内的记录可以有不同的再使用条件。

2.6 版本谱系

版本	首发	关键变化	当前状态
1.0 及更早	2004 年前后	基因、个体、变异三类对象，仅支持单基因库	已不可用
2.0	2007 年	支持一个个体带多个基因的变异，引入自定义列与 API	停止维护，仍有少量实例运行
3.0	2012 年底	拆出疾病、表型、筛查三类对象，支持基因间变异与多转录本独立注释	当前主线，共享实例在用

从 2.0 到 3.0 不是覆盖升级，官方提供的是一条转换脚本：先用 2.0 导出，再转成 3.0 的导入文件，导回同一个 3.0 数据库。这意味着任何想把老库迁到新版的团队，都要做一次人工核对，而不是换个文件就完事。

§3 它的身份：谁是维护方，对谁负责

3.1 三个名字，一个家族

LOVD 有三个层面的称呼。全称是 Leiden Open Variation Database，取「Leiden Open source Variation Database」之意，中间那个 Open 既是「开放」也是「开源」。简称是 LOVD，日常口语里既指软件也指共享实例。代码层面它是 LOVD3 仓库，版本号由主版本加构建号组成，前者表示数据模型，后者表示补丁。

名字里没有出现任何组织名称，这一点容易让人误判归属。它不属于 NCBI，不属于 EBI，也不属于任何国际联盟，而是莱顿大学医学中心人类遗传学系的一个长期项目。这决定了它的治理方式：没有理事会、没有强制的提交规范、没有统一的质量门槛，只有一层薄薄的技术约定（HGVS 命名、HGNC 符号）把各个库串起来。

3.2 维护方与它的利益结构

维护方是莱顿大学医学中心的 den Dunnen 课题组，这个组同时是 HGVS 命名规范的推动者之一。这条线索解释了 LOVD 对命名规范的执着：变异描述必须在基因组与转录本两级都成立，录入时通过 VariantValidator 与 Mutalyzer 在线核对。对一个希望被临床使用的数据库来说，命名不一致是最致命的缺陷，因为所有下游工具都靠字符串匹配来找变异。

官方在莱顿服务器上提供免费托管，这对小基因的策展人是决定性的。一个研究罕见病的临床医生通常没有运维能力，也没有经费养服务器，免费托管把「建一个基因库」的门槛降到了只需提交一份数据。代价是数据放在别人的机器上，公开范围与导出策略要遵循托管方的规则。

3.3 它对谁负责

责任对象	它承担的部分	它不承担的部分
提交者与患者	提供去标识的录入通道与权限控制，允许多级角色审校	不核验提交内容的临床真实性
策展人	提供建库工具、自定义列、转换与校验服务	不替策展人做分类判断
下游使用者	提供 API、按库下载与文献出处	不保证跨库可比，也不保证数据完整
学术共同体	提供可引用论文、开源代码与全球查询中转	不提供全量数据的无条件开放下载

把四条摆在一起，可以提炼出一条使用准则：把 LOVD 当作「一个由许多独立小组维护的联合目录」，而不是「一个统一编辑的百科全书」。它的可信度是分库的，不是整体的。

3.4 免费托管与商业许可的分界

官方在两条线上同时做事，一条是免费，一条是收费，两者并不矛盾。

免费的一侧包括：软件本身、共享实例的网页浏览与按基因查询、单个基因库的「下载全部数据」（前提是策展人开启了该选项）、数据检索 API 的有限字段。收费的一侧是完整病例级数据的 JSON 下载，按商业许可出售，非商业研究用途也需要先联系。

这条分界不是最近才有的。官方在服务条款里写明，用脚本伪装浏览器抓取网页数据一律不允许。这条规则的直接后果是：任何「自动拉全量」的想法在合法路径上都行不通，只能走申请，或者退回到逐库、逐基因地取。

§4 它的手艺：松散的联邦如何还能被查

4.1 三个技术约定撑起整个网络

一个由上百个互不隶属的实例组成的网络，如果没有约定，就是一堆孤岛。LOVD 靠三个约定把它们连起来。

第一个是 HGVS 命名。变异在基因组与转录本两级都有描述，两级互为校验。这条约定让同一变异在不同库里是可识别的，也是全球查询能工作的前提。

第二个是 HGNC 基因符号。入库时符号要经过校验并保存 HGNC 编号，这样即便符号更名，也能靠编号找回。

第三个是 API。从 2.0 的某个构建开始，所有安装都内置了数据检索接口；3.0 又加了数据提交接口，格式基于 VarioML 的 JSON，供实验室信息系统自动上传。第三个约定让「联邦查询」成为可能：全球查询服务不存数据，只是并行去问各个实例的接口，再把结果拼回来。

4.2 全球查询是怎么工作的

它的逻辑与搜索引擎的元搜索类似。用户在入口输入一个基因组位置、一个区间或一个基因符号，服务把请求分发到已登记的各实例，收集返回的记录链接，再按来源分组展示。

这个设计有两个显而易见的特性。其一是延迟，因为要等各个实例响应，慢的实例会拖累整体。其二是覆盖不完整，只有开启了「纳入全球列表」、保持更新、API 未被关闭的实例才会被问到，那些关闭了列表的实例，数据虽然公开，却不会出现在结果里。论文报告全球接口在 2020 年处理了 1.67 亿次请求，其中约三成半至少命中一条记录。

4.3 案例：从一个变异追到三个库

假设临床实验室拿到了一个变异，想在 LOVD 里查有没有别人报道过。这条路径能看清联邦结构在实际使用中的样子。

第一步是查命名。把变异的基因组与转录本两级描述提交给 VariantValidator，确认写法符合 HGVS。这一步不通过，后面的检索会因为字符串不匹配而漏掉记录。

第二步是走全球查询入口，按基因组位置检索。返回的每一条都带着来源实例与记录链接，同一条变异可能出现在三四个库里，因为不同国家的诊断中心各自建了库。

第三步是逐个打开。点开之后看到的不是同一份数据的不同副本，而是不同策展人各自录入的观察：病例数不同、表型描述详细程度不同、分类判断也可能不同。

第四步是合并判断。合并的原则是先按个体的去标识编号去重，再按库的来源保留分歧，而不是直接取其中一个库的结论。这个过程在后面讲跨库合并时会再展开。

4.4 变异的注释层级

LOVD 3.0 最重要的技术决定是「以基因组为中心」。一条变异首先被记成一个基因组坐标上的事件，然后才是它在某个转录本上的效应。这条设计带来了两个能力。

第一个是基因间变异。落在基因之外、但可能落在调控区的变异，2.0 存不了，3.0 可以存。第二个是多转录本效应。同一个基因组变异，在某个转录本上是错义，在另一个转录本上可能落在外显子之外，3.0 允许逐转录本分别记录。

这两个能力对一个病例型数据库很关键，因为临床报告通常按某一个特定转录本写，而研究者在做跨基因分析时需要的是基因组坐标。只存其中一套，另一方就要在每次使用时重新推算，而推算的版本差异会带来难以追查的不一致。

4.5 校验工具链

录入环节有三道自动检查。第一道是命名校验，通过 VariantValidator 与 Mutalyzer 服务在线核对，不合格的写法不能保存。第二道是基因符号校验，向 HGNC 核验符号是否存在、是否已更名。第三道是参考序列展示，系统会把变异所在区域渲染成带标注的页面，方便人工复核上下文。

还有一类检查是针对具体变异类型的，比如外显子缺失或重复时预测是否造成移码。这类检查不通用，只在相关基因库启用。它们的存在说明 LOVD 的目标不只是存储，还包括在录入的那一刻就把可发现的错误挡掉。

4.6 权限与角色

一个库通常有四到五种角色：数据库管理员管整个实例，经理管一个库，策展人管一个基因，协作者可以提交但不能发布，普通提交者只能提交自己名下的记录。这套分级的意义在于把「谁能改什么」写清楚，因为病例数据的争议往往不在于数据本身，而在于谁能下定论。

值得注意的是，不同实例之间的账号互不通用。官方在帮助里专门提醒这一点，因为很多人会在一个实例注册之后去另一个实例登录，然后误以为自己被拒。这条设计不是疏忽，而是安全考量：身份体系不共享，一个实例被攻破不会牵连其他实例。

§5 怎么拿到：三条合法路径与一条禁区

5.1 四条路径的取舍

路径	适合的人	拿到什么	代价与边界
单库「下载全部数据」	只关心某几个基因的人	该库的平铺宽表	需策展人开启，否则只能联系索取
数据检索 API	需要按条件批量查变异的人	基因与变异层面的字段	不含个体数据，有频率限制与公平使用条款
整库 JSON（申请）	需要完整病例级数据的人	全量病例级记录	商业许可，非商业也需先联系
网页抓取	任何人	—	官方明确禁止，会被封 IP

四条路径的差别不只是「免费与付费」，还在于拿到的东西不一样。单库下载拿到的是宽表，丢失了对象之间的一对多关系；整库 JSON 保留了关系，但需要许可；API 只给变异不给病例。想清楚自己要做的是「读某几个已知变异」还是「做全库统计」，路径就定了。

5.2 单库下载

每个基因库的首页如果有「下载全部数据」的链接，点开就能拿到一份制表符分隔的文本。列是该库启用列的并集，行是个体与变异的组合。这是成本最低的路径，适合快速看一眼某个基因的病例构成。

#-- 先确认该基因库是否开启了下载选项，再取文件
curl -sI "https://databases.lovd.nl/shared/genes/BRCA1" | head -20

#-- 下载页会给出制表符分隔的数据文件链接，注意带上可识别的 User-Agent
curl -s -A "research-bot/1.0 (contact: you@example.org)" \
     -o BRCA1_lovd.tsv \
     "https://databases.lovd.nl/shared/genes/BRCA1?download"
head -3 BRCA1_lovd.tsv | cut -c1-200

使用前要确认两件事：该库是否真的开启了下载，以及文件里的许可行写的是什么。不少库的下载页会在首行注明再使用的条件，与数据行的许可字段可能不一致，以后者为准。

5.3 数据检索 API

API 的请求形态是 URL 加查询串，输出可以是 JSON、XML 或 Atom。Atom 是 2.0 时代留下的格式，向后兼容；JSON 是 3.0 新增的，字段更多，包括多个基因组位置、数据所有者与时间戳。

#-- 按基因符号取变异列表，只要 JSON 与少量字段
curl -s -A "research-bot/1.0 (contact: you@example.org)" \
  "https://databases.lovd.nl/shared/api/rest/variants/BRCA1" \
  -H "Accept: application/json" | head -c 2000

#-- 按基因组位置与区间检索，用于查某一段区域内的已知变异
curl -s -A "research-bot/1.0 (contact: you@example.org)" \
  "https://databases.lovd.nl/shared/api/rest/variants/chr13:32315000_32320000" \
  -H "Accept: application/json" | head -c 2000

官方对 API 的公平使用有明确条款：请求太密、重复同一请求、或不用有辨识度的 User-Agent，都可能被封。写脚本时至少要做三件事：带上可联系的联系方式、做请求间隔、把响应缓存下来避免重复请求。

5.4 网页端查询

网页端适合人工核对而不适合批量。按基因进入库首页，可以看变异列表、个体列表、表型列表与文献列表，每张表都能排序、检索与隐藏列。字段较少的变异表可以作为人工抽查的入口，但要全量取数，还是回到 API 或下载。

5.5 合并多个库时的顺序

要把几个库的数据合进一张表，顺序很重要。比较稳妥的做法是：先按基因组坐标与变异类型归一，再按转录本号归一，最后按个体的去标识编号在库内去重。三步都不能省，因为不同库的命名习惯、转录本选择和编号体系都不同。

#-- 合并两个基因库的导出表：先归一坐标，再按库与个体编号去重
import pandas as pd

a = pd.read_csv("BRCA1_lovd.tsv", sep="\t", dtype=str, comment=None)
b = pd.read_csv("BRCA2_lovd.tsv", sep="\t", dtype=str)

#-- 只保留归一所需与来源标识列，避免列名不一致导致的错位
cols = ["gene", "variant", "genomic_position", "transcript", "individual_id"]
frame = pd.concat([a[cols], b[cols]], ignore_index=True)

#-- 用基因 + 坐标 + 变异类型做键，个体的去重只在库内成立
frame["key"] = (frame["gene"] + ":" + frame["genomic_position"].fillna("")
                + ":" + frame["variant"].str.extract(r"([a-z]+>[a-z]+)$")[0].fillna(""))
merged = frame.drop_duplicates(subset=["key", "individual_id"])
print(merged["key"].nunique(), "个归一后的变异，", len(merged), "条病例记录")

这段代码里有一处刻意的克制：去重只按基因与坐标，不跨库合并个体。原因是各库的个体编号是局部的，编号相同不代表同一个人，把它当全局主键会造成错误的合并。

§6 与同行怎么分工

6.1 关系图谱

在变异解释这件事上，LOVD 处在一个中间位置：它比单个实验室的记录更集中，比 ClinVar 更分散。可以把变异资源的格局理解成三层，最上是商业整理的文献库，中间是集中审校的公共库，底座是各基因的专家库。

库内相关词条	与本词条的关系	一句话区隔
ClinVar	下游汇总方，也常是同一批提交者的另一个出口	ClinVar 集中收稿、星级评审、统一下载；LOVD 各库自治、字段各异
HGMD	上游文献整理方，方向相反	HGMD 由机构统一摘录并收费；LOVD 由策展人分头录入且多数免费
OMIM	基因与疾病关系的参照	OMIM 描述基因与表型的关联，不逐条列病例变异
gnomAD	频率参照	gnomAD 给人群频率，LOVD 给病例与表型，不适用频率过滤
LOVD 各基因库	本词条的组成部分	单基因深度最高，但彼此不连通

6.2 与 ClinVar 的逐项区隔

两者经常被拿来比较，因为很多提交者两边都交。差别不在数据量，而在治理结构。

对比项	LOVD	ClinVar
组织形态	上百个独立实例的联邦，共享实例为最大节点	单一中央库
提交单位	基因库的策展人	机构提交者
分级体系	库内自定，口径不一	统一定义的临床意义词表
评审强度	策展人个人判断，无跨库共识机制	星级评审，从单一提交到专家面板
数据粒度	病例级，含个体、表型、筛查	变异级为主，条件信息结构化但不含完整病例
更新时点	各库自行决定，很多库更新滞后	每周发布
下载	单库或申请，禁止抓取	全量文件自由下载

一句话概括分工：LOVD 保存的是「病例」，ClinVar 保存的是「判读」。做变异解读时需要前者提供病史背景，需要后者提供共识结论，二者不能用其中一个替代另一个。

6.3 与 HGMD 的分工

HGMD 的定位是文献型的变异目录，由机构聘请人员统一摘录，通过订阅取得。它与 LOVD 的差别有三处最实际。

其一，收录标准。HGMD 追求「发表即收录」，覆盖面广但与质量分层脱钩；LOVD 靠策展人筛选，覆盖面窄但每条都被看过。其二，访问方式。一个按订阅收费，一个按库或按申请取得。其三，更新机制。一个由机构集中更新，一个由各库里各自的团队更新，所以同一个基因在两个地方的最新状态经常不同。

6.4 检索路径

你的问题	该去哪个入口	理由
某个罕见基因有没有人报道过携带者	该基因的 LOVD 库，或全球查询入口	病例级信息只在这里
某个变异的临床意义共识	ClinVar 词条	星级评审给出跨提交者的共识强度
某个变异的全部文献报道	HGMD 或文献检索	覆盖比 LOVD 全，但需订阅
某个变异在人群中的频率	gnomAD 词条	LOVD 不含频率数据
要自建一个基因库	本词条	这是它作为软件的唯一用途
要做跨基因的变异-表型统计	需要先合并多个库，或改用 ClinVar	LOVD 本身不提供跨库统一定量

6.5 重叠与去重

同一份观察可能同时出现在三处：提交者自己的 LOVD 库、共享实例里的同名基因库、ClinVar 的提交记录。这不是错误，而是同一件事被写进了三个抽屉。

做合并时，正确的做法是以「个体 × 变异」为单位去重，只在同一个库内有效；跨库只能按「变异 × 文献出处」近似去重，且要保留分歧而不是取平均。把三处直接拼起来再数变异个数，会得到明显偏高的数字。

§7 质量评估与局限性

7.0 阅读本节前的一个前置校正

评估 LOVD 最容易犯的错，是把它当成一个需要打质量分的中央数据库，去问它分类准不准、字段完整不完整、更新及不及时。这问法问错了对象，因为这些问题的答案不在一个地方——每个基因库的答案都不一样，而 LOVD 软件本身对这些问题不做任何承诺。

正确的评估框架是分两层问。作为软件，问它的功能覆盖、部署成本与安全记录。作为共享实例，问它在「有多少基因至少有一个人在维护」与「维护到什么程度」这两件事上的分布。前者答案很稳定，后者答案高度不均。把这两层混在一起，得出的结论既不适用于软件选型，也不适用于数据选型。

7.1 五维评分

维度	分数	依据
覆盖广度	4 / 5	共享实例覆盖两万余基因，活跃实例合计四百余万条变异记录
病例深度	5 / 5	个体、表型、筛查三类对象配套，纵向表型与家系关系可存
字段一致性	2 / 5	自定义列体系使各库列集不同，同名字段语义也可能不同
分类可比性	2 / 5	分级由策展人自定，无跨库共识机制，大量条目无分级
可获取性	2 / 5	禁止抓取，整库需许可，免费路径只到单库与 API

五个维度里最能体现其定位的是「病例深度满分、一致性低分」这一对。这不是取舍失误，而是同一件事的两面：正因为允许各库自定，才可能有专家愿意深入维护自己熟悉的基因；也正因为如此，跨库的整齐划一就永远做不到。

7.2 DAIMS 视角下的四条线

DAIMS 线	LOVD 的表现
数据获取与处理	录入链有命名与符号校验，但校验只保格式，不保内容真实性
数据建模	六类对象的关系模型清晰，是它做得最扎实的一环
数据溯源	每条记录有提交者与文献，但版本历史在各库之间不一致
数据使用与治理	许可按条声明，抓取被禁，治理规则清楚但执行依赖托管方

最稳的是建模，最弱的是治理的一致性。六类对象的设计在同类工具里属于超前，放到今天仍然够用；许可按条声明虽然严谨，但导致了实际使用中的判断成本很高。

7.3 已知的、可枚举的偏差

第一，基因偏差。被维护得好的基因集中在大病种与经典罕见病上，冷门基因的库可能只有几十条记录，几年不更新。用共享实例做全基因统计时，这种不均会把「研究热度」误当成「变异频率」。

第二，地理偏差。策展人集中在欧洲、北美与东亚的几个诊断中心，其他地区的病例进入渠道更少。这一点在讨论人群特异性变异时必须说明，否则容易把「没人报道」读成「不存在」。

第三，时间偏差。很多库的更新时间停留在几年前，而临床实践中的分类会随指南修订而改变。一条五年前标为致病的记录，可能早已在别的库里被重分类，但原库没有同步。

第四，报告偏差。阳性病例被报道得多，阴性结果很少被记录。因此从这些库里算出的检出率、外显率都不可靠，因为分母缺了一大块。

第五，版本偏差。2.0 与 3.0 的数据模型不同，跨版本合并时字段语义会变化，尤其是与表型相关的列。老库迁移时如果不做人工核对，最容易被误读的就是这一块。

7.4 外部验证

验证角度	外部证据	结论
生态位	LOVD2 在 2015 年曾覆盖全球绝大多数 LSDB	它是这一类工具的长期事实标准
网络规模	论文报告全球约一百个实例、公开 56 个	分布广但单实例规模小
查询使用量	全球接口 2020 年处理 1.67 亿次请求	被下游工具实际依赖
浏览器集成	数据被做进 Ensembl 与 UCSC 的变异轨道	已嵌入主流基因组浏览流程
标准对接	接入 GA4GH Beacon 网络	与新一代变异共享标准有衔接

7.5 它为何能持续：免费托管与标准输出

一个由学术机构维护的二十余年项目，能活下来靠的不是经费规模，而是两件具体的事。

第一件是免费托管。莱顿的服务器替无数小基因库解决了运维，这让「建一个库」的成本降到了提交一份数据。第二件是标准输出。每一份数据都能用标准命名导出、能被基因组浏览器直接抓取，这让使用它的下游工具愿意长期维护接口。

这两件事互为支撑：托管让库存在，标准让库有用，有用的库又给了托管方继续投入的理由。反过来说，任何试图把它改造成严格集中式数据库的努力，都会同时削弱这两点。

§8 生态位与历史

8.1 历史沿革

时间	事件
2004 年前后	在莱顿投入运行，最初只服务少数基因库
2007 年	2.0 发布，引入自定义列与 API，LSDB-in-a-Box 模式开始扩散
2011 年	2.0 的方法学论文发表，当时已有 71 个公开实例、3294 个基因库、19.9 万条变异
2012 年底	3.0 发布，数据模型扩为六类对象
2015 年	2.0 系实例覆盖全球绝大多数 LSDB
2019 至 2021 年	全球接口请求量逐年翻倍，2021 年达到 1.67 亿次的量级
2021 年	3.0 的方法学论文发表
2020 年前后	2.0 停止维护，官方建议迁移到 3.0
2026 年	共享实例基因条目增至两万三千余个，变异记录突破两百万量级

这条时间线有两处值得停下来看。其一，2.0 到 3.0 之间隔了五年，说明这类工具的迭代不以版本节奏为驱动，而以「有人提出真实需求」为驱动。其二，2020 年之后 2.0 停止维护，但仍有少量实例在跑，这种「旧版长尾」在学术软件里很常见，也是合并数据时必须处理的麻烦。

8.2 与同代工具的分岔

同一时期还有几条技术路线，对照起来能看清 LOVD 的选择。

路线	代表	组织方式	与 LOVD 的区别
联邦式建库软件	LOVD	各基因库自治，软件共享	本词条
中央汇总库	ClinVar	单一库，机构提交	有统一词表，无病例深度
商业文献库	HGMD	机构摘录，订阅访问	覆盖更全，不开放
通用存储库	各类组学档案	按项目存档，不做策展	有原始数据，无病例解释
本体与知识图谱	各表型与疾病本体	概念层，不含个体记录	提供术语，不提供病例

这几条路线今天仍然并存，而且互相引用。LOVD 的独特之处不在于它覆盖最广或最权威，而在于它是唯一一条「由临床医生自己维护、按基因组织」的路线，其他几条要么由机构维护，要么以项目为单位。

8.3 在 AI 时代的位置

以变异为中心的机器学习任务，训练数据通常来自集中式资源，理由是标签整齐。LOVD 在这类任务里不是主力，但它有一个别处难找的补充价值：表型细节与家系信息。

当一个模型需要判断「同一个变异在不同个体上表现不同」这种现象时，仅靠变异级的分级标签是不够的，需要个体级的表型谱。共享实例里有一部分库满足这个条件，但覆盖不完整，所以它更适合作为「精读样本」而不是「批量语料」。

这也带出一个实际判断：如果把共享实例直接当训练集，最需要先做的是分布检查——哪些基因有足够多的记录，哪些库的分类口径接近，哪些表型字段有本体编号。不做这一步，模型学到的会是「哪个库录得多」而不是生物学。

8.4 与集中式资源的互补

有一种看法认为集中式资源最终会吞掉分散式的专家库，这个判断在可预见的范围内不成立。原因在于两者的成本结构不同：集中式资源要覆盖所有基因，就必须把每条记录的深度压到可批量处理的水平；专家库能保留深度，恰恰因为它放弃广度。

合理的分工是：专家库生成与保存细节，集中式资源汇总与分发结论，浏览器与查询服务把两者串起来。这条链今天已经在运转，问题是链上的每一步都可能滞后，使用者需要对滞后有预期。

§9 使用指引

9.1 三种角色的路径

临床遗传医师的路径是查而不是下。从一个具体变异出发，先用命名校验工具确认写法，再走全球查询入口找同一位点的其他报道，最后打开来源库看病例细节。这条路径不需要任何脚本。

做变异注释的研究者的路径是合并。先按基因清单逐个确认对应库是否存在、是否开启下载，再按 §5.5 的顺序归一与去重，最后把库来源作为一列保留，因为不同库的可信度不同。

要自建库的实验室的路径是部署。下载源码，准备 PHP 与 MySQL 环境，按手册设置角色与自定义列，再决定是否纳入全球列表。这一步的关键决定不是技术，而是「公开到什么程度」。

9.2 一条最短的核对流程

下面这条流程从一个变异符号到一个可读的病例列表，是最小可用的核对路径。

#-- 第一步：确认变异描述符合 HGVS，避免后续检索字符串不匹配
curl -s "https://rest.variantvalidator.org/VariantValidator/variantvalidator/GRCh38/NM_004006.3%3Ac.4375C%3ET/all" \
  | head -c 1200

#-- 第二步：在全局查询入口按基因与位置检索，查看命中的实例
curl -s -A "research-bot/1.0 (contact: you@example.org)" \
  "https://databases.lovd.nl/shared/api/rest/variants/DMD?search_position=chrX:32517432" \
  -H "Accept: application/json" | head -c 2000

#-- 第三步：打开来源基因库，确认该库是否开放下载
curl -sI "https://databases.lovd.nl/shared/genes/DMD" | grep -i "last-modified\|content-type"

三步之后拿到的是候选库清单，而不是结论。真正的判断要进到库页面里看个体与表型的原始录入，因为聚合层只给记录链接。

9.3 部署一个自建实例的最小步骤

#-- 一、取源码（官方镜像与 GitHub 开发库二选一）
git clone https://github.com/LOVDnl/LOVD3.git
cd LOVD3

#-- 二、确认运行环境：PHP 与 MySQL/MariaDB 版本需满足手册要求
php -v && mysql --version

#-- 三、按手册建立数据库与配置文件，再通过浏览器完成安装
#-- 四、登入后先设角色与自定义列，再导入第一批数据
ls src/ | head

部署本身不难，难的是之后的事：定义哪些自定义列、谁能发布、公开到什么程度、是否纳入全球列表。这些决定一旦做下去，后续修改会牵连已有记录，所以最好在导入数据之前想清楚。

9.4 引用方式

引用要写到三层。第一层是软件方法与平台论文，2.0 与 3.0 各有一篇，前者说明数据模型与联邦思路，后者说明网络规模与接口设计。第二层是具体基因库的策展人与版本，写清库名与查阅日期。第三层是原始文献，即该条记录引用的论文。只引第一层会让人以为数据是软件附带的，实际上数据属于每个库的策展人。

§10 AI 使用声明

项目	说明
本页 AI 参与程度	由 AI 助手依据官方页面与论文摘要起草，数字经人工复核
数字来源层级	见附录 B，官方列表页与论文为一级
未核实项	共享实例的个体总数未在公开列表页单独给出
版本信息	以 2026 年 10 月读取的官方列表页与共享实例目录为准
已知不一致	论文报告公开实例 56 个，官方活跃列表为十几个，两者口径不同
适用边界	本页描述的是软件与共享实例本身，不含对具体临床结论的评价
更新机制	数据按库滚动更新，本页不承诺随版本同步刷新

常见误读（避坑清单）

常见说法	实际	证据
「LOVD 就是共享实例」	共享实例只是官方托管的一个节点，另有大量独立实例	官方公开列表按实例分开列出
「它是集中审校的公共库」	各库由策展人自治，无跨库共识机制	平台论文描述联邦结构
「可以自动抓全量」	抓取被明确禁止，整库需申请许可	官网服务条款与拦截页
「里面有统一致病性分级」	分级由策展人自定，口径不一	各库分类列与判据版本不同
「病例数等于变异数」	变异记录按个体计，唯一变异数远少于记录数	目录页同时给出两个数
「2.0 能一键升级到 3.0」	只能通过转换脚本加人工核对	官方 FAQ 说明结构差异巨大
「所有库的更新都很及时」	很多库数年未更新	目录页的最后更新日期一列
「表型阴性记录也有」	只有部分库录入未出现的表型与阴性筛查	各库启用列不同
「它包含治疗建议」	设计上不承担，只记观察	六类对象中无用药与随访建议
「全球列表覆盖全部公开实例」	只有开启纳入设置且活跃的实例才被列出	列表页的收录说明

FAQ

Q1：共享实例的变异记录数为什么容易记错？

目录页给的是两万三千个基因条目下的约两百五十万条变异记录，再配约四十八万个唯一变异。前者按个体计，后者按变异计，两个数字都对，只是单位不同。抄写时最容易丢掉「万」字后面的量级，引用前应对回原页面。

Q2：LOVD 和 ClinVar 的数据是不是重复的？

部分重复。很多中心两边都提交，但 ClinVar 的条目以判读为单位，LOVD 以病例为单位。合并时按个体与文献去重，不要按变异去重。

Q3：能不能把共享实例全量下下来做训练？

技术上需要申请，法律上也需要许可。免费能拿到的是单库导出与 API 的有限字段。做研究通常够用，做大规模训练则要先和托管方谈。

Q4：它的变异分类可以直接相信吗？

分情况。有明确判据与文献支撑的条目可信度较高，没有判据只写一个词的要谨慎。判断方法不是看词，而是看该库的策展人是谁、最近一次更新在什么时候。

Q5：为什么同一个基因在不同库里数据不一样？

因为库不同、策展人不同、收录截止时间不同。还有些基因同时存在多个国家库，各自收录本国病例，互补而非互斥。

Q6：自建一个库需要什么？

一台能跑 PHP 与 MySQL 的服务器、一个域名、一份数据，以及一个愿意长期维护的人。最后一项最难，也是很多库停止更新的真实原因。

Q7：2.0 的数据还能用吗？

能读，但要当心字段语义。2.0 没有疾病、表型、筛查三类对象，表型信息塞在个体表的自定义列里，迁移到 3.0 时要人工拆解。

Q8：它有没有给机器学习的现成接口？

没有专门的。API 返回 JSON，坐标与命名都是标准的，自己写解析即可。官方没有提供 Python 或 R 的客户端包。

Q9：为什么有时访问会看到黑名单页面？

因为访问方式被判定为抓取。解决办法是降低频率、加上有辨识度的 User-Agent 与联系方式，必要时用邮件说明用途。

Q10：它的数据可以商用吗？

软件可以，GPL 不限制商用。数据要看每个库与每条提交的许可声明，共享实例的整库商用需要谈许可。

Q11：它和 HGMD 的收录谁更全？

文献覆盖面 HGMD 更全，因为它以发表为收录标准。病例细节与表型谱 LOVD 更细，但只在被认真维护的基因上成立。

Q12：现在还有人在新建 LOVD 库吗？

有，但新库更多是机构自建并挂到自己域名下，同时把数据提交到集中式资源。共享实例的增长主要来自提交而不是新建库。

术语表

术语	含义
LOVD	Leiden Open Variation Database，莱顿开放变异数据库
LSDB	位点特异数据库，围绕单个或一组基因建的变异库
共享实例	官方在莱顿服务器托管的 Global Variome 实例
策展人	负责一个基因库录入、核对与发布的专家
HGVS	人类基因组变异学会，其命名规范是变异描述的通用标准
HGNC	人类基因命名委员会，负责基因符号的唯一化
转录本	基因转录出的 RNA 序列，同一基因可有多个
基因组坐标	变异在参考基因组上的位置，不依赖转录本
自定义列	各库可自行启用的字段，是字段不统一的来源
VarioML	一种用于变异数据交换的 JSON 格式
VariantValidator	在线校验 HGVS 变异描述的服务
Mutalyzer	另一个变异描述校验与重命名工具
Beacon	GA4GH 提出的变异存在性查询协议
唯一变异	按变异本身计数的数量，与按个体计的记录数不同
缺检记录	筛查结果为阴性的记录，可用于计算检出率的分母
外显率	携带致病变异的个体表现出表型的比例

附录 A：核心数字核对表

项	值	来源	来源层级
共享实例基因条目	23051	共享实例基因目录页	一级
共享实例变异记录	两百五十余万	共享实例基因目录页	一级
共享实例唯一变异	四十八万上下	共享实例基因目录页	一级
活跃实例合计变异	约 468 万	官方公开列表页	一级
活跃实例合计个体	约 185 万	官方公开列表页	一级
活跃实例数量	15	官方公开列表页	一级
全球实例总数	约 100	平台论文	二级
公开实例数	56	平台论文	二级
预置自定义列	43	平台论文	二级
共享实例已启用列	超过 200	平台论文	二级
2.0 时期基因库数	3294	2.0 论文摘要	二级
2.0 时期变异数	19.9 万	2.0 论文摘要	二级

附录 B：数字的来源分层

一级：官方页面。 共享实例的基因目录与公开实例列表，给出基因条目数、变异记录数与各实例的分项。这两个页面每天更新，同一数字在不同日期读取会略有差异，引用时应写明读取日期。

二级：论文。 2.0 与 3.0 两篇方法学论文给出的是网络层面的统计，包括全球实例数、公开实例数、自定义列数与查询量。这些数字反映论文写作时的状态，不能用来描述今天的规模，但能说明结构。

三级：未核实。 共享实例的个体总数没有在公开列表页单独给出，本页只用了实例合计口径。各基因库的内部字段完整度无法从外部批量核对，本页只做定性描述。

附录 C：完整参考文献

1. Fokkema IFAC, Taschner PEM, Schaafsma GCP, Celli J, Laros JFJ, den Dunnen JT. LOVD v.2.0: the next generation in gene variant databases. Human Mutation, 2011, 32(5): 557-563. DOI: 10.1002/humu.21438.
2. Fokkema IF, Kroon M, López Hernández JA, Asscheman D, Lugtenburg I, Hoogenboom J, den Dunnen JT. The LOVD3 platform: efficient genome-wide sharing of genetic variants. European Journal of Human Genetics, 2021, 29: 1796-1803. DOI: 10.1038/s41431-021-00959-x.
3. LOVD 官方首页，https://www.lovd.nl/ ，2026 年 10 月访问。
4. LOVD 3.0 说明页与常见问题，https://www.lovd.nl/3.0/home ，2026 年 10 月访问。
5. Global Variome shared LOVD 基因目录，https://databases.lovd.nl/shared/genes ，2026 年 10 月访问。
6. LOVD 公开实例列表，https://www.lovd.nl/3.0/public_list ，2026 年 10 月访问。
7. LOVD3 源码仓库，https://github.com/LOVDnl/LOVD3 ，2026 年 10 月访问。

附录 D：取数代码

#-- 逐库取数并保留来源：只走单库下载与 API 两条合法路径
import time
import pandas as pd
import requests

BASE = "https://databases.lovd.nl/shared"
HEADERS = {"User-Agent": "research-bot/1.0 (contact: you@example.org)",
           "Accept": "application/json"}

def fetch_gene(gene: str) -> pd.DataFrame:
    #-- 一次请求只取一个基因，主动限速，避免触发封禁
    r = requests.get(f"{BASE}/api/rest/variants/{gene}", headers=HEADERS, timeout=30)
    r.raise_for_status()
    rows = r.json().get("data", [])
    frame = pd.DataFrame(rows)
    frame["source_gene"] = gene
    time.sleep(2)
    return frame

genes = ["BRCA1", "BRCA2", "MLH1"]
frames = [fetch_gene(g) for g in genes]
table = pd.concat([f for f in frames if not f.empty], ignore_index=True)

#-- 归一先做坐标与转录本，再决定是否按个体去重
print(table.shape, sorted(table["source_gene"].unique()))
table.to_csv("lovd_panel.tsv", sep="\t", index=False)

这段代码保持了两个习惯：一次只问一个基因，每两次请求之间停顿；把来源基因写成一列。前者是为了不越线，后者是为了后续能分辨哪些记录来自同一个库。

附录 E：如果只记五件事

第一，LOVD 的正身是开源建库软件，遵循 GPL，用 PHP 与 MySQL 写成，全球有上百个基于它搭建的实例。

第二，官方托管的共享实例是可以当数据集用的那部分，基因条目两万三千余个，变异记录两百五十余万条，其中四十八万上下是唯一变异。

第三，它的数据单元是病例而不是变异，个体、表型、筛查是它与变异级数据库最大的不同。

第四，各库字段与分类口径不统一，是设计使然而非缺陷，跨库合并必须人工对齐。

第五，禁止抓取，整库下载需申请许可，免费路径只到单库导出与 API 的有限字段。