NetMe API Documentation

Motivation: The rapid increase of bio-medical literature makes it harder and harder for scientists to keep pace with the discoveries on which they build their studies. Therefore, computational tools have become more widespread, among which network analysis plays a crucial role in several life-science contexts. Nevertheless, building correct and complete networks about some user-defined biomedical topics on top of the available literature is still challenging.

Results: We introduce NetMe 2.0, a web-based platform that automatically extracts relevant biomedical entities and their relations from a set of input texts — i.e., in the form of full-text or abstract of PubMed Central’s papers or free texts — and models them as a BioMedical Knowledge Graph. The node extraction is done by a biomedical entity linker, namely OntoTagMe (which uses a biological subset of the English Wikidata dump, version: 2022-10), while the edge extraction is done through state-of-the-art techniques in spaCy. The results of the annotation process are enriched with PubTator, a Named Entity Recognition tool specialized for biology. The experimental results show that NetMe 2.0 can infer comprehensive and reliable biological networks with significant Precision-Recall metrics when compared to state-of-the-art approaches.

If you want to play with the tool using a web interface, go to https://netme.click, otherwise you can interact with the NetMe tool via curl or Python scripts, as specified below.

How to create a Biomedical Network

The service is hosted by the D4Science. To obtain access you need to register to the NetMe VRE and get your authorization token by clicking on the "Show button" in the left panel. Now you have everything in place to issue a query to NetMe RESTful API.

NetMe works in three different ways:

• PUBMED QUERY: in this case, the query is run on the most relevant/recent papers returned by PubMed/PubMed Central articles for the user query. NetMe will skip all the PubMed Central papers that are not open-access.
• QUERY BY PubMed IDs: in this case, the network is generated on the provided PubMed/PubMed Central IDs, the query will ignore all the PubMed Central IDs corresponding to non-open-access full-texts.
• TEXT QUERY: the network is generated on the user string provided in the query.

The networks can be generated by issuing a query (POST) to the following endpoint, changing the request payload as described in the following parts of the documentation:

https://netme-sobigdata.d4science.org/network_generation

The network_generation REST API returns a task_id:

{"task_id": "<task id of the process>"}

which will be used to download the network JSON file once the task has been completed. Therefore, a user should periodically send a GET request to the following endpoint:

https://netme-sobigdata.d4science.org/task_status/<TASK_ID>

As long as the task is not completed, such a request will return a JSON containing the task in progress. Otherwise, it will return the comprehensive network JSON file.

Annotate by "PubMed query"

In order to get the network generated from a query issued to PubMed or PubMed Central, set the following parameters (payload):

PARAMETERS

• queryMode: put "pubmed"
• input: the query string, formatted like in PubMed and PubMed Central
• networkName: the name of the generated network
• searchOn: put "terms"
• searchType: "full-text" for PubMed Central or "abstract" for PubMed
• papersNumber - the number of articles to use (max 1000)
• sortType - "relevance" (uses the top picks according to the PubMed and PubMed Central ranking functions) or "date" (picks the n most recent papers)

EXAMPLE OF PAYLOAD

payload = {
    "queryMode"     : "pubmed",
    "input"         : "Basigin",
    "networkName"   : "Basigin network test",
    "searchOn"      : "terms",
    "searchType"    : "full-text",
    "papersNumber"  : "10",
    "sortType"      : "relevance"
}

The annotation will be performed by OntoTagMe and enriched with PubTator.

Annotate by "PubMed IDs"

In order to get the network generated from full texts regarding the provided PubMed IDs, set the following parameters (payload):

PARAMETERS

• queryMode: put "pubmed"
• input: the PubMed/PubMed central IDs, comma separated. Use the format "38145760, 38134539, 38127031, 38114725" for PubMed queries, and the format "PMC10680069, PMC10606534, PMC10579889" for PubMed Central queries.
• networkName: the name of the generated network
• searchOn: put "ids"
• searchType: "full-text" for PubMed Central or "abstract" for PubMed

EXAMPLE OF PAYLOAD

payload = {
     "queryMode"    : "pubmed",
     "input"        : "PMC10680069, PMC10606534",
     "networkName"  : "test network",
     "searchOn"     : "ids",
     "searchType"   : "full-text"
}

The annotation will be performed by OntoTagMe and enriched with PubTator.

Annotate by "text query"

In order to get the network generated from a plaintext paragraph, set the following parameters (payload):

• queryMode: put "text"
• input:  the textual sample to use for generating the network
• networkName: the name to give to your network.

EXAMPLE OF PAYLOAD

payload = {
     "queryMode"    : "text",
     "input"        : "BRCA1 upregulates H2A",
     "networkName"  : "test textual queries"
}

The annotation will be performed, in this case, by OntoTagMe alone.

Python Script

You can use this Python snippet to generate NetMe's network using one of the methods mentioned above. You just need to add your NetMe VRE token and a payload from the previously discussed examples. 

import requests
URL_ID = "https://netme-sobigdata.d4science.org/network_generation"
TOKEN = <"your_netme_vre_token">
headers = {"Content-Type": "application/json", "Authorization": "Bearer " + TOKEN}
payload = <INSERT PAYLOAD HERE - SEE EXAMPLES ABOVE>
r = requests.post(URL_ID, headers=headers, json=payload)
if r.status_code != 200:
    raise Exception("Error on query: \n{}".format(r.text))
print(r.json())

To check the status of the network creation process, and to retrieve the network when it is built, you can use the following Python snippet.

import requests
URL_ID = "https://netme-sobigdata.d4science.org/task_status/{}"
TOKEN = <YOUR NETME VRE TOKEN>
headers = {"Content-Type": "application/json", "Authorization": "Bearer " + TOKEN}
r = requests.get(URL_ID.format(<"PUT YOUR NETWORK ID">), headers=headers)
if r.status_code != 200:
    raise Exception("Error on requested network:\n{}".format(r.text))
print(r.json())

HTTP Errors

• 501 (NOT IMPLEMENTED) - The resource you requested is not a valid NetMe service.
• 401 (UNAUTHORIZED) - You haven't provided a Service Authorization Token or it is not valid.
• 400 (BAD REQUEST) - There are issues with the parameters you have sent (or not sent). Check the response message for details.
• 500 (INTERNAL SERVER ERROR) - Something went wrong on the side of NetMe.

Credits and References

NetMe is a joint effort among the University of Pisa, Scuola Normale Superiore, and the University of Catania.

If you used NetMe, please cite our work:

• Alessandro Muscolino, Antonio Di Maria, Rosaria Valentina Rapicavoli, Salvatore Alaimo, Lorenzo Bellomo, Fabrizio Billeci, Stefano Borzì, Paolo Ferragina, Alfredo Ferro, and Alfredo Pulvirenti. "NETME: on-the-fly knowledge network construction from biomedical literature." In: Applied Network Science, 7.1: 1–24, Springer, 2022. DOI: https://doi.org/10.1007/s41109-021-004
• Antonio Di Maria, Lorenzo Bellomo, Fabrizio Billeci, Alfio Cardillo, Salvatore Alaimo, Paolo Ferragina, Alfredo Ferro, and Alfredo Pulvirenti. "NetMe 2.0: A web-based platform for extracting and modeling knowledge from biomedical literature as a labeled graph." To be published in Bioinformatics, 2024.