Accès à la base de données InterPro

Prérequis

uv : Lisez la skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible via PATH.
Notification utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette skill, alors (1) notifiez l'utilisateur de manière bien visible pour qu'il consulte les conditions à https://www.ebi.ac.uk/interpro/ et https://www.ebi.ac.uk/about/terms-of-use/, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.

Aperçu

InterPro combine les signatures de plusieurs bases de données variées dans une seule ressource consultable, réduisant la redondance et aidant les utilisateurs à interpréter les résultats de leur analyse de séquences. En unissant ces bases de données membres (par exemple Pfam, CDD, SMART), InterPro capitalise sur leurs forces respectives pour produire un outil de diagnostic puissant et une ressource intégrée.

Utilisez interpro-database pour :

Identifier les domaines, familles et sites trouvés dans une protéine particulière.
Identifier toutes les protéines appartenant à une famille de protéines ou contenant un domaine particulier, même lorsque les noms et activités des protéines sont très variables.
Examiner les espèces dans lesquelles une famille de protéines ou un domaine particulier se trouve.
Annoter les génomes avec des informations sur les familles de protéines et des termes Gene Ontology (GO).

Cette skill fournit un utilitaire robuste, interpro_client.py, pour interagir avec l'API InterPro de façon fluide. Elle gère nativement la limitation de débit (HTTP 429), le suivi du repos des requêtes en arrière-plan (HTTP 408), les erreurs terminales (HTTP 404/410) et la pagination paresseuse.

Règles essentielles

Utilisez le wrapper : EXÉCUTEZ TOUJOURS le script helper scripts/interpro_client.py pour interroger la base de données au lieu d'y accéder directement. Les scripts appliquent automatiquement l'utilisation équitable et mettent en place une logique de nouvelle tentative.
Pour les requêtes exploratoires : UTILISEZ TOUJOURS la CLI avec un --limit strict. Cela vous permet de comprendre rapidement le schéma des données sans surcharger votre context window ou récupérer des millions de résultats.
Sortie dans un fichier : Utilisez la CLI avec --output pour diriger la sortie vers un fichier au lieu de tout afficher à la console. Traitez la sortie avec jq ou du code.
Pour les pipelines plus complexes, importez le module nativement dans vos scripts Python pour consommer le générateur directement, évitant d'avoir à désérialiser les chaînes CLI dans les grands workflows.
Notification : Si cette skill est utilisée, assurez-vous que cela figure dans la sortie.

Exemples :

uv run ./scripts/interpro_client.py fetch protein --source_db reviewed --limit 2 --query_params tax_id=9606 --output exploratory_results.jsonl

import sys
sys.path.append('scripts')
from interpro_client import fetch_interpro_data
import itertools

# fetch_interpro_data produit paresseusement les résultats page par page
results = fetch_interpro_data(
    endpoint="entry",
    source_db="pfam",
    query_params={"page_size": 10}
)
for match in itertools.islice(results, 10):
    print(match["metadata"]["accession"])

4 façons de construire des endpoints :

Les arguments correspondent strictement aux quatre constructions de chemins API courantes. Ne formatez pas vos propres chaînes séparées par / :

/{endpoint} (ex. /entry) uv run ./scripts/interpro_client.py fetch entry --limit 10 --output entries.jsonl
/{endpoint}/{sourceDB} (ex. /entry/pfam) uv run ./scripts/interpro_client.py fetch entry --source_db pfam --limit 10 --output pfam_entries.jsonl
/{endpoint}/{sourceDB}/{accession} (ex. /entry/pfam/PF00001) uv run ./scripts/interpro_client.py fetch entry --source_db pfam --accession PF00001 --limit 10 --output pf00001_entry.jsonl
/{endpoint}/{sourceDB}/{linked_endpoint}/{sourceDB}/{accession} (ex. /entry/interpro/protein/uniprot/P04637) uv run ./scripts/interpro_client.py fetch entry \ --source_db interpro \ --linked_endpoint protein \ --linked_source_db uniprot \ --linked_accession P04637 \ --limit 10 --output p04637_entries.jsonl

Bases de données sources valides (`--source_db`)

Chaque endpoint n'accepte que des valeurs source_db spécifiques. L'utilisation d'une valeur invalide retourne une erreur 404.

