Cómo ejecutar una canalización de las Recomendaciones de GATK

En esta página, se explica cómo ejecutar una canalización en Google Cloud Platform con la API de Cloud Genomics Pipelines y Recomendaciones de GATK del Broad Institute.

El flujo de trabajo que se utiliza en este instructivo es una implementación de las Recomendaciones de GATK para el descubrimiento de variantes en los datos de la secuenciación del genoma completo (WGS por sus siglas en inglés). El flujo de trabajo está escrito en el lenguaje Workflow Definition Language (WDL) del Broad Institute y se ejecuta en el ejecutor de WDL Cromwell.

Objetivos

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

  • Ejecutar una canalización según las Recomendaciones de GATK con los datos de la versión 38 del genoma humano de referencia.
  • Ejecutar una canalización según las Recomendaciones de GATK con tus propios datos.

Costos

En este instructivo se usan componentes facturables de Google Cloud Platform, como los que se indican a continuación:

  • Compute Engine
  • Cloud Storage

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. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

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

    Descubre cómo puedes habilitar la facturación

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

    Habilita las API

  5. Realiza la instalación y la inicialización del SDK de Cloud.
  6. Actualiza y, luego, instala los componentes de gcloud:
    gcloud components update &&
    gcloud components install Alfa
  7. Instala Git para descargar los archivos necesarios.

    Descargar Git

  8. Con la configuración predeterminada, Compute Engine tiene cuotas de recursos para evitar el uso involuntario. Mediante el aumento de las cuotas, puedes iniciar más máquinas virtuales de forma simultánea, lo que aumenta la capacidad de procesamiento y reduce el tiempo de respuesta.

    Para obtener los mejores resultados en este instructivo, debes solicitar una cuota adicional superior a la predeterminada de tu proyecto. En la siguiente lista se proporcionan recomendaciones para los aumentos de cuota, así como las cuotas mínimas necesarias para ejecutar el instructivo. Realiza tus solicitudes de cuota en la región us-central1:

    • CPU: 101 (17 como mínimo)
    • Estándar de disco persistente (GB): 10,500 (320 como mínimo)
    • Direcciones IP en uso: 51 (2 como mínimo)

    Puedes dejar vacíos otros campos de solicitud de cuota para mantener las cuotas actuales.

Crea un depósito de Cloud Storage

Crea un depósito de Cloud Storage mediante el comando de gsutil mb. Debido a un requisito del motor de Cromwell, no debes utilizar caracteres de guiones bajos (_) en el nombre del depósito o se producirá un error.

gsutil mb gs://BUCKET

La canalización producirá resultados, registros y archivos intermedios en este depósito.

Descarga los archivos de ejemplo

Descarga la secuencia de comandos de WDL y auxiliar:

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

El repositorio gatk-workflows/broad-prod-wgs-germline-snps-indels contiene los siguientes archivos, necesarios para ejecutar la canalización:

  • *.wdl: Definición del flujo de trabajo
  • *.inputs.json: Parámetros de entrada, incluidas las rutas de acceso a los archivos BAM y el genoma de referencia
  • *.options.json: Las opciones de tiempo de ejecución del flujo de trabajo

Puedes encontrar el archivo de definición de la canalización de Cromwell que se usa para ejecutar canalizaciones en WDL en el repositorio openwdl/wdl/runners/cromwell_on_google/.

Cómo ejecutar la canalización con los datos de muestra

La canalización se ejecuta con datos de WGS y la versión 38 del genoma humano de referencia. Los archivos de entrada son archivos BAM sin alinear.

Para ejecutar la canalización, haz lo siguiente:

  1. Crea la variable de entorno GATK_GOOGLE_DIR, que dirige a la carpeta que contiene los archivos de la canalización de Broad:

    export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
    
  2. En el directorio broad-prod-wgs-germline-snps-indels, edita el archivo PairedEndSingleSampleWf.gatk4.0.options.json a fin de reemplazar la etiqueta de Docker 4.0.0.0 con latest para que se use la última versión de GATK, como se muestra a continuación:

    {
      "read_from_cache":false,
      "default_runtime_attributes": {
        "zones": "us-central1-a us-central1-b us-east1-d us-central1-c us-central1-f us-east1-c",
        "docker": "broadinstitute/gatk:latest"
      }
    }
    
  3. Crea la variable de entorno GATK_OUTPUT_DIR que dirige al depósito de Cloud Storage y a la carpeta para el output del flujo de trabajo, los archivos intermedios de workspace y logging:

    export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
    
  4. Cambia el directorio a la carpeta /cromwell_on_google/wdl_runner en el repositorio que descargaste. Este directorio contiene el archivo de definición de la canalización para ejecutar canalizaciones basadas en WDL en GCP:

    cd wdl/runners/cromwell_on_google/wdl_runner/
    
  5. Ejecuta la canalización:

    gcloud alpha genomics pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --regions us-central1 \
      --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.gatk4.0.wdl,\
    WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
    WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.gatk4.0.options.json \
      --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
    OUTPUTS=${GATK_OUTPUT_DIR}/output \
      --logging ${GATK_OUTPUT_DIR}/logging/
    
  6. 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 describe OPERATION_ID \
        --format='yaml(done, error, metadata.events)'
    
  7. El comando operations describe muestra done: true cuando la canalización finaliza.

    Puedes ejecutar una secuencia de comandos incluida con el wdl_runner para comprobar cada 300 segundos si el trabajo se está ejecutando, ha terminado o mostró un error:

    ./monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID 300
    
  8. Una vez que tu canalización finalice, ejecuta el siguiente comando para enumerar los resultados enviados a tu depósito de Cloud Storage:

    gsutil ls gs://BUCKET/FOLDER/outputs/
    

