README.md

metadata

title: CardioScreen AI API
emoji: 🫀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

CardioScreen AI

AI-Assisted Cardiac Screening Tool for Canine Heart Disease
Clinical Validation Study — Veterinary Internal Medicine Thesis

---

Overview

CardioScreen AI is a web-based clinical screening tool that analyzes canine heart sounds (phonocardiograms) to detect cardiac murmurs using a dual-analysis pipeline: a CNN deep learning classifier (primary) and a DSP signal processing analyzer (supplementary).

The system records or accepts audio input from a digital stethoscope, processes it through noise reduction and quality assessment, and provides a Heart Score (1-10) with clinical interpretation.

Architecture

Audio Input (WAV/MP3/Recording)
       │
       ▼
┌─────────────────────────┐
│    Audio Preprocessing   │
│  • Spectral gating NR    │
│  • Bandpass (25-600 Hz)  │
│  • Normalization         │
└────────┬────────────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌──────────┐
│  DSP   │ │   CNN    │
│ (10%)  │ │  (90%)   │
│ Suppl. │ │ Primary  │
└───┬────┘ └────┬─────┘
    │           │
    ▼           ▼
┌─────────────────────────┐
│   Heart Score (1-10)     │
│  Quality-gated fusion    │
│  Clinical interpretation │
└─────────────────────────┘

CNN Pipeline (Primary)

• Input: Mel-spectrogram (128 frequency bands, 128 time steps)
• Model: 1D CNN with 3 convolutional layers (32→64→128 filters)
• Training: 940 balanced recordings (multi-species foundational mix), stratified 5-fold CV
• Performance: 96.3% sensitivity, 96.0% specificity (after threshold tuning)

DSP Pipeline (Supplementary)

• Features: Energy ratio, HF ratio, consistency, spectral entropy, MFCC variance
• Model: Logistic regression trained on 21 annotated recordings
• Quality gating: Automatically dampened when noise is detected

Heart Score

• Composite score: 90% CNN + 10% DSP
• Quality dampening: pulls score toward neutral (5) when recording quality is poor
• Risk levels: Low (8-10), Moderate (6-7), Elevated (4-5), High (1-3)

Dataset

Source	Recordings	Description
PhysioNet CirCor 2022	470	Human pediatric (foundational base)
Kaggle Heart Sounds	200	Mixed cardiac recordings
Hannover Vet School	150	Veterinary clinical recordings
VetCPD / Clinical	120	Canine auscultation samples
Total	940	Balanced (Normal/Murmur)

Performance

Metric	Value
Sensitivity (Recall)	96.3%
Specificity	96.0%
Accuracy	95.9%
Precision (PPV)	96.7%
F1 Score	0.965

Confusion Matrix (Pre-tuning)

	Pred Normal	Pred Murmur
Actual Normal	153 (TN)	46 (FP)
Actual Murmur	18 (FN)	1330 (TP)

Technology Stack

Component	Technology
Frontend	React + Vite
Backend	FastAPI (Python)
ML Framework	PyTorch
Audio Processing	librosa, scipy, soundfile
PDF Reports	jsPDF
Deployment	Render.com

Installation & Running

Prerequisites

• Python 3.9+ with GPU support (optional, for training)
• Node.js 18+

Backend Setup

# Create virtual environment
python -m venv gpu_env
gpu_env\Scripts\activate  # Windows
# source gpu_env/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Download pre-trained model (from Hugging Face)
python download_hf_model.py

# Start API server
python -m uvicorn api:app --host 0.0.0.0 --port 8000

Frontend Setup

cd webapp
npm install
npm run dev

The application will be available at http://localhost:5173.

Environment Variables

# webapp/.env.local (development)
VITE_API_URL=http://127.0.0.1:8000/analyze

# webapp/.env.production (deployment)
VITE_API_URL=https://your-api-url.onrender.com/analyze

Project Structure

├── api.py                  # FastAPI backend
├── inference.py            # ML inference engine
│   ├── load_audio()        # Audio preprocessing
│   ├── reduce_noise()      # Spectral gating NR
│   ├── calculate_bpm()     # Heart rate detection
│   ├── score_quality()     # Signal quality scoring
│   ├── detect_murmur()     # DSP murmur detection
│   ├── predict_cnn()       # CNN inference
│   └── calculate_heart_score()  # Composite scoring
├── models/
│   └── cnn_heart_classifier.pt  # Trained CNN model
├── webapp/
│   ├── src/
│   │   ├── App.jsx         # Main application
│   │   ├── App.css         # Component styles
│   │   └── index.css       # Design system
│   └── package.json
├── src/
│   ├── train_cnn.py        # CNN training script
│   └── find_threshold.py   # Threshold optimization
├── requirements.txt
└── render.yaml             # Deployment config

Features

• 🎤 Live Recording — Record directly from stethoscope microphone
• 📁 File Upload — Support for WAV, MP3, and other audio formats
• ✂️ Audio Trimming — Trim recordings to isolate heart sounds
• 🧠 Dual Analysis — CNN + DSP independent classification
• 📊 Heart Score — 1-10 composite score with clinical interpretation
• 🛡️ Quality Scoring — SNR, regularity, clipping, duration assessment
• 📄 PDF Reports — Professional clinical screening reports
• 📈 Validation Page — Model performance metrics and confusion matrix

Disclaimer

This is an AI-assisted screening tool for preliminary cardiac assessment. Results are NOT diagnostic. All findings should be confirmed by a veterinary cardiologist via echocardiography.

License

This project was developed as part of a veterinary internal medicine thesis. For academic use.