scikit-bio

scikit-bio

概述

scikit-bio 是一个功能全面的 Python 库，可用于处理生物数据。适用于涵盖序列操作、比对、系统发育学、微生物生态学和多变量统计的生物信息学分析。

何时使用此技能

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

• 处理生物序列（DNA、RNA、蛋白质）
• 需要读取或写入生物文件格式（FASTA、FASTQ、GenBank、Newick、BIOM 等）
• 执行序列比对或搜索基序
• 构建或分析系统发育树
• 计算多样性指标（α/β 多样性、UniFrac 距离）
• 执行排序分析（PCoA、CCA、RDA）
• 对生物或生态数据进行统计检验（PERMANOVA、ANOSIM、Mantel）
• 分析微生物组或群落生态数据
• 处理来自语言模型的蛋白质嵌入
• 需要操作生物数据表

核心功能

1. 序列操作

使用专为 DNA、RNA 和蛋白质数据设计的类处理生物序列。

主要操作：

• 从 FASTA、FASTQ、GenBank、EMBL 格式读取或写入序列
• 序列切片、拼接和搜索
• 反向互补、转录（DNA→RNA）和翻译（RNA→蛋白质）
• 使用正则表达式查找基序和模式
• 计算距离（汉明距离、基于 k-mer 的距离）
• 处理序列质量分数和元数据

常见模式：

import skbio

# Read sequences from file
seq = skbio.DNA.read('input.fasta')

# Sequence operations
rc = seq.reverse_complement()
rna = seq.transcribe()
protein = rna.translate()

# Find motifs
motif_positions = seq.find_with_regex('ATG[ACGT]{3}')

# Check for properties
has_degens = seq.has_degenerates()
seq_no_gaps = seq.degap()

重要说明：

• 对经过验证的字母表序列使用 DNA、RNA、Protein 类
• 对不限制字母表的通用序列使用 Sequence 类
• 质量分数会自动从 FASTQ 文件加载到位置元数据中
• 元数据类型：序列级（ID、描述）、位置级（每个碱基）、区间级（区域/特征）

2. 序列比对

使用 pair_align 引擎执行成对和多序列比对。该引擎在 scikit-bio 0.7.0 中引入，是一种灵活高效的动态规划比对器。

主要功能：

• 在一个函数中执行全局、局部和半全局比对（可配置自由端）
• 提供便捷封装函数 pair_align_nucl（类似 BLASTN）和 pair_align_prot（类似 BLASTP）
• 可配置评分：匹配/错配元组或命名替换矩阵；线性或仿射空位罚分
• PairAlignPath 结果包含 CIGAR 字符串，并可转换为比对后的序列
• 使用 TabularMSA 存储和操作多序列比对

常见模式：

from skbio import DNA, Protein
from skbio.alignment import pair_align_nucl, pair_align_prot, pair_align, TabularMSA

# Nucleotide alignment with BLASTN-like defaults
seq1, seq2 = DNA('ACTACCAGATTACTTACGGATCAGG'), DNA('CGAAACTACTAGATTACGGATCTTA')
aln = pair_align_nucl(seq1, seq2)
aln.score                                  # alignment score (float)
path = aln.paths[0]                        # PairAlignPath (repr shows CIGAR)
aligned_seqs = path.to_aligned((seq1, seq2))  # list of gapped strings

# Build a TabularMSA from the alignment path + original sequences
msa = TabularMSA.from_path_seqs(path, (seq1, seq2))

# Customize the algorithm via pair_align (default mode='global')
aln = pair_align(seq1, seq2, mode='local')                       # Smith-Waterman
aln = pair_align(seq1, seq2, sub_score=(2, -3), gap_cost=(5, 2)) # affine gaps
aln = pair_align(seq1, seq2, sub_score='NUC.4.4', gap_cost=3)    # substitution matrix, linear gap

# Protein alignment (BLASTP-like, BLOSUM62)
aln = pair_align_prot(Protein('HEAGAWGHEE'), Protein('PAWHEAE'))

# Read a multiple alignment from file and summarize
msa = TabularMSA.read('alignment.fasta', constructor=DNA)
consensus = msa.consensus()

