TileDB-VCF
개요
TileDB-VCF는 유전체 변이-콜 데이터의 효율적인 저장 및 검색을 위한 고성능 C++ 라이브러리로, Python 및 CLI 인터페이스를 제공합니다. TileDB의 희소 배열 기술을 기반으로 구축되어 VCF/BCF 파일의 확장 가능한 수집, 비용이 많이 드는 병합 작업 없이 점진적 샘플 추가, 로컬 또는 클라우드에 저장된 변이 데이터에 대한 효율적인 병렬 쿼리를 가능하게 합니다.
이 기술을 사용해야 하는 경우
이 기술은 다음과 같은 경우에 사용해야 합니다:
- TileDB-VCF 개념 및 워크플로 학습
- 유전체 분석 및 파이프라인 프로토타이핑
- 소규모~중간 규모 데이터 세트(< 1000개 샘플) 작업
- 기존 데이터 세트에 새 샘플을 점진적으로 추가해야 하는 경우
- 여러 샘플에 걸쳐 특정 유전체 영역을 효율적으로 쿼리해야 하는 경우
- 클라우드 저장 변이 데이터(S3, Azure, GCS) 작업
- 대규모 VCF 데이터 세트의 하위 집합을 내보내야 하는 경우
- 코호트 연구를 위한 변이 데이터베이스 구축
- 교육 프로젝트 및 방법 개발
- 변이 데이터 작업에서 성능이 중요한 경우
빠른 시작
설치
권장 방법: Conda/Mamba
# M1 Mac을 사용하는 경우 다음 두 줄을 입력하세요
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64
# conda 환경 생성
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf
# Mamba는 conda보다 빠르고 안정적인 대안입니다
conda install -c conda-forge mamba
# TileDB-Py 및 TileDB-VCF 설치, 다른 유용한 라이브러리와 함께 정렬
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy
대안: Docker 이미지
docker pull tiledb/tiledbvcf-py # Python 인터페이스
docker pull tiledb/tiledbvcf-cli # 명령줄 인터페이스
기본 예제
데이터 세트 생성 및 채우기:
import tiledbvcf
# 새 데이터 세트 생성
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
cfg=tiledbvcf.ReadConfig(memory_budget=1024))
# VCF 파일 수집 (인덱스가 있는 단일 샘플 파일이어야 함)
# 요구 사항:
# - VCF는 단일 샘플이어야 함 (다중 샘플 불가)
# - 인덱스 파일 필요: .csi (bcftools) 또는 .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
변이 데이터 쿼리:
# 기존 데이터 세트를 읽기 모드로 열기
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
# 특정 영역 및 샘플 쿼리
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
# 두 개의 VCF 샘플 내보내기
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 필드는 원래 데이터 유형으로 보존
- 최적의 저장을 위한 자동 압축 및 청킹
스키마 구성:
# 특정 타일 범위를 가진 사용자 정의 스키마
config = tiledbvcf.ReadConfig(
memory_budget=2048, # MB
region_partition=(0, 3095677412), # 전체 게놈
sample_partition=(0, 10000) # 최대 10k 샘플
)
좌표계 및 영역
중요: TileDB-VCF는 VCF 표준에 따라 1-based 유전체 좌표를 사용합니다:
- 위치는 1-based입니다 (첫 번째 염기는 위치 1)
- 범위는 양쪽 끝을 포함합니다
- 영역 "chr1:1000-2000"은 위치 1000-2000(총 1001개 염기)을 포함합니다
영역 지정 형식:
# 단일 영역
regions = ["chr1:1000000-2000000"]
# 여러 영역
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# 전체 염색체
regions = ["chr1"]
# BED 스타일(0-based, 반개방형, 내부적으로 변환됨)
regions = ["chr1:999999-2000000"] # 1-based chr1:1000000-2000000과 동일
메모리 관리
성능 고려 사항:
- 사용 가능한 시스템 메모리를 기반으로 적절한 메모리 예산 설정
- 매우 큰 결과 집합의 경우 스트리밍 쿼리 사용
- 메모리 고갈을 방지하기 위해 대규모 수집 분할
- 반복적인 영역 액세스를 위해 타일 캐시 구성
- 여러 파일에 대해 병렬 수집 사용
- 인접 영역을 결합하여 영역 쿼리 최적화
클라우드 스토리지 통합
TileDB-VCF는 클라우드 스토리지와 원활하게 작동합니다:
# S3 데이터 세트
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")
일반적인 문제점
- 수집 중 메모리 고갈: 대용량 VCF 파일의 경우 적절한 메모리 예산과 배치 처리를 사용하세요.
- 비효율적인 영역 쿼리: 여러 개별 쿼리 대신 인접 영역을 결합하세요.
- 샘플 이름 누락: VCF 헤더의 샘플 이름이 쿼리 샘플 지정과 일치하는지 확인하세요.
- 좌표계 혼동: TileDB-VCF는 VCF 표준과 같이 1-based 좌표를 사용한다는 점을 기억하세요.
- 대규모 결과 집합: 수백만 개의 변이를 반환하는 쿼리의 경우 스트리밍 또는 페이지 매김을 사용하세요.
- 클라우드 권한: 클라우드 스토리지 액세스를 위한 적절한 인증을 확인하세요.
- 동시 액세스: 동일한 데이터 세트에 대한 여러 작성자는 손상을 일으킬 수 있습니다. 적절한 잠금을 사용하세요.
CLI 사용법
TileDB-VCF는 다음 하위 명령어와 함께 명령줄 인터페이스를 제공합니다:
사용 가능한 하위 명령어:
create- 빈 TileDB-VCF 데이터 세트 생성store- TileDB-VCF 데이터 세트에 샘플 수집export- TileDB-VCF 데이터 세트에서 데이터 내보내기list- TileDB-VCF 데이터 세트에 있는 모든 샘플 이름 나열stat- TileDB-VCF 데이터 세트에 대한 상위 수준 통계 출력utils- TileDB-VCF 데이터 세트 작업을 위한 유틸리티version- 버전 정보를 출력하고 종료
# 빈 데이터 세트 생성
tiledbvcf create --uri my_dataset
# 샘플 수집 (인덱스가 있는 단일 샘플 VCF 필요)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
# 데이터 내보내기
tiledbvcf export --uri my_dataset \
--regions "chr1:1000000-2000000" \
--sample-names "sample1,sample2"
# 모든 샘플 나열
tiledbvcf list --uri my_dataset
# 데이터 세트 통계 표시
tiledbvcf stat --uri my_dataset
고급 기능
대립유전자 빈도 분석
# 대립유전자 빈도 계산
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
샘플 품질 관리
# 샘플 QC 수행
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
사용자 정의 구성
# 고급 구성
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
리소스
도움말
오픈 소스 TileDB-VCF 리소스
오픈 소스 문서:
- TileDB Academy: https://cloud.tiledb.com/academy/
- 집단 유전체학 가이드: https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub: https://github.com/TileDB-Inc/TileDB-VCF
TileDB-Cloud 리소스
대규모/프로덕션 유전체학용:
- TileDB-Cloud 플랫폼: https://cloud.tiledb.com
- TileDB Academy (모든 문서): https://cloud.tiledb.com/academy/
시작하기:
- 무료 계정 가입: https://cloud.tiledb.com
- 문의: [email protected] (엔터프라이즈 요구 사항)
TileDB-Cloud로 확장
유전체학 워크로드가 단일 노드 처리를 초과하는 경우, TileDB-Cloud는 프로덕션 유전체학 파이프라인을 위한 엔터프라이즈급 기능을 제공합니다.
참고: 이 섹션은 사용 가능한 문서를 기반으로 한 TileDB-Cloud 기능을 다룹니다. 완전한 API 세부 정보 및 현재 기능에 대해서는 공식 TileDB-Cloud 문서 및 API 참조를 확인하세요.
TileDB-Cloud 설정
1. 계정 생성 및 API 토큰 받기
# https://cloud.tiledb.com에서 가입
# 계정 설정에서 API 토큰 생성
2. TileDB-Cloud Python 클라이언트 설치
# 기본 설치
uv pip install tiledb-cloud
# 유전체학 특화 기능 포함
uv pip install tiledb-cloud[life-sciences]
3. 인증 구성
# API 토큰으로 환경 변수 설정
export TILEDB_REST_TOKEN="your_api_token"
import tiledb.cloud
# 인증은 TILEDB_REST_TOKEN을 통해 자동으로 수행됩니다.
# 코드에 명시적인 로그인이 필요하지 않습니다.
오픈 소스에서 TileDB-Cloud로 마이그레이션
대규모 수집
# TileDB-Cloud: 분산 VCF 수집
import tiledb.cloud.vcf
# 특수 VCF 수집 모듈 사용
# 참고: 정확한 API는 TileDB-Cloud 문서가 필요합니다.
# 이는 사용 가능한 기능 구조를 나타냅니다.
tiledb.cloud.vcf.ingestion.ingest_vcf_dataset(
source="s3://my-bucket/vcf-files/",
output="tiledb://my-namespace/large-dataset",
namespace="my-namespace",
acn="my-s3-credentials",
ingest_resources={"cpu": "16", "memory": "64Gi"}
)
분산 쿼리 처리
# TileDB-Cloud: 분산 스토리지에서 VCF 쿼리
import tiledb.cloud.vcf
import tiledbvcf
# 데이터 세트 URI 정의
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# 데이터 세트에서 모든 샘플 가져오기
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# 쿼리할 속성 및 범위 정의
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# 분산 방식으로 실행되는 읽기 수행
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # 비용을 청구할 계정 지정
)
df.to_pandas()
엔터프라이즈 기능
데이터 공유 및 협업
# TileDB-Cloud는 네임스페이스 기반 권한 및 그룹 관리를 통해
# 엔터프라이즈 데이터 공유 기능을 제공합니다.
# TileDB-Cloud URI를 통해 공유 데이터 세트 액세스
dataset_uri = "tiledb://shared-namespace/population-study"
# 공유 노트북 및 컴퓨팅 리소스를 통해 협업
# (특정 API는 TileDB-Cloud 문서 필요)
비용 최적화
- 서버리스 컴퓨팅: 실제 컴퓨팅 시간에 대해서만 비용 지불
- 자동 확장: 워크로드에 따라 자동 확장/축소
- 스팟 인스턴스: 배치 작업에 비용 최적화된 컴퓨팅 사용
- 데이터 계층화: 자동 핫/콜드 스토리지 관리
보안 및 규정 준수
- 종단 간 암호화: 전송 중 및 저장 중 데이터 암호화
- 액세스 제어: 세분화된 권한 및 감사 로그
- HIPAA/SOC2 준수: 엔터프라이즈 보안 표준
- VPC 지원: 프라이빗 클라우드 환경에 배포
마이그레이션 시점 체크리스트
✅ 다음과 같은 경우 TileDB-Cloud로 마이그레이션:
- 데이터 세트 > 1000개 샘플
- 100GB 이상의 VCF 데이터를 처리해야 하는 경우
- 분산 컴퓨팅이 필요한 경우
- 여러 팀 구성원이 액세스해야 하는 경우
- 엔터프라이즈 보안/규정 준수가 필요한 경우
- 비용 최적화된 서버리스 컴퓨팅을 원하는 경우
- 24/7 프로덕션 가동 시간이 필요한 경우
TileDB-Cloud 시작하기
- 무료 시작: TileDB-Cloud는 평가를 위한 무료 티어를 제공합니다.
- 마이그레이션 지원: TileDB 팀이 마이그레이션 지원을 제공합니다.
- 교육: 유전체학 관련 튜토리얼에 액세스할 수 있습니다.
…
[번역을 위해 잘림]