Almacena y carga 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 vas a cargar una gran cantidad de archivos, consulta cómo administrar entradas grandes a fin de obtener recomendaciones para mejorar el rendimiento y reducir los costos.

Carga y transforma 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. Usa el siguiente comando para obtener la última versión de Variant Transforms.

    docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms
    
  2. Copia el siguiente texto, guárdalo en un archivo llamado script.sh y reemplaza las variables con los recursos relevantes de tu proyecto de Google Cloud.

    #!/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="vcf_to_bq \
        --input_pattern ${INPUT_PATTERN} \
        --output_table ${OUTPUT_TABLE} \
        --temp_location ${TEMP_LOCATION} \
        --job_name vcf-to-bigquery \
        --runner DataflowRunner"
    docker run -v ~/.config:/root/.config \
        gcr.io/cloud-lifesciences/gcp-variant-transforms \
        --project "${GOOGLE_CLOUD_PROJECT}" \
        --zones us-west1-b \
        "${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 a la vez. Los formatos de archivo aceptables incluyen GZIP, BZIP y VCF. Para 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 de distintos 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.

  3. Ejecuta el siguiente comando para hacer que script.sh sea ejecutable:

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

    ./script.sh
    
  5. 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 Dataflow, puedes navegar a 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.

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

Configura zonas y regiones

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

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

Para cambiar la región en la que se ejecuta la herramienta, actualiza tanto la variable de entorno COMMAND de Docker como el comando de gcloud de la API de Cloud Life Sciences. 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 sería similar a lo siguiente:

#!/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="vcf_to_bq \
    --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"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones europe-west1-b \
    "${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 qué archivos VCF deseas cargar en BigQuery con el marcador --input_pattern en la secuencia de comandos anterior. Por ejemplo, para cargar todos los archivos VCF en el depósito my-bucket de Cloud Storage, establece la marca en lo siguiente:

--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. De lo contrario, la herramienta arrojará un error. La herramienta puede intentar corregir estas incoherencias si se configura para hacerlo. Si deseas 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 de la tabla existente; para ello, agrega la marca --update_schema_on_append además de la marca --append. Las columnas nuevas de los datos agregados se incorporarán al esquema existente, y se ingresará el valor NULL en esas columnas para las filas del esquema existente. De manera similar, si el esquema existente tiene columnas que no están presentes en los datos agregados, se ingresará el valor NULL en esas columnas para las filas de los datos agregados.

Cómo manejar los archivos con formato incorrecto

Existen varias opciones para el manejo de archivos incompatibles o con formato incorrecto. 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 para generar un "encabezado representativo". Este encabezado se usa para crear el esquema de BigQuery. Si se define la misma clave en varios archivos, su definición debe ser compatible con 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 con la marca --annotation_fields, también 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 usan el tipo Float
    • Si ejecutas la herramienta Variant Transforms con la marca --allow_incompatible_records, que resuelve automáticamente los conflictos entre 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 en estos casos:

      • 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), solo si la herramienta se ejecuta con --split_alternate_allele_info_fields establecido como False.
    • Si ejecutas la herramienta Variant Transforms con la marca --allow_incompatible_records, que resuelve automáticamente los conflictos entre campos incompatibles, como Number=1 y Number=.. Esto garantiza que los tipos incompatibles no se omitan en silencio.

Especifica un archivo de encabezados

Cuando ejecutas la herramienta Variant Transforms, puedes pasar la marca --representative_header_file con un archivo de encabezado que se usa para generar el 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 cargas 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 para que la herramienta infiera los valores TYPE y NUMBER de los campos no definidos. Esta inferencia se realiza sobre la base de los valores de los campos presentes 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 envía valores de campo para que coincidan con el esquema de BigQuery si hay diferencias entre la definición de un campo y su valor (por ejemplo, el valor del campo Integer se convierte en String para que coincida con un esquema de campo del tipo String).

Próximos pasos