Seurat对象转h5ad完整指南：从rds到AnnData的格式转换实战

做单细胞分析的老伙计们应该都有体会：R 里面跑完 Seurat 那一套流程，QC、聚类、找 marker、做注释，一路下来都很顺手。结果下游一换场景，比如想用某个 Python 库里的最新模型跑批次整合，或者要让深度学习那套方法直接吃数据，格式问题立刻就变成最大的拦路虎。我最近就碰上一个非常典型的任务——把一份已经做完标准 Seurat 处理的 rds 对象转成 h5ad 格式，中途还涉及到从 mtx 稀疏矩阵重建的环节。这篇文章就是我这次转换的完整记录，内容包括三种格式的本质差异、两条可复用的转换路线、我在实际操作中踩过的坑，以及一套验证数据一致性的方法，希望对正在折腾格式转换的人有点帮助。

1. 先搞清楚三种格式的本质：rds、mtx、h5ad 到底各自是什么

很多人一听到格式转换，第一反应是找个工具一键搞定。但单细胞数据格式转换这件事，绝对不能把数据当成普通文件来看。rds、mtx、h5ad 三种格式背后对应的是完全不同的数据结构，理解了它们各自的组织方式，后面每一步操作才有依据。

1.1 rds 是一个 R 对象的完整快照

.rds 是 R 语言通过saveRDS()生成的序列化文件，简单说就是把 R 内存里的一个对象整个打包落盘。单细胞分析中，这个对象几乎都是 Seurat 对象。要知道 Seurat 对象不是一张单纯的表达矩阵，它内部长得很复杂：

• 一个或多个Assay，每个Assay里又有counts（原始计数矩阵）和data（归一化后的表达值）；
• meta.data，也就是细胞级别的注释表，聚类结果、线粒体比例、样本分组都在这；
• 降维结果，比如 PCA、UMAP、TSNE 的坐标；
• 各种图结构、邻居关系、差异表达结果。

也就是说，一个 rds 文件里装的是你一整个 Seurat 分析过程的现场快照。这也是为什么 rds 文件动不动就几个 G，因为它存的东西真的多。

这里顺带澄清一个缩写问题：RDS 这个缩写在不同领域指代完全不同。做数据库的人说 RDS，通常指关系型数据库服务；但单细胞分析语境下说 rds，就是 R 数据对象文件。两个领域别搞混，否则你去找 R 对象转换教程，看到一堆数据库迁移文章，就完全对不上了。

1.2 mtx 是最朴素的稀疏矩阵交换格式

MTX 全称是 Matrix Market，最初是数值计算社区定义的文本格式。10X Genomics 当年的 Cell Ranger 流程把它带进了单细胞领域，所以大家一看到 mtx 就会想到伴随它的两个文件：barcodes.tsv（细胞条形码）和features.tsv（基因列表）。

矩阵文件本身保存的是坐标式的稀疏数据：每一行写的是"行号 列号 数值"，只记录非零元素。一个 3 万基因乘 10 万细胞的矩阵，如果全部展开写字，文件大小会到几十甚至上百 G；用 mtx 的稀疏存法，通常压缩完也就几百 M 到几个 G。这也是 mtx 能成为单细胞数据分发主流格式的核心原因。

不过 mtx 最大的问题是它只存了矩阵。基因注释、细胞注释、降维结果、聚类标签这些信息都不在里面，需要额外文件去承载。所以 mtx 虽然通用性强，但它是一个"半成品"格式，适合做中间桥梁，不适合做最终交付品。

1.3 h5ad 是 Python 生态的完整数据容器

h5ad 是 AnnData 对象的标准存储格式，底层是 HDF5（Hierarchical Data Format version 5）。AnnData 的设计思路和 Seurat 对象高度相似，它把基因表达矩阵（X）、细胞注释（obs）、基因注释（var）、非结构化元信息（uns）、降维结果（obsm/varm）全部装在一个文件里。由于 HDF5 是层次化的键值存储，h5ad 天然支持懒加载（backed mode），也就是说读取时不用把整个文件塞进内存，可以按需读一部分。

目前单细胞社区对 h5ad 的认可度非常高，特别是跨机构、跨国合作时，h5ad 几乎成了默认的交换格式。很多 Python 生信工具链，比如 Scanpy、scVI、CellTypist、scVelo，都对 h5ad 有原生支持。

1.4 转换的本质：拆开再组装

