Skill RCSB Protein Data Bank

Prérequis

1. uv : Consultez le skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible dans le PATH.
2. Notification utilisateur : Si LICENSE_NOTIFICATION.txt n'existe pas déjà dans ce répertoire de skill, alors (1) notifiez l'utilisateur de manière bien visible pour consulter les conditions sur https://www.rcsb.org/pages/usage-policy, puis (2) créez le fichier en enregistrant le texte et l'horodatage de la notification.

Règles fondamentales

• Préférez toujours les scripts fournis. N'utilisez curl, urllib, les requêtes HTTP brutes ou toute autre méthode pour accéder aux APIs PDB qu'en dernier recours. Les scripts appliquent automatiquement les limites de débit requises.
• Redirigez toujours la sortie vers un fichier. Analysez la sortie avec par exemple jq, grep, ou un court snippet Python. N'imprimez PAS les grandes réponses API sur stdout pour éviter la troncature.
• Notification : Si ce skill est utilisé, assurez-vous que cela soit mentionné dans la sortie.
• Expliquez vos requêtes : Après avoir complété une tâche utilisant des requêtes PDB JSON/GraphQL, expliquez en langage clair ce que votre requête a fait afin que l'utilisateur puisse corriger les mauvaises hypothèses.

Workflow de recherche basée sur les attributs

1. Récupérez le schéma pertinent pour découvrir les noms d'attributs interrogeables. Pour les attributs de structure : uv run scripts/fetch_schema.py --api search_structure --output schema_structure.txt Pour les attributs chimiques : uv run scripts/fetch_schema.py --api search_chemical --output schema_chemical.txt

2. Analysez le schéma avec grep pour trouver les attributs pertinents. Cherchez un mot-clé à la fois et examinez de nombreuses lignes — il y a beaucoup d'attributs similaires et vous devez choisir la meilleure correspondance pour l'intention de l'utilisateur.

3. Composez et exécutez une requête de recherche JSON en utilisant les attributs découverts : uv run scripts/search_pdb.py --query '<JSON>' --return_type <RETURN_TYPE> --output results.json Passez le flag --count_only pour obtenir seulement le nombre d'entrées correspondantes.

Pour l'étape 2 : quelques concepts PDB de base (utiles pour le choix d'attribut)

• Entity : Une molécule unique trouvée dans une structure.
• Instance / Chain : Une copie particulière d'une entity. Par exemple, si une structure contient deux chaînes protéiques avec la même séquence, elles sont la même entity mais des instances / chaînes différentes.
• Assembly : Une collection biologiquement pertinente d'instances / chaînes. Cela peut être identique à la structure déposée, un sous-ensemble, ou plusieurs copies.
• Label vs Auth : Les instances polymères reçoivent des labels lettres ("A", "B", "AA") et leurs monomères sont numérotés. Il existe des schémas attribués par l'auteur ("auth") et internes à PDB ("label"). Le schéma label est plus cohérent et est toujours utilisé dans les scripts et APIs. Cependant, les utilisateurs et les articles peuvent faire référence au schéma auteur (clarifiez quel schéma est utilisé si nécessaire).
• Composant chimique : Une petite molécule / monomère, avec un ID correspondant à [A-Z]{1,3}
• Citation primaire : La publication principale sur une structure. Préférez les attributs primary_citation aux attributs citation.
• Résolution : Mesure fréquemment utilisée de la qualité de la structure (plus bas est mieux). Préférez généralement rcsb_entry_info.resolution_combined, qui tient compte des différentes méthodes expérimentales.

Pour l'étape 3 : Exemples de requêtes

# Protéines non-humaines publiées dans Nature, les plus récentes en premier
uv run scripts/search_pdb.py --query '{ "type": "group", "logical_operator": "and", "nodes": [ { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "negation": true, "value": "Homo sapiens", "attribute": "rcsb_entity_source_organism.taxonomy_lineage.name" } }, { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "Nature", "attribute": "rcsb_primary_citation.rcsb_journal_abbrev" } } ] }' --return_type entry --sort_by rcsb_accession_info.initial_release_date --sort_direction desc --page_start 0 --rows 100 --output results.json

# Structures contenant le composant chimique CA (ion Ca2+)
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text_chem", "parameters": { "operator": "exact_match", "value": "CA", "attribute": "rcsb_chem_comp_container_identifiers.comp_id" } }' --return_type entry --output results.json

