tiledbvcf

TileDB-VCF

使用する場面

コホートバリアントの保存、サンプルの増分取り込み、インターバルクエリ、および 下流のゲノミクス向けにサブセットをエクスポートする場合に使用します。TileDB-VCF は レコードを保存しますが、ジョイントバリアントコール、関連解析、正規化、集団 構造の調整は行いません。データセットのサイズだけではクラウド実行が適切かどうかは 決まりません。想定されるサンプル、領域、属性のワークロードでベンチマークしてください。

このスキルはリリース済みの TileDB-VCF 0.40.3 を対象としています。ネイティブの Python/CLI チェックでは、macOS ARM64 上で 2 つの合成シングルサンプル VCF を使用 しました。クラウドクライアント 0.14.4 のコントラクトは、リリース済みの wheel と モック化されたディスパッチに対して確認しました。ホスト型クエリとジョブは 実行していません。詳細はインストールと検証のメモを 参照してください。

ネイティブスタックのインストールと検証

このレビュー時点で、tiledbvcf Python ディストリビューションは PyPI に公開されて いません。公式の tiledb Conda チャンネルが、macOS ARM64、macOS x86-64、 Linux x86-64 向けの tiledbvcf-py 0.40.3 を提供しており、Python 3.9-3.12 の ビルドがあります。PyPI の tiledb は TileDB-Py であり、TileDB-VCF は インストールしません。ネイティブの Apple Silicon では、CONDA_SUBDIR=osx-64 を 強制する必要はなくなりました。

テスト済みの macOS ARM64 環境では、以下のピン指定により、それ以外は成功する現在の Conda ソルブにおけるバージョン付きライブラリのインポート失敗を回避できます。

conda create -n tiledb-vcf -c tiledb -c conda-forge \
  python=3.12 tiledbvcf-py=0.40.3 \
  azure-core-cpp=1.16.2 azure-storage-blobs-cpp=12.16.0 \
  azure-storage-files-datalake-cpp=12.14.0 capnproto=1.4.0 c-blosc2=2.23.1
conda activate tiledb-vcf
python -c 'import tiledbvcf; print(tiledbvcf.version)'
tiledbvcf version

同等の Micromamba のソルブ/インストールを実行しました。これらの追加の ABI ピンは、 検証済みの macOS ARM64 向けワークアラウンドであり、すべてのプラットフォームに ついての主張ではありません。本番環境では解決済みの環境を保持してください。 他プラットフォームへのインストールと公式 Docker イメージはアップストリームで 文書化されている代替手段であり、ここではテストしていません。

コホートの準備と作成

1. リファレンスアセンブリ、コンティグの命名/長さ、コーラー、正規化ルール、 サンプルアイデンティティ、ファイルチェックサムを記録します。アセンブリを 混在させたり、1 と chr1 が同等であると仮定したりしないでください。入力間で 互換性のあるヘッダーを確認してください。
2. 各入力は1 サンプルを含み、座標でソートされ、インデックスを持つ必要が あります。BGZF 圧縮された VCF または BCF を、対応する .csi/.tbi とともに 使用してください。bcftools query -l sample1.vcf.gz を確認してください。 ファイル名はサンプル識別子ではありません。
3. データセットを明示的に作成してから、取り込みを行います。mode="w" で開くだけ ではスキーマは作成されません。頻繁に読み取られるフィールドは作成時に マテリアライズしてください。
4. スケールする前に、小さな既知のインターバルとラウンドトリップエクスポートを 検証してください。

既存のソート済みプレーンテキスト VCF の場合(入力ごとに 1 回実行します。出力名は 新しい名前にする必要があります):

bcftools view -Oz -o sample1.vcf.gz sample1.vcf
bcftools index -c sample1.vcf.gz
bcftools view -Oz -o sample2.vcf.gz sample2.vcf
bcftools index -c sample2.vcf.gz

以下のローカル例は、サンプル ID S1 と S2、コンティグ chr1、座標 1-100 で 実行しました。実データでは検証済みの ID とインターバルに置き換えてください。

import tiledbvcf

uri = "cohort"
config = {"sm.compute_concurrency_level": "2", "sm.io_concurrency_level": "2"}
with tiledbvcf.Dataset(uri, mode="w", tiledb_config=config) as ds:
    ds.create_dataset(extra_attrs=["fmt_GT", "fmt_DP"])
    ds.ingest_samples(
        ["sample1.vcf.gz"], threads=2, total_memory_budget_mb=512
    )

# Incremental ingestion uses the existing dataset; do not call create_dataset again.
with tiledbvcf.Dataset(uri, mode="w", tiledb_config=config) as ds:
    ds.ingest_samples(
        ["sample2.vcf.gz"], threads=2, total_memory_budget_mb=512
    )

schema-v4 のデータ配列には contig、開始座標、サンプルの次元があります。 ヘッダーとオプションの統計は、データセットグループ内の別々の配列です。明示的に マテリアライズされていないフィールドは、INFO/FORMAT ペイロードに残ります。 pos_start のようなクエリ名は、生のストレージ列名と一致する必要はありません。

