gtars

Gtars

Gtars は、ゲノム区間や参照配列を扱うための Rust ネイティブ実装、Python バインディング、機能フラグで有効化できる gtars バイナリを提供します。まず同梱のローカル検査ツールを使い、データ契約、来歴、リソース上限、副作用を明確にしてからアップストリームのコードを呼び出してください。

検証済みスナップショット（2026-07-23）

• Python：2026-06-17 リリースの gtars==0.9.2。Requires-Python >=3.10。
• Rust メタクレート：2026-06-15 リリースの gtars=0.9.0。デフォルトの機能セットは空です。
• CLI クレート／バイナリ：gtars-cli=0.9.0。インストールされるバイナリの名前は gtars です。
• refget 直接クレート：2026-06-17 リリースの gtars-refget=0.9.1。gtars=0.9.0 自体はコンポーネントのリリースセットを固定しており、これには refget 0.9.0 が含まれます。
• アップストリームでは、ワークスペースのクレート、Python バインディング、CLI のバージョンを意図的に個別管理しています。番号が一致していても、成果物が一致するとは限りません。
• 公開ドキュメントの変更履歴は 0.5.1 までです。ここに記載した API の例は、0.9.2 の Python スタブ／ランタイムと v0.9.0 の CLI／Rust ソースを照合済みです。

license: MIT フィールドは、このスキルに適用されます。公開されている gtars クレートは MIT を宣言していますが、GitHub リポジトリのルートには現在 BSD-2-Clause と表示されています。再配布する前に、対象の成果物のライセンスを確認してください。

ネイティブコードの信頼性ゲートと厳密なバージョン固定

Python ホイールには PyO3 ネイティブ拡張が含まれています。Cargo によるインストールではネイティブバイナリがコンパイルされ、依存関係のビルドスクリプトが実行される場合があります。どちらの方法もコード実行として扱ってください。

1. 公式の PyPI／crates.io／GitHub の所有者と変更不可能なバージョンを確認します。
2. ファイル名、プラットフォームタグ、リリースの来歴、ライセンス、SHA-256 を確認します。GitHub の v0.9.0 バイナリリリースには、アーカイブごとの .sha256 サイドカーファイルが含まれています。
3. 信頼できないプリビルドバイナリ、ホイール、ソースツリー、Cargo ビルドスクリプト、アーカイブインストーラーは実行しないでください。隔離環境を使用し、CPU／RAM／ディスク／時間の上限を設定します。
4. ロックファイルと成果物のハッシュを分析マニフェストとともに保管します。

そのレビューが完了したら、隔離された Python 環境を作成します。

uv venv --python 3.11 .venv-gtars
uv pip install --dry-run --python .venv-gtars/bin/python "gtars==0.9.2"
uv pip install --python .venv-gtars/bin/python "gtars==0.9.2"
.venv-gtars/bin/python -c \
  "import gtars; assert gtars.__version__ == '0.9.2'; print(gtars.__version__)"

レビュー済みの CLI ソースリリースを使用する場合：

cargo install gtars-cli --version 0.9.0 --locked
gtars --version
gtars --help

Rust プロジェクトでは、ラッパーのバージョンを厳密に固定し、必要な機能のみを有効にします。

[dependencies]
gtars = { version = "=0.9.0", default-features = false, features = [
  "core", "overlaprs", "uniwig", "tokenizers", "refget"
] }

新しい直接コンポーネント API が必要で、互換性をテスト済みの場合に限り、gtars-refget = "=0.9.1" を直接使用してください。これらのバージョン固定を Git ブランチや未レビューのリリースに置き換えないでください。

ゲノムデータ契約

すべての操作の前に、この契約を適用してください。

1. 座標： BED 区間は 0 ベースで、終端を含みません（[start, end)）。0 <= start < end <= contig_length を満たすことを確認します。Gtars の座標は u32 なので、4,294,967,295 を超える値は拒否してください。
2. アセンブリ： アセンブリアクセッション／バージョンと、正確な染色体サイズまたは refget 配列コレクションのメタデータの SHA-256 を記録します。ファイル名や chr プレフィックスからアセンブリを推定しないでください。
3. コンティグ： 名前を完全一致で比較します。1 と chr1、代替座位、デコイ、ミトコンドリアの別名は互換ではありません。名前の変更やリフトオーバーは、別途レビューする変換としてのみ実施してください。
4. ソート： 元のファイルを保持し、操作上必要な場合は染色体サイズの順序と数値の start／end でソートしたコピーを使用します。Python の RegionSet(path) は現在、読み込み時にコンティグ名と start の辞書順でソートします。そのため、読み込み後に元の行順が保たれるとは限りません。
5. 鎖： BED6 では +、-、. を使用します。Region.rest は末尾の BED フィールドを保持しますが、ファイルから読み込んだ Python の RegionSet は、現在、独立した strands ベクトルを * で初期化します。複数のセット演算では鎖情報が失われます。科学的に重要な場合は、鎖情報を外部で保持し、検証してください。
6. 重複／隣接： 方針を明示的に決めます。reduce() とコンセンサス処理では、重複する区間と隣接する区間の両方をマージします。通常の半開区間の重なりでは、[0,10) と [10,20) は重なりとはみなしません。

