Cómo ejecutar DeepVariant

En esta página, se explica cómo ejecutar DeepVariant en Google Cloud Platform. DeepVariant es una canalización de análisis que utiliza una red neuronal profunda para llamar variantes genéticas a partir de datos de secuenciación de ADN de última generación.

Objetivos

Después de completar el instructivo, sabrás cómo realizar las actividades que se describen a continuación:

  • Ejecutar DeepVariant en GCP
  • Escribir archivos de configuración para casos prácticos diferentes de DeepVariant
  • Estimar los costos y los tiempos de respuesta para diferentes configuraciones de canalización de DeepVariant

Costos

En este instructivo se usan componentes facturables en GCP, que incluyen los que se indican a continuación:

  • Compute Engine

Usa la calculadora de precios para generar una estimación de los costos según el uso previsto. Los usuarios nuevos de Cloud Platform podrían ser aptos para una prueba gratuita.

Antes de comenzar

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Habilita las Cloud Genomics y Compute Engine API necesarias.

    Habilita las API

  5. Install and initialize the Cloud SDK.
  6. Update and install gcloud components:
    gcloud components update &&
    gcloud components install Alfa

Cómo ejecutar DeepVariant

Para ejecutar DeepVariant en GCP, debes ejecutar una secuencia de comandos que invoque la API de Cloud Genomics Pipelines.

  1. Copia el siguiente texto y guárdalo en un archivo llamado script.sh; sustituye las variables con los recursos relevantes de tu proyecto de GCP. La variable OUTPUT_BUCKET designa un depósito de Cloud Storage que conserva los archivos intermedios y de salida de la canalización. La variable STAGING_FOLDER_NAME es un nombre único para un directorio en el depósito. Puedes establecer las variables para cada ejecución de la canalización.

    #!/bin/bash
    set -euo pipefail
    # Set common settings.
    PROJECT_ID=PROJECT_ID
    OUTPUT_BUCKET=gs://OUTPUT_BUCKET
    STAGING_FOLDER_NAME=STAGING_FOLDER_NAME
    OUTPUT_FILE_NAME=output.vcf
    # Model for calling whole genome sequencing data.
    MODEL=gs://deepvariant/models/DeepVariant/0.7.2/DeepVariant-inception_v3-0.7.2+data-wgs_standard
    IMAGE_VERSION=0.7.2
    DOCKER_IMAGE=gcr.io/deepvariant-docker/deepvariant:"${IMAGE_VERSION}"
    COMMAND="/opt/deepvariant_runner/bin/gcp_deepvariant_runner \
      --project ${PROJECT_ID} \
      --zones us-west1-* \
      --docker_image ${DOCKER_IMAGE} \
      --outfile ${OUTPUT_BUCKET}/${OUTPUT_FILE_NAME} \
      --staging ${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME} \
      --model ${MODEL} \
      --bam gs://deepvariant/quickstart-testdata/NA12878_S1.chr20.10_10p1mb.bam \
      --ref gs://deepvariant/quickstart-testdata/ucsc.hg19.chr20.unittest.fasta.gz \
      --regions chr20:10,000,000-10,010,000 \
      --gcsfuse"
    # Run the pipeline.
    gcloud alpha genomics pipelines run \
        --project "${PROJECT_ID}" \
        --service-account-scopes="https://www.googleapis.com/auth/cloud-platform" \
        --logging "${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME}/runner_logs_$(date +%Y%m%d_%H%M%S).log" \
        --regions us-west1 \
        --docker-image gcr.io/deepvariant-docker/deepvariant_runner:"${IMAGE_VERSION}" \
        --command-line "${COMMAND}"
    
  2. Ejecuta el siguiente comando para hacer que script.sh sea ejecutable:

    chmod +x script.sh
    
  3. Ejecuta script.sh:

    ./script.sh
    
  4. El comando muestra un ID de operación en el formato Running [operations/OPERATION_ID].. Puedes usar el ID de operación a fin de hacer un seguimiento del estado de la canalización; para ello, ejecuta el siguiente comando:

    gcloud alpha genomics operations wait OPERATION_ID
    

    Puedes obtener más detalles sobre la operación en la ruta brindada por la marca --logging. En este instructivo, la ruta es "${OUTPUT_BUCKET}"/runner_logs.

  5. Una vez finalizada la canalización, genera un archivo VCF, output.vcf, en tu depósito de Cloud Storage. Ejecuta el siguiente comando para enumerar los archivos en tu depósito y verifica que el archivo output.vcf esté en la lista.

    gsutil ls gs://BUCKET/
    

