gtars

Gtars: Rust で実装されたゲノムツールとアルゴリズム

概要

Gtars は、ゲノムインターバルデータの操作、解析、処理を行うための高性能な Rust ツールキットです。オーバーラップ検出、カバレッジ解析、機械学習向けのトークン化、リファレンス配列の管理に特化したツールを提供します。

次のような作業でこのスキルを使用してください:

• ゲノムインターバルファイル (BED 形式)
• ゲノム領域間のオーバーラップ検出
• カバレッジトラックの生成 (WIG、BigWig)
• ゲノム ML の前処理とトークン化
• シングルセルゲノミクスにおけるフラグメント解析
• リファレンス配列の取得と検証

インストール

Python のインストール

gtars の Python バインディングをインストールします:

uv pip install gtars

CLI のインストール

コマンドラインツールをインストールします (Rust/Cargo が必要です):

# Install with all features
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit"

# Or install specific features only
cargo install gtars-cli --features "uniwig overlaprs"

Rust ライブラリ

Rust プロジェクトでは Cargo.toml に追加します:

[dependencies]
gtars = { version = "0.1", features = ["tokenizers", "overlaprs"] }

主な機能

Gtars は、それぞれ特定のゲノム解析タスクに焦点を当てた専用モジュールで構成されています:

1. オーバーラップ検出と IGD インデックス

Integrated Genome Database (IGD) データ構造を使用して、ゲノムインターバル間のオーバーラップを効率的に検出します。

使用するタイミング:

• 重なり合う制御エレメントの検索
• バリアントアノテーション
• ChIP-seq ピークの比較
• 共有されているゲノム特徴の特定

簡単な例:

import gtars

# Build IGD index and query overlaps
igd = gtars.igd.build_index("regions.bed")
overlaps = igd.query("chr1", 1000, 2000)

包括的なオーバーラップ検出のドキュメントは references/overlap.md を参照してください。

2. カバレッジトラックの生成

uniwig モジュールを使用して、シーケンシングデータからカバレッジトラックを生成します。

使用するタイミング:

• ATAC-seq のアクセシビリティプロファイル
• ChIP-seq のカバレッジ可視化
• RNA-seq のリードカバレッジ
• 差次的カバレッジ解析

簡単な例:

# Generate BigWig coverage track
gtars uniwig generate --input fragments.bed --output coverage.bw --format bigwig

詳細なカバレッジ解析のワークフローは references/coverage.md を参照してください。

3. ゲノムトークン化

ゲノム領域を離散的なトークンに変換し、機械学習、特にゲノムデータに対する深層学習モデルに利用できるようにします。

使用するタイミング:

• ゲノム ML モデルの前処理
• geniml ライブラリとの統合
• 位置エンコーディングの作成
• ゲノム配列でのトランスフォーマーモデルの学習

簡単な例:

from gtars.tokenizers import TreeTokenizer

tokenizer = TreeTokenizer.from_bed_file("training_regions.bed")
token = tokenizer.tokenize("chr1", 1000, 2000)

トークン化のドキュメントは references/tokenizers.md を参照してください。

4. リファレンス配列の管理

リファレンスゲノム配列を扱い、GA4GH refget プロトコルに従ってダイジェストを計算します。

使用するタイミング:

• リファレンスゲノムの整合性の検証
• 特定のゲノム配列の抽出
• 配列ダイジェストの計算
• 相互参照の比較

簡単な例:

# Load reference and extract sequences
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)

リファレンス配列の操作は references/refget.md を参照してください。

5. フラグメント処理

フラグメントファイルの分割と解析を行います。特にシングルセルゲノミクスのデータに有用です。

使用するタイミング:

• シングルセル ATAC-seq データの処理
• セルバーコードによるフラグメントの分割
• クラスターベースのフラグメント解析
• フラグメントの品質管理

簡単な例:

# Split fragments by clusters
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/

フラグメント処理コマンドは references/cli.md を参照してください。

6. フラグメントスコアリング

フラグメントのオーバーラップを参照データセットに対してスコアリングします。

使用するタイミング:

• フラグメントの濃縮の評価
• 実験データと参照データの比較
• 品質指標の計算
• 複数サンプルのバッチスコアリング

簡単な例:

# Score fragments against reference
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt

一般的なワークフロー

ワークフロー 1: ピークのオーバーラップ解析

ゲノム特徴の重なりを特定します:

import gtars

# Load two region sets
peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
promoters = gtars.RegionSet.from_bed("promoters.bed")

# Find overlaps
overlapping_peaks = peaks.filter_overlapping(promoters)

# Export results
overlapping_peaks.to_bed("peaks_in_promoters.bed")

ワークフロー 2: カバレッジトラックのパイプライン

可視化のためにカバレッジトラックを生成します:

# Step 1: Generate coverage
gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10

# Step 2: Convert to BigWig for genome browsers
gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig

ワークフロー 3: ML の前処理

機械学習のためにゲノムデータを準備します:

from gtars.tokenizers import TreeTokenizer
import gtars

# Step 1: Load training regions
regions = gtars.RegionSet.from_bed("training_peaks.bed")

# Step 2: Create tokenizer
tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")

# Step 3: Tokenize regions
tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]

# Step 4: Use tokens in ML pipeline
# (integrate with geniml or custom models)

Python と CLI の使い分け

Python API を使用する場合:

• 解析パイプラインと統合するとき
• プログラムによる制御が必要なとき
• NumPy/Pandas を扱うとき
• カスタムワークフローを構築するとき

CLI を使用する場合:

• 一度限りの簡単な解析を行うとき
• シェルスクリプトを書くとき
• ファイルをバッチ処理するとき
• ワークフローのプロトタイプを作成するとき

リファレンスドキュメント

モジュールの包括的なドキュメント:

• references/python-api.md - RegionSet の操作、NumPy 連携、データのエクスポートを扱う Python API の完全なリファレンス
• references/overlap.md - IGD インデックス作成、オーバーラップ検出、集合演算
• references/coverage.md - uniwig によるカバレッジトラックの生成
• references/tokenizers.md - 機械学習アプリケーション向けのゲノムトークン化
• references/refget.md - 参照配列の管理とダイジェスト
• references/cli.md - コマンドラインインターフェースの完全なリファレンス

geniml との連携

Gtars は geniml Python パッケージの基盤であり、機械学習ワークフローのためのコアとなるゲノム区間演算を提供します。geniml 関連のタスクに取り組む際は、データの前処理とトークン化に gtars を使用してください。

パフォーマンス特性

• ネイティブ Rust によるパフォーマンス: 低いメモリオーバーヘッドで高速に実行
• 並列処理: 大規模データセットに対するマルチスレッド演算
• メモリ効率: ストリーミングおよびメモリマップドファイルのサポート
• ゼロコピー演算: 最小限のデータコピーによる NumPy 連携

データ形式

Gtars は標準的なゲノムフォーマットを扱います:

• BED: ゲノム区間（3 列または拡張形式）
• WIG/BigWig: カバレッジトラック
• FASTA: 参照配列
• Fragment TSV: バーコード付きのシングルセルフラグメントファイル

エラー処理とデバッグ

トラブルシューティングのために詳細ログを有効にしてください:

import gtars

# Enable debug logging
gtars.set_log_level("DEBUG")

# CLI verbose mode
gtars --verbose <command>