alterlab-scikit-bio

scikit-bio

概要

scikit-bio は、生物学的データを扱うための包括的な Python ライブラリです。配列の操作、アラインメント、系統学、微生物生態学、多変量統計にわたるバイオインフォマティクス解析に、このスキルを利用してください。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• 生物学的配列（DNA、RNA、タンパク質）を扱う
• 生物学的ファイル形式（FASTA、FASTQ、GenBank、Newick、BIOM など）の読み書きが必要
• 配列アラインメントを実行する、またはモチーフを検索する
• 系統樹を構築または解析する
• 多様性指標（アルファ／ベータ多様性、UniFrac 距離）を計算する
• 順序付け解析（PCoA、CCA、RDA）を実行する
• 生物学的データや生態学的データに対する統計検定（PERMANOVA、ANOSIM、Mantel）を実行する
• マイクロバイオームまたは群集生態学のデータを解析する
• 言語モデルによるタンパク質埋め込み表現を扱う
• 生物学的データテーブルを操作する

該当しないケース

ケース	代わりに使用
完全なアンプリコンパイプライン（demux -> DADA2 -> taxonomy -> diversity）を QIIME 2 アーティファクトとして実行する	alterlab-qiime2-amplicon
置換モデル（IQ-TREE/RAxML、ブートストラップ支持値）を用いて系統樹を推定する	alterlab-phylogenetics
一般的な配列レコードの解析、BLAST の解析、Entrez からの取得	alterlab-biopython
群集生態学ではなく、シングルセルまたはバルクの発現解析を行う	alterlab-scanpy / alterlab-pydeseq2
組成データではないデータに対する一般的な多変量統計	alterlab-statistical-analysis

主な機能

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 API を介した、グローバル（Needleman-Wunsch）およびローカル（Smith-Waterman）のペアワイズアラインメント
• スコアリングの設定（一致／不一致のタプル、名前付き置換行列、アフィンギャップコスト）
• PairAlignPath による CIGAR 文字列の処理
• TabularMSA によるマルチプル配列アラインメントの保存と操作
• 0.7.4 で追加された multi_align（および multi_align_nucl / multi_align_prot ラッパー）による段階的なマルチプル配列アラインメント — 以前は TabularMSA は 他で生成されたアラインメントのみを保持できました

よくあるパターン：

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

# Pairwise alignment (0.7+ unified API). mode='global' (default) or 'local'.
seq1, seq2 = DNA('ATCGATCGATCG'), DNA('ATCGGGGATCG')
res = pair_align(seq1, seq2, mode='local')
print(res.score)
aligned = res.paths[0].to_aligned((seq1, seq2))  # tuple of aligned sequences

# Nucleotide / protein convenience wrappers with sensible defaults
res = pair_align_nucl(seq1, seq2)                       # DNA/RNA
# res = pair_align_prot(p1, p2, sub_score='BLOSUM62')   # protein

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

重要な注意事項：

• pair_align は名前付きタプル (score, paths, matrices) を返します。paths は PairAlignPath オブジェクトのリストです（max_paths まで）。
• sub_score は (match, mismatch) タプル、名前付き行列の文字列（例：'BLOSUM62'）、または SubstitutionMatrix を受け取ります。gap_cost は単一の値（線形）または (open, extend) タプル（アフィン — 生物学的配列に推奨）を受け取ります。
• 以前の local_pairwise_align_ssw、StripedSmithWaterman、および *_pairwise_align／AlignScorer インターフェイスは、0.6～0.7 で削除または非推奨になりました。代わりに pair_align* を使用してください。
• 2 つを超える配列の場合、multi_align(seqs)（0.7.4 以降）は段階的アラインメントを構築し、 TabularMSA を返します。これは利便性を目的とした実装であり、MAFFT/MUSCLE の代替ではありません — 大規模なアラインメントや出版物で重要となるアラインメントには、引き続き専用のアライナーを使用してください （この用途については alterlab-phylogenetics を参照してください）。

3. 系統樹

進化的関係を表す系統樹を構築、操作、解析します。

主な機能：

• 距離行列からの系統樹構築（UPGMA、WPGMA、Neighbor Joining、GME、BME）
• 系統樹の操作（枝刈り、再ルート化、走査）
• 距離の計算（パトリスティック距離、コフェネティック距離、Robinson-Foulds 距離）
• ASCII による可視化
• Newick 形式の入出力

一般的なパターン：

from skbio import TreeNode
from skbio.tree import nj

# 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.lowest_common_ancestor(['taxon1', 'taxon2'])

# Calculate distances
patristic_dist = tree.find('taxon1').distance(tree.find('taxon2'))
cophenetic_matrix = tree.cophenetic_matrix()

