feature: Self-Service Clinical Testing Sessions
This commit is contained in:
voltsrage
@@ -4,7 +4,7 @@
|
||||
|
||||
This guide walks you through testing the VigilCare monitoring dashboard. You will review simulated patient scenarios, decide whether alerts are clinically meaningful, and record structured feedback that helps the team improve the system.
|
||||
|
||||
No programming knowledge is required. A facilitator will start the backend services and open the dashboard in your browser.
|
||||
No programming knowledge is required. Log in to the dashboard, open **Simulation**, and start a testing session — the ward populates itself.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,6 +22,7 @@ No programming knowledge is required. A facilitator will start the backend servi
|
||||
10. [Submitting your feedback](#10-submitting-your-feedback)
|
||||
11. [Frequently asked questions](#11-frequently-asked-questions)
|
||||
12. [New dashboard features](#12-new-dashboard-features)
|
||||
13. [Running your own simulation](#13-running-your-own-simulation)
|
||||
|
||||
---
|
||||
|
||||
@@ -45,7 +46,9 @@ Your ratings are the primary output of this study. There are no right or wrong a
|
||||
|
||||
### Simulated patients only
|
||||
|
||||
All patients in this test are **fictional**. Data is generated by a replay simulator, not from real bedside monitors. Treat it like a training exercise, not live clinical work.
|
||||
All patients in this test are **fictional**. Data is generated by the in-app simulation runner, not from real bedside monitors. Treat it like a training exercise, not live clinical work.
|
||||
|
||||
While simulation mode is on, a **SIMULATION MODE** banner appears at the top of the dashboard. Simulated patients also show a **SIM** badge on the ward. Never assume a SIM patient is a real admission.
|
||||
|
||||
### Not a production EHR
|
||||
|
||||
@@ -55,28 +58,26 @@ This dashboard is a **research and evaluation tool**. It does not replace your h
|
||||
|
||||
You can tap **Ack** and **Resolve** on alerts to walk through the workflow. In this environment those actions update the test database only.
|
||||
|
||||
### Feedback stays in your browser (for now)
|
||||
### Feedback is saved on the server
|
||||
|
||||
Your ratings are saved in the browser on the computer you use. Export them at the end of the session (see [§10](#10-submitting-your-feedback)) and send the file to the study facilitator. If you switch computers or clear browser data without exporting, ratings may be lost.
|
||||
Your ratings are stored with the alert in the API (and carry which simulation scenario produced the alert when applicable). Export from **Alert Quality** or **Feedback Summary** at the end of the session if the study asks for a file copy.
|
||||
|
||||
### Default clinician ID
|
||||
### Your login identity
|
||||
|
||||
Acknowledging alerts uses a demo identifier (`DR-DEMO`) unless the facilitator configures yours. This does not affect your feedback ratings.
|
||||
Acknowledging alerts uses your signed-in name and role. Use the nurse or physician account provided for the session.
|
||||
|
||||
---
|
||||
|
||||
## 3. Getting to the dashboard
|
||||
|
||||
The facilitator will ensure the following are running. You only need the browser URL.
|
||||
1. Open the dashboard URL provided for your site (often **http://localhost:5173** in a local lab).
|
||||
2. Log in with the nurse or physician account you were given.
|
||||
3. In the sidebar, open **Simulation**.
|
||||
4. On the **Sessions** tab, pick a recommended session (see [§7](#7-recommended-testing-sessions)) and click **Start session**.
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| Dashboard | **http://localhost:5173** (or URL provided by facilitator) |
|
||||
| Your role | Review alerts and submit feedback |
|
||||
Patients appear on **Virtual Ward** as the session runs. You do not need a terminal or any command-line tools.
|
||||
|
||||
**On first open** you land on **Virtual Ward** — a list of active simulated patients sorted by acuity (NEWS2 score).
|
||||
|
||||
If the ward list is empty, ask the facilitator to start or replay a scenario (see [§8](#8-scenario-scripts)).
|
||||
If the ward is empty and you have not started a session yet, go back to **Simulation → Sessions**. If a previous tester left simulated patients behind, use **Reset ward** on the Simulation page (see [§13](#13-running-your-own-simulation)).
|
||||
|
||||
---
|
||||
|
||||
@@ -236,27 +237,27 @@ Short phrases are enough. Examples:
|
||||
|
||||
**Goal:** Learn the UI and rate at least 5 alerts.
|
||||
|
||||
1. Facilitator replays `stable-baseline-01` — confirm ward stays quiet or low acuity.
|
||||
2. Facilitator replays `uti-sepsis-elderly-01` at faster speed.
|
||||
3. You: Virtual Ward → open patient → review 2–3 alerts with reasoning + charts.
|
||||
4. You: Alert Center → rate remaining alerts.
|
||||
5. Feedback Summary → export CSV.
|
||||
1. Open **Simulation → Sessions** and start **Session A — Quick orientation**.
|
||||
2. Watch Virtual Ward as the two patients appear (stable baseline, then UTI/sepsis).
|
||||
3. Virtual Ward → open a patient → review 2–3 alerts with reasoning + charts.
|
||||
4. Alert Center → rate remaining alerts.
|
||||
5. Feedback Summary or Alert Quality → export CSV.
|
||||
|
||||
### Session B — Alert quality deep dive (45–60 minutes)
|
||||
|
||||
**Goal:** Compare alert types across scenarios.
|
||||
**Goal:** Compare alert types across contrasting scenarios.
|
||||
|
||||
1. `medication-false-alarm-01` — focus on false positives and missing context.
|
||||
2. `uti-sepsis-elderly-01` — sepsis, NEWS2, bundle panel.
|
||||
3. `respiratory-failure-asthma-01` or `post-op-hemorrhage-01` — deterioration patterns.
|
||||
4. Export CSV with notes on at least 10 alerts.
|
||||
1. Open **Simulation → Sessions** and start **Session B — Alert quality deep dive**.
|
||||
2. Rate alerts across the three patients; note differences between false-alarm and sepsis cases.
|
||||
3. Open **Alert Quality** → filter by scenario (e.g. `medication-false-alarm-01` vs `uti-sepsis-elderly-01`).
|
||||
4. Export CSV — `scenarioId` / `sessionId` columns attribute each rating.
|
||||
|
||||
### Session C — Ward workflow (30 minutes)
|
||||
|
||||
**Goal:** Test prioritization and handoff usability.
|
||||
**Goal:** Test prioritization and handoff usability on a full ward.
|
||||
|
||||
1. Facilitator runs `replay-all` on the scenario folder (or 2–3 scenarios back-to-back).
|
||||
2. You: Stay on Virtual Ward — note sort order as new patients appear.
|
||||
1. Open **Simulation → Sessions** and start **Session C — Ward workflow** (seven concurrent patients at high speed).
|
||||
2. Stay on Virtual Ward — note sort order as new patients appear.
|
||||
3. Try sorting by different columns (qSOFA, Alerts, Sepsis) — which view is most useful?
|
||||
4. Use the search bar and quick filters to narrow the list.
|
||||
5. Round on each high-NEWS2 patient — detail page only, no Alert Center until end.
|
||||
@@ -267,13 +268,13 @@ Short phrases are enough. Examples:
|
||||
|
||||
**Goal:** Evaluate the new dashboard features for clinical usefulness.
|
||||
|
||||
1. Facilitator replays 3–4 scenarios (including `uti-sepsis-elderly-01` for sepsis bundles).
|
||||
1. Open **Simulation → Sessions** and start **Session D — New features**.
|
||||
2. Open **Department Overview** — review the unit-level cards and summary stats.
|
||||
3. Open **Sepsis Bundle Board** — watch countdown timers and urgency sorting.
|
||||
4. Return to **Virtual Ward** — test the search bar, quick filters, and column sorting.
|
||||
5. Open a patient → use the **Vitals Entry form** to record manual observations.
|
||||
6. Wait for a critical alert → note the **critical alert banner**, sound, and browser notification.
|
||||
7. Acknowledge an alert using the new **role-aware modal** — review the note preview.
|
||||
7. Acknowledge an alert using the **role-aware modal** — review the note preview.
|
||||
8. Generate a **Handoff Report** and review the SBAR format.
|
||||
9. Document: *Which new features would you use on a real ward? Which need improvement?*
|
||||
|
||||
@@ -281,7 +282,7 @@ Short phrases are enough. Examples:
|
||||
|
||||
## 8. Scenario scripts
|
||||
|
||||
The facilitator runs these from a separate terminal. You watch the dashboard update.
|
||||
Reference only — the clinical stories behind each scenario file. You start these from **Simulation → Sessions** (or **Scenarios** for a single file); you do not need to run commands.
|
||||
|
||||
| Scenario | Clinical story | What to evaluate |
|
||||
|---|---|---|
|
||||
@@ -294,15 +295,7 @@ The facilitator runs these from a separate terminal. You watch the dashboard upd
|
||||
| `dka-electrolyte-01.json` | Metabolic emergency | Multi-parameter scoring, order visibility |
|
||||
| `hypothermia-elderly-01.json` | Temperature-driven risk | Temp warnings, NEWS2 contribution |
|
||||
|
||||
**Facilitator command (example):**
|
||||
|
||||
```bash
|
||||
dotnet run --project VigilCare.Simulator -- replay \
|
||||
VigilCare.Simulator/Scenarios/List/uti-sepsis-elderly-01.json \
|
||||
--speed 60
|
||||
```
|
||||
|
||||
`--speed 60` means 60× real time — a 3-hour scenario completes in a few minutes. Ask the facilitator to pause between scenarios if you need more review time.
|
||||
Replay **speed** is chosen on the Simulation page (Real time / Fast / Very fast / Instant). Session presets also carry a default speed you can override before starting.
|
||||
|
||||
---
|
||||
|
||||
@@ -377,30 +370,34 @@ Use this during or after your session.
|
||||
|
||||
At the end of your session:
|
||||
|
||||
1. Open **Feedback Summary** (sidebar → Feedback).
|
||||
2. Review totals and recent entries.
|
||||
1. Open **Alert Quality** (or **Feedback Summary**) from the sidebar.
|
||||
2. Review totals and, if simulation was used, the **By Scenario** breakdown.
|
||||
3. Click **Export CSV**.
|
||||
4. Save the file (e.g. `vigilcare-feedback-dr-smith-2026-06-20.csv`).
|
||||
5. Send to the facilitator via the method they specify (email, shared drive, study portal).
|
||||
5. Send to the study contact via the method they specify (email, shared drive, study portal).
|
||||
|
||||
The CSV contains: alert ID, alert type, severity, your rating, notes, and timestamp. The research team aggregates exports from all participants.
|
||||
The CSV includes alert ID, alert type, your rating, notes, timestamp, and — when simulation mode is enabled — **`scenarioId`** and **`sessionId`** so ratings can be compared across scenarios (especially useful for Session B).
|
||||
|
||||
**Optional:** Export JSON if the facilitator requests machine-readable format.
|
||||
|
||||
**Same computer:** Ratings persist if you refresh the page on the same browser. **Different computer:** Export before switching devices.
|
||||
**Same computer:** Ratings are stored on the server for your account. **Different computer:** Export before switching devices if you need a local copy.
|
||||
|
||||
---
|
||||
|
||||
## 11. Frequently asked questions
|
||||
|
||||
**I don’t see any patients.**
|
||||
The simulator may not have run yet, or all encounters are discharged. Ask the facilitator to replay a scenario.
|
||||
Open **Simulation → Sessions** and start a session (or an individual scenario on the Scenarios tab). If a previous tester left the ward empty after a reset, start Session A for a quick two-patient setup.
|
||||
|
||||
**How do I clear the ward for the next person?**
|
||||
On **Simulation**, use **Reset ward**. Confirm by typing `RESET`. This deletes only simulated patients and their alerts/feedback — never real patients. Stop any active runs first (or use **Stop all runs**).
|
||||
|
||||
**What does the SIM badge mean?**
|
||||
The patient was created by a simulation session or scenario replay. The amber **SIMULATION MODE** banner means the environment is allowed to create those patients. Treat SIM patients as training data only.
|
||||
|
||||
**Charts are empty but vitals show data.**
|
||||
Wait a few seconds — the page polls every 5 seconds. If charts stay empty, tell the facilitator.
|
||||
Wait a few seconds — the page polls every 5 seconds. If charts stay empty, refresh the patient page or tell the study contact.
|
||||
|
||||
**Can I rate the same alert twice?**
|
||||
You can change your rating; only the latest is kept per alert.
|
||||
You can change your rating; only the latest is kept per alert per user.
|
||||
|
||||
**Do I have to acknowledge before rating?**
|
||||
No. Rate any alert in any status.
|
||||
@@ -409,7 +406,7 @@ No. Rate any alert in any status.
|
||||
*Useful* = good alert clinically. *Would act* = you would specifically change care because of it. An alert can be useful information but not change your plan — use the button that best matches your reasoning.
|
||||
|
||||
**The replay bar doesn’t pause the simulator.**
|
||||
Correct — replay controls scrub observation/chart data already loaded in the browser (pause, speed, and **Next Alert →** move a local timeline). The facilitator controls simulator speed separately.
|
||||
Correct — replay controls scrub observation/chart data already loaded in the browser (pause, speed, and **Next Alert →** move a local timeline). Session and scenario speed are set on the **Simulation** page before you start.
|
||||
|
||||
**The alert sound is annoying — can I turn it off?**
|
||||
Yes. Click the sound toggle icon in the header bar to mute critical alert tones. The visual banner and browser notifications still appear.
|
||||
@@ -427,7 +424,7 @@ A hospital-wide view of all active sepsis bundles with live countdown timers. It
|
||||
Toggle in the header if your eyes prefer it; all screens support dark mode.
|
||||
|
||||
**Who do I contact with problems?**
|
||||
Speak to your session facilitator. Technical issues (blank screen, errors) may need them to restart the API or dashboard.
|
||||
Speak to your session contact. Technical issues (blank screen, errors) may need the API or dashboard restarted by whoever hosts the environment.
|
||||
|
||||
---
|
||||
|
||||
@@ -446,9 +443,12 @@ Speak to your session facilitator. Technical issues (blank screen, errors) may n
|
||||
| Understand why an alert fired | Patient Detail → click alert → Reasoning |
|
||||
| Acknowledge an alert | Alert Center or Patient Detail → Ack button → modal |
|
||||
| Rate an alert | Feedback buttons under alert card or reasoning |
|
||||
| See my ratings aggregate | Feedback Summary |
|
||||
| See ratings by scenario | Alert Quality → scenario filter / By Scenario |
|
||||
| See my ratings aggregate | Feedback Summary or Alert Quality |
|
||||
| Generate a shift handoff | Virtual Ward → Handoff Report button |
|
||||
| Submit results | Feedback Summary → Export CSV |
|
||||
| Start a testing session | Simulation → Sessions |
|
||||
| Clear simulated patients | Simulation → Reset ward |
|
||||
| Submit results | Alert Quality or Feedback Summary → Export CSV |
|
||||
|
||||
---
|
||||
|
||||
@@ -512,4 +512,28 @@ This makes the acknowledgment workflow more realistic and tracks who acknowledge
|
||||
|
||||
---
|
||||
|
||||
## 13. Running your own simulation
|
||||
|
||||
You can drive the entire evaluation from the dashboard — no terminal required.
|
||||
|
||||
### Session presets
|
||||
|
||||
**Simulation → Sessions** lists the recommended packs (A–D) with goals and estimated duration. **Start session** launches every scenario in the preset, staggered so the ward fills smoothly. Capacity is checked up front: if there are not enough free run slots, the Start button stays disabled with an explanation.
|
||||
|
||||
### Individual scenarios
|
||||
|
||||
**Simulation → Scenarios** is the full catalogue. Search and tag filters help you find a single case (e.g. a MIMIC-generated stay). Use this when you want one patient at a time rather than a full session.
|
||||
|
||||
### Speed
|
||||
|
||||
Choose **Real time**, **Fast**, **Very fast**, or **Instant** before starting. Session starts use this speed (overriding the preset default). Faster speeds are better for ward-round sessions; slower speeds help when you want to watch alerts arrive one by one.
|
||||
|
||||
### Reset
|
||||
|
||||
**Reset ward** removes all simulated patients, their observations, alerts, and feedback. Type `RESET` to confirm. Non-simulated patients are never deleted. Reset is blocked while runs are still active — use **Stop all runs** first.
|
||||
|
||||
After a reset, Virtual Ward and Alert Center should be empty of simulated data. Start Session A (or another preset) for the next tester.
|
||||
|
||||
---
|
||||
|
||||
*Thank you for participating. Your clinical feedback directly shapes whether VigilCare alerts help or harm real ward workflows.*
|
||||
|
||||
Reference in New Issue
Block a user