理解了上面三个格式，就会明白转换不是简单地改文件扩展名，而是拆解和重建：

1. 从 rds 对象里，把表达矩阵和注释信息拆出来；
2. 用 mtx 这类通用格式作为中间媒介，让 R 和 Python 两边都能读；
3. 在 Python 里拿到这些零件后，重新组装成 AnnData 对象，再写盘成 h5ad。

整个过程的核心就一句话：把 R 生态里分析好的结果，用中间格式搬运到 Python 生态，然后再封装一次。后面的实操内容，全是围绕这个拆解思路展开的。

2. 转换前要准备的环境和工具选型

工欲善其事，必先利其器。格式转换虽然理论上用 R、Python 各自自带的功能就能完成，但不同工具组合的效率差异非常大。我这次采用的方案是经过对比后确定的，先说结论：R 侧导出 mtx + 注释表，Python 侧用 Scanpy 重建 AnnData。下面详细说明环境准备和选型理由。

2.1 R 侧需要哪些包

R 侧的实际操作很简单，只需要两个基础包：

• Seurat：负责读取 rds 对象，提取表达矩阵和注释；
• Matrix：R 内置矩阵生态的标准包，writeMM()函数可以把矩阵写成 mtx 格式。

这里特别说明一下，很多教程会推荐安装SeuratDisk或SeuratData来转 h5ad，但我不推荐把它作为首选路线。原因很现实：SeuratDisk 依赖的底层库（比如 hdf5r）在部分服务器上安装容易出问题，而且它转出来的 h5ad 经常需要二次处理，坐标名称、数据类型都可能有兼容性毛病。相比之下，Matrix::writeMM()是 R 自带的稳定函数，不存在额外安装问题，产出物又是大家都能读的 mtx，更稳妥。

如果你手头是一个旧版本 Seurat，确保GetAssayData()函数能正常使用即可。如果对象里有多套 Assay（比如 RNA 和蛋白），转换时先想清楚到底要导出哪个 assay 的数据，这一步在实操章节会细说。

2.2 Python 侧需要哪些包

Python 侧我建议用一个独立的 conda 环境管理，避免和项目其他环境互相污染。核心依赖如下：

• anndata：构建和读写 AnnData 对象；
• scanpy：读 10X 标准 mtx 目录、做基本校验；
• scipy：用scipy.io.mmread()读散装的 mtx 文件；
• pandas：处理注释表。

环境创建的参考命令如下：

conda create -n format_convert python=3.10 -y conda activate format_convert pip install scanpy anndata pandas scipy

版本上不用刻意追新，scanpy 和 anndata 保持最新稳定版即可。需要注意：如果你原本就有一个用于数据分析的 Python 环境，建议不要临时往里面塞一堆转换代码，因为 anndata 的底层依赖（numpy、pandas）升级后，可能会影响原本分析脚本的行为。

2.3 为什么首选"导出 mtx + 重建 AnnData"路线

我也整理过其他几条路线，这里用表格对比说明选型原因：

最终我选了"导出 mtx + 重建"的路线，理由有几个。第一，它全程只依赖最稳定的函数，不会因为某个包装不上卡住。第二，它把数据的流向完全暴露出来，矩阵、基因、细胞、注释都是独立文件，一旦转换结果不对，可以逐文件排查。第三，这套方案对任意来源的数据都适用，不管你的 rds 是 Seurat 对象还是其他 R 对象，只要能导出矩阵和注释，后面就能接得上。

3. rds 转 h5ad 完整实操：从 Seurat 对象到 AnnData

这次我转换的是一个约 8 万细胞的人类肿瘤样本 rds 文件，已经完成了过滤、归一化、聚类和细胞类型注释。转换的目标是把细胞注释、原始 counts 和归一化数据都搬进 h5ad，方便后续团队在 Python 里直接跑跨样本整合模型。

3.1 第一步：从 Seurat 对象导出矩阵和注释

在 R 里执行如下脚本：

