Stocker et charger des variantes génomiques

Cette page explique comment transformer et charger directement des fichiers VCF dans BigQuery à l'aide de l'outil Variant Transforms en vue d'une analyse à grande échelle.

Si vous chargez un grand nombre de fichiers, consultez la page Traiter un grand nombre d'entrées pour obtenir des recommandations sur l'amélioration des performances et la réduction des coûts.

Charger et transformer des fichiers VCF dans BigQuery

Avant de commencer

Pour exécuter l'outil, vous devez disposer des éléments suivants :

Exécuter l'outil

Vous pouvez exécuter l'outil à l'aide d'une image Docker sur laquelle tous les fichiers binaires et toutes les dépendances nécessaires sont installés.

Pour exécuter l'outil à l'aide d'une image Docker, procédez comme suit :

  1. Utilisez la commande suivante pour obtenir la dernière version de Variant Transforms.

    docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms
    
  2. Copiez le texte suivant et enregistrez-le dans un fichier nommé script.sh, en remplaçant les variables par les ressources correspondantes de votre projet 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}"
    

    Lorsque vous indiquez l'emplacement de vos fichiers VCF dans un bucket Cloud Storage, vous pouvez spécifier un seul fichier ou utiliser un caractère générique (*) pour charger plusieurs fichiers à la fois. Les formats de fichiers acceptés incluent GZIP, BZIP et VCF. Pour en savoir plus, consultez la section Charger plusieurs fichiers ci-après.

    N'oubliez pas que l'outil s'exécute plus lentement pour les fichiers compressés, car ceux-ci ne peuvent pas être partitionnés. Si vous souhaitez fusionner des exemples sur plusieurs fichiers, consultez la section Fusion de variantes.

    Notez que le répertoire TEMP_LOCATION permet de stocker les fichiers temporaires nécessaires à l'exécution de l'outil. Il peut s'agir de n'importe quel répertoire de Cloud Storage auquel vous avez accès en écriture.

  3. Saisissez la commande suivante pour pouvoir exécuter script.sh :

    chmod +x script.sh
    
  4. Exécutez script.sh :

    ./script.sh
    
  5. En fonction de plusieurs facteurs, tels que la taille de vos données, la tâche peut être effectuée dans un délai de quelques minutes à plus d'une heure.

    Comme l'outil utilise Dataflow, vous pouvez accéder à la console Dataflow pour afficher la vue détaillée de la tâche. Par exemple, vous pouvez afficher le nombre d'enregistrements traités, le nombre de nœuds de calcul et les journaux d'erreur en détail.

  6. Une fois la tâche terminée, exécutez la commande suivante pour répertorier toutes les tables de votre ensemble de données. Vérifiez que la nouvelle table qui contient vos données VCF se trouve dans la liste :

    bq ls --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET
    

    Vous pouvez également afficher des détails sur la table, tels que le schéma et la date de la dernière modification :

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

Définir des zones et des régions

Google Cloud définit l'emplacement géographique des ressources de calcul physiques à l'aide de régions subdivisées en zones.

Vous pouvez exécuter l'outil Variant Transforms dans toute région ou zone dans laquelle Dataflow est disponible.

Pour modifier la région dans laquelle l'outil s'exécute, mettez à jour la variable d'environnement Docker COMMAND et la commande gcloud de l'API Cloud Life Sciences. Par exemple, pour limiter le traitement des tâches en Europe, le script d'image Docker de la section précédente se présente comme suit :

#!/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}"

Pour savoir comment définir l'emplacement d'un ensemble de données BigQuery, consultez la section Créer un ensemble de données.

Charger plusieurs fichiers

Vous pouvez indiquer les fichiers VCF à charger dans BigQuery à l'aide de l'option --input_pattern du script ci-dessus. Par exemple, pour charger tous les fichiers VCF dans le bucket Cloud Storage my-bucket, définissez l'option comme suit :

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

Lorsque vous chargez plusieurs fichiers avec l'outil Variant Transforms, les opérations suivantes sont exécutées :

  1. Un schéma BigQuery fusionné est créé. Il contient les données de tous les fichiers VCF correspondants répertoriés dans l'option --input_pattern. Par exemple, les champs INFO et FORMAT partagés entre les fichiers VCF sont fusionnés. Pour cette étape, nous supposons que les champs définis dans plusieurs fichiers avec la même clé sont compatibles.

  2. Les enregistrements de tous les fichiers VCF sont chargés dans une seule table. Tous les champs manquants sont définis sur null dans la colonne associée.

Vous pouvez également fusionner des exemples dans une troisième étape. Pour en savoir plus, consultez la section Fusion de variantes.

Lors du chargement des fichiers VCF, les définitions et les valeurs de leurs champs doivent être cohérentes. Sinon, l'outil échoue. L'outil peut tenter de corriger ces incohérences s'il est configuré pour exécuter cette tâche. Pour en savoir plus, consultez la section Traiter des fichiers non valides ci-après.

Ajouter des données aux tables BigQuery existantes

Vous pouvez inclure des données à une table BigQuery existante en ajoutant l'option --append lors de l'exécution de l'outil Variant Transforms.

Pour obtenir de meilleurs résultats lors de l'ajout des données, leur schéma doit être identique à celui de la table existante. Si le schéma des données ajoutées contient une colonne portant le même nom qu'une colonne de la table existante, les deux colonnes doivent avoir le même nom, le même type de données et le même mode. Sinon, l'outil Variant Transforms renvoie une erreur.

