Pysam

Overview

Pysam est un module Python pour lire, manipuler et écrire des datasets génomiques. Lisez/écrivez des fichiers d'alignement SAM/BAM/CRAM, des fichiers de variantes VCF/BCF, et des séquences FASTA/FASTQ avec une interface Pythonic vers htslib. Interrogez des fichiers indexés par tabix, effectuez une analyse de pileup pour la couverture, et exécutez des commandes samtools/bcftools.

Quand utiliser cette skill

Cette skill doit être utilisée pour :

• Travailler avec des fichiers d'alignement de séquençage (BAM/CRAM)
• Analyser des variantes génétiques (VCF/BCF)
• Extraire des séquences de référence ou des régions de gènes
• Traiter des données de séquençage brutes (FASTQ)
• Calculer la couverture ou la profondeur de lecture
• Implémenter des pipelines d'analyse bioinformatique
• Contrôle de qualité des données de séquençage
• Workflows d'appel et d'annotation de variantes

Démarrage rapide

Installation

uv pip install pysam

Exemples basiques

Lire un fichier d'alignement :

import pysam

# Ouvrir un fichier BAM et récupérer les lectures dans une région
samfile = pysam.AlignmentFile("example.bam", "rb")
for read in samfile.fetch("chr1", 1000, 2000):
    print(f"{read.query_name}: {read.reference_start}")
samfile.close()

Lire un fichier de variantes :

# Ouvrir un fichier VCF et itérer les variantes
vcf = pysam.VariantFile("variants.vcf")
for variant in vcf:
    print(f"{variant.chrom}:{variant.pos} {variant.ref}>{variant.alts}")
vcf.close()

Interroger une séquence de référence :

# Ouvrir FASTA et extraire la séquence
fasta = pysam.FastaFile("reference.fasta")
sequence = fasta.fetch("chr1", 1000, 2000)
print(sequence)
fasta.close()

Capacités principales

1. Opérations sur les fichiers d'alignement (SAM/BAM/CRAM)

Utilisez la classe AlignmentFile pour travailler avec des lectures de séquençage alignées. C'est approprié pour analyser les résultats de mapping, calculer la couverture, extraire des lectures, ou le contrôle de qualité.

Opérations courantes :

• Ouvrir et lire des fichiers BAM/SAM/CRAM
• Récupérer des lectures d'une région génomique spécifique
• Filtrer les lectures par qualité de mapping, drapeaux, ou autres critères
• Écrire des alignements filtrés ou modifiés
• Calculer les statistiques de couverture
• Effectuer une analyse de pileup (couverture base par base)
• Accéder aux séquences de lecture, aux scores de qualité, et aux informations d'alignement

Référence : Consultez references/alignment_files.md pour la documentation détaillée sur :

• Ouverture et lecture des fichiers d'alignement
• Attributs et méthodes d'AlignedSegment
• Récupération par région avec fetch()
• Analyse de pileup pour la couverture
• Écriture et création de fichiers BAM
• Systèmes de coordonnées et indexation
• Conseils d'optimisation des performances

2. Opérations sur les fichiers de variantes (VCF/BCF)

Utilisez la classe VariantFile pour travailler avec des variantes génétiques provenant de pipelines d'appel de variantes. C'est approprié pour l'analyse de variantes, le filtrage, l'annotation, ou la génétique des populations.

Opérations courantes :

• Lire et écrire des fichiers VCF/BCF
• Interroger des variantes dans des régions spécifiques
• Accéder aux informations de variantes (position, allèles, qualité)
• Extraire les données de génotype pour les échantillons
• Filtrer les variantes par qualité, fréquence allélique, ou autres critères
• Annoter les variantes avec des informations supplémentaires
• Créer des sous-ensembles d'échantillons ou de régions

Référence : Consultez references/variant_files.md pour la documentation détaillée sur :

