alterlab-tiledbvcf

TileDB-VCF

概要

TileDB-VCF は、ゲノム変異コールデータを効率的に保存および取得するための、高性能な C++ ライブラリです。Python および CLI インターフェースを備えています。TileDB のスパース配列テクノロジーを基盤としており、VCF/BCF ファイルのスケーラブルな取り込み、コストのかかるマージ処理を行わないサンプルの段階的な追加、ローカルまたはクラウドに保存された変異データの効率的な並列クエリを可能にします。

このスキルを使用する場面

次のような場合にこのスキルを使用してください：

• 多数の単一サンプル VCF/BCF ファイルから、クエリ可能な圧縮変異ストアを構築する場合（フラットな VCF では大きすぎるコホート／集団データセット）
• 既存のストアに新しいサンプルを、再マージせずに段階的に追加する場合
• 多数のサンプルにわたって、特定のゲノム領域をクエリする場合（領域／サンプルで分割した読み取り）
• 後続のツールで使用するため、領域／サンプルのサブセットを VCF/BCF にエクスポートする場合
• クラウドストレージ（S3、Azure、GCS）または TileDB Cloud 上の変異データを扱う場合
• スケーラブルなゲノム変異ワークフローのプロトタイプを作成したり、指導したりする場合

対象外

シナリオ	代わりに使用
Python（pysam/htslib）で少数の VCF/BAM ファイルを読み取り、フィルタリング、または反復処理する	alterlab-pysam
VCF を最初に生成する（FASTQ -> アラインメント -> 変異コール）	alterlab-nf-core-sarek
特定の変異の臨床的解釈や集団頻度を調べる	alterlab-clinvar / alterlab-gnomad
変異データ以外の一般的なチャンク化配列ストレージ（画像、テンソル、行列）	alterlab-zarr
エクスポートしたテーブルに対するアウトオブコアのデータフレーム分析	alterlab-polars / alterlab-dask

クイックスタート

インストール

推奨方法：tiledb チャンネルから conda/mamba を使用します。 tiledbvcf-py は PyPI、conda-forge、bioconda では提供されていません。Apple Silicon で Rosetta/CONDA_SUBDIR の回避策を必要としないネイティブの osx-arm64 ビルドを含め、TileDB Anaconda チャンネルから提供されています。現在のリリースは 0.40.3（2026年4月）で、Python 3.9–3.12 向けに linux-64、osx-64、osx-arm64 用としてビルドされています。3.13 ビルドはないため、環境を作成する際はインタープリターのバージョンを固定してください。新しい Python バージョンに解決されるデフォルトの conda create では、その理由が説明されず、パッケージが利用できないと表示されます。

# Native Apple Silicon (osx-arm64) — also works on osx-64 / linux-64
conda create -n tiledb-vcf -c conda-forge -c tiledb \
  python=3.12 tiledbvcf-py=0.40 pandas pyarrow numpy
conda activate tiledb-vcf

代替方法：Docker イメージ（CLI/Python インターフェースを取得します。latest タグは現行リリースに追従します）

docker pull tiledb/tiledbvcf-py     # Python interface
docker pull tiledb/tiledbvcf-cli    # Command-line interface

基本的な例

データセットを作成してデータを取り込む：

import tiledbvcf

# Create a new dataset
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
                      cfg=tiledbvcf.ReadConfig(memory_budget_mb=1024))

# Ingest VCF files (must be single-sample with indexes)
# Requirements:
# - VCFs must be single-sample (not multi-sample)
# - Must have indexes: .csi (bcftools) or .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])

変異データをクエリする：

# Open existing dataset for reading
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")

# Query specific regions and samples
df = ds.read(
    attrs=["sample_name", "pos_start", "pos_end", "alleles", "fmt_GT"],
    regions=["chr1:1000000-2000000", "chr2:500000-1500000"],
    samples=["sample1", "sample2", "sample3"]
)
print(df.head())

VCF にエクスポートする：

import os

# Export two VCF samples
ds.export(
    regions=["chr21:8220186-8405573"],
    samples=["HG00101", "HG00097"],
    output_format="v",
    output_dir=os.path.expanduser("~"),
)

主な機能

1. データセットの作成と取り込み

TileDB-VCF データセットを作成し、複数の VCF/BCF ファイルから変異データを段階的に取り込みます。これは、集団ゲノミクスデータベースやコホート研究の構築に適しています。

要件：

• 単一サンプルの VCF のみ：複数サンプルの VCF はサポートされていません
• インデックスファイルが必須：VCF/BCF ファイルにはインデックス（.csi または .tbi）が必要です

一般的な操作：

• 最適化された配列スキーマで新しいデータセットを作成する
• 単一または複数の VCF/BCF ファイルを並列に取り込む
• 既存データを再処理せずに新しいサンプルを段階的に追加する
• メモリ使用量と圧縮設定を構成する
• さまざまな VCF 形式や INFO/FORMAT フィールドを処理する
• 中断された取り込み処理を再開する
• 取り込み中にデータの整合性を検証する

