📚 课程目录第3章材料图数据集构建与预处理

3. 材料图数据集构建与预处理

材料图神经网络的效果，首先取决于图数据集的质量。Materials Project（MP）、OQMD、AFLOW 三大数据库提供了海量晶体结构，但它们的条目组织、能量参考态、元素覆盖和结构精度并不一致。本节围绕“抽取—清洗—去重—划分—标准化”这条主线，说明如何把异构数据库整理成可直接送入 GNN 的图数据集。

一、从三大数据库抽取数据

三个数据库的定位不同，抽取时应按任务需求选择。Materials Project 以 DFT 计算为主，提供形成能、带隙、弹性模量等性质，适合做性质预测；OQMD 条目数量大、覆盖组成广，适合做组成空间探索；AFLOW 提供 AFLOW prototype 标签和多种能量修正，适合做结构原型分类。实际工程中常以 MP 为主，OQMD 和 AFLOW 作为补充。

抽取时优先使用官方 API 或批量下载接口，而不是网页抓取。以 MP 为例，可通过 mp_api 按化学式、元素、空间群或性质范围检索：

from mp_api.client import MPRester

with MPRester("YOUR_API_KEY") as mpr:
    docs = mpr.materials.summary.search(
        elements=["Li", "Fe", "O"],
        energy_above_hull=(0, 0.05),
        fields=["material_id", "formula_pretty",
                "structure", "formation_energy_per_atom",
                "band_gap", "is_stable"]
    )

OQMD 可用 qmpy 或 REST 接口按 composition 和 stability 过滤；AFLOW 可用 aflow 库或 AFLUX 查询。抽取阶段要记录来源数据库、条目 ID、抽取时间和过滤条件，便于后续追溯与复现。

二、清洗：统一能量参考态与结构质量

清洗的核心是让不同来源的数据在同一物理口径下可比。常见问题有三类：能量参考态不一致、结构含缺陷或占位无序、性质字段缺失或异常。

能量方面，MP 的形成能基于其自身元素参考态，OQMD 和 AFLOW 也各有约定。若直接混合训练，模型会把参考态差异当成材料差异。工程上通常统一转换为“每原子形成能”或“相对凸包能”，并剔除 energy_above_hull 过大的条目。结构方面，需检查晶格是否合理、原子间距是否过近、占位是否部分占据。可用 pymatgen 做结构有效性检查：

from pymatgen.core import Structure

def is_valid(structure, min_dist=0.5):
    if not structure.is_valid():
        return False
    dm = structure.distance_matrix
    n = len(structure)
    for i in range(n):
        for j in range(i + 1, n):
            if dm[i][j] < min_dist:
                return False
    return True

性质字段要按任务筛选：回归任务剔除缺失目标值的条目；分类任务检查标签是否平衡。对带隙等字段，还要注意金属体系常记为 0，需与“未计算”区分。

三、去重：结构相似性判定

同一晶体可能在不同数据库中以不同 ID 重复出现，也可能因晶胞选取不同而“看起来不同”。去重不能只比化学式，应比较结构相似性。常用做法是先用 StructureMatcher 做结构匹配，再对匹配上的条目按来源优先级保留。

from pymatgen.analysis.structure_matcher import StructureMatcher

sm = StructureMatcher(ltol=0.2, stol=0.3, angle_tol=5)
groups = sm.group_structures(structures)

其中 ltol 控制长度容差，stol 控制位点容差，angle_tol 控制角度容差。对金属合金等畸变较大的体系，可适当放宽；对分子晶体则应收紧。去重后每个结构组只保留一条代表条目，并记录被合并的 ID 列表。

四、划分：避免数据泄漏

随机划分在材料数据上容易造成泄漏：同一化学式的不同晶型、同一原型的不同组成，可能同时进入训练集和测试集，导致测试指标虚高。更合理的做法是按组成或按原型划分。例如按化学式分组，保证同一化学式的所有结构只出现在一个子集中；或按空间群、AFLOW prototype 分组，检验模型对未见原型的泛化能力。

常用比例为训练:验证:测试 = 8:1:1 或 7:1:2。若数据量小，可采用交叉验证。划分后应统计各子集的元素分布、空间群分布和目标值分布，确认没有明显偏斜。

五、标准化：图表示与数值缩放

GNN 的输入是图：节点为原子，边为原子间连接。建图时需确定截断半径或近邻数。对无机晶体，常用截断半径 4–6 Å，或取最近邻 12 个原子。节点特征可包括元素种类、电负性、原子半径、族数；边特征可包括距离、键角或高斯距离展开。

数值标准化方面，连续目标值（如形成能、带隙）应做零均值单位方差缩放，缩放参数只能从训练集统计，再应用到验证集和测试集。节点特征中的连续量同样处理。分类标签做 one-hot 或整数编码。标准化参数需与数据集一起保存，推理时保持一致。

标准化参数必须“训练集拟合、全量变换”，否则验证集和测试集信息会泄漏进训练过程，导致评估结果不可信。

六、流程总览

下图给出从三大数据库到 GNN 可用图数据集的完整数据流，包括抽取、清洗、去重、划分和标准化五个阶段，以及各阶段的关键操作与输出。

完成上述流程后，建议保存一份数据卡：记录各数据库抽取条目数、清洗剔除数、去重合并组数、最终样本量、划分比例、标准化参数和随机种子。这样当模型效果异常时，可以快速定位是数据问题还是模型问题。

不要用测试集统计标准化参数，也不要在划分前做全局去重后再随机划分——正确顺序是先按分组划分，再在训练集内部去重和拟合标准化参数，否则仍可能泄漏。

实际工程中，MP 条目通常先按 energy_above_hull < 0.05 eV/atom 筛选稳定相，再与 OQMD、AFLOW 做结构匹配去重。若目标是训练通用势函数或性质预测模型，可保留部分亚稳相以增加多样性，但需在数据卡中注明。最终数据集应能回答三个问题：每个样本来自哪里、经过哪些处理、为什么可以进入训练集。