Configuraciones de la canalización

Puedes ejecutar DeepVariant en GCP con diferentes configuraciones, como las que se detallan a continuación:

A continuación, se detallan algunas de las configuraciones más comunes. Tras haber probado las configuraciones, consulta opciones adicionales para obtener información sobre cómo establecer la configuración avanzada.

Configuración de costo optimizado

La siguiente configuración está optimizada para ejecutar DeepVariant con un costo bajo. El total correspondiente al entorno de ejecución y al costo varía según la cantidad de instancias que se interrumpen, pero puedes prever que, para una muestra de 30 veces del genoma completo, la canalización se completará en 1 o 2 horas, y el costo será de entre $3.00 y $4.00.

La configuración utiliza CPU adjuntas a VM interrumpibles, que son hasta un 80% más económicas que las VM normales. Sin embargo, Compute Engine podría terminar (interrumpir) estas instancias si requiere acceso a esos recursos para otras tareas. Además, las VM interrumpibles no están contempladas en el Acuerdo de Nivel de Servicio (ANS), por lo que, si necesitas garantías sobre el tiempo de respuesta, no utilices la marca --preemptible.

Consulta las Recomendaciones de Compute Engine para obtener información sobre cómo usar las VM interrumpibles de forma eficiente.

El ejecutor de DeepVariant contiene una lógica incorporada que reintenta automáticamente los trabajos interrumpidos. Además, puedes especificar la cantidad máxima de reintentos mediante la marca --max_preemptible_tries.

La configuración tiene las siguientes propiedades:

  • Utiliza VM de 32x16 núcleos para el paso make_examples
  • Utiliza VM de 32x32 núcleos para el paso call_variants

Para poder ejecutar la canalización con esta configuración, debes solicitar el siguiente aumento en la cuota de Compute Engine:

  • CPU: 1025
  • Disco persistente: 6.4 TB
  • Direcciones IP en uso: 33
#!/bin/bash
set -euo pipefail
# Set common settings.
PROJECT_ID=PROJECT_ID
OUTPUT_BUCKET=gs://OUTPUT_BUCKET
STAGING_FOLDER_NAME=STAGING_FOLDER_NAME
OUTPUT_FILE_NAME=output.vcf
# Model for calling whole genome sequencing data.
MODEL=gs://deepvariant/models/DeepVariant/0.7.2/DeepVariant-inception_v3-0.7.2+data-wgs_standard
IMAGE_VERSION=0.7.2
DOCKER_IMAGE=gcr.io/deepvariant-docker/deepvariant:"${IMAGE_VERSION}"
COMMAND="/opt/deepvariant_runner/bin/gcp_deepvariant_runner \
  --project ${PROJECT_ID} \
  --zones us-west1-* \
  --docker_image ${DOCKER_IMAGE} \
  --outfile ${OUTPUT_BUCKET}/${OUTPUT_FILE_NAME} \
  --staging ${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME} \
  --model ${MODEL} \
  --bam gs://deepvariant/performance-testdata/HG002_NIST_150bp_downsampled_30x.bam \
  --ref gs://deepvariant/performance-testdata/hs37d5.fa.gz \
  --shards 512 \
  --make_examples_workers 32 \
  --make_examples_cores_per_worker 16 \
  --make_examples_ram_per_worker_gb 60 \
  --make_examples_disk_per_worker_gb 200 \
  --call_variants_workers 32 \
  --call_variants_cores_per_worker 32 \
  --call_variants_ram_per_worker_gb 60 \
  --call_variants_disk_per_worker_gb 50 \
  --preemptible \
  --max_preemptible_tries 5 \
  --gcsfuse"
# Run the pipeline.
gcloud alpha genomics pipelines run \
    --project "${PROJECT_ID}" \
    --service-account-scopes="https://www.googleapis.com/auth/cloud-platform" \
    --logging "${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME}/runner_logs_$(date +%Y%m%d_%H%M%S).log" \
    --regions us-west1 \
    --docker-image gcr.io/deepvariant-docker/deepvariant_runner:"${IMAGE_VERSION}" \
    --command-line "${COMMAND}"