アップストリームは並列スレッド/プロセスでの取り込みをサポートしています。サンプル ごとに異なる作業と、座標のライフサイクル/メンテナンス操作を割り当ててください。 サンプルを盲目的に再取り込みしないでください。resume=True は中断された 取り込みをサポートしますが、任意の重複修正をサポートするものではありません。

完全にクエリし、座標を正しく解釈する

サーフェス	座標の規約
Python regions=["chr1:10-14"]	1 始まり、閉区間
返される pos_start、pos_end	1 始まり、両端を含むレコード端点
BED 入力と query_bed_start、query_bed_end	0 始まり、半開区間
0.40.3 における read_variant_stats() / read_allele_count() の列 pos	0 始まり。VCF POS に結合する前に 1 を加算してください

クエリは重複するレコードを返します。区間内で開始するレコードだけではありません。位置 10-14 にまたがる欠失は chr1:14-14 に現れ、pos_start=10 となります。BED [13,14) の場合、等価な文字列は chr1:14-14 です。 Python の領域パーサーは明示的な contig:start-end を必要とします。このリリースでは裸の "chr1" は拒否されます。コンティグ全体のクエリには、既知のコンティグ長を使用してください。

cfg = tiledbvcf.ReadConfig(memory_budget_mb=128, tiledb_config=config)
attrs = ["sample_name", "contig", "pos_start", "pos_end", "alleles", "fmt_GT"]
with tiledbvcf.Dataset(uri, cfg=cfg) as ds:
    assert {"S1", "S2"}.issubset(ds.samples())
    assert set(attrs).issubset(ds.attributes())
    for batch in ds.read_iter(
        attrs=attrs, regions=["chr1:1-100"], samples=["S1", "S2"]
    ):
        print(batch)  # Replace with a bounded consumer or partitioned output.

• read() は pandas DataFrame を返し、read_arrow() は PyArrow Table を返します。 どちらもメモリ制限された最初のバッチのみを返すことがあります。read_completed() になるまで continue_read() / continue_read_arrow() で続行するか、通常の DataFrame クエリには read_iter() を使用してください。結果がメモリに収まらない場合は、すべてのバッチを 連結しないでください。
• ReadConfig(memory_budget_mb=...) は読み取りを制御します。書き込みには ingest_samples(total_memory_budget_mb=...) を使用してください。読み取りバジェットは プロセスの RSS 上限ではありません。limit は総出力を切り捨てます。ページネーションの サイズではありません。
• sample_partition=(0, 2) は 2 つのうちパーティション ゼロを選択します。同様に、 region_partition=(index, number_of_partitions) はクエリ領域をパーティション分割します。 これらのタプルは座標境界、タイル範囲、サンプル容量ではありません。
• 0.40.3 は、後続の呼び出しで bed_file が省略された場合に BED 選択状態を保持します。 BED/領域入力を変更する際に独立したクエリを行うには、新しい Dataset を開いてください。
• fmt_GT には対立遺伝子インデックスが含まれます。0 は REF を参照し、正の値は ALT を インデックスし、-1 は欠損を意味します。マルチアレリックの同一性と倍数性を保持してください。 すべての正の整数をバイアレリックの投与量として扱ったり、欠損コールを参照として扱ったり しないでください。整数リストだけでは、元のフェーズド GT 文字列をエンコードしません。

エクスポートと検証

from pathlib import Path

Path("exported").mkdir(exist_ok=True)
with tiledbvcf.Dataset(uri, cfg=cfg) as ds:
    ds.export(
        samples=["S1"], regions=["chr1:1-100"],
        output_format="v", output_dir="exported",
    )

Python のエクスポート形式: v VCF、z 圧縮 VCF、u 非圧縮 BCF、b 圧縮 BCF。merge=False はサンプルごとのファイルを書き込み、merge=True は 統合された output_path を必要とします。統合エクスポートはジョイントコールではありません。 インデックス付きの下流アクセスの前に、エクスポートされたファイルを再インデックスしてください。 サンプル ID、コンティグ、レコード数、対立遺伝子、INFO/FORMAT 値、欠損/フェーズド ジェノタイプを比較してください。セマンティックなラウンドトリップの保持は、バイト単位で 同一の圧縮やヘッダーを意味しません。

CLI は位置指定のサンプルパスまたは --samples-file（1 行につき 1 つの URI）を受け付け、 カンマ区切りの --samples 引数は受け付けません:

tiledbvcf create --uri cli_cohort
tiledbvcf store --uri cli_cohort --threads 2 --total-memory-budget-mb 512 \
  -- sample1.vcf.gz sample2.vcf.gz
tiledbvcf list --uri cli_cohort
tiledbvcf stat --uri cli_cohort
tiledbvcf export --uri cli_cohort --regions chr1:1-100 \
  --sample-names S1,S2 -Ot --tsv-fields 'SAMPLE,CHR,POS,REF,ALT,F:GT' \
  --output-path variants.tsv

-- は位置指定パスを --tiledb-config などの可変長オプションから保護します。 終了コードだけでなく、期待されるアーティファクトとサンプル数を確認してください。 レビュー対象の CLI では、無効なストアコマンドがエラーを出力しながら終了コード ゼロを 返しました。TSV フィールドは FORMAT/GT に F:GT、INFO/DP に I:DP を使用します。

