Metadata-Version: 2.4
Name: cosine_sim_engine
Version: 0.1.2
Summary: Cosine similarity engine for disease classification.
Author: Luis Mendez
License-Expression: MIT
Project-URL: Homepage, https://github.com/Mendez016/Disease-Diagnosis-Engine-V1/tree/main
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.0
Requires-Dist: pytest
Dynamic: license-file

# ﻿Disease Diagnosis Retrieval Engine

Disease Diagnosis Retrieval Engine is a personal machine learning project born from the idea of applying concepts learned throughout my computer science education to a real-world healthcare problem. As machine learning continues to mature, it has the potential to support professionals by automating repetitive analytical tasks and providing decision-support tools, allowing experts to dedicate more time to complex cases that require human judgment.

With this motivation, I developed the Disease Diagnosis Retrieval Engine as a platform to explore the complete lifecycle of a machine learning system—from large-scale data preprocessing and feature engineering to vector-space representation, prototype learning, similarity-based retrieval, and model evaluation. The project also investigates how a nearest-centroid classifier behaves under incomplete or sparse patient information, reflecting the challenges encountered in practical diagnostic settings.

While the current implementation is intended for research and experimentation, it establishes a modular foundation that can be extended with natural language interfaces, explainable and statistics supported recommendations, and interactive symptom acquisition in future iterations.

## Architecture

<img width="1364" height="1112" alt="Disease_Engine_v1_diagram drawio (3)" src="https://github.com/user-attachments/assets/c8df17cd-1ab2-4206-b9f5-f9306188b2b1" />

## Mathematical foundation
The mathematical foundation of the retrieval and recommendation system is completely based on Linear Algebra concepts and vector operations and conclusions that will be explained in the following sections.

### How does this system generate a diagnosis?
The core of this system is the formula of the dot-product of two vectors and how it can be used to find the angle between two vectors:

$$
\large{|u \cdot v| = |u||v|cos(\theta)}
$$

$$
\large{\frac{|u \cdot v|}{|u||v|} = cos(\theta)}
$$

The system displays the top-5 diagnosis vector profiles that are the closest to the provided patient vector. To do so, it calculates the cosine of the angle between the vector provided by the patient and the vectors of all the possible diagnosis, then retrieves the top-5 diagnosis profile vectors that yield the highest cosine results, that is, the diagnosis profile vectors that are the most similar to the patient vector. Ensuring that the returned results are those who are mathematically similar to the provided patient information.

### How are diagnosis profile vectors computed?
#### Feature generation
Features are generated by parsing the documentation of the DDXPlus dataset that contains all the possible evidences that the dataset contains, extracting and standardizing all the documented evidences into an empty dataframe where the column names are all the possible evidences.

#### Feature extraction
Features are extracted from each record present in the DDXPlus dataset by cleaning and standardizing all the values contained in the evidences array contained by each record, then, an empty row is created in the documented evidences dataset and then the columns corresponding to the evidences from the original record are set to 1. Finally, any NaN values are replaced by zero to create the binary encoding, or replaced by negative one to create the signed encoding.

#### Profile vector computation
Once all records have been processed and its features extracted, each record is represented by containing the true diagnosis and a value in each evidence column representing the presence of the symptom in the record or its absence. To generate the centroids, those rows are grouped by the true diagnosis column and the average of each column is taken.

$$Profile_{diagnosis} = \frac{\sum i}{n} $$

Where the profile for a specific diagnosis is calculated by taking the average of all the vectors whose true diagnosis matches the provided diagnosis.

As an observation, once this process is finished with binary encoding, each cell in the dataframe represents the empirical probability that a person has a each symptom given their diagnosis.

### Validation
So far, this model has only been validated under the Cosine Similarity retrieval methodology, other methods such as weighted Cosine Similarity and Euclidean Distance can be tested in future iterations.

This model was evaluated in two different configurations: Binary encoding for both training data an validation data simulating the case where a user expresses the presence and absence of all the evidences in the dataset, And a signed encoding for training data while keeping binary encoding for validation data for simulating more realistic scenarios where a user only states the presence of a series of symptoms while not stating the explicit absence/presence of the rest of the symptoms. The results are the following:

#### Binary encoded training validation:

F1-score: 0.99

Weighted precision average: 0.99

Lowest precision achieved: 0.86

Highest precision achieved: 1.00

Weighted recall average: 0.99

Lowest recall achieved: 0.78

Highest recall achieved: 1.00

#### Signed encoded training validation:

F1-score: 0.97

Weighted precision average: 0.98

Lowest precision achieved: 0.50

Highest precision achieved: 1.00

Weighted recall average: 0.97

Lowest recall achieved: 0.32

Highest recall achieved: 1.00

Note: The lowest precisions and lowest recalls in both validation cases happen mostly between pairs of diagnosis that are clinicaly close to each other (example: Chronic Rhinosinousitis and Acute Rhinosinousitis). In the case of the signed encoded training, it is expected to have a lower performance as it is deliberately given less information for accurately generating a diagnosis.

## Data Attribution

This library includes a derived model generated from the DDXPlus dataset.

DDXPlus is licensed under the Creative Commons Attribution 4.0 International
(CC BY 4.0) license.

Original dataset:
https://github.com/mila-iqia/ddxplus#ddxplus-a-new-dataset-for-automatic-medical-diagnosis

License:
https://creativecommons.org/licenses/by/4.0/

Original paper:

> Tchango, A. F., Goel, R., Wen, Z., Martel, J., & Ghosn, J. (2022).
> **DDXPlus: A New Dataset for Automatic Medical Diagnosis.**
> NeurIPS 2022 Datasets and Benchmarks Track.
> DOI: https://doi.org/10.48550/arXiv.2205.09148

The dataset was transformed to produce the disease prototype vectors included
with this package.
