Cloud Life Sciences는 지원 중단되었으며 2025년 7월 8일 이후 Google Cloud에서 더 이상 사용할 수 없습니다. 이제 Cloud Life Sciences 사용 사례가 Batch에서 지원됩니다. 워크로드를 마이그레이션하는 방법은 Batch로 마이그레이션을 참조하세요.

GATK 권장사항 실행

이 페이지에서는 게놈 애널리틱스 툴킷(GATK) 권장사항을 사용하여 Google Cloud에서 보조 게놈 분석 파이프라인을 실행하는 방법을 설명합니다. GATK 권장사항은 Broad Institute에서 제공됩니다.

이 가이드에서 사용되는 워크플로는 전체 게놈 시퀀싱(WGS) 데이터에서 변이 발견을 위한 GATK 권장사항의 구현입니다. 이 워크플로는 Broad Institute의 Workflow Definition Language(WDL)로 작성되었으며 Cromwell WDL 실행기에서 실행됩니다.

목표

이 튜토리얼을 완료하고 나면 다음의 작업을 수행할 수 있게 됩니다.

인간 참조 게놈의 build 38에서 가져온 데이터로 GATK 권장사항에 따라 파이프라인 실행
자체 데이터를 사용하여 GATK 권장사항에 따라 파이프라인 실행

비용

이 문서에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

Compute Engine
Cloud Storage

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요. Google Cloud를 처음 사용하는 사용자는 무료 체험판을 사용할 수 있습니다.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

Enable the APIs

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Update and install gcloud components:

gcloud components update
gcloud components install beta

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

Enable the APIs

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Update and install gcloud components:

gcloud components update
gcloud components install beta

git을 설치하여 필요한 파일을 다운로드합니다.
git 다운로드
기본적으로 Compute Engine에는 부적절한 사용을 방지하기 위해 리소스 할당량이 마련되어 있습니다. 할당량을 늘리면 더 많은 가상 머신을 동시에 실행할 수 있으므로 처리량이 증가하고 처리 시간이 단축됩니다.
이 튜토리얼에서 최상의 결과를 얻으려면 프로젝트의 기본값보다 높은 추가 할당량을 요청해야 합니다. 할당량 증가에 대한 권장사항은 다음 목록에 나와 있고, 튜토리얼을 실행하는 데 필요한 최소 할당량도 나와 있습니다. us-central1 리전에서 할당량을 요청합니다.
- CPU: 101(최소 17)
- 표준 영구 디스크(GB): 10,500(최소 320)
- 사용 중인 IP 주소: 51개(최소 2개)
다른 할당량 요청 필드를 비워두면 현재 할당량을 유지할 수 있습니다.

참고: If your project was created using the 무료 체험판을 사용하여 프로젝트를 만든 경우 더 많은 할당량을 요청해야 Google Cloud에서 GATK 권장사항을 실행할 수 있습니다.

Cloud Storage 버킷 만들기

gcloud storage buckets create 명령어를 사용하여 Cloud Storage 버킷을 만듭니다. Cromwell 엔진의 요구사항으로 인해 버킷 이름에 밑줄(_) 문자를 사용해서는 안 되며 사용하면 오류가 발생합니다.

gcloud storage buckets create gs://BUCKET

파이프라인은 결과, 로그, 중간 파일을 이 버킷에 출력합니다.

예제 파일 다운로드

다음 명령어를 실행하여 WDL 및 도우미 스크립트를 다운로드합니다.

git clone https://github.com/broadinstitute/wdl-runner.git
git clone https://github.com/gatk-workflows/broad-prod-wgs-germline-snps-indels.git

gatk-workflows/broad-prod-wgs-germline-snps-indels 저장소에는 파이프라인을 실행하는 데 필요한 다음 파일이 포함되어 있습니다.

*.wdl: 워크플로 정의
*.inputs.json: BAM 파일 및 참조 게놈에 대한 경로를 포함한 입력 매개변수
*.options.json: 워크플로 런타임 옵션

broadinstitute/wdl-runner/wdl_runner/ 저장소에서 WDL 파이프라인을 실행하는 데 사용되는 Cromwell 파이프라인 정의 파일을 확인할 수 있습니다.

샘플 데이터를 사용하여 파이프라인 실행

이 섹션에서는 인간 참조 게놈의 build 38을 사용한 WGS 데이터로 파이프라인을 실행하는 방법을 보여줍니다. 입력 파일은 정렬되지 않은 BAM 파일입니다.