Configuración de llamada a las regiones del exoma

La siguiente configuración llama solo a las regiones del exoma. Utiliza CPU adjuntas a VM interrumpibles, que son hasta un 80% más económicas que las VM normales. Sin embargo, Compute Engine podría terminar (interrumpir) estas instancias si requiere acceso a esos recursos para otras tareas. Además, las VM interrumpibles no están contempladas en el Acuerdo de Nivel de Servicio (ANS), por lo que, si necesitas garantías sobre el tiempo de respuesta, no utilices la marca --preemptible.

El ejecutor de DeepVariant contiene una lógica incorporada que reintenta automáticamente los trabajos interrumpidos. Además, puedes especificar la cantidad máxima de reintentos mediante la marca --max_preemptible_tries.

El total correspondiente al entorno de ejecución y al costo varía según la cantidad de instancias que se interrumpen; pero puedes prever que la canalización demorará unos 25 minutos y costará alrededor de $0.20. Consulta las Recomendaciones de Compute Engine para obtener información sobre cómo usar las VM interrumpibles de forma eficiente.

La configuración tiene las siguientes propiedades:

  • Utiliza VM de 4x16 núcleos para el paso make_examples
  • Utiliza VM de 1x32 núcleos para el paso call_variants

    #!/bin/bash
    set -euo pipefail
    # Set common settings.
    PROJECT_ID=PROJECT_ID
    OUTPUT_BUCKET=gs://OUTPUT_BUCKET
    STAGING_FOLDER_NAME=STAGING_FOLDER_NAME
    OUTPUT_FILE_NAME=output.vcf
    # Model for calling exome sequencing data.
    MODEL=gs://deepvariant/models/DeepVariant/0.7.2/DeepVariant-inception_v3-0.7.2+data-wes_standard
    IMAGE_VERSION=0.7.2
    DOCKER_IMAGE=gcr.io/deepvariant-docker/deepvariant:"${IMAGE_VERSION}"
    COMMAND="/opt/deepvariant_runner/bin/gcp_deepvariant_runner \
      --project ${PROJECT_ID} \
      --zones us-west1-* \
      --docker_image ${DOCKER_IMAGE} \
      --outfile ${OUTPUT_BUCKET}/${OUTPUT_FILE_NAME} \
      --staging ${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME} \
      --model ${MODEL} \
      --bam gs://deepvariant/exome-case-study-testdata/151002_7001448_0359_AC7F6GANXX_Sample_HG002-EEogPU_v02-KIT-Av5_AGATGTAC_L008.posiSrt.markDup.bam \
      --bai gs://deepvariant/exome-case-study-testdata/151002_7001448_0359_AC7F6GANXX_Sample_HG002-EEogPU_v02-KIT-Av5_AGATGTAC_L008.posiSrt.markDup.bai \
      --ref gs://deepvariant/exome-case-study-testdata/hs37d5.fa.gz \
      --regions gs://deepvariant/exome-case-study-testdata/refseq.coding_exons.b37.extended50.bed \
      --shards 64 \
      --make_examples_workers 4 \
      --make_examples_cores_per_worker 16 \
      --make_examples_ram_per_worker_gb 60 \
      --make_examples_disk_per_worker_gb 100 \
      --call_variants_workers 1 \
      --call_variants_cores_per_worker 32 \
      --call_variants_ram_per_worker_gb 60 \
      --call_variants_disk_per_worker_gb 50 \
      --preemptible \
      --max_preemptible_tries 5 \
      --gcsfuse"
    # Run the pipeline.
    gcloud alpha genomics pipelines run \
        --project "${PROJECT_ID}" \
        --service-account-scopes="https://www.googleapis.com/auth/cloud-platform" \
        --logging "${OUTPUT_BUCKET}/${STAGING_FOLDER_NAME}/runner_logs_$(date +%Y%m%d_%H%M%S).log" \
        --regions us-west1 \
        --docker-image gcr.io/deepvariant-docker/deepvariant_runner:"${IMAGE_VERSION}" \
        --command-line "${COMMAND}"
    

