Documentation de PiscAmp

<< Retour au démonstrateur PiscAmp

La bibliothèque PiscAmp est conçue pour réaliser des alignements multiples de séquences d'acides nucléiques (ADN/ARN) et de protéines, de manière simple et efficace. Elle s'intègre facilement dans n'importe quel site web et propose diverses options pour adapter l'alignement à vos besoins.

Sommaire

• 1. Téléchargement et intégration
• 2. Fonction principale et méthodes
• 3. Fonctions complémentaires
• 4. Limites, comparateurs et ressources

1. Téléchargement et intégration

Sur la page du démonstrateur de PiscAmp, parcourez le menu et cliquez sur 💽 Télécharger PiscAmp pour obtenir le fichier piscamp.js.

Pour intégrer la bibliothèque à votre site web, il suffit d'inclure le fichier JavaScript dans votre page HTML. Par exemple :

Assurez-vous que le chemin vers piscamp.js est correct par rapport à la structure de votre projet.

Vous pouvez aussi retrouver l'ensemble des sources du projet PiscAmp sur https://forge.apps.education.fr/projets-evoluscope/piscamp. Si vous préférez télécharger ces sources alors il vous faudra intégrer les trois fichiers seqalign.js, suffixarrays.js, et treedist.js pour avoir accès à toutes les fonctions de la bibliothèque (ceux-ci étant combinés automatiquement si vous utilisez plutôt le bouton de téléchargement).

La licence est libre mais vous devez citer l'auteur et l'origine de PiscAmp si vous l'utilisez.

2. Fonction principale et méthodes

La bibliothèque fournit plusieurs fonctions essentielles pour réaliser un alignement multiple. La fonction principale de cette bibliothèque est alignLcsMsa, qui permet d'effectuer un alignement multiple de séquences. Il s'agit d'une fonction asynchrone, vous devez donc utiliser le mot-clé await lorsque vous l'appelez. Voici la syntaxe de cette fonction :

Les trois premiers paramètres sont obligatoires, les trois derniers sont facultatifs. Voici leurs rôles :

1. sequences : Array (obligatoire) — Un tableau contenant au moins deux séquences à aligner. Chaque séquence est représentée par une chaine de caractères en majuscules appartenant à l'alphabet choisi.
2. type : String (obligatoire) — Le type de séquences à aligner. Cela peut être "NA" (pour les acides nucléiques, ADN et/ou ARN), "protein" (pour les protéines), "binary" (pour les séquences de 0 et de 1) ou "english" (pour l'alphabet complet de 26 lettres).
3. method : String (obligatoire) — La méthode d'alignement à utiliser. Les valeurs possibles sont "star" ou "quickstar" pour un alignement en étoile, "quickstar" étant une variante rapide qui utilise des distances approximatives par k-mères pour éviter de calculer tous les alignements par paires, "chain" ou "quickchain" (variante rapide également basée sur les k-mères) pour un alignement deux à deux suivant l'ordre du minimum spanning tree (MST), "progressive" pour un alignement progressif, "iterative" pour un alignement progressif avec une recherche itérative d'éventuelles améliorations de cet alignement, et enfin "best" qui laisse l'algorithme décider du meilleur résultat entre l'alignement en étoile, l'alignement en chaine et l'alignement itératif.
4. verbose : Boolean (facultatif) — Indique si l'algorithme doit détailler les informations qu'il traite et les résultats intermédiaires dans la console du navigateur. La valeur true est utilisée par défaut.
5. thresholdProb : Number (facultatif) — Le seuil de probabilité utilisé pour le découpage des séquences (valeur attendue entre 0 et 1). Ce paramètre permet d'en contrôler la spécificité. Si non fourni, la valeur de 0.0001 est utilisée par défaut. Le démonstrateur charge la valeur indiquée dans le menu des paramètres (2^-13 ≈ 0.0001221 par défaut). Une valeur de 0 ne désactive pas complètement le découpage car la probabilité indiquée est ignorée lorsque la plus longue des deux sous-séquences mesure au moins 2000 résidus. La plus longue sous-chaine commune est alors acceptée dès qu'elle compte au moins 3 résidus. Il s'agit d'un garde-fou visant à éviter les alignements extrêmement lent ou pouvant dépasser la mémoire vive disponible.
6. scoreParams : Object (facultatif) — Des paramètres supplémentaires qui peuvent être utilisés pour affiner l'alignement. Si non fourni (ou fourni avec la valeur null), des paramètres par défaut (voir ci-dessous) seront utilisés en fonction du type de séquences (ADN, protéines, etc.).

Voici un exemple d'utilisation simple :

La fonction renvoie les séquences alignées dans l'ordre dans lequel elles ont été fournies. En interne, les séquences sont toujours traitées selon un ordre déterministe, l'ordre dans lequel on les fournit ne peut donc pas influencer le résultat de l'alignement. Elle renvoie null lorsque les paramètres fournis sont invalides.

L'alphabet des acides nucléiques est AGCTU (dans cet ordre, pas dans l'ordre alphabétique ordinaire). Trois ensembles de paramètres pour les acides nucléiques sont prédéfinis dans PiscAmp comme variables globales. C'est balancedNAParams qui est utilisé par défaut si vous ne spécifiez pas le paramètre scoreParams. Voici le détail des valeurs utilisées (ces paramètres sont déjà définis dans PiscAmp, les déclarations ci-dessous sont reproduites à titre documentaire) :