library(Seurat) library(Matrix) # 读取 rds 文件 obj <- readRDS("your_seurat_obj.rds") # 确认对象信息和默认 assay obj DefaultAssay(obj) # 提取原始计数矩阵 counts <- GetAssayData(obj, assay = "RNA", slot = "counts") # 导出稀疏矩阵到 mtx writeMM(counts, file = "converted_counts.mtx") # 导出基因名 write.table(rownames(counts), file = "converted_genes.tsv", row.names = FALSE, col.names = FALSE, quote = FALSE) # 导出细胞条码 write.table(colnames(counts), file = "converted_barcodes.tsv", row.names = FALSE, col.names = FALSE, quote = FALSE) # 导出 meta.data，保留行名 meta <- obj@meta.data write.csv(meta, file = "converted_meta.csv", row.names = TRUE) # 顺带记录一下环境信息 sessionInfo() writeLines(capture.output(sessionInfo()), "session_info_R.txt")

这里有几个操作意图需要展开说明。

GetAssayData(obj, slot = "counts")导出的是原始 UMI 计数。如果在这之前你做过 SCTransform，那么counts槽里存的依然是原始计数，data槽里是 SCT 变换后的残差表达值。绝大多数下游 Python 分析模型，比如 scVI，要求输入是原始 counts 而非归一化值，所以导出 counts 是安全选择。如果你后续只想在 Python 里做可视化和基于表达值的分析，那也可以导data槽，但建议文件命名上明确区分，避免混淆。

writeMM()导出的矩阵，行号对应的正是rownames(counts)，列号对应colnames(counts)，所以基因文件和条码文件的顺序必须与 mtx 的行列一一对应。这也是为什么我冗余地把基因和条码单独存成文件——它们是 mtx 的位置索引。

meta 导出的注意事项：Seurat 的meta.data里可能混有因子型、逻辑型、时间类型等不同数据类型。写 CSV 再读回来时，因子类型会自动变成字符串，逻辑型变成 TRUE/FALSE，这些 Python 里都能处理，但个人建议在导出前尽量统一为字符型或数值型，减少后续转换的隐患。

3.2 第二步：Python 读入并构建 AnnData

在 conda 环境里执行：

import pandas as pd import numpy as np import anndata as ad from scipy.io import mmread from scipy.sparse import csr_matrix # 读取稀疏矩阵 X = mmread("converted_counts.mtx") X = X.T.tocsr() # 转置为 细胞 x 基因，原因见 3.4 节 # 读取基因和条码 genes = pd.read_csv("converted_genes.tsv", header=None)[0].astype(str).tolist() barcodes = pd.read_csv("converted_barcodes.tsv", header=None)[0].astype(str).tolist() # 读取注释表 meta = pd.read_csv("converted_meta.csv", index_col=0) # 按条码顺序重排注释表 meta = meta.loc[barcodes].copy() # 构建 AnnData adata = ad.AnnData( X=X, obs=meta, var=pd.DataFrame(index=genes) ) # 处理可能重名的问题 adata.var_names_make_unique() adata.obs_names_make_unique() # 如果是基因 symbol 不是唯一 ID，建议额外存一列说明 adata.var["gene_symbols"] = adata.var_names # 原始 counts 转成整数存储，减少磁盘占用和后续误判 adata.X = adata.X.astype(np.int32) # 保存 h5ad adata.write_h5ad("converted.h5ad", compression="gzip")

这一套代码跑完，converted.h5ad就生成了。但这个过程中最容易出错的是索引对齐。meta.loc[barcodes]这一步的意图是：因为 mtx 矩阵的列顺序来自 R 的colnames(counts)，而读进来的barcodes列表就是这个顺序，所以元数据表也要按照这个同样的顺序重排，确保 obs 的每一行和矩阵的每一行一一对应。如果你直接meta = pd.read_csv(...)后塞给 AnnData，anndata 会用 obs.index 与矩阵行名匹配，一旦顺序不一致，会报索引不匹配错误；如果中途有人用reset_index()处理过 meta，行顺序就可能错位，这种错位比直接报错更隐蔽。

另一个细节是astype(np.int32)。单细胞 counts 本质是非负整数，而mmread()读进来的矩阵默认是 float64，体积大两倍，后续一些预处理函数也容易把浮点表达值当成归一化数据。转成 int32 既能省内存，也让 h5ad 一打开就能看出'这是原始计数'。

3.3 第三步：转换后的一致性验证

转换完成不等于任务结束。我在每次转换后都会做一套固定的验证，确保数据没在搬运过程中出错：

