Que fait NCATS ARAX ?
Utilisez ARAX comme service de consultation de graphe de connaissances contraint. Soumettez des CURIEs revues et des types Biolink explicites, préservez l'échange TRAPI exact, inspectez les liaisons d'arêtes de requête et la provenance, et traitez chaque chemin retourné comme un candidat pour une vérification ultérieure.
Lisez query-contract.md avant de construire une requête. Lisez output-schema.md lors de l'interprétation des artefacts sauvegardés, des avertissements, de la provenance ou des résultats partiels.
Limites de sécurité
- Utilisez uniquement des questions de recherche publiques et non sensibles. Les installations de statut ARAX peuvent exposer les métadonnées de requête et d'appelant même lorsque
store=falseest demandé. - Ne soumettez pas d'informations patient, de questions de recherche confidentielles, de programmes de composés non publiés ou d'hypothèses de cibles propriétaires.
- Ne présentez pas un chemin retourné comme un mécanisme validé ou une recommandation clinique.
- Signalez un zéro comme "non retourné sous ces contraintes", jamais comme une preuve qu'aucune relation n'existe.
- Décrivez la position comme un ordre de réponse non noté, jamais comme un classement.
- Vérifiez les candidats importants séparément avec la littérature et les bases de données faisant autorité.
Flux de travail
- Normalisez le texte libre séparément, puis examinez et rapportez le CURIE et la catégorie proposés.
- Choisissez une requête typée à un saut ou une requête exactement à deux sauts avec les deux extrémités fixées.
- Utilisez la recherche RTX-KG2 par défaut sauf si l'utilisateur nomme explicitement deux à cinq fournisseurs.
- Reconnaissez que la requête biomédicale est publique et choisissez un répertoire de sortie nouveau ou vide.
- Exécutez le client une fois. Ne modifiez pas silencieusement la sélection de fournisseur ou l'ordre d'expansion après un échec ou un résultat vide.
- Inspectez
summary.jsonpour les liaisons et la provenance bornées etresponse.jsonpour la charge utile TRAPI exacte. - Vérifiez les chemins scientifiquement importants en dehors d'ARAX.
Pré-vérification
Vérifiez l'OpenAPI de production sans effectuer de requête biomédicale :
python skills/ncats-arax/scripts/arax_client.py preflight
Le client vérifie que le service s'identifie comme ARAX, expose /query et rapporte une version TRAPI prise en charge. Un point de terminaison non production ou une série TRAPI non testée nécessite une redéfinition explicite ; aucune redéfinition ne modifie les formes ou opérations de requête fixes.
Normaliser une entité
La normalisation est réservée à la révision et ne déclenche jamais de requête de graphe :
python skills/ncats-arax/scripts/arax_client.py normalize "primary myelofibrosis" \
--expected-category biolink:Disease \
--max-synonyms 10 \
--acknowledge-public-query \
--output-dir outputs/normalize-myelofibrosis
Révisez l'identifiant canonique, le nom, la catégorie et l'aperçu des synonymes avant d'utiliser un CURIE. Rapportez tous les CURIEs et catégories indépendamment du résultat de la requête. Un avertissement de catégorie ou un résultat zéro est une raison de curer l'identifiant, pas d'enchaîner automatiquement vers /query.
Recherche à un saut
Figez au moins une extrémité et typez les deux nœuds :
python skills/ncats-arax/scripts/arax_client.py one-hop \
--subject-id CHEBI:31690 \
--subject-category biolink:SmallMolecule \
--predicate biolink:affects \
--object-id NCBIGene:25 \
--object-category biolink:Gene \
--qualifier biolink:object_aspect_qualifier=activity_or_abundance \
--qualifier biolink:object_direction_qualifier=decreased \
--acknowledge-public-query \
--output-dir outputs/imatinib-abl1
Le mode de recherche est le mode par défaut et fixe l'expansion à infores:rtx-kg2. Par défaut, il produit 20 résultats. Utilisez --result-limit N pour demander 1 à 50 résultats ; 50 est le maximum absolu dans les deux modes.
Recherche à deux sauts avec extrémités fixées
Utilisez exactement un nœud intermédiaire typé et non fixé :
python skills/ncats-arax/scripts/arax_client.py two-hop \
--subject-id CHEBI:66901 \
--subject-category biolink:SmallMolecule \
--predicate-1 biolink:affects \
--intermediate-category biolink:Gene \
--predicate-2 biolink:associated_with \
--object-id MONDO:0009061 \
--object-category biolink:Disease \
--qualifier-1 biolink:object_aspect_qualifier=activity_or_abundance \
--qualifier-1 biolink:object_direction_qualifier=increased \
--expand-order right-first \
--acknowledge-public-query \
--output-dir outputs/ivacaftor-cystic-fibrosis
L'expansion droite-d'abord est le mode par défaut. Si un résultat vide mérite une autre tentative, exécutez une nouvelle requête explicitement avec --expand-order left-first et gardez les exécutions séparées.
Fédération avec fournisseur sélectionné
La fédération est explicite et accepte deux à cinq fournisseurs nommés :
python skills/ncats-arax/scripts/arax_client.py one-hop \
--subject-id CHEBI:31690 \
--subject-category biolink:SmallMolecule \
--predicate biolink:affects \
--object-id NCBIGene:25 \
--object-category biolink:Gene \
--mode federated \
--kp infores:rtx-kg2 \
--kp infores:molepro \
--acknowledge-public-query \
--output-dir outputs/federated-imatinib-abl1
Le mode fédéré utilise par défaut le maximum absolu de 50 résultats. Les erreurs de fournisseur peuvent coexister avec des résultats utiles ; une telle exécution se termine avec le code 7 après avoir conservé ses artefacts et est marquée comme partielle.
Inspecter la provenance sauvegardée
Reconstruisez un résumé borné sans accès réseau :
python skills/ncats-arax/scripts/arax_client.py summarize \
--request outputs/ivacaftor-cystic-fibrosis/request.json \
--response outputs/ivacaftor-cystic-fibrosis/response.json \
--format text
L'inspecteur n'accepte que les mêmes formes de requête contraintes et opérations fixes que celles générées par les commandes en direct. Utilisez --format json pour la vue normalisée sur la sortie standard.
Interpréter les résultats
- Suivez les liaisons d'arêtes de requête de chaque analyse ; ne résumez pas chaque arête du graphe de connaissances.
- Préservez les valeurs physiques de sujet, prédicat, objet et qualificateur d'arête retournées par ARAX. Les prédicats ou aspects de qualificateur retournés peuvent être plus spécifiques que la contrainte de requête.
- Inspectez tous les objets source, y compris les champs URL de source primaire, agrégateur, données de support, ressource amont et enregistrement source.
- Traitez
publication_availability: not_returnedcomme des métadonnées manquantes, pas comme une preuve qu'aucune publication n'existe. - Traitez les références de graphe auxiliaire manquantes et les échecs de fournisseur comme des avertissements explicites.
- Consultez la réponse brute chaque fois que le résumé borné omet des détails ou que la réponse du service est partielle, inhabituelle ou scientifiquement surprenante.
Exclusions délibérées
Le client n'a pas de surface de requête brute, flux de travail, opération, superposition, classement, inférence, prédiction de lien, Pathfinder, ARS, lot, tous fournisseurs, trois sauts, cache, démon, SDK, MCP ou langage naturel vers TRAPI. Ne contournez pas ces limites avec des appels HTTP directs sous cette compétence.