alterlab-eda

探索性数据分析

概览

对跨多个领域的科学数据文件执行全面的探索性数据分析（EDA）。此技能提供自动文件类型检测、特定格式分析、数据质量评估，并生成适合用于文档记录和下游分析规划的详细 Markdown 报告。

主要功能：

• 在分析器脚本中自动检测约 90 种文件扩展名（包括 .fastq.gz 等 gzip/bz2/xz 压缩变体），并提供 200 多种格式的参考条目
• 全面提取特定格式的元数据
• 评估数据质量和完整性
• 提供统计摘要和分布信息
• 推荐可视化方案
• 提出下游分析建议
• 生成 Markdown 报告

何时使用此技能

在以下情况下使用此技能：

• 用户提供了需要分析的科学数据文件路径
• 用户要求“探索”“分析”或“总结”数据文件
• 用户想了解科学数据的结构和内容
• 用户需要在分析前获取数据集的综合报告
• 用户想评估数据质量或完整性
• 用户询问某个文件适合进行何种分析

不适用的情况

场景	改用
对已完成探索的时间序列进行预测	alterlab-timesfm
创建或配置分块 Zarr 数组存储（编解码器、分块布局、云存储）	alterlab-zarr
对 .h5ad 运行完整的单细胞工作流（QC 过滤、标准化、聚类、标记物）	alterlab-scanpy
在检查假设的基础上选择并执行假设检验，同时提供 APA 格式报告	alterlab-statistical-analysis

支持的文件类别

此技能全面涵盖科学文件格式，并将其归为六大类：

1. 化学与分子格式（60 多种扩展名）

结构文件、计算化学输出、分子动力学轨迹和化学数据库。

文件类型包括： .pdb、.cif、.mol、.mol2、.sdf、.xyz、.smi、.gro、.log、.fchk、.cube、.dcd、.xtc、.trr、.prmtop、.psf 等。

参考文件： references/chemistry_molecular_formats.md

2. 生物信息学与基因组学格式（50 多种扩展名）

序列数据、比对结果、注释、变异和表达数据。

文件类型包括： .fasta、.fastq、.sam、.bam、.vcf、.bed、.gff、.gtf、.bigwig、.h5ad、.loom、.counts、.mtx 等。

参考文件： references/bioinformatics_genomics_formats.md

3. 显微镜与成像格式（45 多种扩展名）

显微镜图像、医学成像、全视野切片成像和电子显微镜图像。

文件类型包括： .tif、.nd2、.lif、.czi、.ims、.dcm、.nii、.mrc、.dm3、.vsi、.svs、.ome.tiff 等。

参考文件： references/microscopy_imaging_formats.md

4. 光谱学与分析化学格式（35 多种扩展名）

核磁共振（NMR）、质谱、红外/拉曼、紫外-可见、X 射线、色谱及其他分析技术。

文件类型包括： .fid、.mzML、.mzXML、.raw、.mgf、.spc、.jdx、.xy、.cif（晶体学）、.wdf 等。

参考文件： references/spectroscopy_analytical_formats.md

5. 蛋白质组学与代谢组学格式（30 多种扩展名）

质谱蛋白质组学、代谢组学、脂质组学和多组学数据。

文件类型包括： .mzML、.pepXML、.protXML、.mzid、.mzTab、.sky、.mgf、.msp、.h5ad 等。

参考文件： references/proteomics_metabolomics_formats.md

6. 通用科学数据格式（30 多种扩展名）

数组、表格、分层数据、压缩归档文件和常见科学格式。

文件类型包括： .npy、.npz、.csv、.xlsx、.json、.hdf5、.zarr、.parquet、.mat、.fits、.nc、.xml 等。

参考文件： references/general_scientific_formats.md

工作流

步骤 1：检测文件类型

用户提供文件路径时，首先识别文件类型：

1. 提取文件扩展名
2. 在相应的参考文件中查找该扩展名
3. 确定文件类别和格式说明
4. 加载特定格式的信息

示例：

User: "Analyze data.fastq"
→ Extension: .fastq
→ Category: bioinformatics_genomics
→ Format: FASTQ Format (sequence data with quality scores)
→ Reference: references/bioinformatics_genomics_formats.md

步骤 2：加载特定格式的信息

根据文件类型，阅读相应的参考文件，了解：

