geniml

Geniml

ゲノム区間セットを対象とする機械学習および統計ワークフローには Geniml を使用します。座標、アセンブリ、トークンの語彙、モデルの成果物、サンプルのグループ分けを明示的な契約として扱います。同梱スクリプトは検証または計画を行うもので、Geniml のインポート、サービスへの接続、モデルのデシリアライズ、トレーニングの実行は行いません。

Bash は、このガイドに記載された、明示的にユーザーの承認を得た uv、Python、Geniml、Gtars、Git、およびネイティブ CLI コマンドに対してのみ宣言されています。同梱の Python ヘルパーはサブプロセスを起動しません。data/、refs/、work/、models/ 以下のパス例は、ユーザーが提供するプロジェクトのプレースホルダーであり、同梱ファイルの欠落を示すものではありません。

検証済みリリースのスナップショット

• 2026-07-23 時点で最新の PyPI 安定版リリース：geniml==0.8.4（2026-01-14）。
• PyPI は Requires-Python を宣言していません。分類子には Python 3.10～3.14 が記載されています。すべてのネイティブ／ML ホイールを解決できる Python 3.11 または 3.12 を推奨します。
• geniml==0.8.4 は gtars>=0.2.5 に対応しています。検証済みの基本的なスモークテストでは、現行の gtars==0.9.2（2026-06-17、Python >=3.10）を使用しました。
• エクストラは ml と test です。基本インストールには Torch、Gensim、Scanpy、Hugging Face Hub、pyBigWig、および HMM の依存関係は含まれません。
• 上流のドキュメントには古い例が含まれています。記載内容が食い違う場合は、リリースのソースコードとインストール後の --help の出力を優先してください。

再現可能な方法でインストールする

プロジェクト環境を使用し、生成されたロックファイルをコミットします。

uv venv --python 3.12
uv pip install "geniml==0.8.4" "gtars==0.9.2"

Region2Vec、scEmbed、評価、または ML ライブラリを必要とする universe メソッドの場合：

uv pip install "geniml[ml]==0.8.4" "gtars==0.9.2"

長期的に維持するプロジェクトでは、次を推奨します。

uv add "geniml[ml]==0.8.4" "gtars==0.9.2"
uv lock

Git ブランチをバージョン固定せずにインストールしないでください。Python、OS／アーキテクチャ、解決済みのロックファイル、PyPI 成果物のダイジェストを記録してください。Geniml 自体のライセンスは BSD-2-Clause です。frontmatter の MIT は、このスキルのコンテンツに適用されるライセンスです。

まず安全性の確認を行う

Geniml をインポートしたり、外部バイナリを実行したりする前に、次を行います。

1. 明示的に指定されたローカルの通常ファイルだけを扱います。ユーザーが意図的に方針を変更しない限り、URL、FIFO、デバイス、シンボリックリンクは拒否します。
2. 信頼できるローカルの染色体サイズファイルに照らして、BED の構造と宣言されたアセンブリを検証します。
3. ファイル数、バイト数、行数、ワーカー数、エポック数、出力サイズに上限を設けます。
4. トレーニング／検証／テストの分割は、患者、ドナー、生物学的反復、またはその他の独立した単位ごとに行います。BED の行や細胞だけで分割してはいけません。
5. universe、トークナイザー、モデル、設定、入力、メタデータマニフェスト、ネイティブバイナリの一覧を作成し、チェックサムを確認します。
6. BEDbase または Hugging Face からダウンロードする前に、明示的な承認を得ます。モデル ID や BEDbase 識別子だけで承認済みと判断してはいけません。
7. ログは集計済みで、量を制限したものにします。BED ファイル名、サンプル ID、表現型、ラベル、バーコード、ゲノム区間には機微な情報が含まれる場合があります。

座標とアセンブリの契約

BED 区間は通常、0-based、半開区間 [start, end) です。start は含まれ、end は含まれません。長さは end - start です。VCF／GFF や、ユーザー向けゲノムブラウザーで使われる 1-based の閉区間と混在させないでください。

コーパスと成果物ごとに、次を記録します。

• 可能であればアセンブリとパッチ／アクセッション（例：GRCh38 と GRCh38.p14）、および染色体サイズのチェックサム。
• コンティグの命名規則（chr1 と 1 のどちらか）、alt／random／decoy の扱い、ミトコンドリアの命名規則。
• 座標規約、ソート順、重複／重なりの扱い、BED の鎖情報が意味を持つかどうか。
• liftover ツール、chain のダイジェスト、変換元／変換先のアセンブリ、未マッピングの割合、liftover 後の検証。

負の座標、end <= start、整数オーバーフロー、未知のコンティグ、コンティグ長を超える end、不正な列、異なるアセンブリの混在、暗黙のコンティグ名変更は拒否します。ソートや正規化を行っても、アセンブリの不一致は修正されません。BED3 には鎖情報がありません。6 列目がある場合は、アッセイの契約で別途指定されていない限り、+、-、. を保持します。

解析の前に、上限を設けた検証と正規化の計画を実行します。