Pour les protéines, les paramètres par défaut se servent de la matrice de substitution VTML240 :

Vous pouvez utiliser des paramètres personnalisés à la place de ceux-là (par exemple si vous préférez utiliser BLOSUM62). La matrice de remplacement doit alors bien avoir ses 20 lignes et ses 20 colonnes dans l'ordre alphabétique des codes à une lettre des acides aminés : ACDEFGHIKLMNPQRSTVWY.

Pour les séquences binaires (binary), PiscAmp utilise par défaut la matrice de substitution 2 × 2 binaryParams. Pour les séquences de lettres (english), il utilise la matrice 26 × 26 englishParams. Dans les deux cas, une identité rapporte +1, une différence coute −1, et les pénalités d'ouverture et d'extension des gaps valent chacune −1.

Les paramètres personnalisés doivent être fournis dans un objet contenant trois propriétés : matCost, gapOpen et gapExtend. La matrice matCost est un tableau typé Int16Array (nombres entiers compris entre −16384 et 16383) à une dimension, contenant les coefficients ligne par ligne (25 valeurs pour les acides nucléiques, 400 pour les protéines, 4 pour les séquences binaires et 676 pour les séquences de lettres). Les scores d'identité doivent être strictement positifs, les pénalités de gaps doivent être des entiers strictement négatifs et gapExtend doit être supérieur ou égal à gapOpen. Au moins un score de substitution doit être négatif et aucun score de substitution ne peut dépasser le meilleur score d'identité. Pour les acides nucléiques, les scores des nucléotides T et U doivent être identiques.

Toutes les méthodes de PiscAmp sont des euristiques : aucune ne garantit l'alignement multiple optimal. Par ailleurs, les algorithmes ne fournissent toujours qu'un seul résultat même si plusieurs alignements ont le même meilleur score.

3. Fonctions complémentaires

En plus de la fonction principale alignLcsMsa, la bibliothèque PiscAmp propose plusieurs autres fonctions pour compléter le traitement des séquences. Voici un aperçu de ces fonctions et de leurs usages.

3.1. Conversions avec sequencesToNum et numToSequences

La fonction sequencesToNum convertit un tableau de séquences représentées par des chaines de caractères en un tableau de tableaux typés Int8Array (nombres entiers signés représentés sur 8 bits de -128 à 127). Cette représentation numérique permet de réaliser des comparaisons plus rapidement entre les séquences. La valeur codant les gaps "-" est toujours 127. Les caractères non reconnus sont codés par −1 et restitués sous la forme "?" par numToSequences.

La fonction numToSequences effectue l'inverse de sequencesToNum, elle convertit une représentation numérique des séquences en leurs versions textuelles. Elle peut prendre en entrée un tableau de tableaux typés ou bien un tableau de tableaux classiques.

Avant de commencer l'analyse des séquences PiscAmp convertit toutes les séquences fournies à alignLcsMsa à l'aide de la fonction sequencesToNum, puis lorsque l'alignement est terminé le résultat est à nouveau converti en tableau de chaines de caractères à l'aide de numToSequences.

3.2. Préparation des paramètres de score avec prepareScoreParams

La fonction prepareScoreParams(scoreParams, alphabetSize) convertit les paramètres de score en une représentation utilisée par les algorithmes internes de PiscAmp. Elle double notamment les scores pour permettre l'application des demi-pénalités aux gaps d'ouverture initiaux et terminaux, et précalcule plusieurs informations sur la matrice de substitution.

Le paramètre alphabetSize correspond au nombre de symboles de l'alphabet : 5 pour les acides nucléiques, 20 pour les protéines, 2 pour les séquences binaires et 26 pour les lettres.