重要说明：

• pair_align 取代了已移除的 SSW 封装（local_pairwise_align_ssw、StripedSmithWaterman）以及已弃用的纯 Python 比对器（global_pairwise_align、local_pairwise_align_nucleotide 等）
• 结果为 PairAlignResult，也可解包为 score, paths, matrices（使用 keep_matrices=True 保留 DP 矩阵）
• sub_score 接受 (match, mismatch) 元组或矩阵名称（例如 'NUC.4.4'、'BLOSUM62'）；gap_cost 接受单个数字（线性）或 (open, extend) 元组（仿射）
• 使用 PairAlignPath.from_cigar('1I8M2D5M2I') 解析外部 CIGAR 字符串；使用 align_score(...) 为现有比对评分，并使用 align_dists(...) 从 MSA 构建距离矩阵

3. 系统发育树

构建、操作和分析表示进化关系的系统发育树。

主要功能：

• 根据距离矩阵构建树（UPGMA/WPGMA、Neighbor Joining、GME、BME）
• 使用最近邻互换（nni）重排树
• 操作树（剪枝、重新定根、遍历）
• 计算距离（通过 cophenet 计算系统发育距离，通过 compare_rfd 计算 Robinson-Foulds 距离）
• ASCII 可视化
• Newick 格式输入/输出

常见模式：

from skbio import TreeNode
from skbio.tree import nj, upgma, gme, bme, rf_dists

# Read tree from file
tree = TreeNode.read('tree.nwk')

# Construct tree from distance matrix
tree = nj(distance_matrix)

# Tree operations
subtree = tree.shear(['taxon1', 'taxon2', 'taxon3'])
tips = [node for node in tree.tips()]
lca = tree.lca(['taxon1', 'taxon2'])

# Calculate distances
patristic_dist = tree.find('taxon1').distance(tree.find('taxon2'))
cophenetic_dm = tree.cophenet()           # patristic distance matrix among tips

# Compare two trees (Robinson-Foulds)
rf_distance = tree.compare_rfd(other_tree)
# Pairwise RF distances among many trees -> DistanceMatrix
rf_dm = rf_dists([tree, other_tree, third_tree])

重要说明：

• 使用 nj() 进行 Neighbor Joining（经典系统发育方法）
• 使用 upgma() 进行 UPGMA/WPGMA（假设存在分子钟）
• GME 和 BME 可高度扩展，适用于大型树；使用 nni() 优化拓扑结构
• cophenet()（以前名为 tip_tip_distances）返回系统发育距离矩阵；compare_rfd() 是 Robinson-Foulds 方法（加权/共表型变体分别使用 compare_wrfd/compare_cophenet）
• lca() 表示最近共同祖先；lowest_common_ancestor 仍作为别名保留
• 树可以有根或无根；某些指标要求特定的定根方式

4. 多样性分析

计算微生物生态学和群落分析所需的 Alpha 和 Beta 多样性指标。

主要功能：

• Alpha 多样性：丰富度（sobs、observed_features、chao1、ace）、Shannon、Simpson、Hill 数（hill）、Faith's PD（faith_pd）、广义 PD（phydiv）、Pielou 均匀度
• Beta 多样性：Bray-Curtis、Jaccard、加权/非加权 UniFrac、欧氏距离
• 系统发育多样性指标（需要树作为输入）
• 稀释和子采样
• 与排序分析和统计检验集成

常见模式：

from skbio.diversity import alpha_diversity, beta_diversity

# Alpha diversity (phylogenetic metrics take taxa= for tip-name mapping)
alpha = alpha_diversity('shannon', counts_matrix, ids=sample_ids)
faith_pd = alpha_diversity('faith_pd', counts_matrix, ids=sample_ids,
                           tree=tree, taxa=feature_ids)

# Beta diversity
bc_dm = beta_diversity('braycurtis', counts_matrix, ids=sample_ids)
unifrac_dm = beta_diversity('unweighted_unifrac', counts_matrix,
                            ids=sample_ids, tree=tree, taxa=feature_ids)