• Ouverture et lecture des fichiers de variantes
• Attributs et méthodes de VariantRecord
• Accès aux champs INFO et FORMAT
• Travail avec les génotypes et échantillons
• Création et écriture de fichiers VCF
• Filtrage et création de sous-ensembles de variantes
• Opérations multi-échantillon sur VCF

3. Opérations sur les fichiers de séquences (FASTA/FASTQ)

Utilisez FastaFile pour l'accès aléatoire aux séquences de référence et FastxFile pour lire les données de séquençage brutes. C'est approprié pour extraire des séquences de gènes, valider des variantes par rapport à la référence, ou traiter des lectures brutes.

Opérations courantes :

• Interroger des séquences de référence par coordonnées génomiques
• Extraire des séquences pour des gènes ou des régions d'intérêt
• Lire des fichiers FASTQ avec des scores de qualité
• Valider les allèles de référence des variantes
• Calculer les statistiques de séquence
• Filtrer les lectures par qualité ou longueur
• Convertir entre les formats FASTA et FASTQ

Référence : Consultez references/sequence_files.md pour la documentation détaillée sur :

• Accès et indexation des fichiers FASTA
• Extraction de séquences par région
• Gestion du complément inverse pour les gènes
• Lecture séquentielle des fichiers FASTQ
• Conversion et filtrage des scores de qualité
• Travail avec des fichiers indexés par tabix (BED, GTF, GFF)
• Motifs courants de traitement des séquences

4. Workflows bioinformatiques intégrés

Pysam excelle à intégrer plusieurs types de fichiers pour des analyses génomiques complètes. Les workflows courants combinent des fichiers d'alignement, des fichiers de variantes, et des séquences de référence.

Workflows courants :

• Calculer les statistiques de couverture pour des régions spécifiques
• Valider les variantes par rapport aux lectures alignées
• Annoter les variantes avec les informations de couverture
• Extraire des séquences autour des positions de variantes
• Filtrer les alignements ou les variantes selon plusieurs critères
• Générer des pistes de couverture pour la visualisation
• Contrôle de qualité sur plusieurs types de données

Référence : Consultez references/common_workflows.md pour des exemples détaillés de :

• Workflows de contrôle de qualité (statistiques BAM, cohérence des références)
• Analyse de couverture (couverture par base, détection de faible couverture)
• Analyse de variantes (annotation, filtrage par support de lecture)
• Extraction de séquences (contextes de variantes, séquences de gènes)
• Filtrage et création de sous-ensembles de lectures
• Motifs d'intégration (BAM+VCF, VCF+BED, etc.)
• Optimisation des performances pour les workflows complexes

Concepts clés

Systèmes de coordonnées

Critique : Pysam utilise des coordonnées 0-based, semi-ouvertes (convention Python) :

• Les positions de début sont 0-based (la première base est à la position 0)
• Les positions de fin sont exclusives (non incluses dans la plage)
• La région 1000-2000 inclut les bases 1000-1999 (1000 bases au total)

Exception : Les chaînes de région dans fetch() suivent la convention samtools (1-based) :

samfile.fetch("chr1", 999, 2000)      # 0-based : positions 999-1999
samfile.fetch("chr1:1000-2000")       # chaîne 1-based : positions 1000-2000

Fichiers VCF : Utilisent des coordonnées 1-based dans le format de fichier, mais VariantRecord.start est 0-based.

Exigences d'indexation

L'accès aléatoire à des régions génomiques spécifiques nécessite des fichiers d'index :

• Fichiers BAM : Nécessitent un index .bai (créer avec pysam.index())
• Fichiers CRAM : Nécessitent un index .crai
• Fichiers FASTA : Nécessitent un index .fai (créer avec pysam.faidx())
• Fichiers VCF.gz : Nécessitent un index tabix .tbi (créer avec pysam.tabix_index())
• Fichiers BCF : Nécessitent un index .csi

Sans index, utilisez fetch(until_eof=True) pour une lecture séquentielle.

Modes de fichier

