Cómo almacenar y cargar variantes genómicas

En esta página, se describe cómo utilizar la herramienta Variant Transforms a fin de transformar y cargar archivos VCF directamente en BigQuery para el análisis a gran escala.

Si estás cargando una gran cantidad de archivos, consulta Cómo administrar entradas grandes a fin de obtener recomendaciones para mejorar el rendimiento y reducir los costos.

Cómo cargar y transformar archivos VCF en BigQuery

Antes de comenzar

Para ejecutar la herramienta, necesitarás contar con lo que se detalla a continuación:

Cómo ejecutar la herramienta

Puedes ejecutar la herramienta mediante una imagen de Docker que tenga todos los objetos binarios y las dependencias necesarios instalados.

Para ejecutar la herramienta con una imagen de Docker, completa los siguientes pasos:

  1. Ejecuta la siguiente secuencia de comandos para iniciar la herramienta. Sustituye las variables con recursos relevantes del proyecto de GCP.

    \#!/bin/bash
    \# Parameters to replace:
    \# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
    GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
    INPUT_PATTERN=gs://BUCKET/*.vcf
    OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
    TEMP_LOCATION=gs://BUCKET/temp
    
    COMMAND="/opt/gcp_variant_transforms/bin/vcf_to_bq \
        --project ${GOOGLE_CLOUD_PROJECT} \
        --input_pattern ${INPUT_PATTERN} \
        --output_table ${OUTPUT_TABLE} \
        --temp_location ${TEMP_LOCATION} \
        --job_name vcf-to-bigquery \
        --runner DataflowRunner"
    gcloud alpha genomics pipelines run \
        --project "${GOOGLE_CLOUD_PROJECT}" \
        --logging "${TEMP_LOCATION}/runner_logs_$(date +%Y%m%d_%H%M%S).log" \
        --zones us-west1-b \
        --service-account-scopes https://www.googleapis.com/auth/cloud-platform \
        --docker-image gcr.io/gcp-variant-transforms/gcp-variant-transforms \
        --command-line "${COMMAND}"
    

    Cuando especifiques la ubicación de tus archivos VCF en un depósito de Cloud Storage, puedes especificar un solo archivo o utilizar un comodín (*) para cargar varios archivos de una sola vez. Entre los formatos de archivos aceptables se incluyen GZIP, BZIP y VCF. A fin de obtener más información, consulta Cómo cargar varios archivos.

    Recuerda que la herramienta es más lenta cuando se ejecutan archivos comprimidos, ya que no se pueden fragmentar. Si deseas combinar muestras entre archivos, consulta Combinación de variantes.

    Ten en cuenta que el directorio TEMP_LOCATION se utiliza a fin de almacenar archivos temporales que son necesarios para ejecutar la herramienta. Puede ser cualquier directorio en Cloud Storage al cual tengas acceso de escritura.

  2. El comando muestra un ID de operación en el formato Running [projects/GOOGLE_CLOUD_PROJECT/operations/OPERATION_ID]. Puedes utilizar el ID de operación a fin de hacer un seguimiento del estado de la herramienta. Para ello, ejecuta el siguiente comando, que muestra un mensaje cuando la operación se completa:

    gcloud alpha genomics operations wait OPERATION_ID
    

    Según diferentes factores, como el tamaño de tus datos, completar el trabajo puede demorar entre varios minutos y una hora, o más.

    Debido a que la herramienta utiliza Cloud Dataflow, puedes navegar a Cloud Dataflow Console si deseas obtener una vista detallada del trabajo. Por ejemplo, puedes ver la cantidad de registros procesados, la cantidad de trabajadores y registros de errores detallados.

  3. Una vez que se complete el trabajo, ejecuta el siguiente comando a fin de enumerar todas las tablas en tu conjunto de datos. Corrobora que la nueva tabla que contiene tus datos VCF esté en la lista:

    bq ls --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET
    

    Además, puedes ver detalles sobre tu tabla, como el esquema y cuándo se la modificó por última vez:

    bq show --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
    

Cómo configurar zonas y regiones