# Get available metrics
from skbio.diversity import get_alpha_diversity_metrics
print(get_alpha_diversity_metrics())

重要说明：

• 计数必须是表示丰度的整数，而不是相对频率
• 系统发育指标的参数为 taxa=（在 0.6.0 中由 otu_ids 更名而来；旧名称是已弃用的别名）；observed_otus 现为 observed_features（或 sobs）
• 通过分发系统，counts_matrix 可以接受任意类表格输入（NumPy 数组、pandas/polars DataFrame、BIOM Table 或 AnnData）
• 系统发育指标（Faith's PD、UniFrac）需要树和分类单元到末端节点的映射
• 对特定样本对使用 partial_beta_diversity()，对大型分块计算使用 block_beta_diversity()
• Alpha 多样性返回 pandas.Series，Beta 多样性返回 DistanceMatrix

5. 排序分析方法

将高维生物数据降维到可视化的低维空间。

主要功能：

• 基于距离矩阵的 PCoA（主坐标分析）
• 用于列联表的 CA（对应分析）
• 带环境约束的 CCA（典范对应分析）
• 用于线性关系的 RDA（冗余分析）
• 用于解释特征的双标图投影

常见模式：

from skbio.stats.ordination import pcoa, cca
import skbio

# PCoA from distance matrix (limit dimensions for large matrices)
pcoa_results = pcoa(distance_matrix, dimensions=3)
pc1 = pcoa_results.samples['PC1']
pc2 = pcoa_results.samples['PC2']

# Built-in scatter plot colored by a metadata column
fig = pcoa_results.plot(sample_metadata, column='bodysite')

# CCA with environmental variables
cca_results = cca(species_matrix, environmental_matrix)

# Save/load ordination results
pcoa_results.write('ordination.txt')
results = skbio.OrdinationResults.read('ordination.txt')

重要说明：

• PCoA 适用于任意距离/差异矩阵；dimensions 可传入整数（数量），也可传入 (0, 1] 范围内的浮点数（要保留的累计方差比例）
• OrdinationResults 提供基于 pandas 的属性：samples、features、eigvals、proportion_explained、biplot_scores、sample_constraints
• CCA 可揭示影响群落组成的环境驱动因素
• OrdinationResults.plot() 会生成 matplotlib 图形；结果也可与 seaborn/plotly 集成

6. 统计检验

执行针对生态学和生物学数据的假设检验。

主要功能：

• PERMANOVA：使用距离矩阵检验组间差异
• ANOSIM：用于检验组间差异的替代方法
• PERMDISP：检验组内离散程度的齐性
• Mantel 检验：检验距离矩阵之间的相关性
• Bioenv：查找与距离相关的环境变量
• 差异丰度：skbio.stats.composition 中的 ancom、dirmult_ttest 和 dirmult_lme（纵向混合效应）

常见模式：

from skbio.stats.distance import permanova, anosim, mantel

# Test if groups differ significantly
permanova_results = permanova(distance_matrix, grouping, permutations=999)
print(f"p-value: {permanova_results['p-value']}")

# ANOSIM test
anosim_results = anosim(distance_matrix, grouping, permutations=999)

# Mantel test between two distance matrices
mantel_results = mantel(dm1, dm2, method='pearson', permutations=999)
print(f"Correlation: {mantel_results[0]}, p-value: {mantel_results[1]}")

# Differential abundance on a feature table (raw counts recommended)
from skbio.stats.composition import dirmult_ttest
da = dirmult_ttest(counts_table, grouping, treatment='caseA', reference='control')

重要说明：

• 置换检验可用于非参数显著性检验
• 使用 999 次或更多置换，以获得可靠的 p 值
• PERMANOVA 对离散程度差异较敏感；应配合 PERMDISP 使用
• Mantel 检验用于评估矩阵相关性（例如地理距离与遗传距离）
• 差异丰度检验应使用原始计数，而非预先归一化的比例，以保留丰度信息

7. 文件读写与格式转换

读取和写入 19 种以上的生物学文件格式，并自动检测格式。

支持的格式：

