La gestion des noms de résidus est quelque chose qui peut se révéler plus compliqué que prévu si on prends en compte tous les résidus que l’on peut trouver dans des fichiers PDB. Par exemple on peut trouver les molécules d’eau sous plusieurs formes: ‘W’, ‘H2O’, ‘WAT’, ‘HOH’ … toutes aussi acceptables l’une que l’autre. Il faut donc disposer de fonctions assez souples et c’est ce qui a justifié la mise en place d’un module resname.py distinct du module residues.py (voir les articles portant sur la structure de données resmap) dans le paquetage buildez.pdb.

Publication initiale sur buidez.fr (2024) – Article mis à jour en Mai 2025.

1. Pour des résidus standards

Une premier groupe de fonctions est utilisé pour des conversions (pdb_aa2c1l, pdb_aa2c3l) vers des noms de résidus à 3 lettres ou à 1 lettre, et l’identification de résidus standards (pdb_isaaname, pdb_iswatname, pdb_isaatype). Par exemple le code suivant:

Donnera le résultat suivant :

*** Test standard amino acid names conversion/types => use internal default dictionary 'ALA' in 1 letter code = A 'ALA' is known with 3 letters 'ALA' is a residue of type = aa But ... 'Ala' is a residue of type = ukn 'BAF' in 1 letter code = 'BAF' is known with 0 letters 'F' in 3 letters code = PHE 'F' is known with 1 letters 'Z' in 3 letters code = 'Z' is known with 0 letters

Il s’agit de fonctions simplistes mais qui sont utilisées très souvent en tant que primitives par d’autres codes, donc il fallait les implémenter.

2. Résidus non-standard et ligands

Il existe d’autres résidus qui ne correspondent pas à des acides aminés standards, par exemple de la sélénométhionine (Se-Met, SEM) que l’on trouve parfois dans des structures PDB. Il y a aussi les ions, et les composés issus du tampon et co-cristallisés, sans compter les ‘vrais’ ligands (molécules d’intérêt, j’utilise le terme euligands pour ces derniers). Dans ce cas, il faut créer un dictionnaire qui fait la liste de ces résidus avec obligatoirement un alphabet à 3 lettres. Le plus simple est de le coder au format CSVM ce qui permet d’embarquer d’autres informations et de l’utiliser comme source de données.

Il est possible de faire son propre dictionnaire si des résidus ou des composés chimiques inédits, sont susceptibles d’être présents dans la structure. S’il s’agit de composés déjà connus (dans des structures de la PDB) il est possible d’utiliser un document de la PDB qui fait la correspondance entre le nom chimique et celui utilisé dans la PDB (hetcompound dictionary). Une fonction pdb_csvm2resdico permet de charger le fichier CSVM et revoir un dictionnaire Python utilisable par une fonction d’identification des résidus. Par exemple le code suivant :

Donnera un résultat du type :

Il s’agit d’un petit dictionnaire qui recense 241 composés et que l’on peut faire afficher en fonction du nom PDB, par exemple 'ACT' pour un acide acétique chargé et qui contient aussi un type moléculaire: ion, aa (amino acid), nsr (non standard residue) … Le même dictionnaire peut être affiché en fonction du nom chimique, par exemple :

Ce qui donnera un résultat plus explicite :

A partir de ce moment il est assez facile de proposer un code pour déterminer rapidement l’origine de tel ou tel résidu dans un fichier/chaine/table PDB d’après son nom. La fonction pdb_isres3type permet de réaliser simplement ce travail connaissant le nom à 3 lettres du résidu, le dictionnaire Python, et un type par défaut (par exemple 'ukn' ou '-'). On saura immédiatement si le résidu est inconnu (ukn, -) ou s’il est identifiable et dans ce cas quel est son type. Dans l’exemple suivant on va utiliser une liste testn de noms de résidus arbitraires et tester si les correspondances existent :

Ce qui donnera comme résultat la séquence suivante:

=> Testing following residue names ['ALA', 'VAL', 'Ala', 'BAF', 'MSE', 'GLX', 'HOH', 'UKN', 'TER', 'HET', 'ACD', 'NSR', 'ACE', 'ORN', 'SO4']ALA (Alanine) is of type aa VAL (Valine) is of type aa Ala (-) is of type ukn BAF (-) is of type ukn MSE (Selenomethionine) is of type alt GLX (GLU/GLN ambiguous) is of type alt HOH (Water) is of type wat UKN (Unknown) is of type ukn TER (Terminator) is of type naa HET (Heterogen) is of type het ACD (Acidic unknown) is of type alt NSR (Non-Standard residue) is of type naa ACE (Acetyl) is of type nsr ORN (Ornithine) is of type nsr SO4 (sulfate ion) is of type ion

Attention ! Le système est sensible à la casse (cf. cas du résidu ‘Ala’) qui apparaît être de type inconnu. Cela peut être un avantage ou un inconvénient, en fonction du contexte. En tout cas, rien n’empêche de convertir en majuscules systématiquement le nom du résidu avant la recherche dans le dictionnaire.

Nous y retrouvons la sélénométhionine, et nous constatons que dans la nomenclature PDB, elle est identifiée par MSE et non SEM. Cet identifiant est pris par un autre acide aminé modifié la O-benzyl-L-serine :