파이프라인을 실행하려면 다음 단계를 완료하세요.

Broad 파이프라인 파일을 포함하는 폴더를 가리키는 환경 변수 GATK_GOOGLE_DIR을 만듭니다.
```
export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
```
Cloud Storage 버킷과 워크플로의 output 폴더를 가리키는 GATK_OUTPUT_DIR 환경 변수, 중간 work 파일, logging을 만듭니다.
```
export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
```
다운로드한 저장소의 /wdl_runner 폴더로 디렉터리를 변경합니다. 이 디렉터리에는 Google Cloud에서 WDL 기반 파이프라인을 실행하기 위한 파이프라인 정의 파일이 포함됩니다.
```
cd wdl-runner/wdl_runner/
```

파이프라인을 실행합니다.

기본 VPC 또는 커스텀 VPC를 사용하는지에 따라 다음 옵션 중 하나를 선택합니다.

기본 VPC

gcloud beta lifesciences pipelines run \
--pipeline-file wdl_pipeline.yaml \
--location us-central1 \
--regions us-central1 \
--inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
--env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
OUTPUTS=${GATK_OUTPUT_DIR}/output \
--logging ${GATK_OUTPUT_DIR}/logging/

커스텀 VPC

환경 변수 NETWORK 및 SUBNETWORK를 만들어 VPC 네트워크 및 서브네트워크의 이름을 지정합니다.
```
export NETWORK=VPC_NETWORK
export SUBNETWORK=VPC_SUBNET
```
broad-prod-wgs-germline-snps-indels 디렉터리에 있는 PairedEndSingleSampleWf.options.json 파일을 수정하고 서브넷 리전 내의 영역만 포함하도록 영역을 수정합니다. 예를 들어 us-central1 서브넷을 사용하는 경우 zones 필드는 "zones": "us-central1-a us-central1-b us-central1-c us-central1-f"와 같이 표시됩니다.

gcloud beta lifesciences pipelines run \
--pipeline-file wdl_pipeline.yaml \
--location us-central1 \
--regions us-central1 \
--network ${NETWORK} \
--subnetwork ${SUBNETWORK} \
--inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
--env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
OUTPUTS=${GATK_OUTPUT_DIR}/output,\
NETWORK=${NETWORK},\
SUBNETWORK=${SUBNETWORK} \
--logging ${GATK_OUTPUT_DIR}/logging/

이 명령어는 Running [operations/OPERATION_ID] 형식의 작업 ID를 반환합니다. gcloud beta lifesciences describe 명령어를 사용하고 다음 명령어를 실행해서 파이프라인 상태를 추적할 수 있습니다(--location 플래그 값이 이전 단계에 지정된 위치와 일치하는지 확인).
```
gcloud beta lifesciences operations describe OPERATION_ID \
    --location=us-central1 \
    --format='yaml(done, error, metadata.events)'
```
operations describe 명령어는 파이프라인이 완료될 때 done: true를 반환합니다.

wdl_runner와 함께 포함된 스크립트를 실행하여 작업 실행 여부, 완료 여부 또는 오류 반환 여부를 300초마다 확인할 수 있습니다.
```
../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
```
파이프라인이 끝나면 다음 명령어를 실행하여 Cloud Storage 버킷의 출력을 나열합니다.
```
gcloud storage ls gs://BUCKET/FOLDER/output/
```

파이프라인에서 생성된 중간 파일을 보고 유지할 파일을 선택하거나 제거하여 Cloud Storage와 관련된 비용을 줄일 수 있습니다. 파일을 삭제하려면 Cloud Storage 버킷에서 중간 파일 삭제를 참조하세요.

로컬 데이터로 GATK 권장사항 파이프라인 실행

로컬 데이터로 파이프라인을 실행하기 전에 이 데이터를 Cloud Storage 버킷에 복사해야 합니다.

입력 파일 복사

파이프라인은 Cloud Storage에 저장된 정렬되지 않은 BAM 파일과 함께 실행될 수 있습니다. 정렬된 BAM 또는 FASTQ와 같이 파일 형식이 다를 경우, 변환한 후에만 Cloud Storage에 업로드할 수 있습니다. 이 파일을 로컬에서 변환하거나 Pipelines API를 사용하여 클라우드에서 변환할 수 있습니다.

다음 예는 로컬 파일 시스템에서 Cloud Storage 버킷으로 단일 파일을 복사하는 방법을 보여줍니다.

gcloud storage cp FILE gs://BUCKET/FOLDER

