alterlab-gtars

Gtars：Rust によるゲノムツールとアルゴリズム

概要

Gtars（geniml を開発した研究室 databio による）は、ゲノム領域データの操作、解析、処理を行う高性能な Rust ツールキットです。主な目的は、ゲノム領域を対象とした機械学習用 Python ライブラリ geniml の、性能が求められるバックエンドとして機能することです。オーバーラップ／集合演算、IGD オーバーラップインデックス、カバレッジ（uniwig）トラック、ML 用の領域トークン化、シングルセルフラグメントの擬似バルキング、GA4GH refget 配列コレクション管理を提供します。

このスキルを使う場面

次の作業を行う場合に、このスキルを使用します。

• ゲノム領域ファイル（BED）の処理 — オーバーラップ、ジャッカード係数、集合演算、カバレッジ
• 大規模な領域データベースに対する高速なオーバーラップクエリ用の IGD インデックス作成
• uniwig によるカバレッジ／累積トラックの作成
• ゲノム ML の前処理と領域トークン化
• シングルセルフラグメントファイルの処理（クラスターごとに擬似バルクへ分割）
• 参照配列のダイジェストと取得（refget）

対象外

シナリオ	代わりに使用
領域／シングルセルの埋め込みの学習（Region2Vec、scEmbed、BEDspace）	alterlab-geniml
リード単位の BAM/CRAM/VCF アクセス（CIGAR、MAPQ、パイルアップ）	alterlab-pysam
BAM から正規化した bigWig カバレッジ、TSS ヒートマップ／プロファイルを作成	alterlab-deeptools
地理空間（ゲノム以外）の空間結合とオーバーラップ	alterlab-geopandas

バージョンに関する注意：例は gtars Python パッケージ 0.10.0（PyPI、2026-09）に対して検証済みです（最初は 0.8 向けに記述されましたが、以下の呼び出し方法に変更はありません）。Python API はサブモジュール（gtars.models、gtars.tokenizers、gtars.refget、gtars.utils、および新しい gtars.genomic_distributions、gtars.lola、gtars.vrs）を通じて公開されており、トップレベル関数としてフラットに公開されているわけではありません。Python のサブモジュールに gtars.igd や gtars.uniwig はありません。IGD の作成と uniwig トラックの生成は CLI 専用です。

インストール

Python パッケージ

uv pip install gtars   # or: uv add gtars

インポート対象（検証済み、0.10.0）：

from gtars.models import RegionSet, Region, RegionSetList
from gtars.tokenizers import Tokenizer, tokenize_fragment_file
from gtars import refget          # RefgetStore, digest_fasta, sha512t24u_digest, ...
from gtars import utils           # read/write .gtok token files

CLI（別個の Rust バイナリ）

CLI は gtars-cli クレート（バイナリ名は gtars）として提供され、Cargo でインストールします。ほとんどのサブコマンドはフィーチャーフラグで有効になります。

# All commonly used commands
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit genomicdist"

# Or a subset
cargo install gtars-cli --features "uniwig igd"

利用可能な CLI サブコマンド：igd、overlaprs、uniwig、bbcache、pb（フラグメントの擬似バルキング）、scoring、genomicdist、ranges、consensus、prep。フラグのセットはサブコマンドごとに異なり、バージョンによって変わります。必ず gtars <command> --help で確認してください。

主な機能

Gtars は、それぞれ特定のゲノム解析タスクに特化したモジュールで構成されています。

1. オーバーラップの検出と集合演算

RegionSet（Python）を使って領域セット間のオーバーラップを検出し、集合演算／類似度を計算するか、IGD（CLI）で大規模な領域データベースにインデックスを作成します。

使用場面：

• オーバーラップする調節エレメントの特定、ChIP-seq ピークの比較
• バリアントのアノテーション、共通するゲノム特徴の特定
• BED ファイル間のジャッカード係数／オーバーラップ係数による類似度計算

簡単な例（Python）：

from gtars.models import RegionSet

peaks = RegionSet("chip_peaks.bed")
promoters = RegionSet("promoters.bed")

# Regions in peaks that overlap a promoter (the real method is subset_by_overlaps)
in_promoters = peaks.subset_by_overlaps(promoters)
in_promoters.to_bed("peaks_in_promoters.bed")

print(peaks.count_overlaps(promoters))  # per-region overlap counts
print(peaks.jaccard(promoters))         # similarity score

大規模な参照データベースに対して何度もクエリする場合は、CLI で IGD インデックスを一度作成（gtars igd create ...）してから検索します（gtars igd search ...）。references/overlap.md を参照してください。

2. カバレッジ／累積トラック（uniwig、CLI）

uniwig CLI サブコマンドを使って、BED または BAM ファイルからカバレッジ／累積トラックを生成します。

使用場面：

• ATAC-seq アクセシビリティプロファイル、ChIP-seq カバレッジ、RNA-seq リードカバレッジ

簡単な例（CLI）：

# uniwig reads a sorted BED/BAM and writes accumulation tracks.
# Flags differ by version; confirm with `gtars uniwig --help`.
gtars uniwig --file fragments.bed --filetype bed \
             --fileheader coverage --outputtype bw

検証済みのフラグについては references/coverage.md を、メモリー内で代替処理する場合は RegionSet.coverage() を参照してください。

3. ゲノムトークン化

ゲノム領域を ML 用の離散トークンに変換します（geniml が基盤として使用する前処理レイヤーです）。

使用場面：

• ゲノム ML モデル向けに、ピーク／領域を固定語彙に前処理する
• トークン ID を geniml またはカスタムの Transformer モデルに入力する