Spécifiez le format lors de l'ouverture de fichiers :

• "rb" - Lire BAM (binaire)
• "r" - Lire SAM (texte)
• "rc" - Lire CRAM
• "wb" - Écrire BAM
• "w" - Écrire SAM
• "wc" - Écrire CRAM

Considérations de performance

1. Toujours utiliser des fichiers indexés pour les opérations d'accès aléatoire
2. Utiliser pileup() pour l'analyse colonne par colonne au lieu de répétées opérations fetch
3. Utiliser count() pour compter au lieu d'itérer et compter manuellement
4. Traiter les régions en parallèle lors de l'analyse de régions génomiques indépendantes
5. Fermer explicitement les fichiers pour libérer les ressources
6. Utiliser until_eof=True pour le traitement séquentiel sans index
7. Éviter les itérateurs multiples sauf si nécessaire (utiliser multiple_iterators=True si nécessaire)

Pièges courants

1. Confusion de coordonnées : N'oubliez pas les systèmes 0-based vs 1-based dans différents contextes
2. Indices manquants : De nombreuses opérations nécessitent des fichiers d'index—créez-les d'abord
3. Chevauchements partiels : fetch() retourne les lectures qui chevauchent les limites de la région, pas seulement celles entièrement contenues
4. Étendue de l'itérateur : Gardez les références de l'itérateur pileup actives pour éviter les erreurs "PileupProxy accessed after iterator finished"
5. Édition des scores de qualité : Impossible de modifier query_qualities en place après avoir modifié query_sequence—créez d'abord une copie
6. Limitations de streaming : Seuls stdin/stdout sont pris en charge pour le streaming, pas les objets fichiers Python arbitraires
7. Sécurité des threads : Bien que le GIL soit libéré pendant les E/S, la sécurité complète des threads n'a pas été entièrement validée

Outils en ligne de commande

Pysam fournit l'accès aux commandes samtools et bcftools :

# Trier le fichier BAM
pysam.samtools.sort("-o", "sorted.bam", "input.bam")

# Indexer BAM
pysam.samtools.index("sorted.bam")

# Afficher une région spécifique
pysam.samtools.view("-b", "-o", "region.bam", "input.bam", "chr1:1000-2000")

# Outils BCF
pysam.bcftools.view("-O", "z", "-o", "output.vcf.gz", "input.vcf")

Gestion des erreurs :

try:
    pysam.samtools.sort("-o", "output.bam", "input.bam")
except pysam.SamtoolsError as e:
    print(f"Error: {e}")

Ressources

references/

Documentation détaillée pour chaque capacité majeure :

• alignment_files.md - Guide complet des opérations SAM/BAM/CRAM, incluant la classe AlignmentFile, les attributs d'AlignedSegment, les opérations fetch, l'analyse de pileup, et l'écriture d'alignements

• variant_files.md - Guide complet des opérations VCF/BCF, incluant la classe VariantFile, les attributs de VariantRecord, la gestion des génotypes, les champs INFO/FORMAT, et les opérations multi-échantillon

• sequence_files.md - Guide complet des opérations FASTA/FASTQ, incluant les classes FastaFile et FastxFile, l'extraction de séquences, la gestion des scores de qualité, et l'accès aux fichiers indexés par tabix

• common_workflows.md - Exemples pratiques de workflows bioinformatiques intégrés combinant plusieurs types de fichiers, incluant le contrôle de qualité, l'analyse de couverture, la validation de variantes, et l'extraction de séquences

Obtenir de l'aide

Pour obtenir des informations détaillées sur des opérations spécifiques, consultez le document de référence approprié :

• Travailler avec des fichiers BAM ou calculer la couverture → alignment_files.md
• Analyser des variantes ou des génotypes → variant_files.md
• Extraire des séquences ou traiter FASTQ → sequence_files.md
• Workflows complexes intégrant plusieurs types de fichiers → common_workflows.md

Documentation officielle : https://pysam.readthedocs.io/