# Nombre d'entrées avec des liaisons disulfure
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "disulfide bridge", "attribute": "rcsb_polymer_struct_conn.connect_type" } }' --return_type entry --count-only --output count.json

Opérateurs courants : exact_match, equals, exists, contains_phrase, contains_words, in, greater, less

Workflow de recherche par similarité

Les recherches par similarité ne nécessitent pas de récupération de schéma. Exemples basiques :

# Similarité de séquence
uv run scripts/search_pdb.py --query '{ "query": { "type": "terminal", "service": "sequence", "parameters": { "evalue_cutoff": 1, "identity_cutoff": 0.9, "sequence_type": "protein", "value": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQ" } }, "request_options": { "scoring_strategy": "sequence" } }' --return_type polymer_entity --output results.json

# Similarité de structure
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "structure", "parameters": { "value": {"entry_id": "6LU7", "asym_id": "A"}, "number_of_candidates": 2000 } }' --return_type polymer_entity --output results.json

# Correspondance de motif de séquence
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "seqmotif", "parameters": { "value": "C-x(2,4)-C-x(3)-[LIVMFYWC]-x(8)-H-x(3,5)-H.", "pattern_type": "prosite", "sequence_type": "protein" } }' --return_type polymer_entity --output results.json

# Correspondance de descripteur chimique
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "chemical", "parameters": { "value": "InChI=1S/C8H9NO2/c1-6(10)9-7-2-4-8(11)5-3-7/h2-5,11H,1H3,(H,9,10)", "type": "descriptor", "descriptor_type": "InChI", "match_type": "graph-strict" } }' --return_type mol_definition --output results.json

Consultez https://search.rcsb.org/#search-services pour plus de détails.

Workflow de recherche en texte intégral

Recherche tout le texte associé à une entrée. Exemple :

uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "full_text", "parameters": { "value": "isopeptide + ( collagen | fibrinogen )" } }' --return_type entry --output results.json

Important : utilisez la recherche full_text comme dernier recours quand il n'y a pas de recherche d'attribut plus précise disponible. Envisagez d'utiliser les attributs struct.title ou rcsb_pubmed_abstract_text à la place.

Workflow de téléchargement de fichiers

Pour télécharger les entrées PDB complètes, utilisez le script download_coordinate_files.py. Utilisez-le quand vous avez besoin d'accès aux coordonnées atomiques, quand on vous demande un fichier pdb / mmcif, ou quand on vous demande de manière non-spécifique de récupérer un code PDB. Exemple :

uv run scripts/download_coordinate_files.py --ids "4HHB,6BEA" --format "mmcif" --output_dir <OUTPUT_DIR>

Workflow de requête de métadonnées

Ce flux est significativement plus efficace que de télécharger les fichiers de coordonnées complets quand vous avez besoin seulement de quelques métadonnées sur chaque entrée / entity.

1. Récupérez le schéma pour le type d'objet pertinent. Par exemple : uv run scripts/fetch_schema.py --api data_entry --output schema_entry.txt

2. Analysez le schéma avec grep pour les champs pertinents (un mot-clé à la fois, de nombreuses lignes).

3. Composez et exécutez une requête de métadonnées GraphQL : uv run scripts/fetch_pdb_metadata.py --query '<GraphQL>' --output results.json

Pour l'étape 3 : Exemples de requêtes

# Récupérez les titres de structures et les méthodes expérimentales
uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids: ["1STP", "2JEF", "1CDG"]) { rcsb_id struct { title } exptl { method } } }' --output results.json

# Récupérez la taxonomie des polymère entities et l'appartenance au cluster
uv run scripts/fetch_pdb_metadata.py --query '{ polymer_entities(entity_ids:["2CPK_1","3WHM_1","2D5Z_1"]) { rcsb_id rcsb_entity_source_organism { ncbi_taxonomy_id ncbi_scientific_name } rcsb_cluster_membership { cluster_id identity } } }' --output results.json

# Récupérez les accessions de base de données de séquence externe des polymère entities
uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids:["7NHM", "5L2G"]){ polymer_entities { rcsb_id rcsb_polymer_entity_container_identifiers { reference_sequence_identifiers { database_accession database_name } } } } }' --output results.json