簡単な例（Python）：

from gtars.tokenizers import Tokenizer
from gtars.models import Region

tokenizer = Tokenizer.from_bed("universe.bed")   # vocab = the universe BED
tokens = tokenizer.tokenize([Region("chr1", 1000, 2000, None)])  # -> ['chr1:1000-2000']
ids = tokenizer.convert_tokens_to_ids(tokens)                     # -> [<int>]

references/tokenizers.md を参照してください。注意：クラス名は Tokenizer です（TreeTokenizer はありません）。

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

GA4GH refget ダイジェストを計算し、リファレンス配列を管理・取得します。

使用する場面：

• 配列ダイジェストによるリファレンスゲノムの整合性検証
• ローカルの配列コレクションストアの構築と部分配列の抽出

簡単な例（Python）：

from gtars import refget

# Digest a FASTA into a GA4GH SequenceCollection (no sequence data loaded)
collection = refget.digest_fasta("hg38.fa")

# Or a one-off sequence digest
d = refget.sha512t24u_digest("ACGTACGT")   # 32-char base64url GA4GH sha512t24u digest

RefgetStore（読み込み、保存、get_substring）については、references/refget.md を参照してください。

5. フラグメントの疑似バルク化（pb、CLI）

クラスタ／細胞グループの対応付けに基づいて、単一細胞フラグメントファイルを疑似バルクに分割します。

使用する場面：

• 単一細胞 ATAC-seq の処理、クラスタに基づくフラグメントの集約

簡単な例（CLI）：

# The fragsplit feature exposes the `pb` (pseudobulk) subcommand.
gtars pb --fragments fragments.bed.gz --mapping cluster_mapping.tsv

Python 側では、フラグメントを直接トークン化する gtars.tokenizers.tokenize_fragment_file(...) も利用できます。references/cli.md を参照してください。

6. フラグメント／領域のスコアリング

scoring CLI サブコマンドを使用して、リファレンスデータセットに対する領域／フラグメントファイルのスコアを算出します。

使用する場面：

• リファレンスユニバースに対する領域のエンリッチメント評価
• サンプル間の品質メトリクスのバッチ計算

gtars scoring --help   # confirm subcommands and flags for your installed version

一般的なワークフロー

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

プロモーターとオーバーラップするピークを特定します（Python）：

from gtars.models import RegionSet

peaks = RegionSet("chip_peaks.bed")
promoters = RegionSet("promoters.bed")

overlapping_peaks = peaks.subset_by_overlaps(promoters)
overlapping_peaks.to_bed("peaks_in_promoters.bed")

# Iterate results (regions expose .chr/.start/.end)
for r in overlapping_peaks:
    print(r.chr, r.start, r.end)

ワークフロー 2：IGD インデックス＋繰り返しオーバーラップ検索（CLI）

大規模なリファレンスデータベースに一度インデックスを作成し、繰り返し検索します：

# Build the IGD database from a directory or list of BED files
gtars igd create --help     # confirm the exact input/output flags for your version

# Search the database with query regions
gtars igd search --help

ワークフロー 3：ML の前処理（トークン化）

ML モデル用にゲノム領域を準備します：

from gtars.tokenizers import Tokenizer
from gtars.models import RegionSet

# Step 1: Build a tokenizer from the universe BED (defines the vocabulary)
tokenizer = Tokenizer.from_bed("universe.bed")

# Step 2: Tokenize a region set (tokenize accepts a RegionSet or a list of Region)
regions = RegionSet("training_peaks.bed")
tokens = tokenizer.tokenize(regions)                      # list of 'chr:start-end' strings
ids = tokenizer.convert_tokens_to_ids(tokens)             # integer IDs for the model

# Step 3: feed `ids` to geniml or a custom model (see alterlab-geniml for training)

Python と CLI の使い分け

Python API を使う場面：

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

CLI を使う場面：

• 手早く一度だけ解析する場合
• シェルスクリプト
• ファイルのバッチ処理
• ワークフローのプロトタイピング

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

• references/python-api.md — RegionSet／Region の操作、集合演算、オーバーラップ、エクスポート
• references/overlap.md — オーバーラップの検出と IGD インデックス作成
• references/coverage.md — uniwig カバレッジトラック
• references/tokenizers.md — ML 向け領域のトークン化
• references/refget.md — refget ダイジェストと RefgetStore
• references/cli.md — CLI サブコマンドの概要

geniml との関係

gtars は、geniml（databio のゲノム区間向け ML ライブラリ）の Rust 製パフォーマンスバックエンドです。負荷の高い区間演算とトークン化には gtars を使用し、これらのトークンに基づく埋め込み／モデルのトレーニングには geniml（スキル alterlab-geniml）を使用してください。

データ形式

• BED：ゲノム区間（3 列または拡張形式）— 中核となる入力
• BigWig／WIG：カバレッジ／蓄積トラック（uniwig の出力）
• FASTA：リファレンス配列（refget）
• フラグメントファイル：単一細胞フラグメント（多くは .bed.gz）。pb には別途クラスタ対応付けファイルが必要です

API の確認

このパッケージの公開 API はリリースによって異なり、Python API と CLI API は互いに完全に対応しているわけではありません。使い慣れていないメソッドやフラグを使用する前に、インストール済みバージョンで確認してください：

uv run python -c "from gtars import models, tokenizers, refget; print(dir(models), dir(tokenizers), dir(refget))"
gtars <command> --help

AlterLab Academic Skills スイートの一部です。