Ejecuta las prácticas recomendadas de GATK

Aviso: En este instructivo, se muestra cómo ejecutar un flujo de trabajo predefinido en un caso de uso limitado, pero no está diseñado para ejecutarse en producción. A fin de obtener información para realizar el procesamiento de datos genómicos en un entorno de producción en Google Cloud, consulta Arquitectura de referencia del procesamiento de datos genómicos.

En esta página, se explica cómo ejecutar una canalización de análisis genómico secundario en Google Cloud con las Prácticas recomendadas del kit de herramientas de análisis de genomas (GATK). El Instituto Broad proporciona las prácticas recomendadas de GATK.

El flujo de trabajo que se utiliza en este instructivo es una implementación de las prácticas recomendadas de GATK para el descubrimiento de variantes en los datos de la secuenciación del genoma completo (WGS). El flujo de trabajo está escrito en el lenguaje Workflow Definition Language (WDL) del Broad Institute y se realiza en el ejecutor de WDL Cromwell.

Nota: Eres responsable de cumplir con las condiciones del Contrato de Licencia de Usuario Final de GATK, incluido el requisito de atribución.

Objetivos

Después de completar el instructivo, sabrás cómo realizar las siguientes actividades:

• Ejecutar una canalización según las prácticas recomendadas de GATK con los datos de la versión 38 del genoma humano de referencia
• Ejecutar una canalización según las prácticas recomendadas de GATK con tus propios datos

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Compute Engine
• Cloud Storage

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

2. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

4. Habilita las API de Cloud Life Sciences, Compute Engine, and Cloud Storage.

   Habilita las API

5. Instala Google Cloud CLI.

6. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

   gcloud init

7. Instala y actualiza los componentes de gcloud:

   gcloud components update
   gcloud components install beta

8. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

9. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

10. Habilita las API de Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Habilita las API

11. Instala Google Cloud CLI.

12. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init

13. Instala y actualiza los componentes de gcloud:

    gcloud components update
    gcloud components install beta

14. Instala Git para descargar los archivos necesarios.

    Descargar Git

15. Con la configuración predeterminada, Compute Engine tiene cuotas de recursos para evitar el uso involuntario. Cuando aumentas 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 este 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.

    Nota: Si tu proyecto se creó con una prueba gratuita, debes solicitar cuotas más altas para ejecutar las prácticas recomendadas de GATK en Google Cloud.

Crea un bucket de Cloud Storage

Crea un depósito de Cloud Storage con el comando gsutil mb. Debido a un requisito del motor de Cromwell, no debes utilizar caracteres de guion bajo (_) en el nombre del bucket. De lo contrario, se producirá un error.

gsutil mb gs://BUCKET

La canalización genera resultados, registros y archivos intermedios en este bucket.

Descarga los archivos de ejemplo

Ejecuta los siguientes comandos para descargar la secuencia de comandos de WDL y auxiliar:

git clone https://github.com/broadinstitute/wdl-runner.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, como las rutas de acceso a los archivos BAM y el genoma de referencia
• *.options.json: opciones del entorno 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 broadinstitute/wdl-runner/wdl_runner/.

Ejecuta la canalización con los datos de muestra

En esta sección, se muestra cómo ejecutar la canalización con datos de WGS mediante la compilación 38 del genoma humano de referencia. Los archivos de entrada son archivos BAM sin alinear.

Para ejecutar la canalización, complete los siguientes pasos:

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. Crea la variable de entorno GATK_OUTPUT_DIR, que dirige al depósito de Cloud Storage y una carpeta para el output del flujo de trabajo, los archivos work intermedios y logging:

   export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
   

3. Cambia el directorio a la carpeta /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 Google Cloud:

   cd wdl-runner/wdl_runner/
   

4. Ejecuta la canalización:

   Importante: Si aparece el mensaje de error que dice "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together", consulta Solución de problemas.

   Elige una de las siguientes opciones según si usas una VPC predeterminada o una VPC personalizada:

   VPC predeterminada

   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 personalizada

   1. Crea las variables de entorno NETWORK y SUBNETWORK para especificar el nombre de la red y subred de VPC:

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET
      

   2. Edita el archivo PairedEndSingleSampleWf.options.json ubicado en el directorio broad-prod-wgs-germline-snps-indels y modifica las zonas para incluir solo las zonas dentro de la región de la subred. Por ejemplo, si usas una subred us-central1, el campo zones se vería así: "zones": "us-central1-a us-central1-b us-central1-c us-central1-f".

   3. 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/
      

