NetMedEx is a Python-based tool designed to extract BioConcept entities (e.g., genes, diseases, chemicals, and species) from Pubtator files generated by Pubtator3. It calculates the frequency of BioConcept pairs (e.g., gene-gene, gene-chemical, chemical-disease) based on co-mentions in publications and generates a co-mention interaction network. These networks can be viewed in a browser or imported into Cytoscape for advanced visualization and analysis.
NetMedEx offers four ways for users to interact with the tool:
For additional details, refer to the Documentation.
If you have Docker installed on your machine, you can run the following command to launch the web application using Docker, then open localhost:8050 in your browser:
docker run -p 8050:8050 --rm lsbnb/netmedexInstall NetMedEx from PyPI to use the web application locally or access the CLI:
pip install netmedexWe recommend using Python version >= 3.11 for NetMedEx.
After installing NetMedEx, run the following command and open localhost:8050 in your browser:
netmedex runThe sidebar parameters are detailed in the Available Commands section and Documentation.
To generate a network, run netmedex search first to retrieve relevant articles and then run netmedex network to generate the network.
Use the CLI to search articles containing specific biological concepts via the PubTator3 API:
# Query with keywords and sort articles by relevance (default: recency)
netmedex search -q '"N-dimethylnitrosamine" AND "Metformin"' [-o OUTPUT_FILEPATH] --sort score
# Query with article PMIDs
netmedex search -p 34895069,35883435,34205807 [-o OUTPUT_FILEPATH]
# Query with article PMIDs (from file)
netmedex search -f examples/pmids.txt [-o OUTPUT_FILEPATH]
# Query with PubTator3 Entity ID and limit the number of articles to 100
netmedex search -q '"@DISEASE_COVID_19" AND "@GENE_PON1"' [-o OUTPUT_FILEPATH] --max_articles 100Note: Use double quotes for keywords containing spaces and logical operators (e.g., AND/OR) to combine keywords.
Available commands are detailed in Search Command.
The PubTator file outputs from netmedex search is used to generate the network.
# Use default parameters and set edge weight cutoff to 1
netmedex network -i examples/pmids_output.pubtator -o pmids_output.html -w 1
# Keep MeSH terms and discard non-MeSH terms
netmedex network -i examples/pmids_output.pubtator -o pmids_output.html -w 1 --node_type mesh
# Keep confident relations between entities
netmedex network -i examples/pmids_output.pubtator -o pmids_output.html -w 1 --node_type relation
# Save the result in XGMML format for Cytoscape
netmedex network -i examples/pmids_output.pubtator -o pmids_output.xgmml -w 1 -f xgmml
# Use normalized pointwise mutual information (NPMI) to weight edges
netmedex network -i examples/pmids_output.pubtator -o pmids_output.html -w 5 --weighting_method npmiAvailable commands are detailed in Network Command.
- HTML Output: Open in a browser to view the network.
- XGMML Output: Import into Cytoscape for further analysis.
Refer to the Documentation for more details.
usage: netmedex [-h] {search,network,run} ...
positional arguments:
{search,network,run}
search Search PubMed articles and obtain annotations
network Build a network from annotations
run Run NetMedEx app
options:
-h, --help Show this help message and exitusage: netmedex search [-h] [-q QUERY] [-o OUTPUT] [-p PMIDS] [-f PMID_FILE] [-s {score,date}] [--max_articles MAX_ARTICLES] [--full_text]
[--use_mesh] [--debug]
options:
-h, --help show this help message and exit
-q QUERY, --query QUERY
Query string
-o OUTPUT, --output OUTPUT
Output path (default: [CURRENT_DIR].pubtator)
-p PMIDS, --pmids PMIDS
PMIDs for the articles (comma-separated)
-f PMID_FILE, --pmid_file PMID_FILE
Filepath to load PMIDs (one per line)
-s {score,date}, --sort {score,date}
Sort articles in descending order by (default: date)
--max_articles MAX_ARTICLES
Maximal articles to request from the searching result (default: 1000)
--full_text Collect full-text annotations if available
--use_mesh Use MeSH vocabulary instead of the most commonly used original text in articles
--debug Print debug informationusage: netmedex network [-h] [-i INPUT] [-o OUTPUT] [-w CUT_WEIGHT] [-f {xgmml,html,json}] [--node_type {all,mesh,relation}]
[--weighting_method {freq,npmi}] [--pmid_weight PMID_WEIGHT] [--debug] [--community] [--max_edges MAX_EDGES]
options:
-h, --help show this help message and exit
-i INPUT, --input INPUT
Path to the pubtator file
-o OUTPUT, --output OUTPUT
Output path (default: [INPUT_DIR].[FORMAT_EXT])
-w CUT_WEIGHT, --cut_weight CUT_WEIGHT
Discard the edges with weight smaller than the specified value (default: 2)
-f {xgmml,html,json,pickle}, --format {xgmml,html,json,pickle}
Output format (default: html)
--node_type {all,mesh,relation}
Keep specific types of nodes (default: all)
--weighting_method {freq,npmi}
Weighting method for network edge (default: freq)
--pmid_weight PMID_WEIGHT
CSV file for the weight of the edge from a PMID (default: 1)
--debug Print debug information
--community Divide nodes into distinct communities by the Louvain method
--max_edges MAX_EDGES
Maximum number of edges to display (default: 0, no limit)In addition to the web interface and CLI, NetMedEx can be used programmatically as a Python library. This allows for more flexible integration into custom pipelines and analysis workflows.
Example usage is available in notebooks/netmedex_usage.ipynb.