2. 効率的なクエリとフィルタリング

ゲノム領域、サンプル、変異属性にわたって、高いパフォーマンスで変異データをクエリします。これは、関連解析、変異の探索、集団解析に適しています。

一般的な操作：

• 特定のゲノム領域をクエリする（単一または複数）
• サンプル名またはサンプルグループでフィルタリングする
• 特定の変異属性（位置、対立遺伝子、遺伝子型、品質）を抽出する
• INFO および FORMAT フィールドに効率的にアクセスする
• 空間フィルタリングと属性ベースのフィルタリングを組み合わせる
• 大規模なクエリ結果をストリーミングする
• サンプルまたは領域にわたる集計を実行する

3. データのエクスポートと相互運用性

下流の分析や他のゲノミクスツールとの統合に向けて、さまざまな形式でデータをエクスポートします。データセットの共有、分析用サブセットの作成、他のパイプラインへのデータの受け渡しに適しています。

一般的な操作：

• 標準的なVCF/BCF形式にエクスポートする
• 選択したフィールドを含むTSVファイルを生成する
• サンプルや領域に固有のサブセットを作成する
• データの来歴とメタデータを保持する
• すべてのアノテーションを保持したロスレスなデータエクスポート
• 圧縮出力形式
• 大規模なデータセット向けのストリーミングエクスポート

4. 集団ゲノミクスのワークフロー

TileDB-VCFは、多数のサンプルとゲノム領域にまたがる変異データへ効率的にアクセスする必要がある、大規模な集団ゲノミクス解析に優れています。

一般的なワークフロー：

• ゲノムワイド関連解析（GWAS）用データの準備
• 希少変異の負荷検定
• 集団構造解析
• 集団間の対立遺伝子頻度の計算
• 大規模コホートの品質管理
• 変異のアノテーションとフィルタリング
• 集団間の比較解析

主要な概念

配列スキーマとデータモデル

TileDB-VCFのデータモデル：

• 変異は、ゲノム座標を次元とするスパース配列として保存されます
• サンプルは属性として保存され、サンプル固有のクエリを効率化します
• INFOフィールドとFORMATフィールドは、元のデータ型を保持します
• 最適なストレージを実現するため、自動的に圧縮とチャンク分割が行われます

スキーマの設定：

# Partition a large read across region/sample space
config = tiledbvcf.ReadConfig(
    memory_budget_mb=2048,        # memory budget in MB
    region_partition=(0, 10),     # (partition_index, num_partitions) over regions
    sample_partition=(0, 4),      # (partition_index, num_partitions) over samples
)

座標系と領域

重要： TileDB-VCFでは、VCF標準に準拠した1始まりのゲノム座標を使用します。

• 位置は1始まりです（最初の塩基の位置は1です）
• 範囲の両端を含みます
• 領域「chr1:1000-2000」には、位置1000～2000（合計1001塩基）が含まれます

領域の指定形式：

# Single region
regions = ["chr1:1000000-2000000"]

# Multiple regions
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]

# Whole chromosome
regions = ["chr1"]

注： regions=の文字列は常に1始まりで両端を含みます。start <= 0の場合は「Regions must be 1-based」エラーが発生します。暗黙的にBED形式へ変換されることはありません。0始まりの半開区間であるBED区間を使用するには、regions=リストではなく、read(bed_file="regions.bed", ...)でBEDファイルを渡してください。

メモリ管理

パフォーマンスに関する考慮事項：

1. 適切なメモリ予算を設定する：利用可能なシステムメモリに基づいて設定します
2. ストリーミングクエリを使用する：非常に大きな結果セットに使用します
3. 大規模な取り込みを分割する：メモリ不足を防ぎます
4. タイルキャッシュを設定する：領域へのアクセスを繰り返す場合に使用します
5. 並列取り込みを使用する：複数のファイルを処理する場合に使用します
6. 領域クエリを最適化する：近接する領域をまとめます

クラウドストレージとの統合

TileDB-VCFはクラウドストレージとシームレスに連携します。

# S3 dataset
ds = tiledbvcf.Dataset(uri="s3://bucket/dataset", mode="r")

# Azure Blob Storage
ds = tiledbvcf.Dataset(uri="azure://container/dataset", mode="r")

# Google Cloud Storage
ds = tiledbvcf.Dataset(uri="gcs://bucket/dataset", mode="r")

よくある落とし穴

1. 取り込み中のメモリ不足： 大きなVCFファイルには、適切なメモリ予算とバッチ処理を使用してください
2. 非効率な領域クエリ： 個別のクエリを多数実行するのではなく、近接する領域をまとめてください
3. サンプル名の欠落： VCFヘッダーのサンプル名が、クエリで指定するサンプル名と一致していることを確認してください
4. 座標系の混同： TileDB-VCFでは、VCF標準と同じ1始まりの座標を使用することを忘れないでください
5. 大きな結果セット： 数百万の変異を返すクエリには、ストリーミングまたはページネーションを使用してください
6. クラウドの権限： クラウドストレージにアクセスするための適切な認証を確認してください
7. 同時アクセス： 同じデータセットへの複数の書き込みによって破損が発生する可能性があります。適切なロックを使用してください