# 重新读取新生成的 h5ad import anndata as ad import scanpy as sc import numpy as np adata = ad.read_h5ad("converted.h5ad") # 1. 维度检查：期望是 细胞数 x 基因数 print("adata shape:", adata.shape) print("obs 行数:", adata.n_obs, " var 列数:", adata.n_vars) # 2. 矩阵内容检查：总 UMI 数是否与 R 里一致 total_r = 123456789 # 替换为 R 里 sums(counts) 的结果 total_py = adata.X.sum() print("total counts in R:", total_r) print("total counts in Python:", total_py) assert abs(total_r - total_py) < 1e-5, "total counts mismatch!" # 3. 抽查几个细胞：在 R 和 Python 中取同一个细胞、同一批基因求和对比 print(adata[:5, :100].X.sum(axis=1)) # 4. 注释完整性：关键列不能有全空 for col in ["seurat_clusters", "celltype"]: if col in adata.obs.columns: print(col, "非空比例:", adata.obs[col].notna().mean())

总 UMI 数比对是成本最低但最有效的全局一致性检查方式。矩阵只要发生易位、错行、多读少读，总和几乎不可能完全一致（万亿级别的数字差一点就会被发现）。共享细胞抽查则是补充检查行方向是否正确。这套验证跑完，基本可以放心把 h5ad 发给下游。

3.4 转置这个经典坑：为什么矩阵方向必须反转

这个坑太经典了，值得单独拿出来说。R 的数据框和矩阵，行名通常是基因，列名通常是细胞，所以 Seurat 里 counts 矩阵的形状是基因数 x 细胞数。而 AnnData 的约定正好相反，obs对应细胞，var对应基因，矩阵形状必须是细胞数 x 基因数。中间经过 mtx 文本文件交流时，不会自动帮你翻转，因此必须手动.T转置。

如果不转置，会出现一种很隐蔽的错误：h5ad 能正常生成、能正常读取，但所有 gene 的列都变成了 cell 的索引，obs 行也全是基因名，下游一跑 find_markers 或者 harmony 整合，立刻报错或者结果完全错乱。更尴尬的是，有些人只在几千个基因上跑个简单聚类可能看不出问题，一旦做跨样本整合，结果就全废了。

一个记忆技巧：导出 mtx 之前想一下 R 里矩阵的行是什么，Python 里 AnnData 的行应该是什么，两者方向相反，就在读入后抬手加个.T。

4. mtx 转 h5ad 的实操：从 10X 目录到 AnnData

更多时候我们手里的原始数据本身就是 10X 输出的 mtx 目录，还没经过 Seurat。这种情况转换更简单，但仍然有需要注意的细节。

4.1 直接读 10X 标准输出目录

如果你拿到的是 Cell Ranger 输出的标准目录：

sample_dir/ ├── barcodes.tsv.gz ├── features.tsv.gz（旧版本叫 genes.tsv） └── matrix.mtx.gz

可以用 Scanpy 的read_10x_mtx一步到位：