# Compare tree topologies (Robinson-Foulds)
rf_distance = tree.compare_rfd(other_tree)

重要な注意事項：

• 系統樹の構築は skbio.tree にあります。nj（近隣結合法）、upgma（分子時計を仮定）、gme／bme（貪欲／均衡最小進化法）を使用します。
• Robinson-Foulds 距離は tree.compare_rfd(other) です。モジュールレベルの rf_dists() は、複数の系統樹間のペアごとの RF 距離を計算します。（robinson_foulds は名称が変更されました。）
• GME と BME は、大規模な系統樹に対して高いスケーラビリティを備えています。
• 系統樹は有根または無根にできます。一部の指標では特定のルート設定が必要です。

4. 多様性解析

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

主な機能：

• アルファ多様性：リッチネス、シャノンエントロピー、シンプソン指数、Faith の PD、ピエルー均等度
• ベータ多様性：Bray-Curtis、Jaccard、重み付き／非重み付き UniFrac、ユークリッド距離
• 系統学的多様性指標（系統樹の入力が必要）
• レアファクションとサブサンプリング
• 序列化および統計検定との連携

一般的なパターン：

from skbio.diversity import alpha_diversity, beta_diversity
import skbio

# Alpha diversity
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())

重要な注意事項：

• カウントは、相対頻度ではなく存在量を表す整数である必要があります。
• 系統学的指標の特徴量 ID パラメーターは taxa= です（0.6 で otu_ids= から名称が変更されました。「OTU」という用語はプロジェクト全体で「taxon」に置き換えられました）。通常のリッチネスには、以前の observed_otus ではなく observed_features を使用します。
• 系統学的指標（Faith の PD、UniFrac）には、tree と系統樹の末端に一致する taxa（特徴量）ID が必要です。
• 特定のサンプルペアのみを計算する場合は、partial_beta_diversity() を使用します。
• アルファ多様性は pandas.Series を返し、ベータ多様性は DistanceMatrix を返します。

5. 序列化手法

高次元の生物学的データを、可視化可能な低次元空間に変換します。

主な機能：

• 距離行列からの PCoA（主座標分析）
• 分割表の CA（対応分析）
• 環境制約を用いた CCA（正準対応分析）
• 線形関係を扱う RDA（冗長性分析）
• 特徴量の解釈に用いるバイプロット投影

一般的なパターン：

from skbio.stats.ordination import pcoa, cca

# PCoA from distance matrix
pcoa_results = pcoa(distance_matrix)
pc1 = pcoa_results.samples['PC1']
pc2 = pcoa_results.samples['PC2']

# CCA: y = samples-by-features table, x = samples-by-constraints (environment)
cca_results = cca(feature_table, environmental_matrix)

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

重要な注意事項：

• PCoA は任意の距離／非類似度行列に対応します。
• CCA は群集構成に影響する環境要因を明らかにします。
• 序列化の結果には、固有値、説明された割合、サンプル／特徴量の座標が含まれます。
• 結果はプロットライブラリ（matplotlib、seaborn、plotly）と連携できます。

6. 統計検定

生態学および生物学データに特化した仮説検定を実施します。

主な機能：

• PERMANOVA：距離行列を用いて群間差を検定
• ANOSIM：群間差を検定する代替手法
• PERMDISP：群の分散の均質性を検定
• Mantel 検定：距離行列間の相関を検定
• Bioenv：距離と相関する環境変数を特定

一般的なパターン：

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]}")

重要な注意事項：

• 置換検定により、ノンパラメトリックな有意性検定を行えます。
• 堅牢な p 値を得るには、999 回以上の置換を使用します。
• PERMANOVA は分散の違いに敏感なため、PERMDISP と併用してください。
• Mantel 検定では、行列間の相関（例：地理的距離と遺伝的距離）を評価します。
• permanova、mantel、permdisp、pcoa および UniFrac 指標は engine="fast" を受け付けます （0.7.4 以降）。この設定では、Numba がインストールされていれば Numba を、それ以外の場合は Cython を使用します。skbio.get_config() で 現在の設定を確認でき、グローバルな compute_engine オプションを使うと、設定を一か所で行えます。デフォルトは 変更されないため、このオプションを有効にしても結果は変わらず、実行時間のみが変わります。

6b. 差次的存在量分析（組成データ）

skbio.stats.composition には、組成データのツールキットが用意されています。clr／ilr／rclr（および rclr_inv）変換、ancom、ancombc、ancombc2（0.7.4 以降。全体、ペアワイズ、Dunnett、 トレンドの事後検定に対応）、dirmult_ttest、dirmult_lme が含まれます。