• 典型数据： 此格式包含哪类数据
• 使用场景： 此格式的常见应用
• Python 库： 如何在 Python 中读取文件
• EDA 方法： 适用于此类数据的分析方法

在参考文件中搜索具体的扩展名（例如，在 bioinformatics_genomics_formats.md 中搜索 "### .fastq"）。

步骤 3：执行数据分析

使用 scripts/eda_analyzer.py 脚本，或自行实现分析：

选项 A：使用分析器脚本（自动检测类型、加载参考信息、运行特定格式的分析并生成报告）

uv run python scripts/eda_analyzer.py <filepath> [output.md]

该脚本内置了针对表格数据（.csv/.tsv）、数组（.npy/.npz/.hdf5）、JSON、序列数据（.fasta/.fastq，也支持 gzip/bz2/xz 压缩）和基础图像数据（.tif）的分析器。对于其他所有格式，脚本仍会检测类型并嵌入参考信息，但需要你自行分析数据（选项 B）。

选项 B：在对话中自定义分析 根据参考文件中的格式信息，执行适当的分析：

对于表格数据（CSV、TSV、Excel）：

• 使用 pandas 加载（在 pandas 3 中，文本列会以 str dtype 加载；select_dtypes(include='object') 仍会匹配这些列，但已弃用，因此请使用 exclude='number'，此方法兼容 pandas 2 和 3）
• 检查维度和数据类型
• 分析缺失值
• 计算汇总统计
• 识别异常值
• 检查重复项

对于序列数据（FASTA、FASTQ）：

• 统计序列数量
• 分析长度分布
• 计算 GC 含量
• 评估质量分数（FASTQ）

对于图像（TIFF、ND2、CZI）：

• 检查维度（X、Y、Z、C、T）
• 分析位深和取值范围
• 提取元数据（通道、时间戳、空间校准）
• 计算强度统计数据

对于数组（NPY、HDF5）：

• 检查形状和维度
• 分析数据类型
• 计算统计摘要
• 检查缺失/无效值

步骤 4：生成全面报告

创建 Markdown 报告，包含以下部分：

必需部分：

1. 标题和元数据

   • 文件名和时间戳
   • 文件大小和位置

2. 基本信息

   • 文件属性
   • 格式识别

3. 文件类型详情

   • 参考文件中的格式说明
   • 典型数据内容
   • 常见使用场景
   • 用于读取文件的 Python 库

4. 数据分析

   • 结构和维度
   • 统计摘要
   • 质量评估
   • 数据特征

5. 关键发现

   • 值得注意的模式
   • 潜在问题
   • 质量指标

6. 建议

   • 预处理步骤
   • 适当的分析
   • 工具和方法
   • 可视化方法

模板位置

使用 assets/report_template.md 作为报告结构的参考。

步骤 5：保存报告

使用描述性文件名保存 Markdown 报告：

• 格式：{original_filename}_eda_report.md
• 示例：experiment_data.fastq → experiment_data_eda_report.md

详细格式参考

每个参考文件都包含数十种文件类型的全面信息。要查找特定格式的信息：

1. 根据扩展名确定类别
2. 阅读相应的参考文件
3. 搜索与扩展名匹配的章节标题（例如 "### .pdb"）
4. 提取格式信息

参考文件结构

每个格式条目都包含：

• 描述： 格式的定义
• 典型数据： 包含的内容
• 使用场景： 常见应用
• Python 库： 如何读取（附代码示例）
• EDA 方法： 要执行的具体分析

查找示例：

### .pdb - Protein Data Bank
**Description:** Standard format for 3D structures of biological macromolecules
**Typical Data:** Atomic coordinates, residue information, secondary structure
**Use Cases:** Protein structure analysis, molecular visualization, docking
**Python Libraries:**
- `Biopython`: `Bio.PDB`
- `MDAnalysis`: `MDAnalysis.Universe('file.pdb')`
**EDA Approach:**
- Structure validation (bond lengths, angles)
- B-factor distribution
- Missing residues detection
- Ramachandran plots

最佳实践

读取参考文件

参考文件很大（每个超过 10,000 个单词）。要高效使用这些文件：

1. 按扩展名搜索： 使用 grep 查找特定格式

   import re
   with open('references/chemistry_molecular_formats.md', 'r') as f:
       content = f.read()
       pattern = r'### \.pdb[^#]*?(?=###|\Z)'
       match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
   

