Package: openpredict
🔮🐍 Translator OpenPredictOpenPredictis a python package to help serve predictions of biomedical associations, as Translator Reasoner API (aka. TRAPI).TheTranslator Reasoner API(TRAPI) defines a standard HTTP API for communicating biomedical questions and answers leveraging theBiolink model.The package provides:a decorator@trapi_predictto which the developer can pass all informations required to integrate the prediction function to a Translator Reasoner APIaTRAPIclass to deploy a Translator Reasoner API serving a list of prediction functions decorated with@trapi_predictHelpers to store your models in a FAIR manner, using tools such asdvcandmlemPredictions are usually generated from machine learning models (e.g. predict disease treated by drug), but it can adapt to generic python function, as long as the input params and return object follow the expected structure.Additionally to the library, this repository contains the code for theOpenPredict Translator APIavailable atopenpredict.semanticscience.org, which serves a few prediction models developed at the Institute of Data Science.📦️ Use the packageInstallpipinstallopenpredictUseTheopenpredictpackage provides a decorator@trapi_predictto annotate your functions that generate predictions. The code for this package is insrc/openpredict/.Predictions generated from functions decorated with@trapi_predictcan easily be imported in the Translator OpenPredict API, exposed as an API endpoint to get predictions from the web, and queried through the Translator Reasoner API (TRAPI)fromopenpredictimporttrapi_predict,PredictOptions,PredictOutput@trapi_predict(path='/predict',name="Get predicted targets for a given entity",description="Return the predicted targets for a given entity: drug (DrugBank ID) or disease (OMIM ID), with confidence scores.",edges=[{'subject':'biolink:Drug','predicate':'biolink:treats','object':'biolink:Disease',},{'subject':'biolink:Disease','predicate':'biolink:treated_by','object':'biolink:Drug',},],nodes={"biolink:Disease":{"id_prefixes":["OMIM"]},"biolink:Drug":{"id_prefixes":["DRUGBANK"]}})defget_predictions(input_id:str,options:PredictOptions)->PredictOutput:# Add the code the load the model and get predictions herepredictions={"hits":[{"id":"DB00001","type":"biolink:Drug","score":0.12345,"label":"Leipirudin",}],"count":1,}returnpredictions🍪 You can useour cookiecutter templateto quickly bootstrap a repository with everything ready to start developing your prediction models, to then easily publish, and integrate them in the Translator ecosystem🌐 The OpenPredict Translator APIAdditionally to the library, this repository contains the code for theOpenPredict Translator APIavailable atopenpredict.semanticscience.organd the predictions models it exposes:the code for the OpenPredict API endpoints insrc/trapi/defines:a TRAPI endpoint returning predictions for the loaded modelsindividual endpoints for each loaded models, taking an input id, and returning predicted hitsendpoints serving metadata about runs, models evaluations, features for the OpenPredict model, stored as RDF, using theML Schema ontology.various folders fordifferent prediction modelsserved by the OpenPredict API are available undersrc/:the OpenPredict drug-disease prediction model insrc/openpredict_model/a model to compile the evidence path between a drug and a disease explaining the predictions of the OpenPredict model insrc/openpredict_evidence_path/a prediction model trained from the Drug Repurposing Knowledge Graph (aka. DRKG) insrc/drkg_model/The data used by the models in this repository is versionned usingdvcin thedata/folder, and storedon DagsHub athttps://dagshub.com/vemonet/translator-openpredictDeploy the OpenPredict API locallyRequirements: Python 3.8+ andpipinstalledClone the repository:gitclonehttps://github.com/MaastrichtU-IDS/translator-openpredict.gitcdtranslator-openpredictPull the data required to run the models in thedatafolder withdvc:pipinstalldvc
dvcpullStart the API in development mode with docker onhttp://localhost:8808, the API will automatically reload when you make changes in the code:docker-composeupapi# Or with the helper script:./scripts/api.shContributions are welcome! If you wish to help improve OpenPredict, see theinstructions to contribute :woman_technologist:for more details on the development workflowTest the OpenPredict APIRun the tests locally with docker:docker-composeruntests# Or with the helper script:./scripts/test.shSee theTESTING.mdfile for more details on testing the API.You can change the entrypoint of the test container to run other commands, such as training a model:docker-composerun--entrypoint"python src/openpredict_model/train.py train-model"tests# Or with the helper script:./scripts/run.shpythonsrc/openpredict_model/train.pytrain-modelUse the OpenPredict APIThe user provides a drug or a disease identifier as a CURIE (e.g. DRUGBANK:DB00394, or OMIM:246300), and choose a prediction model (only thePredict OMIM-DrugBankclassifier is currently implemented).The API will return predicted targets for the given drug or disease:Thepotential drugs treating a given disease:pill:Thepotential diseases a given drug could treat:microbe:Feel free to try the API atopenpredict.semanticscience.orgTRAPI operationsOperations to query OpenPredict using theTranslator Reasoner APIstandards.Query operationThe/queryoperation will return the same predictions as the/predictoperation, using theReasonerAPIformat, used within theTranslator project.The user sends aReasonerAPIquery asking for the predicted targets given: a source, and the relation to predict. The query is a graph with nodes and edges defined in JSON, and uses classes from theBioLink model.You can use the default TRAPI query of OpenPredict/queryoperation to try a working example.Example of TRAPI query to retrieve drugs similar to a specific drug:{"message":{"query_graph":{"edges":{"e01":{"object":"n1","predicates":["biolink:similar_to"],"subject":"n0"}},"nodes":{"n0":{"categories":["biolink:Drug"],"ids":["DRUGBANK:DB00394"]},"n1":{"categories":["biolink:Drug"]}}}},"query_options":{"n_results":3}}Predicates operationThe/predicatesoperation will return the entities and relations provided by this API in a JSON object (following theReasonerAPIspecifications).Try it athttps://openpredict.semanticscience.org/predicatesNotebooks examples :notebook_with_decorative_cover:We provideJupyter Notebookswith examples to use the OpenPredict API:Query the OpenPredict APIGenerate embeddings with pyRDF2Vec, and import them in the OpenPredict APIAdd embedding :station:The default baseline model isopenpredict_baseline. You can choose the base model when you post a new embeddings using the/embeddingscall. Then the OpenPredict API will:add embeddings to the provided modeltrain the model with the new embeddingsstore the features and model using a unique ID for the run (e.g.7621843c-1f5f-11eb-85ae-48a472db7414)Once the embedding has been added you can find the existing models previously generated (includingopenpredict_baseline), and use them as base model when you ask the model for prediction or add new embeddings.Predict operation :crystal_ball:Use this operation if you just want to easily retrieve predictions for a given entity. The/predictoperation takes 4 parameters (1 required):Adrug_idto get predicted diseases it could treat (e.g.DRUGBANK:DB00394)ORadisease_idto get predicted drugs it could be treated with (e.g.OMIM:246300)The prediction model to use (default toPredict OMIM-DrugBank)The minimum score of the returned predictions, from 0 to 1 (optional)The limit of results to return, starting from the higher score, e.g. 42 (optional)The API will return the list of predicted target for the given entity, the labels are resolved using theTranslator Name Resolver APITry it athttps://openpredict.semanticscience.org/predict?drug_id=DRUGBANK:DB00394More about the data model :minidisc:The gold standard for drug-disease indications has been retrieved fromhttps://www.ncbi.nlm.nih.gov/pmc/articles/PMC3159979Metadata about runs, models evaluations, features are stored as RDF using theML Schema ontology.See theML Schema documentationfor more details on the data model.Diagram of the data model used for OpenPredict, based on the ML Schema ontology (mls):Translator applicationService SummaryQuery for drug-disease pairs predicted from pre-computed sets of graphs embeddings.Add new embeddings to improve the predictive models, with versioning and scoring of the models.Component ListAPI componentComponent Name:OpenPredict APIComponent Description:Python API to serve pre-computed set of drug-disease pair predictions from graphs embeddingsGitHub Repository URL:https://github.com/MaastrichtU-IDS/translator-openpredictComponent Framework:Knowledge ProviderSystem requirements5.1. Specific OS and version if required:python 3.85.2. CPU/Memory (for CI, TEST and PROD):32 CPUs and 32 Go memory ?5.3. Disk size/IO throughput (for CI, TEST and PROD):20 Go ?5.4. Firewall policies: does the team need access to infrastructure components?The NodeNormalization APIhttps://nodenormalization-sri.renci.orgExternal Dependencies (any components other than current one)6.1. External storage solution:Models and database are stored in/data/openpredictin the Docker containerDocker application:7.1. Path to the Dockerfile:Dockerfile7.2. Docker build command:dockerbuildghcr.io/maastrichtu-ids/openpredict-api.7.3. Docker run command:Replace${PERSISTENT_STORAGE}with the path to persistent storage on host:dockerrun-d-v${PERSISTENT_STORAGE}:/data/openpredict-p8808:8808ghcr.io/maastrichtu-ids/openpredict-apiLogs of the application9.2. Format of the logs:TODOAcknowledgments​This service has been built from thefair-workflows/openpredictproject.Predictions made using thePREDICT method.Service funded by theNIH NCATS Translator project.