まずローカルバリデーターを実行してください。

python3 -B scripts/bed_validator.py \
  --input data.bed.gz \
  --assembly GRCh38.p14 \
  --chrom-sizes GRCh38.p14.chrom.sizes \
  --require-sorted

安全なローカルワークフロー

1. ローカルファイル、チェックサム、アセンブリ、コンティグ辞書、座標系、鎖のポリシー、患者／反復測定のグループ、想定する出力を棚卸しします。
2. BED／フラグメントを検証し、必要な作業量を見積もります。小さな合成ファイルで試験運用します。
3. ドキュメントに記載されたインターフェースに基づいて Python、CLI、または Rust を選択します。推測で API 名を翻訳しないでください。
4. 入力のバイト数／レコード数／ファイル数、スレッド／ジョブ数、メモリ、一時ディスク、出力サイズ、実行時間に厳格な上限を設定します。
5. 専用の出力ディレクトリで実行します。上書きが明示的に承認されていない限り、競合を拒否します。
6. 出力のソート順、範囲、行数、チェックサム、来歴を再検証します。

現在の Python コア

インポート元は gtars のトップレベルではなく、サブモジュールです。

from gtars.models import Region, RegionSet

query = RegionSet.from_regions(
    [
        Region(chr="chr1", start=100, end=200, rest=None),
        Region(chr="chr1", start=300, end=400, rest=None),
    ],
    strands=["+", "-"],
)
universe = RegionSet.from_vectors(
    ["chr1", "chr1"],
    [150, 500],
    [350, 600],
)

counts = query.count_overlaps(universe)       # one count per query region
flags = query.any_overlaps(universe)          # one bool per query region
indices = query.find_overlaps(universe)       # indices into universe
pieces = query.intersect_all(universe)        # all intersection fragments
fraction = query.coverage(universe)           # fraction of query bp covered

RegionSet.sort() は対象を変更し、None を返します。集合演算には reduce、setdiff、pintersect（インデックス順にペアを作成）、concat、union、jaccard、coverage、overlap_coefficient、intersect_all、closest、cluster、gaps があります。順序や鎖を前提とする前に、references/python-api.md をお読みください。

コンセンサスは別のモジュールにある Python バインディングです。

from gtars.genomic_distributions import consensus

rows = consensus([query, universe])
# rows: [{"chr": ..., "start": ..., "end": ..., "count": ...}, ...]

Python 0.9.2 では、シグナルトラックの生成は gtars.uniwig として公開されていません。レビュー済みの CLI または Rust API を使用してください。RegionSet.coverage() は塩基対集合の指標であり、WIG／bigWig ジェネレーターではありません。

トークナイザー、フラグメント、参照ストア

デフォルトではローカルコンストラクターのみを使用します。

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

tokenizer = Tokenizer.from_bed("reviewed-universe.bed")
regions = RegionSet("local-query.bed")
tokens = tokenizer.tokenize(regions)
encoding = tokenizer(regions)
ids = encoding["input_ids"]

引数が既存のローカルディレクトリでない場合、Tokenizer.from_pretrained(name) は Hugging Face に接続し、キャッシュに書き込みます。リビジョンやキャッシュを指定する引数はありません。明示的な承認を得て、レビュー済みの方法で不変のリビジョンを取得し、チェックサムを検証してから、ローカルのスナップショットディレクトリを渡してください。references/tokenizers.md を参照してください。

refget には、RefgetStore.in_memory() または RefgetStore.open_local(path) の使用を優先してください。open_remote(cache_path, remote_url) はリモートサービスに接続し、ローカルキャッシュを作成または使用して、オンデマンドの範囲読み取りを実行します。references/refget.md を参照してください。

ネットワークとキャッシュのゲート

このスキルでは、ダウンロードやキャッシュへの書き込みは暗黙に行われません。ネットワークに接続できる上流呼び出しを行う前に、次の対応をしてください。

• 接続先のホスト、エンドポイント、データ、キャッシュを明示して、ユーザーから承認を得ます。
• HTTPS ホストを許可リストに登録し、レビューされていないリダイレクトを拒否します。
• 不変のリビジョン／識別子、取得時刻、想定される SHA-256 およびドメインダイジェスト、アセンブリアクセッション、サイズの上限、来歴を記録します。
• 承認された環境の外部に漏れる可能性のある、機微な BED 座標、バーコード、サンプルラベル、参照の選択を開示します。
• ダウンロードしたコンテンツは、使用前に信頼できないものとして検証します。

