netmedex 0.3.0

A tool to extract BioConcept entities (e.g., genes, diseases, chemicals, and species) from Pubtator3 and generate a co-mention network for interactive use.

NetMedEx

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.

Getting Started

NetMedEx offers four ways for users to interact with the tool:

1. Web Application (via Docker)
2. Web Application (Local)
3. Command-Line Interface (CLI)
4. Python API

For additional details, refer to the Documentation.

Web Application (via Docker)

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/netmedex

Installation

Install NetMedEx from PyPI to use the web application locally or access the CLI:

pip install netmedex

We recommend using Python version >= 3.11 for NetMedEx.

Web Application (Local)

After installing NetMedEx, run the following command and open localhost:8050 in your browser:

netmedex run

The sidebar parameters are detailed in the Available Commands section and Documentation.

Command-Line Interface (CLI)

To generate a network, run netmedex search first to retrieve relevant articles and then run netmedex network to generate the network.

Search PubMed Articles

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 100

Note: Use double quotes for keywords containing spaces and logical operators (e.g., AND/OR) to combine keywords.

Available commands are detailed in Search Command.

Generate Co-Mention Networks

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 npmi

Available commands are detailed in Network Command.

View the Network

• 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.

Available Commands

General

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 exit

Search Command

usage: 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 information

Network Command

usage: 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)

Package API

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.