• 序列：FASTA、FASTQ、GenBank、EMBL、QSeq
• 比对：Clustal、PHYLIP、Stockholm
• 树：Newick
• 表格：BIOM（HDF5 和 JSON）
• 距离：分隔符分隔的方阵
• 分析：BLAST+6/7、GFF3、排序结果
• 元数据：TSV/CSV（带验证）

常见模式：

import skbio

# Read with automatic format detection
seq = skbio.DNA.read('file.fasta', format='fasta')
tree = skbio.TreeNode.read('tree.nwk')

# Write to file
seq.write('output.fasta', format='fasta')

# Generator for large files (memory efficient)
for seq in skbio.io.read('large.fasta', format='fasta', constructor=skbio.DNA):
    process(seq)

# Convert formats
seqs = list(skbio.io.read('input.fastq', format='fastq', constructor=skbio.DNA))
skbio.io.write(seqs, format='fasta', into='output.fasta')

重要说明：

• 处理大型文件时使用生成器，以避免内存问题
• 指定 into 参数后，可自动检测格式
• 某些对象可以写入多种格式
• 支持使用 verify=False 通过 stdin/stdout 进行管道传输

8. 距离矩阵

使用统计方法创建和处理距离／差异矩阵。

主要功能：

• 存储对称数据（DistanceMatrix，对角线为零）或一般成对数据（PairwiseMatrix）
• 基于 ID 的索引和切片
• 与多样性分析、排序和统计检验集成
• 读取／写入分隔文本格式

常见模式：

from skbio import DistanceMatrix
import numpy as np

# Create from array
data = np.array([[0, 1, 2], [1, 0, 3], [2, 3, 0]])
dm = DistanceMatrix(data, ids=['A', 'B', 'C'])

# Access distances
dist_ab = dm['A', 'B']
row_a = dm['A']

# Read from file
dm = DistanceMatrix.read('distances.txt')

# Use in downstream analyses
pcoa_results = pcoa(dm)
permanova_results = permanova(dm, grouping)

重要说明：

• DistanceMatrix 强制要求矩阵对称且对角线为零；它是 SymmetricMatrix 的子类
• PairwiseMatrix（由 DissimilarityMatrix 更名而来，后者作为已弃用的别名保留）允许一般／非对称值
• ID 便于与元数据和生物学知识集成
• 与 pandas、numpy 和 scikit-learn 兼容

9. 生物学表格

处理微生物组研究中常见的特征表（OTU/ASV 表）。

主要功能：

• 通过原生 Table 类进行 BIOM 格式读写（HDF5 和 JSON）
• 表格分发系统（0.7.0+）：函数可接受任意 table_like 输入——BIOM Table、pandas/polars DataFrame、NumPy 数组或 AnnData——无需显式转换
• 数据增强技术（phylomix、mixup、aitchison_mixup、compos_cutmix）
• 样本／特征筛选与归一化
• 元数据集成

常见模式：

from skbio import Table
from skbio.diversity import beta_diversity

# Read BIOM table
table = Table.read('table.biom')

# Access data
sample_ids = table.ids(axis='sample')
feature_ids = table.ids(axis='observation')
counts = table.matrix_data

# Filter
filtered = table.filter(sample_ids_to_keep, axis='sample')

# Pass table-like objects directly to scikit-bio drivers (dispatch system)
import pandas as pd
df = pd.read_table('data.tsv', index_col=0)   # samples x features
bdiv = beta_diversity('braycurtis', df)         # no manual conversion needed

重要说明：

• BIOM 表格是 QIIME 2 工作流中的标准格式
• 行通常表示样本，列表示特征（OTU/ASV）
• 支持稀疏和稠密表示
• 使用分发系统时，函数的返回格式与输入格式相同，也可由用户指定输出格式

10. 蛋白质嵌入

处理蛋白质语言模型的嵌入，以用于下游分析。

主要功能：

• 存储蛋白质语言模型（ESM、ProtTrans 等）生成的嵌入
• 将嵌入转换为距离矩阵
• 生成用于可视化的排序对象
• 导出为 numpy/pandas 格式，以用于机器学习工作流