重要な副作用：

• RegionSet(path) は HTTP に対応しており、存在しないローカル文字列は URL として扱われる場合があります。構築前にローカルパスの存在を確認してください。
• Tokenizer.from_pretrained は Hugging Face キャッシュに universe.bed.gz をダウンロードする場合があります。
• RefgetStore.on_disk はストアを作成／書き込みます。open_remote はリモートメタデータを読み込み、デフォルトで永続化を有効にします。
• gtars bbcache は、クライアントの構築時にもキャッシュディレクトリを作成します。キャッシュ／ダウンロードコマンドは BBCLIENT_CACHE（デフォルトは ~/.bbcache）と BEDBASE_API（デフォルトは https://api.bedbase.org）を使用します。

機微なメタデータと情報漏えい

ゲノム領域、希少な座位、バーコード、サンプル名、表現型、アセンブリの選択は、個人の特定につながる可能性があります。ログにフルパスや生の座標を記録しないでください。デフォルトの同梱レポートではパスを秘匿し、件数／チェックサムのみを出力します。

まず患者／ドナー単位でデータ分割を固定し、すべての技術的・生物学的反復測定を同じ分割に含めます。コンセンサスセット、ユニバース、トークナイザー、スケーリング、しきい値、QC ルールは、トレーニングデータのみを使って適合させます。全サンプルからユニバースを作成してからデータを分割しないでください。検証／テストの座位情報が漏えいします。除外したサンプルと反復測定の集約は、別々に記録してください。

同梱されている決定論的 CLI

6 つのヘルパーはすべて、URL、パストラバーサル、シンボリックリンク、特殊ファイルを拒否します。また、バイト数、レコード数、ファイル数、座標、ワーカー数に上限を適用し、ネットワークも gtars のインポートも使用せず、出力ファイルを書き込みません。プランには固定の argv テンプレートが含まれますが、それらを実行することはありません。

python3 -B scripts/bed_validator.py --help
python3 -B scripts/execution_plan.py --help
python3 -B scripts/tokenizer_manifest.py --help
python3 -B scripts/refget_digest_plan.py --help
python3 -B scripts/coverage_preflight.py --help
python3 -B scripts/artifact_inspector.py --help

バイトコードを生成せずに合成テストを実行します。

PYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest discover \
  -s tests/gtars -p 'test_*.py' -v

1.1 で削除された移行時の落とし穴

gtars.RegionSet、RegionSet.from_bed、TreeTokenizer、gtars.igd.build_index、gtars.uniwig.coverage_from_bed、gtars.RefgetStore、グローバルな set_option／set_log_level、parallel_apply、または独自に作られた例外クラスを含む古い例は使用しないでください。uniwig generate、igd build、scoring score、fragsplit cluster-split などの CLI 形式も、0.9.0 では古いものです。

上流で公開されているドキュメントやスタブには、内容のずれがある場合があります（例：古い GlobalRefgetStore チュートリアルや不完全な 0.9.2 スタブ）。それらが食い違う場合は、インストール済み環境でのシグネチャのスモークテストと、不変のタグ付きソースを優先してください。

同梱リファレンス

同梱されているリファレンスは次の 6 つのみです。リンクはすべてローカルにあり、存在します。

• references/python-api.md — Python 0.9.2 の正確なインポートと動作
• references/overlap.md — 重複／カウント／集合演算とコンセンサスの意味
• references/coverage.md — uniwig、bigWig、カバレッジ、ソート、リソース
• references/tokenizers.md — トークナイザー／ユニバースとフラグメントの互換性
• references/refget.md — ダイジェスト、ストア、BEDbase、ネットワーク／キャッシュの制御
• references/cli.md — CLI 0.9.0 のコマンド、機能、移行

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、リファレンスゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果を変える値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 まず小さなサブセット（1 サンプル、1 染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を明記します。

次のような場合	対応
入力間でゲノムビルドや識別子が一致しない	続行する前に停止して整合させます（liftover、ID マッピング）。
これらの手順にある関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜調整してユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できないことがあれば、明確に伝えてください。
• 統計的な裏付けを超えて生物学的な意義を解釈しないでください。多重検定補正について報告してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭がかかる操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データに触れる操作、または取り消せない操作の前には、必ず確認してください。

関連スキル

• geniml：Geniml（0.8.4）と Gtars を使用して、ローカルなゲノム区間の機械学習ワークフローを計画・監査します。染色体 si…に対して BED ファイルを検証します。
• polars-bio：Arrow と DataFusion を基盤とし、Polars DataFrame 上でゲノム区間操作とバイオインフォマティクスのファイル入出力を行う Python ライブラリです。
• genomic-coordinates：ゲノム区間を座標規約間で変換し、バリアント表現を正規化して比較し、アセンブリまたはコンティグ名の…を検出します。