Skip to content

README.md

Latest commit

 

History

History
246 lines (171 loc) · 5.9 KB

README.md

File metadata and controls

246 lines (171 loc) · 5.9 KB
Raw

Developed in collaboration with Lampros Mpaltadoros.

❤️ AFib Cardiology Records and ECG Visualization App

A Django web application for managing anonymized cardiology subject records and visualizing uploaded ECG waveform files.

Django App → Authentication → Subject Records → ECG Upload → Waveform Visualization → Clinical Summary Dashboard

Important: This is a software demonstration app. It is not a medical or diagnostic system.

🔍 Overview

This project demonstrates a Django-based application for storing and reviewing anonymized AFib/cardiology subject records. The app includes authentication, subject CRUD workflows, search and rhythm filtering, dashboard-level summary visualizations, and an ECG upload feature that plots waveform files on each subject detail page.

The original project has been cleaned and modernized so it can run from a fresh environment without the old local virtual environment or SQLite database.

⚙️ Features

Feature Description
Authentication Register, login, and logout workflows
Subject dashboard List anonymized cardiology records
Summary visualizations Display rhythm, age, gender, and electrical-axis distributions with Chart.js
Search and filtering Search by subject label and filter by rhythm
CRUD operations Create, view, update, and delete subject records
ECG upload Upload a .csv or .txt ECG waveform file for each subject
ECG waveform visualization Plot uploaded ECG time-series data on the subject detail page
Demo data Synthetic subject records and a synthetic ECG sample for local testing

📈 ECG Visualization

Each subject record can optionally include an uploaded ECG file. The subject detail page reads the file, parses the waveform, and renders it as an interactive line chart.

Supported upload formats:

.csv or .txt

Supported ECG structures:

time,amplitude
0.000,0.01
0.004,0.03
0.008,0.05

or one amplitude value per line:

0.01
0.03
0.05

If the uploaded file contains only amplitude values, fill in the subject's ECG sampling rate (Hz) field so the x-axis can be interpreted in seconds.

A synthetic ECG example is included at:

data/demo/sample_ecg.csv

See docs/ECG_UPLOAD_FORMAT.md for details.

🧪 Repository Structure

afib-cardiology-records-app/
├── afibapp/                 # Django project settings and URL config
├── project/                 # Main cardiology records app
├── users/                   # Authentication-related views/templates
├── templates/               # Shared templates
├── static/                  # CSS and images
├── fixtures/                # Synthetic subject records
├── data/demo/               # Synthetic ECG example file
├── docs/                    # Upgrade, data model, and ECG format notes
├── scripts/                 # Smoke test script
├── manage.py
├── requirements.txt
├── environment.yml
├── .env.example
├── .gitignore
└── README.md

🚀 Run Locally

Create and activate a virtual environment:

python -m venv .venv

Windows PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

macOS/Linux:

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Run migrations:

python manage.py migrate

Optional: load synthetic demo subject records:

python manage.py loaddata fixtures/demo_subjects.json

Create an admin/superuser account:

python manage.py createsuperuser

Start the development server:

python manage.py runserver

Open:

http://127.0.0.1:8000/

🩺 How to Upload and View an ECG

  1. Log in.
  2. Open the subject dashboard:
http://127.0.0.1:8000/subjects/
  1. Create or edit a subject.
  2. Upload an ECG file in the ECG file field.
  3. Optionally add the ECG sampling rate (Hz).
  4. Save the subject.
  5. Open the subject detail page to view the ECG waveform.

For testing, use:

data/demo/sample_ecg.csv

✅ Smoke Test

After installing dependencies, run:

python scripts/smoke_test.py

The test checks the Django project configuration and verifies that migrations are in sync.

🔒 Data and Privacy

The original local SQLite database is not included. This prevents sharing local users, passwords, or subject records. The repository includes only synthetic demo records and a synthetic ECG sample.

Files excluded from version control include:

db.sqlite3
*.sqlite3
media/
.venv/
env/
__pycache__/
staticfiles/
.env

Uploaded ECG files are stored under media/ecg_uploads/ during local development and are not committed to GitHub.

🛠️ Technical Stack

  • Python
  • Django 5.2 LTS
  • SQLite
  • Bootstrap 5
  • Chart.js
  • HTML/CSS

⚠️ Limitations

  • The app is intended for software demonstration and local development.
  • It is not designed for production deployment without additional security, privacy, and compliance work.
  • The included subject records and ECG waveform are synthetic.
  • The ECG visualization is intended for viewing uploaded waveform data, not automated diagnosis.
  • It is not a medical or diagnostic system.

📄 License

Code in this repository is provided under the MIT License.