Premiers pas

Cette page guide les premiers pas de l'utilisateur de MyCGR.

On appelle meta_root le répertoire dans lequel sont stockés les fichiers suivant les conventions de nommage. On suppose que le répertoire dans lequel se trouvent les programmes mycgr[...].x est dans la variable PATH de l'utilisateur, de façon à pouvoir les lancer directement d'après leur nom, sans avoir à préciser ce répertoire.

Séquences

Une séquence est représentée par une suite de caractères ascii. Les blancs (espaces, retour chariot, nouvelle ligne, tabulation) sont ignorés. Les caractères suivants sont acceptés:

  • a, A ou 1 pour l'adénine,
  • c, C ou 2 pour la cytosine,
  • g, G ou 3 pour la guanine,
  • t, T ou 4 pour la thymine.

Les autres caractères provoquent une erreur.

Pour l'instant, la représentation interne des séquences est un tableau d'entiers. Cela peut poser problème si on doit charger en entier une séquence de taille supérieure à la taille maximale des tableaux d'entiers en OCaml (un peu plus de 4.000.000 sur une architecture 32 bits). C'est suffisant pour nos applications, sauf dans certains cas (par exemple la génération de séquences pour construire les arbres-CGR) où une autre représentation avec des tableaux plus grands mais plus lents a été développée (en utilisant le module Bigarray de la bibliothèque standard d'OCaml).

Les séquences manipulées sont soit des séquences récupérées dans les bases de génomes séquencés puis mise au format indiqué ci-dessus, soit des séquences générées d'après une loi donnée.

L'outil mycgr_seq.x permet de manipuler des fichiers de séquences. Voici quelques exemples.

La commande suivante génère une séquence i.i.d. de longueur 10000 et de loi (pA,pC,pG,pT)=(0.1,0.2,0.3,0.4); la séquence est stockée dans le fichier file.seq au lieu d'être affichée à l'écran:

mycgr_seq.x --iid 10000 --probs 0.1,0.2,0.3,0.4 -o file.seq

Pour générer une séquence markovienne d'ordre 1 et de matrice de transition (pAA,pAC,pAG,pAT,pCA,pCC,pCG,pCT,pGA,pGC,pGG,pGT,pTA,pTC,pTG,pTT)= (0.1,0.2,0.3,0.4,0.12,0.28,0.3,0.3,0.15,0.35,0.1,0.4,0.1,0.2,0.3,0.4), on fera plutôt:

mycgr_seq.x --markov 1,10000 \
  --mprobs 0.1,0.2,0.3,0.4,0.12,0.28,0.3,0.3,0.15,0.35,0.1,0.4,0.1,0.2,0.3,0.4 -o file.seq

On peut également générer une séquence avec une loi aléatoire, par exemple ici, une séquence markovienne d'ordre 2:

mycgr_seq.x --markov 2,10000 --random-probs -o file.seq

Il n'est guère plus difficile de générer N séquences d'un coup, dans des fichiers distincts dont on donne le préfixe, ici foo. La commande suivante génère 100 fichiers foo_1, foo_2, ..., foo_100, contenant chacun une séquence i.i.d. de longueur 5000 et avec une loi aléatoire pour chacune:

mycgr_seq.x --iid 5000 --random-probs --number foo,100

Il est également possible, à partir des fréquences empiriques des lettres et mots dans une séquences, de calculer une loi pour voir la séquence comme étant i.i.d. ou markovienne. La commande suivante génère une séquence i.i.d. avec une loi de (0.35,0.15,0.1,0.4) et fournit la séquence en entrée d'un deuxième appel à mycgr_seq.x pour en obtenir les fréquences:

mycgr_seq.x --probs 0.35,0.15,0.1,0.4 --iid 10000 | mycgr_seq.x --get-probs

De même, on peut obtenir les probabilités d'une matrice de transition correspondant à une séquence markovienne d'ordre 3, en partant encore d'une séquence i.i.d.:

mycgr_seq.x --probs 0.35,0.15,0.1,0.4 --iid 10000 | mycgr_seq.x --get-mprobs 3

... ou en utilisant la séquence contenue dans un fichier file.seq:

mycgr_seq.x -f file.seq --get-mprobs 3

Une autre fonction utile est le découpage d'une grosse séquence en plusieurs petites, par exemple après avoir récupéré une longue séquence, pour effectuer des calculs sur des morceaux de cette séquence. La commande suivante prend la séquence contenue dans le fichier bigseq.seq et découpe celle-ci en 20 séquences de taille 20000, en les stockant dans les fichiers bigseq_part-0.seq, ..., bigseq_part-19.seq:

mycgr_seq.x -f bigseq.seq --isolate bigseq_part,20000,20000 -n 20 -v

L'option -v demande le mode verbeux. Les paramètres de l'option --isolate sont le préfixe des fichiers générés, la longueur minimale et la longueur maximale des séquences isolées. Cela peut être utile lorsqu'une séquence récupérée comporte des caractères incorrects (par exemple U pour indiquer plusieurs possibilités pour ce nucléotide); si on a déjà trouvé la longueur minimale demandée lorsqu'on rencontre ce caractère, on génère un fichier, sinon on recommence à 0 après le caractère incorrect.

Calcul de la CGR

Dans tout le reste de ce guide, nous détaillons les commandes correspondant à la Chaos Game Representation dans le carré. Des commandes équivalentes existent pour la CGR sur le segment et dans le tétraèdre, en remplaçant square par segment ou tetra dans les noms de commandes.

Les coordonnées des points de la CGR dans le carré pour une séquence donnée dans le fichier file.seq sont affichées par la commande suivante:

mycgr_square.x -f file.seq

A noter, la version ci-dessus lit toute la séquence, calcule toutes les coordonnées puis les affiche. Cela peut poser problème pour de grosses séquences (cf. Séquences). L'option --stream permet d'effectuer le calcul au vol, c'est-à-dire que le programme lit un nucléotide, calcule et affiche les coordonnées du point, puis continue avec le nucléotide suivante. Les coordonnées ne sont pas conservées (sauf le point précédent, bien sûr).

mycgr_square.x -f file.seq --stream
Dessin de la CGR

A partir des coordonnées générées par mycgr_square.x, le programme mycgr_square_draw.x dessine les points de la CGR dans le carré. Ainsi, pour créer un fichier PostScript file.ps contenant le dessin de la CGR dans le carré pour la séquence contenue dans le fichier file.seq, on fera:

mycgr_square.x -f file.seq | mycgr_square_draw.x -o file

Différentes options de mycgr_square_draw.x permettent de changer la taille du dessin, la police, l'affichage ou non des coordonnées, des lettres, d'afficher une vue par fréquences dans des sous-carrés, ...

Zones et partitions

Pour effectuer les tests de structure et calculer les distances entre séquences, on utilise des partitions du carré, du segment ou du tétraèdre. Une partition est une liste de zones, chaque zone de la partition étant une liste de zones simples.

Les partitions sont définies par du texte avec une syntaxe spécifique. Une zone simple peut être:

  • un rectangle, en indiquant les coordonnées des points inférieur gauche et supérieur droit, de la façon suivante: [(x1,y1);(x2,y2)],
  • un cercle, défini par son centre et son rayon, avec la syntaxe C((x,y),r),
  • l'intersection de deux zones simples, notée zone1&zone2,
  • un prédicat, indiqué par le nom d'une fonction prédéfinie, muni éventuellement d'une séquence. Pour savoir si un point vérifie le prédicat, on applique la CGR inverse de la séquence sur ce point et on regarde si la fonction renvoie vrai ou faux. Les fonctions prédéfinies ne sont pas encore documentées; elles sont notamment à base de sinus ou de droites, mais on peut imaginer bien d'autres constructions. La syntaxe est la suivante: name_of_function(), ou name_of_function(sequence). Par exemple: sin1(AC),
  • le complément d'un prédicat, comme indiqué ci-dessus mais avec un '-' devant, par exemple: -sin2(CGT).

Une zone de partition est une liste de zones simples, séparées par des virgules, sur une seule ligne. La zone peut avoir un nom, en mettant ce nom en tête de ligne, suivi de deux points. Par exemple, avec Z1:[(0.0,0.0);(0.1,0.2)],C((0.5,0.5),0.4)&[(0.0,0.5);(1.0,1.0)], on définit une zone "Z1" composée de deux zones simples, l'une étant un rectangle de coordonnées [(0.0,0.0);(0.1,0.2)], l'autre étant l'intersection entre le cercle de centre (0.5,0.5) et de rayon 0.4 et le rectangle [(0.0,0.5);(1.0,1.0)]. Un point sera dans la zone "Z1" s'il appartient à l'une des deux zones simples qui la composent (la virgule signifie donc l'union des zones simples entre lesquelles elle est placée).