2. 提取相关章节： 不要在不必要时将整个参考文件加载到上下文中

3. 缓存格式信息： 如果要分析多个相同类型的文件，请重复使用格式信息

数据分析

1. 抽样分析大型文件： 对于包含数百万条记录的文件，分析有代表性的样本
2. 妥善处理错误： 许多科学格式需要特定的库；请提供清晰的安装说明
3. 验证元数据： 交叉检查元数据是否一致（例如，声明的维度与实际数据是否相符）
4. 考虑数据来源： 记录仪器、软件版本和处理步骤

报告生成

1. 内容全面： 包含下游分析所需的所有相关信息
2. 具体明确： 根据文件类型提供具体建议
3. 可付诸行动： 建议明确的后续步骤和工具
4. 包含代码示例： 展示如何加载和处理数据

示例

流程始终是：检测扩展名 -> 读取匹配的参考章节 -> 执行适合该格式的分析 -> 写入 <stem>_eda_report.md。

• reads.fastq -> 生物信息学。from Bio import SeqIO; SeqIO.parse(path, 'fastq')。报告读取数量、长度分布、每条读取的质量、GC 含量，然后提供质量控制建议。
• experiment_results.csv -> 通用科学数据。pd.read_csv。报告形状、数据类型、缺失值模式、汇总统计、相关性、重复项和异常值。
• cells.nd2 -> 显微成像（Nikon）。import nd2; f = nd2.ND2File(path)（f.sizes、f.metadata、f.voxel_size()）。报告 XYZCT 维度、通道/时间点、像素大小/校准、强度统计，然后提供图像分析建议。

故障排除

缺少库

许多科学格式需要专用库：

问题： 尝试读取文件时出现导入错误

解决方案： 使用 uv pip install <pkg> 安装解析器（本机上不要使用裸 pip），然后重试。各类别常见的依赖项：

• 生物信息学： biopython、pysam、pyBigWig
• 化学： rdkit、mdanalysis、cclib
• 显微成像： tifffile、nd2、bioio，以及格式插件，例如 bioio-czi 或 bioio-lif（作为已进入维护模式的 aicsimageio 的后继项目）、pydicom
• 光谱学： nmrglue、pymzml、pyteomics
• 通用： pandas、numpy、h5py、scipy

未知文件类型

如果参考资料中没有某个文件扩展名：

1. 询问用户文件格式
2. 检查它是否为供应商专用的变体
3. 根据文件结构（文本还是二进制）尝试通用分析
4. 提供通用建议

大型文件

对于非常大的文件：

1. 使用抽样策略（前 N 条记录）
2. 使用内存映射访问（适用于 HDF5、NPY）
3. 分块处理（适用于 CSV、FASTQ）
4. 根据样本提供估算值

脚本用法

uv run python scripts/eda_analyzer.py data.csv                 # report -> data_eda_report.md
uv run python scripts/eda_analyzer.py data.csv output_report.md

该脚本会自动检测文件类型（包括末尾带有 .gz/.bz2/.xz 的文件），加载匹配的参考章节，在支持时运行内置分析，并写入 Markdown 报告。对于没有内置分析器的格式，建议在对话中进行自定义分析（选项 B），以获取针对特定领域的见解。注意：对于 .csv/.tsv，脚本只抽取前 10,000 行进行采样，因此除非对整个文件重新运行，否则报告中的维度/缺失值数量均为采样值。

高级用法

• 多文件： 分别对每个文件进行 EDA，然后撰写对比报告，说明文件间的关系、依赖项和集成策略。
• 质量控制： 检查格式是否合规，验证元数据的一致性（声明的尺寸与实际尺寸是否相符），评估完整性，并标记超出预期范围的离群值或异常。
• 预处理建议： 根据数据量身定制，包括归一化、缺失值填补、离群值处理、批次校正和格式转换。

资源

scripts/

• eda_analyzer.py：综合分析脚本，可直接运行或导入

references/

• chemistry_molecular_formats.md：60 多种化学／分子文件格式
• bioinformatics_genomics_formats.md：50 多种生物信息学格式
• microscopy_imaging_formats.md：45 多种成像格式
• spectroscopy_analytical_formats.md：35 多种光谱格式
• proteomics_metabolomics_formats.md：30 多种组学格式
• general_scientific_formats.md：30 多种通用格式

assets/

• report_template.md：用于 EDA 报告的综合 Markdown 模板