import scanpy as sc adata = sc.read_10x_mtx( "sample_dir/", var_names="gene_symbols", # 新版本 features.tsv 里第一列是 ensembl ID，第二列是 symbol make_unique=True, cache=False ) # 查看结果 print(adata.shape) print(adata.obs.head()) print(adata.var.head()) # 保存为 h5ad adata.write_h5ad("from_10x.h5ad", compression="gzip")

var_names="gene_symbols"的意思是让 AnnData 的 var 索引使用基因 symbol，比如TP53，而不是 ENSG 开头的 Ensembl ID。这样后面做基因过滤、画火山图时直观很多。但要注意，symbol 有时会有重复（后面会讲），所以保留一列 ensembl ID 是稳妥做法。

4.2 手里只有一个散装 mtx，没有配套文件怎么办

很多情况下，同事发给你的可能只有一个matrix.mtx，基因列表和条码列表都没给。这种情况处理起来就麻烦一些：

import anndata as ad from scipy.io import mmread from scipy.sparse import csr_matrix import pandas as pd X = mmread("matrix.mtx") X = X.T.tocsr() # 没有基因名和细胞名的替代方案：用占位名 adata = ad.AnnData(X=X) adata.var_names = [f"gene_{i+1}" for i in range(X.shape[1])] adata.obs_names = [f"cell_{i+1}" for i in range(X.shape[0])]

但这里必须提醒一句：没有基因名的 mtx，几乎只能用来做维数统计，没法做任何有生物学意义的分析。基因名是连接数据与生物学知识的关键，如果对方只给了 matrix.mtx，一定要回去要 features 文件。另外，如果 mtx 文件里第一行写了%%MatrixMarket注释，用mmread读取时会自动忽略；如果文件是 gzip 压缩的，mmread通常也能直接处理，但保险起见可以先用gzip.open()解压后再读。

4.3 长表和宽表的问题：不要用 read.csv 硬读 mtx

我见过有同事把 mtx 当成普通文本，用 pandas 的read_csv去读，结果 8 万细胞的数据读了几十分钟，内存直接打满。mtx 是稀疏坐标格式，关掉 sparse 存储优势，内存开销是恐怖的。

举例说明差别：10 万细胞、3 万基因的完整稠密矩阵，即便每个数值只占 4 字节，也需要 120 亿字节（约 12 GB）内存；如果转成 float64，就是 24 GB。而稀疏矩阵如果非零元素只占 5%，内存占用可以降到原来的 5% 左右。所以正确做法永远是scipy.io.mmread读入并保持 sparse 结构，任何.toarray()操作都要慎重。如果你有特殊需求必须转稠密，至少先确认数据规模在可承受范围内。

5. 常见问题排查与避坑记录

转换过程中我踩过不少坑，有些浪费了我一整个下午。这里整理成问题速查表，按频率从高到低排列。

5.1 基因名重复、缺失和符号冲突

这个问题在小鼠数据里尤为突出。小鼠基因名存在大量像Sep-15、Mt1、Mar-01这样的命名，和日期、数字冲突，10X 的 features 文件里偶尔出现重复。如果在构建 AnnData 时没有处理，后续所有需要按基因名索引的操作都会出问题。

处理方法有三层：

• 读 10X 目录时，设置make_unique=True自动给重复名添加后缀；
• 手动构建时，先adata.var_names_make_unique()；
• 更稳妥的做法是导出 R 时，把 ENSEMBL ID 作为 var 索引，symbol 放在独立列，从根上避免重复。

我现在的习惯是：凡是准备进入深度分析的数据，var 索引一律用 ENSEMBL ID，symbol 单独存一列。这样既不丢生物学可读性，也不会因为 symbol 重复导致索引错乱。

5.2 细胞条码后缀不一致导致 meta 匹配失败

一个非常隐晦的坑。Seurat 在读入 10X 数据后，默认会给细胞条码加上_1之类的 sample 后缀（以obj@meta.data$barcode为例），而 Python 侧读原始barcodes.tsv时，条码是纯净的AAACCTGAG...形式。如果你把 Seurat 里的 meta 直接塞给 Python，两边索引对不上：meta.loc[barcodes]会报 KeyError。

解决方案是统一规则，我建议以 R 导出的条码为准：

# 如果 meta 里是 "AAACCTGAG...-1" 而 barcodes 里没有后缀 # 可以把 meta 索引的后缀去掉再匹配 meta_clean = meta.copy() meta_clean.index = [b.split("-")[0] for b in meta_clean.index] meta_clean = meta_clean.loc[barcodes].copy()

还有另一种情况：两个样本合并后，Seurat 里有AAACCTGAG...-1和AAACCTGAG...-2，这种重复条码在 R 侧本来就不唯一，导出时务必确认colnames(counts)是唯一的。如果不唯一，建议在 R 侧先RenameCells()统一加后缀，让每个条码全局唯一。

5.3 内存爆炸：稀疏矩阵怎么保命

转换大矩阵时，内存是最大的物理瓶颈。8 万细胞、3 万基因的 counts 矩阵，用稀疏格式存储大概占 200 到 600 MB，完全可控；但如果你不小心把矩阵转成稠密格式，12 GB 以上的内存需求会让很多个人工作站直接卡死。

几个实用操作：

• 读入后立即csr_matrix()压缩，不要用默认的 coo 格式做后续计算；
• 绝对避免.toarray()；
• 如果数据量实在太大，用 AnnData 的 backed 模式：adata.write_h5ad(..., compression="gzip")只影响存储，不影响计算；后续用adata = ad.read_h5ad("file.h5ad", backed="r")可以按需读取切片，不用把整个文件载入内存。

另外提一个细节：write_h5ad加上compression="gzip"会让文件小很多，但写入时间会明显变长，而且 gzip 压缩后的 h5ad 在部分旧版本 anndata 里读取会略慢。批量转换时可以先不压缩，确认没有问题后再二次压缩保存。

5.4 数据错位而代码不报错：怎么自查

最危险的情况不是报错，而是数据静默错位。比如矩阵某一行整体平移了一位，不仔细看完全发现不了。我自己总结了一套快速自查流程：

• 总 UMI 比对：R 里sum(counts)，Python 里adata.X.sum()，必须一致；
• 按细胞抽查：随机找 5 个细胞，在 R 和 Python 里分别计算它们的基因表达总和，逐一比对；
• 按基因抽查：随机找 5 个已知高表达基因，比如ACTB、MALAT1，在两个环境里分别看它们在这批细胞里的表达和占比；
• 检查维度：adata.X.shape[0]必须等于len(barcodes)，shape[1]必须等于len(genes)。

这套检查做完只要五分钟，但能避免百分之九十九的错位问题。

5.5 元数据类型和 counts 类型的陷阱

还有一个经常忽略的细节是数据类型。R 的meta.data里如果有数值列（比如percent.mt、nCount_RNA），导出 CSV 再读回 pandas 通常没问题；但如果有因子列，读回来会变成字符串，后续排序就乱。所以导出 meta 前，建议把所有分类列先as.character()，数值列确认是 numeric。

表达矩阵这边，mmread()读出来的永远是浮点，如果是 counts，务必转换回整数。否则有些流程会拿 float 的 counts 去做负二项建模，报错或者结果异常。归一化数据则相反，应保留浮点。记住一个原则：counts 是整数，表达值是浮点，两者混了后面必出问题。

6. 我的实操心得与额外建议

转格式这件事看起来简单，但实际操作中我逐渐形成了一套方法论。分享几个个人经验，不一定都写在教科书里，但很实用。

6.1 并不是所有数据都值得转

如果你的分析完全在 R 生态里，下游就是做做热图、跑跑通路富集，那没必要为了转格式而转格式。转换本身有时间成本，还会带来数据错位的风险。只有在跨生态协作、要跑 Python 深度学习模型、或者要用 h5ad 做长期归档时才值得转。

h5ad 让我特别喜欢的一点是，它支持把整个分析历史写进uns里。我每次转换都会在 h5ad 里记录来源信息：

adata.uns["conversion_log"] = { "source": "your_seurat_obj.rds", "converted_by": "your_name", "date": "2025-01-15", "r_version": "4.3.1", "seurat_version": "5.0.0", "python_version": "3.10.12", "anndata_version": "0.10.0", "notes": "counts from RNA assay, raw integer matrix" }

这样别人拿到这个 h5ad，打开第一眼就知道这份数据从哪来、经过什么处理，不需要额外翻邮件和文档。

6.2 小规模可行性验证：不要一上来就跑全量

我的习惯是转换脚本写好之后，先用几百个细胞、几千个基因的子集跑通一遍。可以在 R 里先对对象做obj_sub <- subset(obj, cells = colnames(obj)[1:500])，然后走一遍完整流程。这样整个过程只需要几十秒，如果脚本有低级错误（比如写错文件名、转置方向反了），能立刻暴露。确认无误后，再全量跑，中间定时盯着内存和磁盘占用。

还有一个容易忽略的点：转换过程中间文件（mtx、genes、barcodes、meta）有几个 GB，转完记得清理。很多人的服务器 /tmp 分区被撑爆，往往就是因为这些中间产物没收拾。

6.3 团队协作时的格式管理约定

如果这份数据要传给同事，或者过几个月自己回来看，有几个约定能让双方都省心：

• 明确 counts 还是归一化值：h5ad 里X如果是 counts，建议设adata.raw = adata.copy()备份一份；如果是表达值，务必在uns["conversion_log"]里写明；
• 基因名规范：统一用 Ensembl ID 做 var 索引，symbol 放列；
• 保留原始文件：rds 和 mtx 原始文件不要删，h5ad 只是下游分析的输入，不是唯一真相；
• 脚本化：转换代码整理成可重复执行的脚本，顺便把 R 的sessionInfo()和 Python 环境导出文件一起保存。以后谁要复现，直接跑脚本即可。

我在实际工作中发现，格式转换这种事，最难的不是写代码，而是保证数据在转换前后语义一致。矩阵方向、索引顺序、数据类型这三个地方任何一个出错，都会导致下游分析结果不可信。每次转换后花五分钟做一致性验证，比事后排查浪费一周要划算得多。这套方法我用了很久，整体很稳，希望也能帮大家少踩点坑。