Enfin, une partition est une liste de zones de partition, chacune sur une ligne. Il revient à l'utilisateur de s'assurer que ces zones forment bien une partition (pas de chevauchement, notamment). En effet, les méthodes de tests et de distances utilisées sont définies pour des partitions. On pourra au besoin ajouter une zone de partition "vide" de la forme name: (sans zone simple) pour indiquer que cette zone est le complémentaire des autres zones. Une seule zone complémentaire est tolérée par partition.

Exemple

On crée le fichier example_partition.txt avec le contenu suivant:

Z1:[(0.0,0.0);(0.2,0.7)]
Z2:C((0.6,0.5),0.35)
Z3:[(0.1,0.8);(0.3,1.0)]&C((0.1,0.9),0.1)
Z4:

La commande suivante génère un fichier example.ps au format Embedded-PostScript contenant le dessin de cette partition dans le carré. Le carré a 150 pixels de côté, les coordonnées et les lettres des coins ne sont pas affichées, et on utilise 100x100 points pour afficher les zones. Les couleurs des zones étant aléatoires, si le résultat n'est pas satisfaisant, on peut relancer la commande pour obtenir de nouvelles couleurs.

echo -n | mycgr_square_draw.x -o example --guess-draw-zones 100 -I example_partition.txt \
  -b 150 --hide-coords --hide-letters --eps