Google Cloud Platform utiliza regiones, subdivididas en zonas para definir la ubicación geográfica de los recursos de computación físicos.

Puedes ejecutar la herramienta Variant Transforms en cualquier región o zona compatible con Cloud Dataflow.

Para cambiar la región en la que se ejecuta la herramienta, actualiza tanto la variable de entorno del COMMAND de Docker como el comando de gcloud de la API de canalización. Por ejemplo, para restringir el procesamiento de los trabajos a Europa, la secuencia de comandos de la imagen de Docker de la sección anterior se vería de la siguiente manera:

\#!/bin/bash
\# Parameters to replace:
\# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="/opt/gcp_variant_transforms/bin/vcf_to_bq \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner
    --region europe-west1
    --zone europe-west1-b"
gcloud alpha genomics pipelines run \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --logging "${TEMP_LOCATION}/runner_logs_$(date +%Y%m%d_%H%M%S).log" \
    --zones europe-west1-b \
    --service-account-scopes https://www.googleapis.com/auth/cloud-platform \
    --docker-image gcr.io/gcp-variant-transforms/gcp-variant-transforms \
    --command-line "${COMMAND}"

Si deseas obtener información sobre cómo configurar la ubicación de un conjunto de datos de BigQuery, consulta Cómo crear un conjunto de datos.

Cómo cargar varios archivos

Puedes especificar los archivos VCF que deseas cargar en BigQuery mediante la marca --input_pattern en la secuencia de comandos anterior. Por ejemplo, para cargar todos los archivos VCF en el depósito de Cloud Storage my-bucket, configura la marca de la siguiente manera:

--input_pattern=gs://my-bucket/*.vcf

Cuando cargues varios archivos en la herramienta Variant Transforms, se producirán las siguientes operaciones:

  1. Se crea un esquema BigQuery combinado que contiene datos de todos los archivos VCF coincidentes detallados en la marca --input_pattern. Por ejemplo, los campos INFO y FORMAT compartidos entre los archivos VCF se combinan. Este paso supone que los campos definidos en varios archivos con la misma clave son compatibles.

  2. Los registros de todos los archivos VCF se cargan en una sola tabla. Cualquier campo faltante se configura como null en su columna asociada.

Además, puedes combinar muestras como un tercer paso. Para obtener más información, consulta Combinación de variantes.

Cuando cargues los archivos VCF, las definiciones de sus campos y valores deben ser coherentes o la herramienta arrojará un error. La herramienta puede intentar corregir estas inconsistencias si se la configura para que lo haga. A fin de obtener más información, consulta Cómo manejar los archivos con formato incorrecto.

Cómo agregar datos a tablas existentes de BigQuery

Puedes agregar datos a una tabla existente de BigQuery; para ello, agrega la marca --append cuando ejecutes la herramienta Variant Transforms.

A fin de obtener mejores resultados cuando agregues datos, el esquema utilizado para estos datos agregados debería ser el mismo que el esquema de la tabla existente. Si el esquema de los datos agregados contiene una columna con el mismo nombre que una columna en la tabla existente, entonces ambas columnas deberán tener el mismo nombre, el mismo tipo de datos y el mismo modo. De lo contrario, la herramienta Variant Transforms mostrará un error.

Puedes agregar datos que tengan un esquema diferente al de la tabla existente; para ello, agrega la marca --update_schema_on_append además de la marca --append. Cualquier columna nueva de los datos agregados se agregará al esquema existente, y los valores de las filas del esquema existente en las columnas nuevas se configurarán como NULL. De manera similar, si el esquema existente tiene columnas que no tengan los datos agregados, entonces los valores de las filas en las columnas de los datos agregados también serán NULL.

Cómo manejar los archivos con formato incorrecto

Existen varias opciones para administrar los archivos con formato incorrecto o incompatibles. Antes de cargar archivos VCF, puedes buscar si hay archivos con formato incorrecto o incompatibles mediante la herramienta del procesador de archivos VCF.

Cómo manejar la incompatibilidad de los campos