Puedes ver los archivos intermedios creados por la canalización y elegir cuáles quieres conservar, o bien quitarlos para reducir los costos asociados con Cloud Storage. Si quieres quitar los archivos, consulta Cómo borrar archivos intermedios en tu depósito de Cloud Storage.

Cómo ejecutar la canalización de las Recomendaciones de GATK en tus datos

Antes de ejecutar la canalización en tus datos locales, tienes que copiar los datos en un depósito de Cloud Storage.

Cómo copia los archivos de entrada

La canalización puede ejecutarse con los archivos BAM sin alinear almacenados en Cloud Storage. Si tus archivos están en otro formato, como BAM alineado o FASTQ, debes convertirlos para que puedan subirse a Cloud Storage. Puedes convertirlos de manera local o usar la API de Pipelines para convertirlos en la nube.

El ejemplo siguiente muestra cómo copiar un archivo único de un sistema de archivos local a un depósito de Cloud Storage:

gsutil -m -o 'GSUtil:parallel_composite_upload_threshold=150M' cp FILE \
    gs://BUCKET/FOLDER

Para ver más ejemplos de cómo copiar archivos a un depósito de Cloud Storage, consulta la sección sobre Cómo copiar datos a Cloud Storage.

La herramienta de línea de comandos de gsutil verifica las sumas de verificación automáticamente, de modo que cuando la transferencia se completa correctamente, tus datos podrán usarse con las Recomendaciones de GATK.

Cómo ejecutar la canalización en tus datos

Para ejecutar las Recomendaciones de GATK en tus propios archivos BAM sin alinear, haz una copia de PairedEndSingleSampleWf.hg38.inputs.json y, luego, actualiza las rutas de acceso para que dirijan a tus archivos almacenados en un depósito de Cloud Storage. Después, puedes seguir los pasos en Cómo ejecutar la canalización con los datos de muestra con el archivo PairedEndSingleSampleWf.hg38.inputs.json actualizado.

Si tus datos no están compuestos por archivos BAM sin alinear y contienen genomas de referencia, secuenciación del exoma, paneles orientados y datos somáticos, tendrás que usar flujos de trabajo distintos. Consulta el Foro de asistencia de GATK y el repositorio de GitHub del Instituto Broad para obtener más información.

Solución de problemas

  • La canalización está configurada para usar las instancias de Compute Engine en regiones y zonas específicas. Cuando ejecutas la herramienta de gcloud, utiliza automáticamente una región y zona predeterminadas según la ubicación en la que se haya creado tu proyecto de GCP. Esto puede generar el siguiente mensaje de error cuando ejecutas la canalización:

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

    Para resolver este problema, quita la región y zona predeterminadas mediante los siguientes comandos y, luego, ejecuta la canalización nuevamente:

    gcloud config unset compute/zone
    gcloud config unset compute/region
    

    Si quieres obtener más información acerca de cómo configurar la región y zona predeterminadas en tu proyecto de GCP, consulta Cómo cambiar la zona o región predeterminadas.

  • Si tienes problemas para ejecutar la canalización, consulta Solución de problemas de la API de Pipelines.

  • GATK tiene exigencias estrictas acerca de los formatos de archivos de entrada. Para evitar problemas, puedes validar tus archivos con ValidateSamFile.

  • Si tu ejecución de GATK falla, puedes comprobar los registros mediante el siguiente comando:

    gsutil ls gs://BUCKET/FOLDER/logs
    
  • Si te encuentras con errores de permiso, comprueba que tu cuenta de servicio tenga acceso de lectura a los archivos de entrada y acceso de escritura a la ruta de acceso del depósito de los archivos de salida. Si estás escribiendo los archivos de salida en un depósito en un proyecto de GCP que no es tuyo, necesitarás otorgar permiso a la cuenta de servicio para acceder al depósito.

Limpieza

Sigue estos pasos para evitar que se generen cargos en tu cuenta de Google Cloud Platform por los recursos que se usaron en este instructivo:

Una vez que hayas terminado el instructivo Cómo ejecutar la canalización de las Recomendaciones de GATK, puedes limpiar los recursos que creaste en Google Cloud Platform para que no se te facturen en el futuro. La siguiente sección describe cómo borrar o desactivar estos recursos.

Borra los archivos intermedios en el depósito de Cloud Storage

Cuando ejecutas la canalización, almacena los archivos intermedios automáticamente en gs://BUCKET/FOLDER/workspace. Puedes quitar los archivos luego de que se complete el flujo de trabajo para reducir los cargos de Cloud Storage.

Para ver cuánto espacio se usa en el directorio workspace, haz lo siguiente:

gsutil du -sh gs://BUCKET/FOLDER/workspace

Para quitar todos los archivos intermedios del directorio workspace, haz lo siguiente:

gsutil -m rm gs://BUCKET/FOLDER/workspace/**

Cómo borrar el proyecto

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

Para borrar el proyecto, haz lo siguiente:

  1. En la GCP Console, dirígete a la página Proyectos.

    Ir a la página Proyectos

  2. En la lista de proyectos, selecciona el proyecto que deseas borrar y haz clic en Borrar.
  3. En el cuadro de diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

  • Los foros y el sitio de GATK del Broad Institute ofrecen información general, documentación y asistencia más completas sobre las herramientas de GATK y WDL.
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...