Vous pouvez ajouter des données avec un schéma différent de celui de la table existante en ajoutant l'option --update_schema_on_append en plus de l'option --append. Toutes les nouvelles colonnes issues de ces données sont ajoutées au schéma existant. Les valeurs des lignes de ce schéma sont définies sur NULL dans les nouvelles colonnes. De même, si le schéma existant contient des colonnes qui ne sont pas incluses dans les données ajoutées, les valeurs des lignes des colonnes des données ajoutées sont également NULL.

Traiter des fichiers non valides

Plusieurs options permettent de traiter les fichiers non valides ou incompatibles. Avant de charger des fichiers VCF, vous pouvez rechercher ces fichiers à l'aide du préprocesseur de fichiers VCF.

Gérer les incompatibilités de champs

Lorsque vous chargez plusieurs fichiers VCF, l'outil Variant Transforms fusionne tous les champs INFO et HEADER pour générer un "en-tête représentatif". Cet en-tête permet ensuite de créer le schéma BigQuery. Si la même clé est définie dans plusieurs fichiers, sa définition doit être compatible entre les différents fichiers. Les règles de compatibilité sont les suivantes :

  • Les champs sont compatibles s'ils partagent les mêmes valeurs dans les champs Number et Type. Les champs d'annotation, spécifiés à l'aide de l'option --annotation_fields, doivent également avoir une valeur identique dans le champ Description.
  • Les champs qui contiennent des valeurs Type différentes sont compatibles dans les cas suivants :

    • Si les champs Integer et Float sont compatibles, et qu'ils utilisent tous deux le type Float.
    • Si vous exécutez l'outil Variant Transforms avec l'option --allow_incompatible_records pour résoudre automatiquement les conflits entre les champs incompatibles, tels que String et Integer. Cela permet de s'assurer que les types incompatibles ne sont pas ignorés sans notification.
  • Les champs qui contiennent des valeurs Number différentes sont compatibles dans les cas suivants :

    • Si les valeurs contiennent des nombres "répétés" compatibles entre eux, tels que :

      • Number=. (nombre inconnu) ;
      • N'importe quelle valeur Number (nombre) supérieure à 1 ;
      • Number=G (une valeur par génotype) et Number=R (une valeur pour chaque substitut et référence) ;
      • Number=A (une valeur pour chaque substitut), uniquement si l'outil est exécuté avec l'option --split_alternate_allele_info_fields définie sur False.
    • Si vous exécutez l'outil Variant Transforms avec l'option --allow_incompatible_records pour résoudre automatiquement les conflits entre les champs incompatibles, tels que Number=1 et Number=.. Cela permet de s'assurer que les types incompatibles ne sont pas ignorés sans notification.

Spécifier un fichier d'en-têtes

Lorsque vous exécutez l'outil Variant Transforms, vous pouvez transmettre l'option --representative_header_file avec un fichier d'en-têtes qui permet de générer le schéma BigQuery. Le fichier répertorie les en-têtes fusionnés de tous les fichiers en cours de chargement.

L'outil Variant Transforms lit uniquement les informations d'en-tête du fichier et ignore tous les enregistrements des fichiers VCF. Autrement dit, le fichier peut contenir uniquement les champs d'en-tête ou il peut s'agir d'un fichier VCF.

Le fichier d'en-têtes présente les avantages suivants :

  • Le pipeline est exécuté plus rapidement, surtout si vous chargez un grand nombre de fichiers. L'outil Variant Transforms génère le schéma BigQuery à l'aide du fichier d'en-têtes et ignore l'étape de fusion des en-têtes dans plusieurs fichiers. Ceci est particulièrement utile si tous les fichiers VCF disposent des mêmes en-têtes.

  • Vous pouvez fournir des définitions pour tous les champs d'en-tête manquants.

  • Vous pouvez résoudre les définitions de champs incompatibles dans les fichiers.

Déduire les en-têtes

Lorsque vous exécutez l'outil Variant Transforms, vous pouvez avoir des champs non définis ou vous pouvez souhaiter que l'outil ignore les définitions d'en-tête incompatibles avec les valeurs des champs. Dans ce cas, vous souhaiterez peut-être qu'il déduise les définitions d'en-tête correctes pour ces champs.

Si vous transmettez l'option --infer_headers, l'outil déduira les valeurs TYPE et NUMBER des champs non définis. Il déduit ces valeurs en fonction des valeurs de champ de tous les fichiers VCF.

Cet indicateur permet également de générer un en-tête représentatif qui contient les définitions déduites et les définitions d'en-têtes.

Autoriser les enregistrements incompatibles

L'outil Variant Transforms échoue dans les deux cas suivants :

  • Si une incohérence existe entre une définition de champ et les valeurs du champ
  • Si un champ a deux définitions incohérentes dans deux fichiers VCF différents

Dans les deux cas, vous pouvez transmettre l'option --allow_incompatible_records. L'outil résout automatiquement les conflits dans les définitions d'en-têtes. Il modifie également les valeurs de champ qui correspondent au schéma BigQuery si une incohérence existe entre la définition d'un champ et sa valeur (par exemple, la valeur de champ Integer est remplacée par String pour correspondre à un schéma de champ de type String).

Étapes suivantes