Cuando se cargan varios archivos VCF, la herramienta Variant Transforms combina todos los campos INFO y HEADER a fin de generar un "encabezado representativo". Luego, el encabezado representativo se utiliza para crear el esquema de BigQuery. Si se define la misma clave en varios archivos, su definición debe ser compatible entre todos ellos. A continuación, se detallan las reglas de compatibilidad:

  • Los campos son compatibles si tienen los mismos valores en sus campos Number y Type. Los campos de anotación, que se especifican mediante la marca --annotation_fields, deben tener el mismo valor en su campo Description.
  • Los campos que contienen valores Type diferentes son compatibles en los siguientes casos:

    • Si los campos Integer y Float son compatibles y ambos utilizan el tipo Float.
    • Si ejecutas la herramienta Variant Transforms con la marca --allow_incompatible_records, que resuelve automáticamente los conflictos entre los campos incompatibles, como String y Integer. Esto garantiza que los tipos incompatibles no se omitan en silencio.
  • Los campos con valores diferentes en su campo Number son compatibles en los siguientes casos:

    • Si los valores contienen números "repetidos" que son compatibles entre sí, como los siguientes:

      • Number=. (número desconocido)
      • Cualquier Number mayor que 1
      • Number=G (un valor por genotipo) y Number=R (un valor por cada alternativa y referencia)
      • Number=A (un valor por cada alternativa), solamente si la herramienta se ejecuta con --split_alternate_allele_info_fields como False.
    • Si ejecutas la herramienta Variant Transforms con la marca --allow_incompatible_records, que resuelve automáticamente los conflictos entre los campos incompatibles, como Number=1 y Number=. Esto garantiza que los tipos incompatibles no se omitan en silencio.

Cómo especificar un archivo de encabezados

Cuando ejecutas la herramienta Variant Transforms puedes pasar la marca --representative_header_file con un archivo de encabezados que se utiliza para generar un esquema de BigQuery. El archivo especifica los encabezados combinados de todos los archivos que se cargan.

La herramienta Variant Transforms solo lee la información del encabezado del archivo y omite todos los registros de VCF. Esto significa que el archivo puede contener solo los campos del encabezado, o puede ser un archivo VCF real.

Proporcionar el archivo de encabezados tiene los siguientes beneficios:

  • La canalización se ejecutará más rápido, especialmente si estás cargando grandes cantidades de archivos. La herramienta Variant Transforms utiliza el archivo de encabezados para generar un esquema de BigQuery y omite el paso de combinar los encabezados entre archivos. Esto es especialmente útil si todos los archivos tienen los mismos encabezados VCF.

  • Puedes proporcionar definiciones para los campos de encabezado faltantes.

  • Puedes resolver definiciones de campo incompatibles entre archivos.

Cómo inferir encabezados

Cuando ejecutas la herramienta Variant Transforms, es posible que tengas campos que no tengan una definición, o que desees que la herramienta omita las definiciones de encabezado que son incompatibles con los valores de los campos. En tal caso, posiblemente quieras que la herramienta deduzca las definiciones de encabezado correctas para esos campos.

Puedes pasar la marca --infer_headers y la herramienta deducirá los valores TYPE y NUMBER para los campos no definidos. Infiere los valores de acuerdo con los valores de los campos en todos los archivos VCF.

Si pasas esta marca también se generará un encabezado representativo con las definiciones inferidas y las definiciones de los encabezados.

Cómo permitir registros incompatibles

La herramienta Variant Transforms muestra errores en los siguientes casos:

  • Si existe una inconsistencia entre una definición de campo y los valores del campo.
  • Si un campo tiene dos definiciones inconsistentes en dos archivos VCF diferentes.

En ambos casos, puedes pasar la marca --allow_incompatible_records. De esta forma, la herramienta resuelve los conflictos en las definiciones de encabezado automáticamente. La herramienta también convierte los valores de los campos para que coincidan con el esquema de BigQuery en caso de inconsistencias entre la definición de un campo y su valor (por ejemplo, el valor del campo Integer se convertirá en String para que coincida con un esquema de campo del tipo String).

Próximos pasos

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

Enviar comentarios sobre...