nexusbert/heart-disease-random-forest

Heart Disease Controlled Random Forest

A controlled Random Forest classifier for binary heart disease classification using seven selected and preprocessed features.

This model was developed as part of a comparative machine learning research project evaluating traditional machine learning and neural-network approaches for tabular heart disease classification.

Model Overview

The model is a RandomForestClassifier implemented using scikit-learn.

The controlled configuration was selected to reduce unnecessary model complexity while maintaining strong predictive performance.

Target

Binary classification:

• 0 — No Heart Disease
• 1 — Heart Disease

Input Features

The model expects seven features in exactly this order:

Index	Feature
0	Age
1	Resting Blood Pressure
2	Cholesterol
3	Fasting Blood Sugar
4	Oldpeak
5	Exercise Angina: No
6	Exercise Angina: Yes

The features must be supplied in the same preprocessed representation used during training.

Random Forest Configuration

n_estimators = 300
max_depth = 6
min_samples_split = 20
min_samples_leaf = 10
max_features = sqrt
class_weight = balanced
random_state = 42
n_jobs = -1

Dataset Split

The dataset used for the experiment was divided into:

Split	Samples
Training	38,427
Validation	8,235
Test	8,235

The validation and test sets were kept separate from model training.

Validation Performance

The controlled Random Forest achieved:

Metric	Score
Accuracy	1.0000
Precision	1.0000
Recall	1.0000
F1 Score	1.0000
ROC-AUC	1.0000
PR-AUC	1.0000

Test Performance

The final held-out test performance was:

Metric	Score
Accuracy	0.9999
Precision	1.0000
Recall	0.9998
F1 Score	0.9999
ROC-AUC	1.0000
PR-AUC	1.0000

These results correspond to the experimental test split described above.

Repository Contents

heart-disease-random-forest/
├── README.md
├── config.json
├── metrics.json
├── model.joblib
├── inference.py
└── requirements.txt

model.joblib

Contains the trained Random Forest model.

config.json

Contains model configuration and metadata required by the inference implementation.

metrics.json

Contains recorded evaluation metrics.

inference.py

Provides the inference interface for making predictions.

requirements.txt

Contains the Python dependencies required to run the model.

Installation

Clone or download this repository and install the dependencies:

pip install -r requirements.txt

Usage

The repository includes an inference.py module for prediction.

Example:

from inference import predict


features = [
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    1.0
]


result = predict(features)


print(result)

The seven values must correspond to the model's expected feature order.

Example Result

A prediction may contain information similar to:

{
    "prediction": 1,
    "label": "Heart Disease",
    "probability": 0.97
}

The probability is model-generated and depends on the supplied input.

Preprocessing Important

this model expects the seven features in the preprocessed representation used during training. Raw clinical measurements should not be passed directly to the model unless they have first undergone the same preprocessing procedure used during model development.

For example, a raw value such as:

Age = 56

may not correspond directly to the numerical representation expected by the trained model.

For reproducible inference, the original preprocessing procedure should be applied before generating predictions.

Feature Representation

The two exercise-angina features are represented using one-hot encoding:

• Exercise Angina: No
• Exercise Angina: Yes

Therefore, the model expects both corresponding feature positions.

Example:

• No -> [1, 0]
• Yes -> [0, 1]

The complete feature vector therefore contains seven values.

Intended Use

This model is intended for:

• Machine learning research
• Educational demonstrations
• Benchmarking tabular classification models
• Experimentation with Random Forest classifiers
• Research into explainable machine learning

Limitations

This model is a research and educational machine learning system.

It is not a medical diagnostic device and should not be used to diagnose, treat, prevent, or make clinical decisions about an individual.

The reported performance was obtained on the dataset and experimental split used during development. Performance on external or real-world clinical populations may differ substantially.

Healthcare Safety

Predictions from machine learning models should not be interpreted as medical diagnoses.

Any real-world healthcare application would require appropriate clinical validation, external testing, monitoring, regulatory review, and involvement of qualified healthcare professionals.

Reproducibility

The model uses:

random_state = 42

to provide deterministic Random Forest behavior under the same software and data conditions.

Reproducing the reported metrics also requires using the same dataset, preprocessing procedure, feature selection procedure, and train/validation/test split.

Model Card Authors

Developed as part of a heart disease machine learning research project.