/entry (16 valeurs) : interpro, pfam, cathgene3d, ssf, panther, cdd, profile, smart, ncbifam, prosite, prints, hamap, pirsf, sfld, antifam.
/protein (3 valeurs) : uniprot (tous), reviewed (SwissProt), unreviewed (TrEMBL).
/structure (1 valeur) : pdb.
/taxonomy (1 valeur) : uniprot.
/proteome (1 valeur) : uniprot.
/set (2 valeurs) : pfam, cdd.

Référence rapide / Endpoints essentiels et paramètres

Pour une liste complète et exhaustive de tous les paramètres de requête, voir la Référence API complète.

L'API est entièrement ouverte et supporte 6 endpoints principaux. Vous pouvez les combiner en utilisant les paramètres liés décrits ci-dessus. Voici une liste imbriquée des paramètres de requête spécifiques disponibles pour chaque endpoint :

/entry (Entrées de domaine, famille, site actif, répétition ou superfamille homologue)
- integrated : Filtrer par statut intégré (ex. pfam).
- type : Filtrer par type (ex. family, domain, homologous_superfamily).
- go_term / go_category : Filtrer par Gene Ontology.
- ida_search / ida_ignore / exact / ordered : Filtrer par architecture de domaine (voir section Recherche IDA).
- extra_fields : Demander des données supplémentaires (ex. counters pour les coordonnées d'appariement).
- group_by / sort_by : Agréger ou trier les résultats (les valeurs valides dépendent du contexte, voir Référence API complète).
- Exemple : uv run ./scripts/interpro_client.py count entry --source_db pfam --query_params type=domain --output count.jsonl
/protein (Enregistrements de protéines correspondant aux entrées ou domaines)
- tax_id : Filtrer par identifiant taxonomique (ne recherche pas la lignée).
- match_presence : Filtrer les protéines ayant des appariements InterPro (true/false).
- is_fragment : Filtrer les séquences complètes par rapport aux fragments.
- group_by : Agréger les résultats (ex. taxonomy).
- extra_fields : Demander les détails de séquence ou d'appariement.
- isoforms / residues / structureinfo : Inclure des sous-fonctionnalités spécifiques.
- conservation / extra_features : Ajouter des drapeaux de conservation des résidus ou des fonctionnalités Mobidb/coil (valide uniquement pour /protein/{source_db}/{accession}).
- Exemple : uv run ./scripts/interpro_client.py fetch protein --source_db uniprot --limit 20 --query_params tax_id=9606 --output human_proteins.jsonl
/structure (Structures PDB liées aux entrées InterPro)
- experiment_type : Filtrer par méthode expérimentale (ex. X-RAY DIFFRACTION).
- resolution : Filtrer par limite de résolution.
- extra_fields : Inclure des métadonnées structurales supplémentaires.
- group_by : Agréger les résultats.
- Exemple : ./scripts/interpro_client.py fetch structure --source_db pdb --accession 1ATP --limit 10 --output 1atp_structures.jsonl
/taxonomy (Nœuds de distribution taxonomique)
- key_species : Filtrer pour se limiter aux espèces clés.
- with_names : Inclure les noms scientifiques.
- filter_by_entry / filter_by_entry_db : Filtrer l'intersection avec des entrées spécifiques.
- extra_fields : Métadonnées taxonomiques supplémentaires.
- Exemple : ./scripts/interpro_client.py fetch taxonomy --source_db uniprot --accession 9606 --limit 10 --output human_taxonomy.jsonl
/proteome (Protéomes complets liés à InterPro)
- extra_fields : Expansion de requête générale.
- Exemple : uv run ./scripts/interpro_client.py fetch proteome --source_db uniprot --accession UP000005640 --limit 10 --output proteome.jsonl
/set (Ensembles organisés d'entrées connexes, par ex. clans Pfam)
- extra_fields : Métadonnées supplémentaires (valide uniquement pour /set/{sourceDB}).
- Exemple : uv run ./scripts/interpro_client.py fetch set --source_db pfam --accession CL0001 --limit 10 --output pfam_clan.jsonl

Recherche d'architecture de domaine InterPro (IDA)

InterPro fournit des outils puissants pour rechercher les protéines par leur architecture de domaine (la combinaison et l'ordre exacts des domaines). Comme l'API ne permet pas d'interroger les protéines directement par plusieurs domaines à la fois (par ex. « donnez-moi les protéines avec PF00069 ET PF00017 »), trouver les protéines avec des combinaisons de domaines spécifiques nécessite un processus en deux étapes.

Étape 1 : Trouver les architectures correspondantes (`ida_search`)

Le paramètre ida_search est utilisé sur l'endpoint racine /entry pour trouver toutes les architectures de domaine (IDA) contenant les domaines que vous spécifiez.

Contraintes :
- Valide UNIQUEMENT sur l'endpoint racine /entry.
- Ne peut pas être combiné avec des paramètres non-IDA.
Modificateurs (Valides uniquement avec ida_search) :
- ida_ignore : Ignore les domaines donnés dans la recherche (paramètre de requête).
- ordered : Assure que les domaines apparaissent dans l'ordre spécifié exact (drapeau).
- exact : Assure que l'architecture correspond exactement (pas de domaines supplémentaires) (drapeau). Nécessite que le drapeau ordered soit présent.

Exemple : Trouver les architectures contenant à la fois un domaine kinase (PF00069) et un domaine SH2 (PF00017), dans cet ordre exact :

uv run scripts/interpro_client.py fetch entry
  --query_params ida_search=PF00069,PF00017
  --flags ordered exact
  --output architectures.jsonl

Remarque : Ceci retourne les architectures et leurs ida_ids uniques, pas toutes les protéines individuelles.

Étape 2 : Récupérer les protéines pour ces architectures (`ida`)

Une fois que vous avez les ida_ids (par ex. 619edbb...) de l'étape 1, vous pouvez récupérer toutes les protéines actuelles qui partagent cette disposition précise en filtrant l'endpoint /protein.

Contraintes :

Valide sur les endpoints /protein et /entry/{sourceDB}/{accession}.

Exemple : Récupérer les protéines correspondant à l'un des identifiants d'architecture de l'étape 1 :

uv run scripts/interpro_client.py fetch protein
  --source_db uniprot
  --query_params ida=619edbb2b445bfa3ad51bd894e3c115b025a5f25
  --output matching_proteins.jsonl

(Lors de la construction de pipelines ou d'interrogations complètes, vous bouclez sur tous les ida_ids de l'étape 1 et exécutez l'étape 2 pour chacun).

Types d'entrées InterPro

Chaque entrée InterPro se voit assigner un type indiquant ce que vous pouvez déduire lorsqu'une protéine correspond à l'entrée :

Domain : Unités fonctionnelles, structurelles ou de séquence distinctes qui peuvent exister dans de nombreux contextes biologiques. Exemple : domaine PH ou doigt de zinc C2H2 classique.
Family : Un groupe de protéines partageant une origine évolutive commune reflétée par des fonctions connexes, des similarités de séquence ou des structures primaires/secondaires/tertiaires.
Homologous Superfamily : Protéines partageant une origine évolutive reflétée par la similarité structurelle mais affichant souvent une très faible similarité de séquence. Comprend généralement les signatures des bases de données SUPERFAMILY et CATH-Gene3D.
Repeat : Une courte séquence typiquement répétée dans une protéine, souvent <50 acides aminés. Exemple : Leucine Rich Repeats ou répétitions WD40.
Site : Inclut les sites actifs (séquence contenant des résidus conservés pour l'activité catalytique) et les sites de liaison (séquence contenant des résidus conservés formant un site d'interaction protéique).

Prédictions InterPro-N

InterPro-N est une extension basée sur l'apprentissage profond de la base de données InterPro standard. Elle utilise une architecture IA inspirée par la vision par ordinateur pour traiter l'annotation de séquence protéique comme une tâche de « segmentation panoptique », étiquetant les résidus et distinguant les domaines.

Quand utiliser InterPro-N

Les signatures InterPro standard sont le « standard or » et ne doivent pas être abandonnées en faveur des prédictions InterPro-N. Utilisez InterPro-N principalement pour combler les lacunes ou affiner les résultats.

En plus d'InterPro standard :

Analyser la « Matière noire » (Protéines non caractérisées) : À utiliser lorsqu'une protéine ne retourne pas de résultats dans InterPro standard. InterPro-N excelle à identifier les homologues distants.
Résoudre les répétitions complexes : À utiliser pour les protéines avec plusieurs répétitions en tandem (ex. TPR ou WD40) où les HMM standard pourraient les fusionner ou les manquer.
Prédire les domaines discontinus : À utiliser lorsqu'une séquence de domaine est interrompue par une séquence insertée complètement différente.

À la place d'InterPro standard (scénarios spécifiques) :

Délimitation précise des limites : Lorsque vous avez besoin de coordonnées de début et d'arrêt plus précises pour un domaine que ce que les résultats floue standard fournissent.
Criblage métagénomique à grande échelle : Pour un criblage initial à récupération élevée de séquences fragmentées ou hautement divergentes.

Stratégie de secours : Vérification d'InterPro-N

Lorsqu'on vous demande de trouver les annotations pour une protéine et que les requêtes InterPro standard ne retournent aucun résultat ou aucune annotation, vous DEVEZ vérifier InterPro-N comme secours.

Scénario d'exemple : Si un utilisateur demande « Listez les annotations SSF pour la protéine X » et la requête standard ne retourne aucun résultat, vous devez réessayer la requête avec le drapeau interpro_n.

Ce secours est crucial car InterPro-N peut identifier les homologues distants et les domaines dans les protéines de « matière noire » que les méthodes standard manquent.

Si trouvé, SIGNALEZ TOUJOURS à l'utilisateur que ces annotations sont des prédictions d'apprentissage profond d'InterPro-N.

Comment utiliser

Les prédictions InterPro-N sont accessibles en passant le drapeau interpro_n à l'endpoint protein avec uniprot comme base de données source.

Via CLI :

uv run ./scripts/interpro_client.py fetch protein
    --source_db uniprot
    --accession A0A096LNN2
    --flags interpro_n
    --output A0A096LNN2_interpro_n.jsonl

Via pipeline Python :

results = fetch_interpro_data(
    endpoint="protein",
    source_db="uniprot",
    accession="A0A096LNN2",
    flags=["interpro_n"])

Règles de recherche strictes

Utilisez toujours les accessions UniProt, JAMAIS les noms de gènes : Lorsque vous recherchez des protéines dans InterPro, vous DEVEZ utiliser leurs accessions UniProt (ex. P04637). InterPro ne supporte pas nativement ou ne mappe pas de manière fiable les noms de gènes (ex. TP53). Si l'utilisateur fournit un nom de gène, vous devez d'abord utiliser une base de données comme Ensembl ou UniProt pour le résoudre en une accession.
NE PAS itérer pour compter : Lorsqu'on vous demande un nombre agrégé (par ex. « Combien de domaines y a-t-il ? »), vous DEVEZ lire le champ count de la réponse JSON initiale de l'API en utilisant le helper get_interpro_count(). NE JAMAIS itérer sur le générateur fetch_interpro_data pour compter les éléments. Itérer sur un endpoint avec 50 000+ entrées juste pour les compter gèle silencieusement l'agent et abuse de l'API. À chaque fois. Aucune exception.

✅ Correct :

Via CLI :
```
uv run ./scripts/interpro_client.py count entry
    --source_db interpro
    --query_params type=domain
    --output count.json
```
Via pipeline Python :
```
from interpro_client import get_interpro_count
cnt = get_interpro_count(
    endpoint="entry",
    source_db="interpro",
    query_params={"type": "domain"},
)
```
❌ Faux (Itérer sur fetch) :
```
# NE FAITES JAMAIS CELA :
uv run ./scripts/interpro_client.py fetch entry
    --source_db interpro
    --query_params type=domain
    --output output.jsonl
    && wc -l output.jsonl
```

Exemples rapides

Pour des exemples détaillés des appels et des schémas de sortie JSON retournés par différents endpoints, voir la Référence des réponses d'exemple. Ce TSV contient les appels de ligne de commande, les équivalents Python et les structures de payload JSON correspondantes.

1. Déterminer tous les domaines protéiques

# Récupère les entrées InterPro au sein de la protéine UniProt P04637
# Équivalent URL : /entry/interpro/protein/uniprot/P04637
uv run ./scripts/interpro_client.py fetch entry
    --source_db interpro
    --linked_endpoint protein
    --linked_source_db uniprot
    --linked_accession P04637
    --output p04637_domains.jsonl

2. Récupérer toutes les structures PDB pour une entrée

# Équivalent URL : /structure/pdb/entry/interpro/IPR011615
# Récupère uniquement les 5 premières structures
uv run ./scripts/interpro_client.py fetch structure
    --source_db pdb
    --linked_endpoint entry
    --linked_source_db interpro
    --linked_accession IPR011615
    --output ipr011615_structures.jsonl