MedLink: Clinical Case Retrieval and Ranking Dashboard

MedLink is a web application designed to support clinical decision-making by retrieving and ranking relevant clinical case reports based on physician-provided medical reports. Built with Plotly's Dash in Python, this app utilizes advanced NLP models to help healthcare professionals find similar cases, aiding in complex diagnostic scenarios.

Visit MedLink here

Table of Contents

• Overview
• Features
• Installation
• Usage
• Project Structure
• Dependencies
• License

Overview

In healthcare, physician-patient interactions are often documented as free-text medical reports, which may be challenging to reference in complex diagnostic cases. MedLink addresses this by retrieving and ranking relevant clinical case reports from health conferences and journals, offering valuable insights based on similar past cases. This tool utilizes advanced NLP techniques, specifically two BERT models, to:

1. Retrieve similar cases (using a bi-encoder) and,
2. Re-rank the retrieved cases based on relevance (using a cross-encoder).

MedLink’s effectiveness was evaluated by a physician, achieving a ranking model performance of NDCG@10 of 0.747.

Features

• Medical Report Search: Input a medical report to retrieve similar published case reports.
• Ranking and Scoring: Case reports are ranked based on relevance using a cross-encoder model.
• Clinical Entity Visualization: Key entities (e.g., symptoms, diagnoses) highlighted using Named Entity Recognition (NER).
• Textual Explanations: Provides context and explanations to facilitate comparison of case reports.

Installation

Note: The models are available in HuggingFace and dataset for the dash app is available in this repository. Therefore and it is not necessary to run the data extraction and model training scripts to run MedLink application.

Prerequisites

• Python 3.7+
• Virtual Environment Tool: You can use Python’s built-in venv module or a tool like virtualenv.

Setup

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/LIAAD/MedLink.git
   cd medlink

2. Create a virtual environment in the project directory:

   python3 -m venv venv

3. Activate the virtual environment:

   • On Windows:

     venv\ Scripts\ activate

   • On macOS and Linux:

     source venv/bin/activate

4. Install the required dependencies:

   pip install -r requirements.txt

Usage

Run the data extraction scripts

Run the model training scripts

Run the Dash app:

python app.py

File/Directory Explanations

MedLink repository is divided in 3 different folders each containing the essential components to replicate and extend the proposed application.

-- data: Contains the necessary scripts for extracting and cleaning the dataset used for this project as well the dataself itself. In addition it also contains the sample dataset used for evaluation.

• models: Contains the scripts required to reproduce the retrieval and re-ranker models.

• dash_app: Contains the MedLink application as well as the necessary files to run it.

  • pages/: Contains the different files for the application pages.

    • assets/: Contains the css and images for the application.

• requirements.txt: Lists all dependencies needed to run the project. Install these with pip install -r requirements.txt.

• README.md: Documentation file (this file), providing an overview, installation instructions, and usage guidelines.

• LICENSE: Specifies the license for the project, detailing permissions and restrictions.

Support

For questions please contact the authors.

Authors and acknowledgment

License

For open source projects, say how it is licensed.

Project status