data-export-excel

Excel 数据导出（通用）

概述

此技能可将生物信息学数据、分析结果和格式化表格导出为专业的 Excel 电子表格。与云托管解决方案不同，此技能使用 openpyxl Python 库，并在你的环境中本地执行，因此兼容所有 LLM 提供商，包括 GPT、Gemini、Claude、DeepSeek 和 Qwen。

何时使用此技能

• 将 AnnData 观测值（.obs）或变量（.var）导出到 Excel
• 保存经过格式化的 DEG 分析结果
• 创建包含不同数据类型的多工作表工作簿
• 生成带有单元格样式的 Excel 格式报告
• 导出聚类注释、细胞类型分配或质量控制指标

如何使用

步骤 1：导入所需库

import openpyxl
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
from openpyxl.utils.dataframe import dataframe_to_rows
import pandas as pd
import numpy as np

步骤 2：准备数据

将数据转换为 pandas DataFrame 格式：

# Example: Export AnnData observations
df = adata.obs.copy()

# Example: Export DEG results
deg_df = pd.DataFrame({
    'gene': gene_names,
    'log2FC': log2_fold_changes,
    'pvalue': pvalues,
    'qvalue': qvalues
})

# Example: Export cluster statistics
cluster_stats = adata.obs.groupby('clusters').size().reset_index(name='count')

步骤 3：创建 Excel 工作簿

# Create new workbook
wb = Workbook()
ws = wb.active
ws.title = "Sheet Name"

# Write DataFrame to worksheet
for r in dataframe_to_rows(df, index=False, header=True):
    ws.append(r)

步骤 4：添加格式（可选）

# Style header row
header_fill = PatternFill(start_color="4472C4", end_color="4472C4", fill_type="solid")
header_font = Font(bold=True, color="FFFFFF")

for cell in ws[1]:
    cell.fill = header_fill
    cell.font = header_font
    cell.alignment = Alignment(horizontal='center')

# Auto-adjust column widths
for column in ws.columns:
    max_length = 0
    column_letter = column[0].column_letter
    for cell in column:
        try:
            if len(str(cell.value)) > max_length:
                max_length = len(str(cell.value))
        except:
            pass
    adjusted_width = min(max_length + 2, 50)
    ws.column_dimensions[column_letter].width = adjusted_width

# Add borders
thin_border = Border(
    left=Side(style='thin'),
    right=Side(style='thin'),
    top=Side(style='thin'),
    bottom=Side(style='thin')
)
for row in ws.iter_rows(min_row=1, max_row=ws.max_row, min_col=1, max_col=ws.max_column):
    for cell in row:
        cell.border = thin_border

步骤 5：保存工作簿

# Save to file
output_path = "analysis_results.xlsx"
wb.save(output_path)
print(f"✅ Excel file saved to: {output_path}")

多工作表工作簿

为不同的数据类型创建包含多个工作表的工作簿：

wb = Workbook()

# Sheet 1: Cell metadata
ws1 = wb.active
ws1.title = "Cell Metadata"
for r in dataframe_to_rows(adata.obs, index=True, header=True):
    ws1.append(r)

# Sheet 2: Gene metadata
ws2 = wb.create_sheet("Gene Metadata")
for r in dataframe_to_rows(adata.var, index=True, header=True):
    ws2.append(r)

# Sheet 3: DEG results
ws3 = wb.create_sheet("DEG Results")
for r in dataframe_to_rows(deg_df, index=False, header=True):
    ws3.append(r)

wb.save("multi_sheet_analysis.xlsx")

最佳实践

1. 列标题：始终在第一行包含列标题
2. 数据类型：写入前将 numpy 数组转换为列表
3. 大型数据集：对于超过 100K 行的数据集，可考虑改用 CSV 导出
4. 文件路径：使用绝对路径，或确保输出目录已存在
5. 格式设置：尽量少用格式设置，以减小文件大小
6. 索引：决定是否包含 DataFrame 索引（在 dataframe_to_rows 中设置 index=True/False）

常见用例

导出质量控制指标

qc_metrics = adata.obs[['n_genes', 'n_counts', 'percent_mito', 'clusters']].copy()

wb = Workbook()
ws = wb.active
ws.title = "QC Metrics"

for r in dataframe_to_rows(qc_metrics, index=False, header=True):
    ws.append(r)

# Highlight cells with high mitochondrial content
for row in range(2, ws.max_row + 1):
    if ws.cell(row, 3).value > 0.2:  # percent_mito > 20%
        ws.cell(row, 3).fill = PatternFill(start_color="FFC7CE", end_color="FFC7CE", fill_type="solid")

wb.save("qc_metrics.xlsx")

按聚类导出标记基因

# Assuming you have marker genes for each cluster
marker_dict = {
    'Cluster_0': ['CD3D', 'CD3E', 'CD8A'],
    'Cluster_1': ['CD79A', 'MS4A1', 'CD19'],
    'Cluster_2': ['LYZ', 'S100A9', 'CD14']
}

wb = Workbook()

for cluster_name, genes in marker_dict.items():
    ws = wb.create_sheet(cluster_name)
    ws.append(['Marker Gene'])
    for gene in genes:
        ws.append([gene])

# Remove default sheet
if 'Sheet' in wb.sheetnames:
    wb.remove(wb['Sheet'])

wb.save("marker_genes.xlsx")

导出带有条件格式的 DEG 分析结果

wb = Workbook()
ws = wb.active
ws.title = "DEG Analysis"

# Write DEG results
for r in dataframe_to_rows(deg_df, index=False, header=True):
    ws.append(r)

# Color code by fold change
for row in range(2, ws.max_row + 1):
    log2fc = ws.cell(row, 2).value  # Assuming log2FC in column 2
    if log2fc > 1:  # Upregulated
        ws.cell(row, 2).fill = PatternFill(start_color="C6EFCE", end_color="C6EFCE", fill_type="solid")
    elif log2fc < -1:  # Downregulated
        ws.cell(row, 2).fill = PatternFill(start_color="FFC7CE", end_color="FFC7CE", fill_type="solid")

wb.save("deg_results_formatted.xlsx")

故障排除

问题：“找不到 openpyxl”

解决方案：安装该库：

import subprocess
subprocess.check_call(['pip', 'install', 'openpyxl'])

问题：“单元格的数据类型无效”

解决方案：将 numpy/pandas 类型转换为原生 Python 类型：

# Convert numpy types
df = df.astype(object).where(pd.notnull(df), None)

# Or convert specific columns
df['column_name'] = df['column_name'].astype(str)

问题：“大型数据集导致内存错误”

解决方案：分块导出，或改用 CSV 格式：

# Fallback to CSV for large data
df.to_csv('large_dataset.csv', index=False)
print("Dataset too large for Excel, saved as CSV instead")

技术说明

• 库：使用 openpyxl（纯 Python，无外部依赖）
• 执行方式：在 Agent 的沙盒中本地运行
• 兼容性：兼容所有 LLM 提供商（GPT、Gemini、Claude、DeepSeek、Qwen 等）
• 文件限制：Excel 最多支持 1,048,576 行（更大的数据集请使用 CSV）
• 性能：写入约 10K 行需要 1–2 秒；写入 100K 行需要 10–20 秒

参考资料

• openpyxl 文档：https://openpyxl.readthedocs.io/
• pandas DataFrame 导出：https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_excel.html