读取数据：三个核心函数

好，到了真正动手的环节了。

数据读取，是所有分析的起点。这一步如果错了，后面全是白费功夫。我个人习惯在项目一开始就花几分钟确认数据格式，而不是跑了几十个步骤才发现读进来的数据是空的——这种坑我踩过不止一次。

今天咱们就聊透 Scanpy 的三个主力读取函数：read_10x_mtx、read_h5ad 和 read_csv。每个函数长什么样，参数怎么配，什么时候用哪个，我给你掰扯清楚。

4.1 家族图谱：数据从哪里来

在读代码之前，先让你对这三个函数的关系有个整体感觉。下面这张图总结了它们各自服务的场景：

4.2 read_10x_mtx：标准 10X 数据读取

做单细胞分析，10X Genomics 的数据格式基本是标配。你从 Cell Ranger 拿到的输出目录里，通常会有一个 filtered_feature_bc_matrix 文件夹。里面有三个文件：matrix.mtx、barcodes.tsv 和 features.tsv。

read_10x_mtx 就是专门吃这种结构的。你用不着手动拼文件路径，它自己会去目录里找。

import scanpy as sc

adata = sc.read_10x_mtx(
    path="data/filtered_feature_bc_matrix/",
    var_names="gene_symbols",
    make_unique=True
)
print(adata)
# Output: AnnData object with n_obs × n_vars = 5000 × 33694

# 错误示范：自己拼接文件路径
adata = sc.read_10x_mtx("data/matrix.mtx")  # 不要这样做！

# 正确做法：给目录路径
adata = sc.read_10x_mtx("data/filtered_feature_bc_matrix/")

还有一个细节：var_names 选 "gene_symbols" 还是 "gene_ids"？我推荐前者，因为后续画图、查找 marker 时，人类可读的基因名比 ENSEMBL ID 直观太多。

4.3 read_h5ad：加载已处理数据

如果你手头有一份 .h5ad 文件，那真是最省心的格式了。h5ad 是 AnnData 的原生持久化格式，里面把矩阵、观测信息、变量信息、非结构化元数据全都打包了。说白了，读进来就直接是一个完整的 AnnData 对象，什么都不用再配。

adata = sc.read_h5ad("path/to/processed_data.h5ad")
print(adata)
# Output: AnnData object with n_obs × n_vars = 15000 × 2000
#     obs: 'cell_type', 'sample_id', 'n_genes'
#     var: 'highly_variable'
#     uns: 'pca', 'umap', 'neighbors'

你可能会问：那什么时候用 read_10x_mtx，什么时候用 read_h5ad？我一般这样区分：

4.4 read_csv：灵活导入外部表格

现实工作中，数据格式并不总是那么标准。有时候你会拿到第三方平台导出的 CSV、TSV，或者某个实验室自己整理的表达矩阵。read_csv 就是为你提供后门的。

import pandas as pd
import scanpy as sc

# 先读成 DataFrame
df = pd.read_csv("my_data.csv", index_col=0)
# 再转成 AnnData
adata = sc.AnnData(X=df.values,
                   obs=pd.DataFrame(index=df.index),
                   var=pd.DataFrame(index=df.columns))
print(adata.shape)
# Output: (8000, 30000)

read_csv 的参数其实不多，因为它本质上是给 pd.read_csv 搭了个桥：

4.5 实战对比：我该怎么选？

为了让你更直观地记住区别，我把三个函数的核心特征拉了个表：