pedl 1.0.2

Search the biomedical literature for protein interactions andprotein associations.

PEDL+: Protein-centered relation extraction from PubMed at your fingertip

PEDL+ is a powerful framework designed to extract protein-protein and drug-protein associations from biomedical literature. By searching over 30 million abstracts of biomedical publications and more than 4 million full texts using PubTatorCentral, PEDL+ leverages state-of-the-art machine reading models to predict association types between proteins, supported by literature evidence.

PEDL+ is capable of detecting the following association types:

• Protein-Protein: controls-phosphorylation-of, controls-state-change-of, controls-transport-of, controls-expression-of, in-complex-with, interacts-with, and catalysis-precedes
• Drug-Protein: antagonist, agonist, agonist-inihibitor, direct-regulator, activator, inhibitor, indirect-downregulator, indirect-upregulator, part-of, product-of, substrate, and substrate_product-of

For example usage with expected results, see this notebook.

README Contents

• Installation
• Usage
• FAQ

Installation

Install PEDL+ via pip:

pip install pedl

Usage

PEDL+ provides two main commands: pedl-extract and pedl-summarize. The default workflow consists of using pedl-extract to obtain associations for one or more protein or drug pairs of interest, storing the results for each pair in separate files. These files can then be aggregated into a single spreadsheet using pedl-summarize.

Proteins should be identified using HGNC symbols (for human genes) or Entrez gene IDs, searchable via NCBI Gene. Drugs should be identified by their MeSH ID, searchable via MeSH NLM.

Building the PubTator Index (Optional)

For searches involving more than 100 pairs with PEDL+, it is recommended to use an ElasticSearch index. If you do not build the index, PEDL+ will automatically download the required data using the PubTatorCentral API and run the search on the fly. However, this will be slower and won't work for more than 100 pairs.

PEDL+ supports storing a preprocessed version of all PTC texts in an ElasticSearch index. Install and run Elasticsearch 7.17 and download all PubTatorCentral files on your server. Note that this requires around 800GB of disk space. You can either build a docker container or follow the instructions on the website to run a default Elasticsearch host. Rebuilding the PubTator index can take considerable time (around a day on 70 threads).

pedl-rebuild_pubtator_index

pedl-rebuild_pubtator_index elastic.server=<server_address> pubtator_file=<path_to_pubtator_file> n_processes=<number of processes>

Example call:

pedl-rebuild_pubtator_index elastic.server=https://localhost:9200 pubtator_file=/home/pedl/output/BioCXML n_processes=10

pedl-extract

Single Protein or Drug Interactions

To extract interactions, you can use either the Entrez gene ID or name for proteins, and the MeSH ID or name for drugs. If using Entrez and/or MeSH IDs, set use_ids=True. Please note that mixing names and IDs in the same query is not possible.

Set type=protein_protein for protein-protein interactions or type=drug_protein for drug-protein interactions.

• Example (Protein-Protein Interaction):

  pedl-extract e1=CMTM6 e2=CD274 type=protein_protein out=PEDL_extractions
  

• Example (Drug-Protein Interaction):

  pedl-extract e1=MeSH:D063325 e2=1813 type=drug_protein out=PEDL_extractions use_ids=True
  

Pairwise Interactions Between Multiple Proteins or Drugs

• Protein-Protein Interaction:

  pedl-extract e1=[CMTM6,PDCD1LG2] e2=CD274 type=protein_protein out=PEDL_extractions
  

• Drug-Protein Interaction:

  pedl-extract e1=[MeSH:D000661,D008694] e2=4129 type=drug_protein out=PEDL_extractions use_ids=true
  

Pairwise Interactions Between All Proteins or Drugs

• Protein-Protein Interaction:

  pedl-extract e1=all e2=CD274 type=protein_protein out=PEDL_extractions 
  

• Drug-Protein Interaction:

  pedl-extract e1=all e2=4129 type=drug_protein out=PEDL_extractions use_ids=true
  

• With a local PubTator index:

  pedl-extract e1=all e2=4129 type=drug_protein out=PEDL_extractions use_ids=true elastic.server=<server_address> 
  

Read Protein or Drug Lists from Files

• Protein-Protein Interaction:

  pedl-extract e1=proteins.txt e2=[54918,920] type=protein_protein out=PEDL_extractions use_ids=true
  

• Drug-Protein Interaction:

  pedl-extract e1=drugs.txt e2=4129 type=drug_protein out=PEDL_extractions use_ids=true
  

pedl-summarize

Create a summary spreadsheet for all results in a directory:

pedl-summarize input=PEDL_predictions output=summary

In case, you want a CSV file instead of an Excel file, use the plain parameter:

pedl-summarize input=PEDL_predictions output=summary plain=True

To filter results by specific MeSH terms, use the mesh_terms parameter. Escape special characters with a backslash \:

pedl-summarize input=PEDL_extractions output=summary mesh_terms=["Apoptosis","Lymphoma\, B-Cell"]

To only use high-confidence extractions, use the threshold parameter:

pedl-summarize input=PEDL_extractions output=summary threshold=0.9

FAQ

• On which platforms does PEDL+ work?
  • We have thoroughly tested PEDL+ on Linux and MacOS and verified that its basic functionality works on Windows. We strongly recommend using mambaforge or anaconda as your Python environment.
• How can I perform a clean uninstall of PEDL+?
  1. Uninstall the package: pip uninstall pedl
  2. Delete the PEDL+ cache folder. You can typically find it under ~/.cache/pedl. So you can delete it by running rm -rf ~/.cache/pedl.
• I am running into issues with PEDL+. What can I do?
  • Try to perform a clean uninstall and reinstall of PEDL+. If the issue persists, please open an issue on GitHub and we will try to help you as soon as possible.