コホート統計と QC

with tiledbvcf.Dataset(uri, cfg=cfg) as ds:
    stats = ds.read_variant_stats(regions=["chr1:1-100"], drop_ref=True)
    stats["vcf_pos"] = stats["pos"] + 1
    print(stats[["contig", "vcf_pos", "alleles", "ac", "an", "af"]])

qc = tiledbvcf.sample_qc(uri, samples=["S1"], config=config)
print(qc)

統計配列は作成時にデフォルトで有効になります。古い配列や無効化された配列は、これらの操作をサポートしていない場合があります。read_variant_stats には samples 引数がありません。古い read_allele_frequency(dataset_uri, region) ラッパーは単一のリージョンを受け付け、非推奨の単数引数に委譲します。上記の Dataset メソッドを優先してください。sample_qc は最初の引数として uri ではなく dataset_uri を使用します。

ac、an、af の値は、選択された祖先やクエリのサンプルサブセットではなく、取り込まれたコホートを要約したものです。read(samples=[...], set_af_filter=">0.6") フィルターは、テストされたリリースでは依然としてコホート AF を使用していました。サブグループの頻度は、明示的な欠損性、倍数性、コーラブル領域、gVCF 参照ブロックのポリシーを用いて正しく選択されたコールから計算してください。普遍的に 2 * number_of_samples ではなく、適切なコール済みアリルの分母を使用してください。VCF レコードの欠落は、ホモ接合参照コールの証明にはなりません。QC メトリクスとスパースストレージは、GWAS の準備完了や科学的妥当性を確立するものではありません。

オブジェクトストレージと TileDB Cloud

直接ストレージは s3://bucket/path、azure://container/path、または gcs://bucket/path を使用し、インストールされている TileDB バックエンドとそのプロバイダー認証情報によってサポートされます。これは計算を自動的に分散するものではありません。プロバイダーの認証情報チェーンまたはスコープ付き設定を使用し、データセットとソースインデックスの両方へのアクセスを検証してください。TileDB Cloud トークンはバケット認証情報とは別のものです。以下のリモートストレージの例は例示であり、ソースで検証されたもので、エンドツーエンドの認証済みテストではありません。

互換性のある環境に tiledb-cloud==0.14.4 をインストールしてください。その life-sciences エクストラは TileDB-SOMA を追加しますが、TileDB-VCF は追加しません。クライアントをインポートする前に、実行環境を通じて TILEDB_REST_TOKEN を提供してください。必要に応じて TILEDB_REST_HOST がカスタムデプロイを選択します。コードにトークンを埋め込んだり、設定を出力したりしないでください。

# Illustrative: requires an accessible registered cohort and a billing namespace.
import tiledb.cloud
import tiledb.cloud.vcf

cloud_cfg = tiledb.cloud.Config()
with tiledbvcf.Dataset("tiledb://my-namespace/cohort", tiledb_config=cloud_cfg) as ds:
    sample_names = ds.samples()

result = tiledb.cloud.vcf.read(
    dataset_uri="tiledb://my-namespace/cohort",
    config=cloud_cfg, attrs=["sample_name", "pos_start", "fmt_GT"],
    regions=["chr1:1-100"], samples=sample_names[:2],
    num_region_partitions=1, namespace="my-namespace", max_workers=2,
)
frame = result.to_pandas()  # read returns an Arrow table, not a DataFrame.

分散読み取りは Arrow 結果を組み立て、相当なワーカー/クライアントメモリを使用する場合があります。要求するリージョン/サンプルとワーカー数を制限してください。パーティショニングは、最終的に連結された結果をメモリフリーにするものではありません。これは SDK タスクの実行であり、ページネーションされた VCF REST リスト API ではありません。

# Illustrative, mutating cloud job: use only for an authorized ingestion task.
submission = tiledb.cloud.vcf.ingest(
    dataset_uri="s3://my-bucket/cohort",
    sample_list_uri="s3://my-bucket/inputs/sample-uris.txt",
    namespace="my-namespace", acn="registered-storage-role",
    register_name="cohort", max_samples=2,
    ingest_resources={"cpu": "2", "memory": "4Gi"},
)
print(submission["graph_id"])

search_uri、sample_list_uri、または metadata_uri のいずれか 1 つだけを使用してください。ファイル検索パターンは search_uri に適用されます。登録にはアクセス認証情報名(acn)が必要です。vcf.ingest は非同期で送信され、{"status": "started", "graph_id": ...} を返します。完了を主張する前に、そのグラフを追跡して最終的な成功を確認し、取り込まれたサンプルを検証してください。リリースされた ingest_vcf_dataset(source=..., output=...) API は存在しません。価格設定、可用性、セキュリティ制御、およびデプロイ義務については、現在のアカウント/サービス条件が必要です。

公式リファレンス

• TileDB-VCF 0.40.3 リリース
• Dataset API
• 取り込み
• 大規模クエリ
• クラウドストレージ
• TileDB Cloud クライアントリリース
• 検証の詳細と既知のリリース問題