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.

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 de Genome Analysis Toolkit (GATK). El Broad Institute 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 ejecuta en el ejecutor de WDL Cromwell.

Nota: Es tu responsabilidad cumplir con las condiciones del Acuerdo de Licencia para el usuario final de GATK, incluida la de atribución obligatoria.

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. Update and install gcloud components:

   gcloud components update
   gcloud components install beta

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

    Enable the APIs

11. Install the Google Cloud CLI.

12. To initialize the gcloud CLI, run the following command:

    gcloud init

13. Update and install gcloud components:

    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. 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 los otros campos de la solicitud de cuota para mantener las cuotas actuales.

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

Cree un bucket de Cloud Storage

Crea un bucket de Cloud Storage con el comando gcloud storage buckets create. 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.

gcloud storage buckets create gs://BUCKET

La canalización produce 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 usando la versión 38 del genoma humano de referencia. Los archivos de entrada son archivos BAM sin alinear.

Para ejecutar la canalización, completa 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 tu 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 que incluyan solo zonas dentro de la región de tu subred. Por ejemplo, si usas una subred us-central1, el campo zones se verá de la siguiente manera: "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:

   gcloud storage 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:

gcloud storage 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.

Gcloud CLI verifica las sumas de verificación 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, utiliza automáticamente una región y una 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:

  gcloud storage 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, esta almacena los archivos intermedios en gs://BUCKET/FOLDER/work. Puedes quitar los archivos después 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.

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

Ejecuta el siguiente comando para quitar los archivos intermedios del directorio work:

gcloud storage 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 se borrará cualquier otro trabajo que hayas realizado en él.
• 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 diferentes instructivos y 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 que quieres borrar y haz clic en Borrar proyecto (Delete project.
3. En el cuadro de diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

• 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.