Cette préparation est effectuée automatiquement par alignLcsMsa. Elle ne doit être réalisée manuellement que pour appeler directement certaines fonctions complémentaires, notamment needlemanWunsch et alignProfilesMsa.

3.3. Alignement de deux séquences avec needlemanWunsch

La fonction needlemanWunsch permet d'appliquer l'algorithme classique de Needleman-Wunsch pour réaliser un alignement global de deux séquences. Voici la syntaxe à respecter :

Les paramètres seq1 et seq2 doivent être des tableaux typés de nombres entiers obtenus avec la fonction sequencesToNum. Le paramètre params est obligatoire. Les paramètres freeLeft et freeRight sont facultatifs et ont pour valeur false par défaut.

Les paramètres freeLeft et freeRight permettent d'appliquer une réduction de moitié du cout de l'ouverture d'un gap respectivement au début et à la fin d'une séquence. Cela permet d'encourager le placement en priorité aux extrémités des séquences.

3.4. Alignement de deux alignements avec alignProfilesMsa

Cette fonction effectue un alignement de deux lots de séquences déjà alignées entre elles et qui correspondent aux paramètres prof1 et prof2. Ces deux paramètres sont des tableaux de tableaux typés représentant les séquences de manière numérique. La fonction utilise une euristique d'alignement de profils, et non une optimisation exacte garantie. Un profil peut ne contenir qu'une seule séquence. Si les deux profils n'en contiennent qu'une seule alors l'algorithme donne le même résultat que la fonction précédente (il est alors préférable d'utiliser directement needlemanWunsch). Voici la syntaxe à utiliser :

Le paramètre params est obligatoire comme pour la fonction précédente. Il doit être préalablement préparé par la fonction prepareScoreParams dont les deux arguments sont d'abord les paramètres à préparer, puis la taille de l'alphabet. Le paramètre supplémentaire weightMat est également obligatoire, il représente les pondérations entre les séquences. Si vous souhaitez que toutes les paires de séquences aient le même poids vous pouvez utiliser une matrice remplie de 1. Le paramètre weightMat doit être un tableau de tableaux (donc une matrice) contenant des nombres strictement positifs et non infinis (sauf pour les valeurs de la diagonale qui ne sont jamais utilisées). Elle doit être une matrice carrée symétrique de dimension prof1.length + prof2.length. Les indices des lignes et des colonnes de cette matrice représentent les séquences dans l'ordre où elles apparaissent dans prof1 puis prof2. On peut aussi utiliser la valeur null pour des poids tous égaux. Voici un exemple d'utilisation de cette fonction :

3.5. Calcul de score avec computeMsaScore

Calcule le score d'un alignement multiple de séquences.

3.6. Calcul des poids naturels avec computeNaturalWeightsFromSequences

Cette fonction calcule les poids naturels pour un ensemble de séquences, qu'elles soient déjà alignées ou non. Elle commence par supprimer les gaps éventuellement présents dans les séquences, calcule leurs distances approximatives à partir des k-mères, puis construit un arbre par la méthode du neighbor-joining. Celui-ci permet ensuite de calculer une matrice de poids entre toutes les paires de séquences. L'algorithme repose sur un parcours d'arbre permettant de résoudre astucieusement le problème de la covariance des distances entre les différentes séquences sans avoir à inverser la matrice des covariances.

4. Limites, comparateurs et ressources

Le démonstrateur permet également de comparer PiscAmp à deux méthodes de la bibliothèque externe BioMSA : Diagonal et Complet. Ces méthodes sont accessibles dans les benchmarks de qualité et de vitesse, mais ne font pas partie de la bibliothèque PiscAmp et ne peuvent pas être appelées avec alignLcsMsa.

Vous pouvez adapter et étendre la bibliothèque selon vos besoins particuliers. Si vous avez des questions ou des suggestions, n'hésitez pas à nous contacter ou à participer à l'amélioration du projet.

Un exemple d'intégration de PiscAmp dans un logiciel pédagogique est GenieGen 2.

La bibliothèque PiscAmp est avant tout une bibliothèque ayant des objectifs pédagogiques pour les étudiants en biologie et en bioinformatique. Pour des résultats optimaux, il est préférable d'avoir recours à des logiciels professionnels à la pointe de la recherche scientifique.

Pour une meilleure compréhension des algorithmes d'alignement utilisés dans PiscAmp, vous pouvez consulter les ressources suivantes :

• Alignement de séquences : bien comprendre l'incontournable algorithme de Needleman-Wunsch
• La diversité des algorithmes de clustering