python skills/geniml/scripts/bed_validator.py \
  --input data/peaks.bed \
  --assembly GRCh38 \
  --chrom-sizes refs/GRCh38.chrom.sizes

バリデーターは実施予定の処理を報告しますが、BED ファイルを書き換えることはありません。

現在の API マップ

Region とトークナイザーの入出力

新しい区間／トークナイザーのコードでは、Gtars を優先してください。

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

regions = RegionSet("data/peaks.bed")
tokenizer = Tokenizer.from_bed("refs/universe.bed")
encoded = tokenizer(regions)
input_ids = encoded["input_ids"]

RegionSet と Tokenizer は、一部のコンストラクターでリモート入力も受け付けます。このスキルでは、ネットワークアクセスが明示的に承認されていない限り、ローカルパスのみを使用します。geniml.io.RegionSet(regions, backed=False) は、従来の Python 実装として引き続き利用できます。バックドセットは反復可能ですが、インデックス指定はできません。geniml.io.Region は stop を使用し、gtars.models.Region は end を使用します。

gtars 0.9.2 では、BED の語彙に7つの特殊トークンが追加されます。そのため、len(tokenizer) はユニバースの行数と単純に一致するわけではありません。ユニバースの行順と、特殊トークンのマップを正確に維持してください。

Region2Vec

最新のクラスは、具体的なモジュールパスにあります。

from geniml.region2vec.main import Region2VecExModel
from geniml.region2vec.utils import Region2VecDataset
from gtars.tokenizers import Tokenizer

tokenizer = Tokenizer.from_bed("refs/universe.bed")
dataset = Region2VecDataset("work/tokens.parquet", shuffle=True)
model = Region2VecExModel(tokenizer=tokenizer, embedding_dim=100)
model.train(dataset, epochs=10, window_size=5, num_cpus=4, seed=42)

Parquet 入力には、行ごとに1つのドキュメントを表す、リスト値の tokens 列が1つ含まれている必要があります。エクスポート、エンコード、従来の CLI、評価の詳細については、references/region2vec.md を参照してください。

scEmbed

geniml.scembed.main から ScEmbed をインポートしてください。AnnData の .var には chr、start、end が含まれている必要があります。行は細胞を表し、ゼロ以外の特徴はアクセス可能な領域を示します。事前に Parquet の tokens 列へトークン化し、トレーニングと推論で同じ Tokenizer を使用してください。references/scembed.md を参照してください。

BEDspace

BEDspace は 0.8.4 に引き続き含まれており、外部の StarSpace 実行ファイルを呼び出します。StarSpace はアーカイブされており、上流の Geniml は互換性のあるリビジョンを固定していません。BEDspace は従来の再現用の手段として扱い、新しいシステムのデフォルトにはしないでください。正確で安定した CLI の表記と、変更されないものの明示的に未検証のビルド基準については、references/bedspace.md を参照してください。

コンセンサスユニバースと評価

インストールされる 0.8.4 の CLI では、次のコマンドを使用します。

geniml build-universe {cc,ccf,ml,hmm} ...
geniml assess-universe ...
geniml eval {gdst,npt,ctt,rct,bin-gen} ...

CC／CCF／ML／HMM は、事前計算済みのカバレッジ bigWig を使用します。すべての BED ファイルが同じアセンブリ要件を満たすまでは、カバレッジを連結したり生成したりしないでください。評価と埋め込みメトリクスは別物です。assess-universe はユニバースと区間コレクションの適合度を測定し、eval は埋め込みに対する CTT、RCT、GDST、NPT を実装します。references/consensus_peaks.md と references/utilities.md を参照してください。

重要な 0.8.4 移行メモ

• 0.7.0 の変更履歴では、新しい RegionSet／トークナイザーの作業が Gtars に移行しました。
• 0.4.0 の TreeTokenizer と AnnDataTokenizer は過去の名称です。現在の Gtars API では Tokenizer が公開されています。
• 0.8.4 の wheel では、geniml.region2vec と geniml.scembed は最新のクラス／関数を再エクスポートしません。上記の具体的なモジュールパスを使用してください。
• geniml tokenize と geniml region2vec は、パッケージの __init__ ファイルからは公開されなくなった名前を呼び出します。インストール済みバージョンでスモークテストを行わずに、これらの CLI パスを中心とした新しいワークフローを構築しないでください。
• geniml scembed は従来の MatrixMarket オプションを解析しますが、0.8.4 ではコマンド本体は何もしません。geniml.scembed.main.ScEmbed を使用してください。
• 公式ページには引き続き geniml assess と記載されていますが、リリース版のコマンドは geniml assess-universe です。
• .gtok は従来のデータセットに引き続き存在しますが、上流の issue #14 では、多数の .gtok ファイルを使うワークフローの非推奨化が提案されています。サイズを制限した単一の Parquet コーパスを優先してください。
• 設定キー embedding_size は後方互換性のためにのみ受け付けられます。embedding_dim を使用してください。

モデルとユニバースの互換性

Region2Vec/scEmbed の推論バンドルが有効なのは、次の項目が一致している場合に限られます。