Si necesitas que la canalización se ejecute más rápido o necesitas garantizar su tiempo de respuesta, puedes realizar los siguientes cambios en la configuración:

  • Quita la marca --preemptible
  • Duplica la cantidad de fragmentos a 256; para ello, duplica los trabajadores en el paso make_examples, de la siguiente manera:

    ...
    --make_examples_workers 8
    --make_examples_cores_per_worker 32
    ...
    

Configuración genómica de VCF (gVCF)

DeepVariant es compatible con gVCF como formato de resultados. Para generar un resultado en gVCF, utiliza cualquiera de las configuraciones anteriores y agrega la marca --gvcf_outfile. La marca --gvcf_outfile especifica la ruta de destino para el archivo gVCF.

Si ejecutas cualquiera de las configuraciones anteriores y generas datos gVCF, el tiempo de ejecución de la canalización aumenta aproximadamente 2 horas. Además, se requiere un disco más grande para el paso postprocess_variants. Para obtener mejores resultados cuando generes un resultado gVCF, agrega la marca --postprocess_variants_disk_gb 200 en la opción ./opt/deepvariant_runner/bin/gcp_deepvariant_runner.

También puedes utilizar la marca --gvcf_gq_binsize a fin de controlar el tamaño del contenedor utilizado para cuantificar las calidades del genotipo gVCF. Los tamaños de contenedores más grandes reducen el número de registros de gVCF, pero generan una pérdida de calidad en el nivel de detalle.

Opciones de configuración adicionales

Además de las configuraciones básicas anteriores, puedes especificar las siguientes para que se adapten a tu caso práctico.

Cuando especifiques cualquiera de las siguientes marcas, agrégalas en la opción ./opt/deepvariant_runner/bin/gcp_deepvariant_runner.

Opción de configuración Descripción Ejemplo de caso práctico
job_name_prefix Un prefijo que se agrega a los nombres de los trabajos. Puede ser útil a fin de distinguir ejecuciones de canalizaciones, por ejemplo, para la facturación. Cuando especificas --job_name_prefix gpu_, aparecerá un informe de facturación gpu_make_examples, gpu_call_variants y gpu_postprocess_variants como las tres etapas de la canalización.
jobs_to_run Se utiliza para ejecutar solo una parte de la canalización. Puede ser útil si una parte de la canalización tiene un error por algún motivo, por ejemplo, si especificaste rutas de acceso de archivos incorrectas. Cuando utilices esta marca, todas las configuraciones (como la ubicación de etapas de pruebas y la cantidad de fragmentaciones y trabajadores) debe ser igual a la ejecución original para reutilizar los resultados intermedios existentes. Si la canalización arrojó un error en el paso call_variants, puedes volver a ejecutarla. Para ello, especifica --jobs_to_run call_variants postprocess_variants, lo que omitirá el paso make_examples y volverá a utilizar los resultados existentes.
  • bai
  • ref_fai
  • ref_gzi
Los archivos BAM deben tener un .bam.bai presente en la misma ubicación que el archivo BAM. Si el archivo BAM tiene un índice de referencia y un índice gzip, los archivos .fai y .gzi, respectivamente, también deben estar presentes. Un archivo .gzi será obligatorio solo si tu referencia está comprimida. Se puede utilizar si los archivos del índice no están en la misma ubicación que los archivos sin procesar o si los archivos del índice no tienen las extensiones comunes.

Limpieza

Para evitar que se generen cargos en tu cuenta de GCP por los recursos que usas en esta guía de inicio rápido, haz lo siguiente:

Una vez que hayas terminado el instructivo Cómo ejecutar DeepVariant, puedes limpiar los recursos que creaste en GCP a fin de que no se facturen en el futuro. En las siguientes secciones se describe cómo borrar o desactivar estos recursos.

Cómo borrar el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que utilizaste para el instructivo.

Para borrar el proyecto, haz lo siguiente:

  1. En GCP Console, ve a la página Proyectos.

    Ir a la página Proyectos

  2. En la lista de proyectos, selecciona el proyecto que quieres borrar y haz clic en Borrar proyecto. Después de seleccionar la casilla de verificación junto al nombre del proyecto, haz clic en Borrar proyecto
  3. En el cuadro de diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...