CLIの使用方法

TileDB-VCFには、次のサブコマンドを備えたコマンドラインインターフェイスがあります。

利用可能なサブコマンド：

• create - 空のTileDB-VCFデータセットを作成します
• store - サンプルをTileDB-VCFデータセットに取り込みます
• export - TileDB-VCFデータセットからデータをエクスポートします
• list - TileDB-VCFデータセットに含まれるすべてのサンプル名を一覧表示します
• stat - TileDB-VCFデータセットの概要統計を出力します
• utils - TileDB-VCFデータセットを操作するためのユーティリティです
• version - バージョン情報を出力して終了します

# Create empty dataset
tiledbvcf create --uri my_dataset

# Ingest samples (requires single-sample VCFs with indexes)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz

# Export data
tiledbvcf export --uri my_dataset \
  --regions "chr1:1000000-2000000" \
  --sample-names "sample1,sample2"

# List all samples
tiledbvcf list --uri my_dataset

# Show dataset statistics
tiledbvcf stat --uri my_dataset

高度な機能

これらはDatasetオブジェクト（mode="r"で開いたもの）のメソッドであり、トップレベルのtiledbvcf関数ではありません。read_allele_frequencyやsample_qc関数はありません。以下のメソッドを使用してください。

アレル数／頻度

ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")

# Internal allele-count (AC) array, returned as a pandas DataFrame
ac_df = ds.read_allele_count(region="chr1:1000000-2000000")

# Apply an allele-frequency filter at read time on a normal read()
df = ds.read(
    attrs=["sample_name", "pos_start", "alleles", "fmt_GT"],
    regions=["chr1:1000000-2000000"],
    set_af_filter="<0.01",  # keep variants with AF below threshold
)

バリアント統計（QC）

# Internal variant-stats array (per-variant aggregate stats) as a DataFrame
stats_df = ds.read_variant_stats(region="chr1:1000000-2000000")

注：read_allele_count と read_variant_stats を使用するには、対応する内部配列を有効にしてデータセットを取り込んでいる必要があります（最近のバージョンではデフォルトで有効です）。

TileDB 設定の受け渡し

# Pass raw TileDB Embedded config keys (e.g. cloud creds, cache sizing)
config = tiledbvcf.ReadConfig(
    memory_budget_mb=4096,
    tiledb_config={
        "sm.tile_cache_size": "1000000000",
        "vfs.s3.region": "us-east-1",
    },
)

リソース

• TileDB-VCF GitHub（ソース、課題、リリース）：https://github.com/TileDB-Inc/TileDB-VCF
• 集団ゲノミクスガイド（Academy）：https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
• Python API リファレンス：https://tiledb-inc.github.io/TileDB-VCF/documentation/reference/Dataset.html
• TileDB Cloud（マネージド、分散型）：https://cloud.tiledb.com

TileDB-Cloud へのスケーリング

ワークロードが単一ノードでの処理の限界を超える場合（目安：サンプル数が 1000 を超える、VCF が 100 GB を超える、または分散コンピューティング／共有アクセスが必要な場合）、同じデータセットを tiledb-cloud-py 経由で TileDB Cloud に取り込み、クエリできます。ローカルの tiledbvcf API は変わりません。クラウドパッケージによって分散オーケストレーションが追加されます。

セットアップ

pip install "tiledb-cloud[life-sciences]"   # cloud client with genomics extras
export TILEDB_REST_TOKEN="your_api_token"   # auth is automatic from this env var

分散取り込みと読み取り。 Cloud の VCF エントリポイントは tiledb.cloud.vcf にあります。

• tiledb.cloud.vcf.ingest(...) — tiledb://namespace/dataset URI に分散取り込みを行います
• tiledb.cloud.vcf.build_read_dag(...) — 領域／サンプルを対象とする分散読み取り DAG を構築します

リリースによって正確なシグネチャやリソース引数が変わるため、引数をハードコードするのではなく、最新の Cloud API リファレンスを参照してください：https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/api-reference/cloud/

Cloud でホストされたデータセットも、認証情報を含む tiledb_config と tiledb:// URI を渡すことで、通常の tiledbvcf.Dataset API で開くことができます。

import tiledbvcf

cfg = {"rest.token": "your_api_token"}  # or rely on TILEDB_REST_TOKEN
ds = tiledbvcf.Dataset("tiledb://TileDB-Inc/gvcf-1kg-dragen-v376",
                       mode="r", tiledb_config=cfg)
df = ds.read(
    attrs=["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"],
    regions=["chr13:32396898-32397044", "chr13:32398162-32400268"],
    samples=ds.samples(),
)