• モデルの config.yaml の vocab_size と embedding_dim。
• universe.bed のバイト列と順序、およびアセンブリが完全に一致していること。
• トークナイザーの実装とバージョン、および特殊トークン ID。
• チェックポイントのテンソル形状とプーリングポリシー。
• Geniml/Gtars のバージョンと、トークン化パラメーター。

Geniml 0.8.4 では、デフォルトで checkpoint.pt、config.yaml、universe.bed が使用されます。 ローダーは torch.load(..., weights_only=True) を使用しますが、.pt、Gensim .model、pickle、joblib、ネイティブバイナリは依然として信頼できない入力です。読み込む前にアーティファクトを検査してチェックサムを確認し、隔離された環境を使用してください。また、メタデータを確認するためだけにチェックポイントを読み込まないでください。

python skills/geniml/scripts/model_artifact_inspector.py \
  --model-dir models/region2vec

python skills/geniml/scripts/tokenizer_compatibility.py \
  --model-dir models/region2vec \
  --universe refs/universe.bed \
  --assembly GRCh38

Region2VecExModel(model_path="org/repo")、ScEmbed(model_path="org/repo")、 および Gtars の Tokenizer.from_pretrained(...) は Hugging Face からダウンロードできます。 ローカルの from_pretrained("models/local") はローカルバンドルを読み込みます。ユーザーがダウンロードを承認した場合は、Hub のリビジョンと期待するハッシュを固定してください。その後は検証済みキャッシュからオフラインで作業します。

BEDbase のダウンロードとキャッシュ

BBClient.load_bed、load_bedset、およびトークンキャッシュ操作では、 https://api.bedbase.org に接続する場合があります。デフォルトのキャッシュは $BBCLIENT_CACHE または ~/.bbcache です。BEDBASE_API を設定するとエンドポイントが変わります。無関係な環境変数は読み取らないでください。明示的にプロジェクト用キャッシュを設定し、サイズを見積もり、識別子とエンドポイントの使用を承認してから、利用前に返されたチェックサムを確認してください。

ローカルの検査コマンドのほうが安全です。

geniml bbclient seek ID --cache-folder /absolute/project/cache
geniml bbclient inspect-bedfiles --cache-folder /absolute/project/cache
geniml bbclient inspect-bedsets --cache-folder /absolute/project/cache

cache-bed、cache-bedset、cache-tokens のサブコマンドでは、ネットワークが使用される場合があります。暗黙的に実行しないでください。また、機密性の高いローカル BED ファイルをアップロード／キャッシュのワークフローに含めないでください。

ローカル監査と計画用 CLI

すべてのスクリプトは標準ライブラリのみを使用し、デフォルトで秘匿化された JSON を出力します。

# Audit manifest paths, checksums, assemblies, and patient/donor leakage
python skills/geniml/scripts/corpus_auditor.py \
  --manifest data/manifest.tsv --assembly-column assembly \
  --group-column patient_id --split-column split

# Plan tokenizer/model compatibility checks
python skills/geniml/scripts/tokenizer_compatibility.py \
  --model-dir models/r2v --universe refs/universe.bed --assembly GRCh38

# Plan consensus construction; does not execute Geniml or coverage tools
python skills/geniml/scripts/consensus_plan.py \
  --manifest data/manifest.tsv --chrom-sizes refs/GRCh38.chrom.sizes \
  --assembly GRCh38 --method cc --output-dir work/consensus

# Plan an embedding run; does not import ML libraries
python skills/geniml/scripts/embedding_plan.py \
  --mode region2vec --data work/tokens.parquet \
  --universe refs/universe.bed --output-dir work/r2v \
  --assembly GRCh38

リソース制限と、パス開示を明示的に制御する方法については、--help を使用してください。

参考資料

• Region2Vec：最新の API、アーティファクト、CLI の変更点、 トレーニング、エンコード、評価。
• scEmbed：AnnData／トークンの準備、トレーニング、 推論、アノテーション、プライバシー、データリーク。
• BEDspace：メタデータスキーマ、旧 CLI の正確な仕様、 StarSpace の状況、アーティファクト、検索。
• コンセンサスピーク：カバレッジの前提条件、 CC／CCF／ML／HMM、評価、アセンブリの安全対策。
• ユーティリティ：I/O、Gtars トークナイザー、BBClient、 評価、モデルの安全性、移行、日付付き情報源。

ソースのスナップショットと主要論文へのリンクの日付は、 references/utilities.md に記載されています。固定したバージョンを変更する前に、リリースのメタデータとインストール済みのシグネチャを再確認してください。

エージェントの作業手順

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

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

誠実性に関するルール

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

関連スキル

• gtars：ゲノム領域のためのRust／Python／CLIツールキットであるGtarsを使用して、作業を調査・計画します。BED RegionSetの集合演算（reduce、setdiff、intersec…
• genomic-coordinates：ゲノム区間を座標規約間で変換し、バリアント表現を正規化して比較し、アセンブリまたはコンティグ名の不一致を検出します…