古いコードでも実行でき、結果が異なるため、0.7.4 での次の 2 つの変更に注意してください。 ancombc の戻り値は DataFrame から ANCOMBCResult に変更されました（主要なテーブルは .result で、正確性の修正後、全体検定は ANCOMBCResult.global_test() に移動しました）。 また、値は常に自然対数だったため、Log2(FC) 列の名前が Log(FC) に変更されました。 Log2(FC) を読み取ったり、底が 2 の値として指数変換したりするコードでは、効果量が誤って報告されていました。

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）または非対称データ（DissimilarityMatrix）の格納
• 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 では対称性と対角成分がゼロであることが保証されます
• DissimilarityMatrix では非対称値を使用できます
• ID により、メタデータや生物学的知識との統合が可能です
• pandas、numpy、scikit-learn と互換性があります

9. 生物学的テーブル

マイクロバイオーム研究で一般的なフィーチャーテーブル（OTU/ASV テーブル）を扱います。

主な機能：

• BIOM 形式の入出力（HDF5 および JSON）
• pandas、polars、AnnData、numpy との統合
• データ拡張手法（phylomix、mixup、組成データ手法）
• サンプル／フィーチャーのフィルタリングと正規化
• メタデータとの統合

一般的なパターン：

from skbio.table import Table

# 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  # scipy sparse; .toarray() for dense

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

# To pandas (sparse by default)
df = table.to_dataframe(dense=True)

重要な注意事項：

• Table は scikit-bio が再エクスポートする BIOM の Table です。トップレベルの skbio 名前空間ではなく、skbio.table からインポートしてください。
• BIOM の慣例では、observation はフィーチャー（分類群／OTU／ASV）、sample はサンプルを表し、matrix_data は観測値を行、サンプルを列とするスパースデータです。
• 既存のデータから構築するには、Table(data, observation_ids, sample_ids) コンストラクター、または Table.from_tsv／from_json／from_hdf5 を使用します（from_dataframe はありません）。
• BIOM テーブルは QIIME 2 のワークフローで標準的に使用されます。大きなテーブルでは、JSON より HDF5 のほうが効率的です。

10. タンパク質埋め込み

下流の解析で使用するタンパク質言語モデルの埋め込みを扱います。

主な機能：

• タンパク質言語モデル（ESM、ProtTrans など）の埋め込みを格納
• 埋め込みを距離行列に変換
• 可視化用の順序付けオブジェクトを生成
• ML ワークフロー向けに numpy/pandas へエクスポート

一般的なパターン：

from skbio.embedding import (
    ProteinEmbedding, ProteinVector,
    embed_vec_to_distances, embed_vec_to_ordination, embed_vec_to_numpy,
)

# Per-residue embedding for one protein (e.g. an ESM output)
emb = ProteinEmbedding(embedding_array, sequence)

# One fixed-length vector per protein (e.g. a mean-pooled embedding)
vecs = [ProteinVector(vec, seq) for vec, seq in zip(vectors, sequences)]

# Module-level helpers operate on a collection of *Vector objects:
arr = embed_vec_to_numpy(vecs)                      # ndarray for ML
dm = embed_vec_to_distances(vecs, metric='euclidean')   # DistanceMatrix
ord_results = embed_vec_to_ordination(vecs)             # OrdinationResults (PCoA)

重要な注意事項：

• *Embedding（単一配列の位置ごとの行列）と *Vector（配列ごとの要約ベクトル 1 つ）を区別してください。
• to_distances／to_ordination／to_numpy／to_dataframe 変換は、埋め込みオブジェクトのメソッドではなく、ベクトルのリストを受け取るモジュールレベル関数（embed_vec_to_*）です。
• 出力（DistanceMatrix、OrdinationResults）は、scikit-bio の多様性／順序付け／統計のエコシステムにそのまま組み込めます。

ベストプラクティス

インストール

uv pip install "scikit-bio>=0.7,<0.8"   # examples here target the 0.7 API (current 0.7.4)
uv pip install numba                    # optional: enables engine="fast" / GPU paths

0.6→0.7 系では、複数のインターフェースの名前が変更され（otu_ids→taxa、observed_otus→observed_features、robinson_foulds→compare_rfd）、従来のペアワイズアラインメント関数が pair_align* に置き換えられました。これらに依存する場合は、バージョンを固定してください。

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

• 大きなシーケンスファイルのメモリ使用量を抑えるには、ジェネレーターを使用してください
• 大規模な系統樹には、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://forum.qiime2.org（scikit-bio は QIIME 2 エコシステムの一部です）