常见模式：

from skbio.embedding import ProteinEmbedding, ProteinVector

# Create embedding from array
embedding = ProteinEmbedding(embedding_array, sequence_ids)

# Convert to distance matrix for analysis
dm = embedding.to_distances(metric='euclidean')

# PCoA visualization of embedding space
pcoa_results = embedding.to_ordination(metric='euclidean', method='pcoa')

# Export for machine learning
array = embedding.to_array()
df = embedding.to_dataframe()

重要说明：

• 嵌入可将蛋白质语言模型与传统生物信息学衔接起来
• 与 scikit-bio 的距离、排序和统计生态系统兼容
• SequenceEmbedding 和 ProteinEmbedding 提供专门功能
• 适用于序列聚类、分类和可视化

最佳实践

安装

uv pip install scikit-bio

需要 Python 3.10+ 和 NumPy 2.0+。自 0.7.0 版本起，每次发布都会提供预编译的 wheel，因此大多数平台无需编译器即可安装。Conda 用户也可以运行 conda install -c conda-forge scikit-bio。

性能注意事项

• 处理大型序列文件时使用生成器，以尽量减少内存占用
• 对于超大型系统发育树，优先选择 GME 或 BME，而非 NJ
• 可使用 partial_beta_diversity() 并行计算 Beta 多样性
• 对于大型表格，BIOM 格式（HDF5）比 JSON 更高效

与生态系统集成

• 序列可通过标准格式与 Biopython 互操作
• 表格可与 pandas、polars 和 AnnData 集成
• 距离矩阵与 scikit-learn 兼容
• 可使用 matplotlib/seaborn/plotly 将排序结果可视化
• 可与 QIIME 2 工件（BIOM、树、距离矩阵）无缝协作

常见工作流

1. 微生物组多样性分析：读取 BIOM 表 → 计算 Alpha/Beta 多样性 → 排序（PCoA）→ 统计检验（PERMANOVA）
2. 系统发育分析：读取序列 → 比对 → 构建距离矩阵 → 构建树 → 计算系统发育距离
3. 序列处理：读取 FASTQ → 质量过滤 → 修剪/清理 → 查找基序 → 翻译 → 写入 FASTA
4. 比较基因组学：读取序列 → 两两比对 → 计算距离 → 构建树 → 分析分支

参考文档

有关详细的 API 信息、参数说明和高级用法示例，请参阅 references/api_reference.md，其中包含以下内容的全面文档：

• 所有功能的完整方法签名和参数
• 复杂工作流的扩展代码示例
• 常见问题的故障排查
• 性能优化技巧
• 与其他库的集成模式

其他资源

• 官方文档：https://scikit.bio/docs/latest/
• GitHub 仓库：https://github.com/scikit-bio/scikit-bio
• 更新日志：https://github.com/scikit-bio/scikit-bio/blob/main/CHANGELOG.md
• 参考论文：“scikit-bio: a fundamental Python library for biological omic data,” Nature Methods (2025)，https://www.nature.com/articles/s41592-025-02981-z
• 论坛支持：https://forum.qiime2.org（scikit-bio 是 QIIME 2 生态系统的一部分）

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会影响结果的值都应询问确认，而不是猜测。
3. 先运行小规模版本。 先在小型子集上运行流水线（一个样本、一条染色体、几千个细胞）。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请这样处理
输入之间的基因组版本或标识符不匹配	停止并进行统一（liftover、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装的版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），调整操作，并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要解读统计结果无法支持的生物学意义；报告多重检验校正情况。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• biopython：提供 Biopython（Bio.Seq、Bio.SeqIO、Bio.Align、Bio.Entrez、Bio.Blast、Bio.PDB、Bio.Phylo、Bio.motifs、Bio.SeqUtils、Bio.Restriction），用于…
• etetoolkit：使用 ETE 4 分析、操作、比较、注释和可视化系统发育树或其他层级树。
• waypoint-bio：适用于使用 Outpost Bio 的开源微生物组基础模型 Waypoint 检查点（Waypoint-6m、Waypoint-45m、Waypoint-170m）…