파일을 Cloud Storage 버킷으로 복사하는 방법에 대한 예를 더 확인하려면 Cloud Storage로 데이터 복사의 섹션을 참조하세요.

gcloud CLI는 체크섬을 자동으로 확인하므로, 전송이 성공하면 GATK 권장사항에 따라 사용할 수 있도록 데이터가 호환됩니다.

데이터에서 파이프라인 실행

정렬되지 않은 자체 BAM 파일에서 GATK 권장사항을 실행하려면 PairedEndSingleSampleWf.hg38.inputs.json을 복사한 후 Cloud Storage 버킷의 파일을 가리키도록 경로를 업데이트합니다. 그런 후 업데이트된 PairedEndSingleSampleWf.hg38.inputs.json 파일을 사용하여 샘플 데이터를 사용하여 파이프라인 실행의 단계를 수행합니다.

데이터가 정렬되지 않은 BAM 파일로 구성되지 않고 참조 게놈, 엑솜 시퀀싱, 표적화된 패널, 체세포 데이터를 포함하는 경우 다른 워크플로를 사용해야 합니다. 자세한 내용은 GATK Support Forum 및 Broad Institute GitHub repository를 참조하세요.

문제 해결

파이프라인은 특정 지역 및 영역의 Compute Engine 인스턴스를 사용하도록 구성됩니다. gcloud CLI를 실행하면 Google Cloud 프로젝트가 생성된 위치에 따라 기본 리전 및 영역이 자동으로 사용됩니다. 파이프라인을 실행할 때 이로 인해 다음 오류 메시지가 표시될 수 있습니다.

"ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"

이 문제를 해결하려면 다음 명령어를 실행하여 기본 리전 및 영역을 삭제한 후 파이프라인을 다시 실행합니다.
```
gcloud config unset compute/zone
gcloud config unset compute/region
```
Google Cloud 프로젝트의 기본 리전 및 영역을 설정하는 방법에 대한 자세한 내용은 기본 영역 또는 리전 변경을 참조하세요.
파이프라인을 실행할 때 문제가 발생하면 Cloud Life Sciences API 문제 해결을 참조하세요.
GATK는 입력 파일 형식 기준이 엄격합니다. 문제를 방지하려면 파일이 ValidateSamFile을 통과하는지 유효성을 검사할 수 있습니다.
GATK 실행에 실패하면 다음 명령어를 실행하여 로그를 확인할 수 있습니다.
```
gcloud storage ls gs://BUCKET/FOLDER/logging
```
권한 오류가 발생하면 서비스 계정에 입력 파일에 대한 읽기 권한이 있고 출력 버킷 경로에 대한 쓰기 권한이 있는지 확인합니다. 자신의 것이 아닌 Google Cloud 프로젝트에 출력 파일을 작성할 경우 버킷에 액세스할 수 있는 서비스 계정 권한을 부여해야 합니다.

삭제

Cloud Storage 버킷에서 중간 파일 삭제

파이프라인을 실행하면 중간 파일이 gs://BUCKET/FOLDER/work에 저장됩니다. Cloud Storage 요금을 줄이기 위해 워크플로가 완료된 후 파일을 삭제할 수 있습니다.

work 디렉터리에 사용된 공간을 확인하려면 다음 명령어를 실행합니다. 디렉터리에 있는 파일 크기로 인해 명령어를 실행하는 데 몇 분 정도 걸릴 수 있습니다.

gcloud storage du gs://BUCKET/FOLDER/work --readable-sizes --summarize

work 디렉터리에 있는 중간 파일을 삭제하려면 다음 명령어를 실행합니다.

gcloud storage rm gs://BUCKET/FOLDER/work/**

프로젝트 삭제

비용이 청구되지 않도록 하는 가장 쉬운 방법은 튜토리얼에서 사용한 프로젝트를 삭제하는 것입니다.

프로젝트를 삭제하는 방법은 다음과 같습니다.

Google Cloud 콘솔에서 프로젝트 페이지로 이동합니다.
프로젝트 페이지로 이동
프로젝트 목록에서 삭제할 프로젝트를 선택하고 프로젝트 삭제를 클릭합니다.
대화상자에서 프로젝트 ID를 입력한 다음 종료를 클릭하여 프로젝트를 삭제합니다.

다음 단계

Broad Institute GATK 사이트와 포럼에서는 보다 자세한 배경 정보, 문서뿐 아니라 GATK 도구와 WDL 지원을 제공합니다.