MSE (Sélénométhionine) Présent en tant que ligand dans 20 entrées PDB, présent en tant qu’acide aminé (dans les chaines polypeptidiques) dans 10177 entrées PDB (mars 2025). [ https://www.rcsb.org/ligand/MSE ]	SEM (O-Benzyl-L-serine) Présent dans 1 entrée PDB en  (mars 2025). [ https://www.rcsb.org/ligand/SEM ]

3. Référentiel

Fonctions du module resname.py en mode abrégé (mai 2025).

Fonction	Utilisation
pdb_isaaname	A partir d’une chaine (string) en majuscules, renvoie 1 ou 3 s’il y a correspondance avec un nom d’AA (acide aminé) standard à 1 lettre ou 3 lettres (sinon zéro). Utilise le dictionnaire interne au module.
pdb_iswatname	A partir d’une chaine (string) en majuscules, renvoie 1 s’il y a correspondance avec le nom (au sens PDB) d’une molécule d’eau (sinon zéro). Utilise le dictionnaire interne au module.
pdb_isaatype	Interface aux fonctions pdb_isaaname et pdb_iswatname mais renvoie une chaine 'aa' ou 'wat' s’il y a correspondance avec un AA standard ou une molécule d’eau. S’il n’y a pas de match, renvoie la chaine 'ukn'  (nom inconnu).
pdb_aa2c1l	A partir d’une chaine (string) en majuscules correspondant à un code d’AA à 3 lettres, renvoie le code à 1 lettre (sinon une chaine vide).
pdb_aa2c3l	A partir d’une chaine (string) en majuscules correspondant à un code d’AA à 1 lettre, renvoie le code à 3 lettres, sinon une chaine vide).
pdb_csvm2resdico	Lit un fichier CSVM incluant des données sur des noms de résidus et le convertir en dictionnaire (Python, pas CSVM) utilisable par le module. Un CSVM de base aa-names.csvm est fourni dans le dossier \pdb\data mais on peut utiliser un autre CSVM.
pdb_dict_resname2restype	Laissé pour compatibilité, appelle fonction pdb_isres3type.
pdb_isres3type	A partir d’un nom de résidu à 3 lettres, utilise un dictionnaire python pour caractériser le résidu correspondant. Renvoie une chaine : 'aa', 'w', 'het', 'alt' … en fonction du contenu du dictionnaire. Sinon renvoie le caractère blank (blank='-' défini par défaut) que l’on peut choisir en tant qu’argument. Si un dictionnaire externe (ex: aa-names.csvm) est utilisé, la fonction pdb_csvm2resdico est un préalable.

4. Données additionnelles

Le fichier CSVM aa-names.csvm peut être étendu au fur et à mesure des besoins, dans sa version 1.03 (mars 2017) il inclue d’autres noms de résidus que les acides aminés, standards ou non, les TABs sont utilisés en tant que caractère délimiteurs (comme dans un fichier CSV).

Il s’agit d’un fichier CSVM de type dictionnaire. Nous trouvons les champs #TITLE, #HEADER, #TYPE, #WIDTH, #META et des commentaires, tous marqués par un caractère #. Ces lignes sont des remarques ou des métadonnées, mais ne seront pas prises en compte dans la table de données (self.DATA au sens CSVM). Mais nous voyons aussi des commentaires en fin de ligne, ils permettent l’utilisation du fichier en tant qu’outil d’interconversion de données dans l’espace CSVM. Avec ce mécanisme, les colonnes MOLNAME et RNAME (voir la ligne #HEADER à la fin du fichier)  sont interchangeables. Par exemple, un fichier CSVM n’incluant que des noms longs, de type MOLNAME (cf. 'Alanine') dans une colonne, peut être converti en une seule opération (voir le paquetage buildez.parsers et le module csvmdict.py), la colonne MOLNAME n’inclura que des noms courts (cf. 'ALA').

Explication – Les dictionnaires CSVM ne sont pas limités qu’à deux colonnes, ils sont conçus pour de l’interconversion de données CSVM pendant la phase de collecte ou de dépôt (‘data museum‘) avant l’intégration dans une ‘vraie’ base de données (typiquement un SGBDR).
Ainsi il est possible que chaque collecteur de données fasse son travail sans s’occuper de la définition d’une norme (ex: noms de colonnes, unités de mesure …) pour collecter des données CSVM (ou CSV annoté). Il suffit de définir un dictionnaire CSVM qui pourra servir de support pour transformer (selon la norme) les différents ilots de données CSVM et ainsi de pouvoir les fusionner, avant curation et intégration dans le SGBDR.

5. Conclusion

A partir d’un concept assez simple nous avons décliné ne série de fonctions assez flexibles et utiles dans des opérations qui mettent en jeu une identification des résidus basés sur le leur nom. C’est un élément important à prendre en compte car il arrive que le bloc PDB de connectivité pour des ligands soit absent ou ambigu (correct pour la cristallographie mais pas forcément vis à vis de la formule chimique). Dans ce cas, nous avons un moyen simple pour le regénérer, avant de faire le nécessaire pour l’intégrer dans la structure (numéros d’atomes, rotamères, éventuellement minimisation locale).