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 で導入）を使って、ペアワイズおよび多重配列アライメントを実行します。これは汎用性と効率に優れた動的計画法によるアライナーです。

主な機能：

• 1 つの関数でグローバル、ローカル、セミグローバルアライメントを実行（フリーエンドを設定可能）
• 便利なラッパー 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 としてアンパックすることもできます（DP 行列を保持するには keep_matrices=True を使用します）
• sub_score には (match, mismatch) タプルまたは行列名（例：'NUC.4.4'、'BLOSUM62'）を指定できます。gap_cost には単一の数値（線形）または (open, extend) タプル（アフィン）を指定できます
• 外部の CIGAR 文字列は PairAlignPath.from_cigar('1I8M2D5M2I') で解析できます。既存のアライメントのスコアは align_score(...) で計算でき、MSA から距離行列は align_dists(...) で作成できます

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() を使用してください
• UPGMA/WPGMA（分子時計を仮定）には upgma() を使用してください
• GMEとBMEは大規模な系統樹に対して高いスケーラビリティを備えています。nni() でトポロジーを調整してください
• cophenet()（旧称 tip_tip_distances）は系統樹上の距離行列を返します。compare_rfd() はRobinson-Foulds法です（重み付き／コフェネティックな派生手法には compare_wrfd／compare_cophenet を使用）
• lca() は最小共通祖先です。lowest_common_ancestor は引き続きエイリアスとして利用できます
• 系統樹には根付きと非根付きがあり、一部の指標では特定の根付けが必要です

4. 多様性分析

微生物生態学および群集分析のために、アルファ多様性とベータ多様性の指標を計算します。

主な機能：

• アルファ多様性：種数（sobs、observed_features、chao1、ace）、Shannon、Simpson、Hill数（hill）、FaithのPD（faith_pd）、一般化PD（phydiv）、Pielouの均等度
• ベータ多様性：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のPD、UniFrac）には、系統樹と分類群から末端へのマッピングが必要です
• 特定のサンプルペアには partial_beta_diversity() を使用してください。大規模なブロック分割計算には block_beta_diversity() を使用してください
• アルファ多様性は pandas.Series を返し、ベータ多様性は 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')

重要な注意事項：

• 順列検定により、ノンパラメトリックな有意性検定を実行できます
• 信頼性の高い p 値を得るには、999 回以上の順列を使用してください
• 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 以降）：関数は、明示的な変換なしに、BIOM Table、pandas/polars DataFrame、NumPy 配列、AnnData など、あらゆる table_like 入力を受け取ります
• データ拡張手法（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 以降の各リリースではコンパイル済みのホイールが公開されているため、ほとんどのプラットフォームではコンパイラーなしでインストールできます。Conda ユーザーは代わりに conda install -c conda-forge scikit-bio を実行できます。

パフォーマンスに関する考慮事項

• メモリー使用量を最小限に抑えるには、大きな配列ファイルにジェネレーターを使用します
• 非常に大きな系統樹には、NJ より GME または BME を使用します
• ベータ多様性の計算は partial_beta_diversity() で並列化できます
• 大きなテーブルでは、BIOM 形式（HDF5）のほうが JSON より効率的です

エコシステムとの統合

• 配列は標準形式を介して Biopython と相互運用できます
• テーブルは pandas、polars、AnnData と統合できます
• 距離行列は scikit-learn と互換性があります
• 順序付けの結果は matplotlib／seaborn／plotly で可視化できます
• QIIME 2 のアーティファクト（BIOM、系統樹、距離行列）をシームレスに扱えます

一般的なワークフロー

1. マイクロバイオーム多様性分析：BIOM テーブルを読み込む → アルファ／ベータ多様性を計算する → 順序付け（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 エコシステムの一部です）

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、および入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を明確にします。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果が変わる値は推測せず、質問してください。
3. まず小規模に実行します。 最初に、少量のサブセット（1サンプル、1染色体、数千個の細胞）でパイプラインを実行します。
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）を提供し、fo…
• etetoolkit：ETE 4 を使用して、系統樹やその他の階層ツリーを解析、操作、比較、注釈付け、可視化します。
• waypoint-bio：Outpost Bio のオープンなマイクロバイオーム基盤モデル（Waypoint チェックポイント：Waypoint-6m、Waypoint-45m、Waypoint-170m）を使用する場合に利用します…