Documentation de PiscAmp

<< Retour au démonstrateur PiscAmp

La bibliothèque PiscAmp est conçue pour réaliser des alignements multiples de séquences 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

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 :

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Intégration de Piscamp</title> <!-- Inclusion de la bibliothèque Piscamp --> <script src="chemin/vers/piscamp.js" defer></script> </head> <body> <h1>Mon Application d'Alignement Multiple</h1> <!-- Votre contenu --> </body> </html>

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/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. Exemples d’Utilisation de la Fonction Principale

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'appellez. Voici la syntaxe de cette fonction :

const alignment = await alignLcsMsa(sequences, type, method, thresholdProb, params);

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

  • sequences : Array (obligatoire) — Un tableau contenant les séquences à aligner. Chaque séquence est représentée par une chaine de caractères.
  • type : String (obligatoire) — Le type de séquences à aligner. Cela peut être "DNA", "RNA", "NA" (permet d'aligner des ARN et des ADN en considérant que U et T sont le même résidu), ou "protein".
  • method : String (obligatoire) — La méthode d'alignement à utiliser. Les valeurs possibles sont "star" pour un alignement en étoile (le plus rapide et le moins précis), "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 et l'alignement itératif.
  • 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. Une valeur de 0 rend le découpage des séquences impossible, ce qui peut ralentir substantiellement l'alignement.
  • params : 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 :

// Exemple d'alignement de séquences ADN const sequences = ["TGCGTGCCTT", "TCCGCATTGA", "CAGTTAGTTT"]; const type = "DNA"; const method = "progressive"; const alignment = await alignLcsMsa(sequences, type, method); console.log(alignment);

Trois ensembles de paramètres sont prédéfinis dans PiscAmp comme variables globales. C'est balancedDNAParams qui est utilisé par défaut si vous ne spécifiez pas le paramètre params. Voici le détail des valeurs utilisées :

// Paramètres très simples mais peu réalistes, pour les séquences extrêmement similaires const simplestDNAParams = { match: 1, tiCost: -1, tvCost: -1, gapOpen: -1, gapExtend: -1, } // Paramètres simples pour les séquences très similaires const conservativeDNAParams = { match: 1, tiCost: -1, tvCost: -1, gapOpen: -4, gapExtend: -1, }; // Paramètres équilibrés, pour tout type de séquences const balancedDNAParams = { match: 2, tiCost: -1, tvCost: -2, gapOpen: -8, gapExtend: -1, };

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

// Format 1/3-bit scaling // Acides aminés dans l'ordre alphabétique (code une lettre) const VTML240 = { matCost: [ [3, 1, -1, 0, -2, 0, -1, -1, -1, -1, -1, 0, 0, 0, -1, 1, 1, 0, -4, -2], [1, 11, -3, -3, -2, -2, -1, 0, -3, -2, 0, -2, -2, -3, -2, 1, 0, 1, -5, 0], [-1, -3, 6, 3, -5, 0, 0, -4, 0, -4, -3, 2, -1, 1, -1, 0, 0, -3, -5, -4], [0, -3, 3, 4, -4, -1, 0, -3, 1, -3, -2, 1, -1, 2, 0, 0, 0, -2, -5, -3], [-2, -2, -5, -4, 7, -5, 0, 1, -4, 2, 2, -3, -3, -3, -3, -2, -2, 0, 3, 5], [0, -2, 0, -1, -5, 7, -2, -5, -1, -5, -4, 0, -2, -1, -2, 0, -1, -3, -4, -4], [-1, -1, 0, 0, 0, -2, 7, -2, 0, -2, -2, 1, -1, 1, 1, 0, -1, -2, -1, 2], [-1, 0, -4, -3, 1, -5, -2, 4, -3, 3, 2, -3, -3, -2, -3, -2, 0, 3, -1, -1], [-1, -3, 0, 1, -4, -1, 0, -3, 4, -2, -2, 1, -1, 2, 3, 0, 0, -2, -4, -2], [-1, -2, -4, -3, 2, -5, -2, 3, -2, 4, 3, -3, -2, -2, -2, -2, -1, 2, -1, 0], [-1, 0, -3, -2, 2, -4, -2, 2, -2, 3, 5, -2, -3, -1, -2, -2, 0, 2, -2, -1], [0, -2, 2, 1, -3, 0, 1, -3, 1, -3, -2, 4, -1, 1, 0, 1, 0, -3, -4, -1], [0, -2, -1, -1, -3, -2, -1, -3, -1, -2, -3, -1, 8, 0, -1, 0, -1, -2, -4, -4], [0, -3, 1, 2, -3, -1, 1, -2, 2, -2, -1, 1, 0, 4, 2, 0, 0, -2, -5, -2], [-1, -2, -1, 0, -3, -2, 1, -3, 3, -2, -2, 0, -1, 2, 6, 0, -1, -2, -3, -2], [1, 1, 0, 0, -2, 0, 0, -2, 0, -2, -2, 1, 0, 0, 0, 3, 2, -1, -3, -2], [1, 0, 0, 0, -2, -1, -1, 0, 0, -1, 0, 0, -1, 0, -1, 2, 3, 0, -4, -2], [0, 1, -3, -2, 0, -3, -2, 3, -2, 2, 2, -3, -2, -2, -2, -1, 0, 4, -3, -2], [-4, -5, -5, -5, 3, -4, -1, -1, -4, -1, -2, -4, -4, -5, -3, -3, -4, -3, 14, 4], [-2, 0, -4, -3, 5, -4, 2, -1, -2, 0, -1, -1, -4, -2, -2, -2, -2, -2, 4, 8] ], gapOpen: -12, gapExtend: -2, }

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

3. Autres Fonctions Utiles

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.

const sequences = ["ATCG", "TACC", "GCGT"]; const seqNums = sequencesToNum(sequences, "DNA"); console.log(seqNums); // Affiche dans la console : // Array(3) // 0: Int8Array(4) [0, 3, 2, 1, buffer: ArrayBuffer(4), byteLength: 4, byteOffset: 0, length: 4, Symbol(Symbol.toStringTag): 'Int8Array'] // 1: Int8Array(4) [3, 0, 2, 2, buffer: ArrayBuffer(4), byteLength: 4, byteOffset: 0, length: 4, Symbol(Symbol.toStringTag): 'Int8Array'] // 2: Int8Array(4) [1, 2, 1, 3, buffer: ArrayBuffer(4), byteLength: 4, byteOffset: 0, length: 4, Symbol(Symbol.toStringTag): 'Int8Array'] // length: 3 // [[Prototype]]: Array(0)

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.

const sequences = numToSequences([[0, 1, 2], [1, 0, 3]], "DNA"); console.log(sequences); // Affiche dans la console : // (2) ['AGC', 'GAT'] // 0: "AGC" // 1: "GAT" // length: 2 // [[Prototype]]: Array(0)

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

needlemanWunsch(seq1, seq2, type, params, freeLeft = false, freeRight = false);

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

const seq1 = sequencesToNum(["AATTGGCC"], "DNA")[0]; const seq2 = sequencesToNum(["AAGGCC"], "DNA")[0]; const alignment = needlemanWunsch(seq1, seq2, "DNA", balancedDNAParams); console.log(numToSequences(alignment, "DNA")); // Affiche dans la console : // (2) ['AATTGGCC', 'AA--GGCC'] // 0: "AATTGGCC" // 1: "AA--GGCC" // length: 2 // [[Prototype]]: Array(0)

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.3. 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. L'algorithme effectue un alignement optimal sans réduire les profiles à des fréquences de résidus. Un profile peut ne contenir qu'une seule séquence. Si les deux profiles n'en contiennent qu'une seule alors l'Algorithme donne le même résultat que la fonction précédente. Voici la syntaxe à utiliser :

alignProfilesMsa(prof1, prof2, type, params, weightMat, freeLeft = false, freeRight = false);

Le paramètres params est obligatoire comme pour la fonction précédente. 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. Voici un exemple d'utilisation de cette fonction :

const seq1 = sequencesToNum(["AATTGGCC"], "DNA")[0]; const seq2 = sequencesToNum(["AAGGCC"], "DNA")[0]; const seq3 = sequencesToNum(["AATTGGCC"], "DNA")[0]; const seq4 = sequencesToNum(["AATTGGAACC"], "DNA")[0]; const alignA = needlemanWunsch(seq1, seq2, "DNA", balancedDNAParams); const alignB = needlemanWunsch(seq3, seq4, "DNA", balancedDNAParams); const weights = [ [1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1] ]; // Poids tous égaux const alignment = alignProfilesMsa(alignA, alignB, "DNA", balancedDNAParams, weights); console.log(numToSequences(alignA, "DNA")); console.log(numToSequences(alignB, "DNA")); console.log(numToSequences(alignment, "DNA")); // Affiche dans la console : // (2) ['AATTGGCC', 'AA--GGCC'] // (2) ['AATTGG--CC', 'AATTGGAACC'] // (4) ['AATTGG--CC', 'AA--GG--CC', 'AATTGG--CC', 'AATTGGAACC']

3.4. Calcul de score avec computeMsaScore

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

computeMsaScore(sequences, type, params = null, weights = null) const sequences = ["ATCG", "TACC", "GCGT"]; const type = "DNA"; const score = computeMsaScore(sequences, type); console.log(score); // Affiche le score de l'alignement dans la console : // -5.666666666666667

3.5. Calcul des poids naturels avec computeNaturalWeightsFromSequences

Cette fonction calcule les poids naturels pour un ensemble de séquences alignées. Elle construit 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.

const seqNums = sequencesToNum(["ATCG", "TACC", "GCGT"], "DNA"); const type = "DNA"; const naturalWeights = computeNaturalWeightsFromSequences(seqNums, type); console.log(naturalWeights);

4. Ressources complémentaires

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.

Lien GenieGen2

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 :