# VigilCare Dashboard — Charts & Visualizations Guide

This document describes every chart in the VigilCare Clinical dashboard: what it shows, how to read it, and what the colors and thresholds mean.

---

## Table of Contents

1. [Vital Signs Trends (5 Charts)](#1-vital-signs-trends)
2. [NEWS2 History](#2-news2-history-chart)
3. [GCS History](#3-gcs-history-chart)
4. [qSOFA Screen History](#4-qsofa-screen-history-chart)
5. [SOFA History](#5-sofa-history-chart)
6. [Alert Quality](#6-alert-quality-chart)
7. [Department Acuity Bar](#7-department-acuity-bar)

---

## 1. Vital Signs Trends

**Location:** Patient Detail view — rendered as a 2×3 grid of line charts  
**Component:** `TrendsGrid.vue` → `VitalTrendChart.vue` → `VitalChart.vue`

### Overview

Five individual line charts, one per vital sign, showing how each measurement has changed over time. Each chart plots recorded observations on the X-axis (time) and the vital value on the Y-axis.

### Individual Charts

| Vital Sign | Y-Axis Range | Line Color | Unit |
|---|---|---|---|
| Heart Rate | 30 – 180 | Red (#ef4444) | bpm |
| Respiratory Rate | 0 – 40 | Blue (#3b82f6) | breaths/min |
| Systolic Blood Pressure | 60 – 250 | Purple (#8b5cf6) | mmHg |
| SpO₂ (Oxygen Saturation) | 80 – 100 | Cyan (#06b6d4) | % |
| Temperature | 34 – 42 | Amber (#f59e0b) | °C |

### How to Read

- **Each dot** on the line represents a single recorded observation at a specific time.
- **The line** connecting the dots shows the trend direction — rising, falling, or stable.
- **Y-axis** is fixed to a clinically relevant range so that values near the edges indicate an abnormal reading.
- **X-axis** labels show timestamps of when each observation was recorded.

### Medication Markers

Dashed purple vertical lines may appear on any vital chart. These mark the time a medication was administered.

- **Hover over** a purple line to see the drug name, dose, route, and timestamp.
- Medication markers help correlate treatment events with changes in vital signs (e.g., did a dose of antihypertensive cause blood pressure to drop?).
- The tooltip activates within a 15-minute window of the marker.

---

## 2. NEWS2 History Chart

**Location:** Patient Detail view  
**Component:** `News2History.vue`

### What It Shows

The **National Early Warning Score 2 (NEWS2)** over time. NEWS2 is an aggregate score (0–20) calculated from six physiological parameters: respiratory rate, oxygen saturation, systolic blood pressure, pulse rate, consciousness level, and temperature. A higher score indicates greater clinical deterioration.

### How to Read

- **Blue line** traces the NEWS2 score at each assessment point.
- **Y-axis:** 0 to 20 (total NEWS2 range).
- **X-axis:** Time of each assessment.
- **Each dot** (radius 4px) is one assessment — hover for the exact score.

### Background Color Bands (Severity Zones)

The chart background is color-filled to show the severity of the score:

| Background Color | Score Range | Meaning |
|---|---|---|
| **Green** | 0 – 4 | **Low risk** — routine monitoring is appropriate |
| **Amber** | 5 – 6 | **Medium risk** — increased frequency of monitoring; urgent clinical review needed |
| **Red** | 7 – 20 | **High risk** — emergency assessment required; continuous monitoring |

**Key insight:** If the line enters the amber or red zone, the patient's condition is deteriorating and requires escalated care. A line that stays in or returns to the green zone suggests clinical stability or improvement.

---

## 3. GCS History Chart

**Location:** Patient Detail view  
**Component:** `GcsHistory.vue`

### What It Shows

The **Glasgow Coma Scale (GCS)** over time. GCS measures a patient's level of consciousness across three components: Eye opening (1–4), Verbal response (1–5), and Motor response (1–6). The total ranges from 3 (deep unresponsiveness) to 15 (fully alert).

### How to Read

This chart displays **four lines**:

| Line | Color | Style | Range |
|---|---|---|---|
| **GCS Total** | Dark accent | Solid, thick (2px) | 3 – 15 |
| Eye component | Blue (#3b82f6) | Dashed | 1 – 4 |
| Verbal component | Purple (#8b5cf6) | Dashed | 1 – 5 |
| Motor component | Cyan (#06b6d4) | Dashed | 1 – 6 |

- **Focus on the solid total line** for an overall consciousness assessment.
- **Use the dashed component lines** to identify which specific domain is changing (e.g., verbal response dropping while motor stays stable may indicate different clinical concerns than all three declining together).

### Point Colors on the Total Line (Severity)

The dots on the GCS total line change color to indicate severity:

| Point & Fill Color | Score Range | Severity |
|---|---|---|
| **Green** (#22c55e) | 13 – 15 | **Mild** — patient is alert and oriented |
| **Amber** (#f59e0b) | 9 – 12 | **Moderate** — impaired consciousness |
| **Red** (#dc2626) | 3 – 8 | **Severe** — patient may need intubation/airway protection |

**Key insight:** A downward trend (especially into the red zone) signals worsening neurological status. The tooltip footer displays the severity label for each point.

---

## 4. qSOFA Screen History Chart

**Location:** Patient Detail view  
**Component:** `QsofaHistory.vue`

### What It Shows

The **quick Sequential Organ Failure Assessment (qSOFA)** screen results over time. qSOFA is a bedside screening tool for sepsis risk using three criteria:

1. **Respiratory rate ≥ 22 breaths/min**
2. **Systolic blood pressure ≤ 100 mmHg**
3. **Altered mentation** (GCS < 15)

Each criterion is scored as either present (1) or absent (0), giving a total of 0–3 active criteria.

### How to Read

This is a **dual-axis chart**:

**Left Y-axis — Active Criteria Count (0–3):**
- The solid stepped line shows how many qSOFA criteria are met at each assessment.
- Points are color-coded by risk level.

**Right Y-axis — Individual Criteria (normalized 0–1):**
- Three dashed lines show whether each individual criterion is present (1) or absent (0):
  - **Respiratory rate:** Blue (#3b82f6) dashed
  - **Systolic BP:** Purple (#8b5cf6) dashed
  - **Altered mentation:** Pink (#ec4899) dashed

### Point Colors & Shapes

| Color | Count | Meaning |
|---|---|---|
| **Green** (#22c55e) | 0 criteria | **Screen negative** — low sepsis risk |
| **Amber** (#f59e0b) | 1 criterion | **Screen negative** — one criterion present, monitor closely |
| **Red** (#dc2626) | ≥ 2 criteria | **Screen positive** — suspected sepsis; escalate care |

- **Circle points:** Standard assessment.
- **Star points (larger, radius 7):** An alert was fired at this assessment time.

**Key insight:** A score of ≥ 2 is the critical threshold — this is a **positive qSOFA screen** suggesting possible sepsis. The tooltip shows whether the screen was positive/negative and whether an alert fired.

---

## 5. SOFA History Chart

**Location:** Patient Detail view  
**Component:** `SofaHistory.vue`

### What It Shows

The **Sequential Organ Failure Assessment (SOFA)** score over time. SOFA provides a more detailed assessment of organ dysfunction than qSOFA, scoring six organ systems on a 0–4 scale each, for a total range of 0–24.

### How to Read

This chart has **two visual layers**:

#### Layer 1: Stacked Area (Organ System Contributions)

Six semi-transparent colored areas stacked on top of each other, showing how much each organ system contributes to the total SOFA score:

| Organ System | Color |
|---|---|
| Respiratory | Blue (#3b82f6) |
| Coagulation | Purple (#8b5cf6) |
| Liver | Amber (#f59e0b) |
| Cardiovascular | Red (#ef4444) |
| CNS (Central Nervous System) | Pink (#ec4899) |
| Renal | Cyan (#06b6d4) |

The **height of each colored band** represents that organ system's individual score (0–4). The **total stack height** equals the total SOFA score.

#### Layer 2: Total SOFA Line (Overlaid)

A solid line with color-coded dots sits on top of the stacked areas:

| Point Color | Score Range | Risk Level |
|---|---|---|
| **Green** (#22c55e) | 0 – 5 | **Low** — minimal organ dysfunction |
| **Amber** (#f59e0b) | 6 – 9 | **Moderate** — significant organ dysfunction |
| **Red** (#dc2626) | ≥ 10 | **High** — severe organ dysfunction; high mortality risk |

**Key insight:** This chart answers two questions at once: (1) How severe is overall organ dysfunction? (read the total line) and (2) Which organ systems are driving the score? (read the colored stacked bands). For example, if the respiratory (blue) band is growing while others stay flat, the lungs are the primary concern.

---

## 6. Alert Quality Chart

**Location:** Alert Quality Analytics view  
**Component:** `AlertQualityChart.vue`

### What It Shows

Quality and performance metrics for the clinical alerting system over time. This chart evaluates how useful and accurate the alerts are. It can display one of four metrics at a time (controlled by the view):

| Metric | What It Measures |
|---|---|
| **Useful Rate %** | Percentage of alerts that clinicians rated as clinically useful |
| **False Positive Rate %** | Percentage of alerts that turned out to be false alarms |
| **Acknowledgement Rate %** | Percentage of alerts that were acknowledged by staff |
| **Would Act Rate %** | Percentage of alerts where a clinician said they would take clinical action |

### How to Read

- **Blue line** traces the metric value over time.
- **Light blue fill** below the line provides visual weight.
- **Y-axis:** 0% to 100%.
- **X-axis:** Alert types or time windows (sorted by alert window start time).
- **Each dot** is one data point — hover for the exact percentage.

**Key insight:**
- **Useful Rate / Would Act Rate:** Higher is better — clinicians find the alerts actionable.
- **False Positive Rate:** Lower is better — high values indicate alert fatigue risk.
- **Acknowledgement Rate:** Higher is better — low values may indicate staff are ignoring alerts.

This chart is used by system administrators and quality improvement teams to tune alerting thresholds and reduce alert fatigue.

---

## 7. Department Acuity Bar

**Location:** Department Overview view (inside each Department Card)  
**Component:** `AcuityBar.vue`

### What It Shows

A horizontal stacked bar showing the **distribution of patient acuity levels** within a department at a glance.

### How to Read

The bar is divided into up to three colored segments, each proportional to the number of patients at that acuity level:

| Segment Color | Acuity Level | Meaning |
|---|---|---|
| **Green** (#22c55e) | Low | Stable patients requiring routine care |
| **Amber** (#f59e0b) | Medium | Patients requiring increased monitoring or clinical attention |
| **Red** (#dc2626) | High | Critical patients requiring urgent or intensive care |
| **Gray** (#d1d5db) | Empty | No patients (shown when department has capacity) |

- **Segment width** is proportional to the percentage of patients at each level.
- **Count labels** below the bar show the exact number of patients in each category.
- **Hover** over a segment to see the exact count.

**Key insight:** A bar that is mostly red indicates a department under heavy clinical pressure. A bar that shifts from green to amber/red over time suggests a department's workload is escalating.

---

## Universal Visual Conventions

### Color Coding (Traffic Light System)

Across all clinical charts, the dashboard uses a consistent traffic-light color scheme:

| Color | Hex | Meaning |
|---|---|---|
| **Green** | #22c55e | Safe / Low risk / Normal |
| **Amber** | #f59e0b | Warning / Medium risk / Monitor |
| **Red** | #dc2626 or #ef4444 | Critical / High risk / Escalate |

### Dark Mode

All charts support dark mode. Grid lines, text, and backgrounds automatically adjust:
- **Light mode:** Dark text (#6b7280), subtle gridlines
- **Dark mode:** Light text (#9ca3af), subdued gridlines

### Interactivity

- **Hover tooltips** are available on all charts — hover over any data point for exact values.
- **Legends** appear at the bottom of multi-dataset charts (GCS, qSOFA, SOFA).
- **Medication markers** (purple dashed lines) can appear on any vital signs chart.

### Responsiveness

All charts maintain a 16:9 aspect ratio and have a minimum height of 220px for readability on smaller screens. Animations are disabled when the user has the "prefers reduced motion" accessibility setting enabled.