Cela donne l'image suivante:
Picture of partition
Génération de zones et partitions

Il est également possible de générer automatiquement des zones ou des partitions, grâce au programme mycgr_square_zones.x. Différentes options permettent de générer des partitions aléatoires ou régulières. Par exemple, cette commande génère un fichier random.txt contenant une parition aléatoire composée de 5x5 zones:

mycgr_square_zones.x --random 5 -o random.txt

Utiliser l'option --help de mycgr_square_zones.x pour obtenir la liste des options acceptées.

Zones et partitions dans le segment et le tétraèdre

La différence avec le carré se situe au niveau des zones simples.

Sur le segment, les zones simples ne peuvent être que des intervalles de la forme [x1;x2].

Dans le tétraèdre, les zones simples ne peuvent être pour l'instant que des tétraèdres, définis pas leurs quatre sommets avec la syntaxe suivante: [(x1,y1,z1);(x2,y2,z2);(x3,y3,z3);(x4,y4,z4)].

Tests de structure

Les simulations pour la nouvelle famille de tests introduite dans la thèse de Peggy Cénac sont réalisés à l'aide des programmes mycgr_square_vn.x (test d'indépendance) et mycgr_square_test_markov.x (test de dépendance markovienne d'un ordre donné). Voici quelques exemples d'utilisation.

La commande suivante permet d'effectuer le test d'indépendance sur 1000 séquences i.i.d. générées ayant chacune une loi de génération aléatoire. Pour ces séquences, on calcule la statistique du test d'indépendance et on accepte ou on rejette chaque séquence avec un quantile correspondant à un niveau d'acceptation de 5%. On réalise ces calculs pour des tailles de séquences de 500,1000,2000,5000 et 10000. Enfin, nous réalisons ces tests pour 3 partitions différentes qui se trouvent dans les fichiers zones_pearson.txt, zones_square_9_random.txt et zones_square_9_equi.txt. Le résultat est ajouté à la fin du fichier test.tex.

mycgr_square_vn.x --nb 1000 --lengths 500,1000,2000,5000,10000 --gen-order 0 \
   -I zones_pearson.txt -I zones_square_9_random.txt -I zones_square_9_equi.txt \
   -O test.tex

On peut réaliser le même test mais en générant des séquences markoviennes d'ordre 1:

mycgr_square_vn.x --nb 1000 --lengths 500,1000,2000,5000,10000 --gen-order 1 \
   -I zones_pearson.txt -I zones_square_9_random.txt -I zones_square_9_equi.txt \
   -O test.tex

Le contenu du fichier test.tex peut-être inclus dans un document LaTeX et compilé. On obtient des résultats de cette forme.

Pour réaliser le test de structure markovienne d'un certain ordre, on utilise de façon similaire le programme mycgr_square_test_markov.x. Par exemple, tester si des séquences sont markoviennes d'ordre 1 en générant des séquences markoviennes d'ordre 1:

mycgr_square_test_markov.x --order 1 --nb 1000 --lengths 500,1000,2000,5000 \
   --gen-order 1 \
   -I zones_pearson.txt -I zones_square_9_random.txt -I zones_square_9_equi.txt \
   -O test.tex

Un dernier exemple, en générant des séquences markoviennes mixées:

mycgr_square_test_markov.x --order 1 --nb 1000 --lengths 500,1000,2000,5000 \
   --mixed-markov 1,3 \
   -I zones_pearson.txt -I zones_square_9_random.txt -I zones_square_9_equi.txt \
   -O test.tex
Programmes de haut niveau

mycgr_meta.x et mycgr.x sont des programmes dits "de haut niveau" car ils offrent l'accès aux fonctionnalités des autres programmes de façon simplifiée et en gérant la convention de nommage des fichiers et répertoires.

Lors de la compilation de MyCGR, le répertoire meta_root par défaut a été fixé. On peut en indiquer un autre à l'exécution par l'intermédiaire de la variable d'environnement MYCGR_META_ROOT.

La première chose à faire, avant d'utiliser les deux outils ci-dessus, est de créer l'arborescence sous meta_root. Cela est réalisé par la commande suivante:

mycgr_meta.x --build-root -v

Les répertoires créés sont affichés. Il est alors possible de placer dans le répertoire meta_root/sequences des fichiers de séquences récupérés dans les banques de génomes. Seuls les fichiers ayant l'extension .seq sont considérés comme des séquences dans ce répertoire. Une fois que c'est fait, on peut découper ces séquences en sous-séquences pour les utiliser dans les calculs de distances entre espèces (cf. Taxonomie). La commande suivante permet de découper les séquences "originales" en séquences de 100000 bases, en ne créant que 5 sous-séquences par fichier original (-v est pour le mode verbeux):

mycgr_meta.x --add-size 100000,5 -v

L'utilisation de l'interface graphique mycgr.x est plus aisée et permet de parcourir facilement les répertoires sous meta_root. Ce programme nécessite une base de données MySQL, car il y stocke certaines informations pour la manipulation des arbres-CGR (cf. Chapitre 3 de la thèse). Par défaut, la base de données à laquelle mycgr.x se connecte est mycgr sur localhost, avec comme nom d'utilisateur le login de l'utilisateur. Les options -d, -h et -u permettent de spécifier une base, une machine et un utilisateur. Pour créer la base mydb et pouvoir l'utiliser avec l'utilisateur myuser depuis la machine localhost, il faut se connecter en tant qu'administrateur à MySQL et entrer les commandes suivantes:

create database mydb;
grant all privileges on mydb.* to myuser@localhost;

Consulter la documentation de MySQL pour plus de détails.

Une fois que la base est configurée, il faut l'initialiser en créant les tables:

mycgr_meta.x --create-db [-h ...] [-u ...] [-d ...]

Ensuite, on peut lancer mycgr.x pour accéder à l'interface graphique, par laquelle on peut manipuler les séquences, les zones, les résultats et les arbres-CGR. Voyons son utilisation pour réaliser des arbres taxonomiques, dans la section suivante.

Taxonomie

Nous allons créer un arbre taxonomique d'espèces à partir des séquences disponibles dans meta_root/sequences.

Les noms de fichiers des séquences originales sont importants, car ils sont repris lors du découpage des séquences (on leur ajoute -n avec n un numéro affecté lors du découpage des séquences). Par la suite, lors du regroupement par espèce des distances entre séquences, on se base sur le nom du fichier pour savoir quelles séquences font partie de la même espèce. A partir d'un nom de fichier, le nom de l'espèce est récupéré de la manière suivante: On cherche dans le nom le premier caractère qui ne soit pas une lettre ou un '-' et on isole la partie qui précède (privée éventuellement du '-' final) pour s'en servir comme nom d'espèce. Par exemple, à partir des fichiers Euk-mae-homsa1-0.seq et Bac-p-braj-0.seq, les noms d'espèces isolés sont respectivement Euk-mae-homsa et Bac-p-braj.

On commence par découper les séquences originales disponibles dans meta_root/sequences pour créer 5 séquences de taille 100000 par fichier original. Pour cela, on utilise le menu Sequences/Add size et on saisit 100000 comme longueur et 5 comme nombre maximum de fichiers par séquence originale.

Il faut ensuite définir une partition du carré, si l'on veut faire les calculs de distances avec la CGR sur le carré. A compléter pour la création de zones depuis l'interface. Pour l'instant, les fichiers de zones doivent êtres ajoutés à la main dans le bon répertoire.

Il ne reste plus qu'à lancer les calculs par l'intermédiaire du menu Dists/Cenac dists. Dans la boîte de dialogue qui s'ouvre, on indique

  • la longueur des séquences à utiliser (celle que l'on vient de créer par exemple),
  • la méthode de CGR (le carré),
  • le fichier de partition,
  • si l'on souhaite ajouter aux séquences, lors des calculs, leur complément inversé,
  • la méthode de calcul de distance, par exemple AbsRn.

Il ne reste plus qu'à valider et attendre. Lorsque les calculs sont terminés, les résultats sont visibles dans l'onglet "Results", dans la longueur choisie. Un double-clic sur un fichier de résultat permet de l'afficher. A noter, il faut parfois utiliser le menu "View/Refresh" pour voir s'afficher les fichiers de résultats qui viennent d'être créés.