rnanorm 完整使用手册RNA测序标准化Python工具一、rnanorm 包概述与核心功能1. 包定位rnanorm是专为RNA-seq转录组测序开发的标准化归一化Python工具配套经典转录组定量算法兼容featureCounts、Salmon、Kallisto、STAR输出的基因表达计数矩阵替代R语言edgeR/ DESeq2的标准化流程轻量、支持批量处理、可嵌入Python生信流水线。2. 核心功能分类1主流转录组归一化算法实现CPM/CPM-log2每百万计数基础文库深度校正TPM转录本每百万校正基因长度测序深度转录本水平FPKM/FPKM-UQ基因水平校正长度文库深度TMMedgeR加权中位数标准化消除高表达基因偏差差异分析首选DESeq2 Median RatioMRN中位数比率标准化适合差异基因筛选Geometric mean TPM几何均值校正适用于qPCR联合转录组Quantile normalization分位数标准化芯片/RNA-seq通用CLR中心化对数转换微生物/宏转录组相对丰度校正2配套辅助功能自动读取多种定量输出文件csv/tsv/featureCounts汇总表基因长度自动匹配GTF/GFF提取基因长度批量样本归一化、分群分组标准化病例/对照分开校正输出标准化矩阵、绘图接口文库分布箱线图、标准化前后密度图低表达基因过滤、去离群样本预处理兼容单细胞RNA-seq粗计数矩阵简易标准化3. 优势纯Python实现无需R环境调用适合自动化Snakemake、Nextflow流水线速度远快于rpy2调用R归一化函数输出格式直接适配scanpy、pandas、seaborn下游分析内置异常值检测、标准化质控指标输出二、rnanorm 完整安装教程1. 基础pip安装稳定版pipinstallrnanorm# 国内加速pipinstallrnanorm-ihttps://pypi.tuna.tsinghua.edu.cn/simple2. 源码安装开发版含最新算法gitclone https://github.com/biocore/rnanorm.gitcdrnanorm pipinstall.3. 依赖环境自动安装如缺失手动补pipinstallpandas numpy scipy matplotlib seaborn gff3pyrpandas矩阵读写numpy数值计算scipy统计标准化gff3pyrGTF基因长度提取matplotlib/seaborn质控绘图4. 版本校验importrnanormprint(rnanorm.__version__)三、核心语法、函数与全参数详解rnanorm分为命令行接口CLI和Python API编程调用两套语法生信流水线多用CLI交互式分析用API。一Python API 核心对象Normalizer1. 类初始化语法fromrnanormimportNormalizer normNormalizer(method:str,# 归一化算法必填gene_lengths:pd.SeriesNone,# 基因长度TPM/FPKM必须group:pd.SeriesNone,# 样本分组TMM/MRN分组校正filter_low_counts:boolTrue,# 过滤低表达基因min_count:int10,# 最低总计数阈值log_transform:boolFalse,# 是否log2转换pseudo_count:float1.0,# log转换加伪计数避免0)2. 核心参数完整说明参数取值范围作用必需场景methodcpm,tpm,fpkm,tmm,deseq2,quantile,clr,cpm_log指定标准化算法全部场景必填gene_lengthspandas Seriesindexgene_idvaluelength基因外显子总长度TPM、FPKM、FPKM-UQ必填groupSeriesindexsample_idvaluegroupcontrol/treat分组独立标准化TMM、DESeq2中位数比率filter_low_countsTrue/False移除跨样本总计数过低基因差异分析建议Truemin_count整数基因所有样本计数总和低于该值则过滤filter_low_countsTrue生效log_transformTrue/False输出log2(标准化值pseudo_count)可视化、聚类分析开启pseudo_count浮点数对数转换加偏移防止log2(0)报错log_transformTrue生效reference_sampleslistTMM算法指定参考样本集TMM标准化优化upper_quantilefloat(0-1)FPKM-UQ上分位数阈值method“fpkm_uq”3. 标准化执行与输出语法# counts_matrixpandas DataFrame行gene列sample值raw read countsnorm_matrixnorm.fit_transform(counts_matrix)# 质控指标获取size_factorsnorm.size_factors# 文库校正因子TMM/DESeq2norm.plot_distribution(outputnorm_qc.png)# 绘制标准化前后分布对比图二命令行CLI语法批量处理脚本推荐rnanorm normalize\--countscounts.tsv\--methodtmm\--gene-lengths gene_lengths.tsv\--sample-groups groups.tsv\--log-transform\--outputnormalized_matrix.tsv\--qc-plot qc_dist.png关键CLI参数对应API文件均为制表符分隔TSV--counts原始计数矩阵--gene-lengths两列gene_id、length--sample-groups两列sample_id、group--filter-min-count低表达过滤阈值四、8个完整可运行实际应用案例前置公共数据准备所有案例共用importpandasaspdimportnumpyasnpfromrnanormimportNormalizer# 1. 模拟RNA-seq原始计数矩阵500基因6样本3对照3处理np.random.seed(42)raw_countspd.DataFrame(np.random.randint(0,5000,size(500,6)),index[fgene_{i}foriinrange(500)],columns[ctrl1,ctrl2,ctrl3,treat1,treat2,treat3])# 2. 模拟基因长度SeriesTPM/FPKM使用gene_lenpd.Series(np.random.randint(300,3000,size500),indexraw_counts.index)# 3. 样本分组信息TMM/DESeq2分组校正sample_grouppd.Series([control,control,control,treat,treat,treat],indexraw_counts.columns)案例1基础CPM标准化文库深度校正全局表达量对比适用场景简单样本间基因丰度粗略比较不适合差异分析norm_cpmNormalizer(methodcpm,log_transformTrue,pseudo_count1)cpm_matrixnorm_cpm.fit_transform(raw_counts)# 输出结果cpm_matrix.to_csv(cpm_log2_matrix.tsv,sep\t)# 绘制质控图norm_cpm.plot_distribution(cpm_qc.png)案例2TPM标准化转录本水平跨基因长度校正适用场景单样本内部基因表达丰度排序、转录本定量Salmon输出norm_tpmNormalizer(methodtpm,gene_lengthsgene_len)tpm_matrixnorm_tpm.fit_transform(raw_counts)tpm_matrix.to_csv(tpm_matrix.tsv,sep\t)案例3FPKM-UQ标准化基因水平肿瘤转录组常规校正适用场景癌症RNA-seq消除超长基因表达干扰norm_fpkmNormalizer(methodfpkm_uq,gene_lengthsgene_len,upper_quantile0.75)fpkm_uq_matnorm_fpkm.fit_transform(raw_counts)案例4TMM标准化edgeR算法差异基因分析金标准适用场景病例/对照分组差异筛选、批量转录组差异分析支持分组校正norm_tmmNormalizer(methodtmm,gene_lengthsNone,groupsample_group,filter_low_countsTrue,min_count20,log_transformTrue)tmm_log_matnorm_tmm.fit_transform(raw_counts)# 提取文库校正因子用于下游差异计算size_factornorm_tmm.size_factorsprint(TMM文库校正因子\n,size_factor)tmm_log_mat.to_csv(tmm_log2_norm.tsv,sep\t)案例5DESeq2中位数比率标准化适合低深度测序样本适用场景小样本量、低测序深度转录组稀有基因差异检测norm_deseqNormalizer(methoddeseq2,groupsample_group,filter_low_countsTrue)deseq_normnorm_deseq.fit_transform(raw_counts)案例6分位数标准化芯片RNA-seq整合、聚类分析适用场景多批次数据整合、表达模式聚类、PCA降维norm_quantNormalizer(methodquantile,log_transformTrue)quant_matnorm_quant.fit_transform(raw_counts)# 直接导入scanpy做PCAimportscanpyassc adatasc.AnnData(quant_mat.T)sc.tl.pca(adata)sc.pl.pca(adata,saverna_pca.png)案例7CLR中心化对数标准化宏转录组/微生物转录组适用场景菌群转录组、相对丰度数据消除组成型偏差norm_clrNormalizer(methodclr)clr_matnorm_clr.fit_transform(raw_counts)clr_mat.to_csv(clr_metatranscriptome.tsv,sep\t)案例8GTF文件自动提取基因长度批量TPM流水线完整自动化流程适用场景真实下机featureCounts数据从GTF提取长度一键归一化fromrnanorm.ioimportload_gene_lengths# 从基因组注释GTF提取所有基因长度gene_lengthsload_gene_lengths(hg38.gtf,featuregene,id_attrgene_id)# 读取真实featureCounts输出矩阵rawpd.read_csv(featureCounts_counts.tsv,sep\t,index_col0)# 过滤仅保留蛋白编码基因匹配长度common_genesraw.index.intersection(gene_lengths.index)raw_filterraw.loc[common_genes,:]len_filtergene_lengths.loc[common_genes]# 批量TPM归一化并输出normNormalizer(methodtpm,gene_lengthslen_filter)tpm_outnorm.fit_transform(raw_filter)tpm_out.to_csv(batch_tpm_all_samples.tsv,sep\t)五、常见报错、原因与解决方案1. ValueError: gene_lengths must be provided for TPM/FPKM原因使用tpm/fpkm算法但未传入gene_lengths参数解决传入index与count矩阵完全匹配的基因长度Series2. KeyError: Some gene IDs missing in gene_lengths原因计数矩阵基因ID与长度文件ID不匹配大小写、版本ID不一致解决取交集过滤基因common counts.index.intersection(gene_len.index)只保留共有基因3. RuntimeWarning: Division by zero in size factor calculation原因存在全样本计数为0的基因文库校正计算分母为0解决开启filter_low_countsTrue设置合理min_count过滤空表达基因4. ValueError: group series index does not match count columns原因分组信息样本名和计数矩阵列名不一致空格、后缀差异解决统一样本ID格式对齐索引5. ImportError: No module named gff3pyr原因缺少GTF读取依赖包解决pip install gff3pyr6. Log transform error: log2(0) encountered原因未设置pseudo_count标准化后存在0值取对数解决log_transformTrue时固定pseudo_count17. MemoryError: Large count matrix原因上万基因上百样本矩阵内存溢出解决使用CLI分文件读写或分批次归一化用dtypenp.float32压缩矩阵8. MethodNotFoundError: method‘xxx’ not supported原因输入算法名称拼写错误区分大小写不能写Tmm、DESeq支持字符串cpm, tpm, fpkm, fpkm_uq, tmm, deseq2, quantile, clr, cpm_log六、关键使用注意事项生信分析避坑要点1. 算法选择边界最重要TPM仅用于单样本内基因丰度比较不能直接用于组间差异分析组间对比优先TMM/DESeq2CPM仅粗略可视化受高表达管家基因干扰严禁做差异检验TMM/DESeq2差异基因筛选标准方案必须提供样本分组提升校正精度Quantile适合聚类、PCA会破坏真实表达倍数变化不做差异分析2. 输入矩阵规范行基因ID列样本ID数值必须是原始整数reads计数不可提前输入CPM/TPM二次校正样本名禁止包含空格、特殊符号#、/、-避免读写报错3. 基因长度文件规范GTF提取长度必须为基因全长外显子总和不可用转录本长度混用TPM/FPKM非编码RNA、lncRNA长度过短会导致TPM异常偏高建议单独过滤4. 低表达过滤逻辑差异分析必须开启过滤极低计数基因统计噪音极大会扭曲文库校正因子min_count根据测序深度调整30M reads设置10~20100M深度可设505. 对数转换使用场景绘图、聚类、PCA必须log2转换差异统计检验使用原始标准化值不要log后做检验pseudo_count统一设1保证全流程可复现6. 批量流水线兼容Nextflow/Snakemake推荐使用CLI接口减少Python环境交互异常标准化校正因子size_factors必须保存后续差异分析工具需要复用7. 单细胞RNA-seq限制rnanorm仅适用于bulk RNA-seq单细胞数据推荐scanpy归一化CLR仅可粗略校正不做精细分析8. 可重复性要求固定random seed完整记录method、min_count、pseudo_count、过滤阈值所有参数写入流程脚本避免人为调参偏差《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。