5. El comando muestra un ID de operación en el formato Running [operations/OPERATION_ID]. Puedes usar el comando gcloud beta lifesciences describe para realizar un seguimiento del estado de la canalización. Para ello, ejecuta el siguiente comando (asegúrate de que el valor de la marca --location coincida con la ubicación especificada en el paso anterior):

   gcloud beta lifesciences operations describe OPERATION_ID \
       --location=us-central1 \
       --format='yaml(done, error, metadata.events)'
   

6. El comando operations describe muestra done: true cuando finaliza la canalización.

   Puedes ejecutar una secuencia de comandos incluida con el wdl_runner para comprobar cada 300 segundos si el trabajo está en ejecución, finalizó o mostró un error:

   ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
   

7. Una vez que tu canalización finalice, ejecuta el siguiente comando para enumerar los resultados enviados a tu bucket de Cloud Storage:

   gsutil ls gs://BUCKET/FOLDER/output/
   

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 bucket 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 bucket 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 bucket 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 checksums automáticamente, de modo que cuando la transferencia se realice correctamente, tus datos serán compatibles para que los uses con las prácticas recomendadas de GATK.

Ejecuta la canalización en tus datos

Para ejecutar las prácticas recomendadas de GATK en tus propios archivos BAM sin alinear, crea una copia de PairedEndSingleSampleWf.hg38.inputs.json y actualiza las rutas de acceso para que dirijan a tus archivos en un depósito de Cloud Storage. A continuación, puedes seguir los pasos de Ejecuta la canalización con los datos de muestra con el archivo PairedEndSingleSampleWf.hg38.inputs.json actualizado.

Si tus datos no son 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 Broad Institute para obtener más información.

Soluciona problemas

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

  "ERROR: (gcloud.beta.lifesciences.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 Google Cloud, consulta Cambia la región o la zona predeterminadas.

• Si tienes problemas para ejecutar la canalización, consulta la solución de problemas de la API de Cloud Life Sciences.

• 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/logging
  

• 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 bucket de los archivos de salida. Si escribes archivos de salida en un bucket de un proyecto de Google Cloud que no es tuyo, debes otorgarle permiso a la cuenta de servicio para que acceda al bucket.

Realice una limpieza

Borra los archivos intermedios del bucket de Cloud Storage

Cuando ejecutas la canalización, almacena los archivos intermedios en gs://BUCKET/FOLDER/work. 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 work, ejecuta el siguiente comando. Es posible que el comando tarde varios minutos en ejecutarse debido al tamaño de los archivos en el directorio.

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

Para quitar los archivos intermedios del directorio work, ejecuta el siguiente comando:

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

Borra 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:

Advertencia: Borrar un proyecto tiene las siguientes consecuencias:

• Si usaste un proyecto existente, también borrarás cualquier otro trabajo que hayas realizado en el proyecto.
• No puedes reutilizar el ID de un proyecto borrado. Si creaste un ID de proyecto personalizado que planeas volver a usar en el futuro, borra los recursos en sí y no el proyecto que los contiene. De esta manera, tendrás la seguridad de que las URL que usen el ID del proyecto, como una URL appspot.com, permanezcan disponibles.

Si estás explorando varios instructivos y varias guías de inicio rápido, puedes volver a usar los proyectos en lugar de borrarlos para evitar exceder los límites de cuotas de proyectos.

1. En la consola de Google Cloud, 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.
3. En el cuadro de diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

• En este instructivo, En este instructivo, se muestra cómo ejecutar un flujo de trabajo predefinido en un caso de uso limitado, pero no está diseñado para ejecutarse en producción. A fin de obtener información para realizar el procesamiento de datos genómicos en un entorno de producción en Google Cloud, consulta Arquitectura de referencia del procesamiento de datos genómicos.
• El sitio de GATK y los foros del Broad Institute ofrecen información general, documentación y asistencia más completas sobre las herramientas de GATK y WDL.