HighCostDrugsDemo/docs/USER_GUIDE.md

User Guide - NHS Patient Pathway Analysis Tool

This guide explains how to use the NHS High-Cost Drug Patient Pathway Analysis Tool to analyze treatment pathways for secondary care patients.

Table of Contents

1. Getting Started
2. Interface Overview
3. Filtering Data
4. Using the Drug Browser
5. Understanding the Pathway Chart
6. GP Indication Matching
7. Troubleshooting

---

Getting Started

Accessing the Application

Start the application by running:

python run_dash.py

Then open your browser to http://localhost:8050

The application automatically loads pre-computed pathway data from SQLite on startup. No additional setup is needed to view existing data.

Data Freshness

The header bar shows when data was last refreshed:

• Patient count: Total patients in the dataset (e.g., "11,118 patients")
• Last updated: Relative time since the last data refresh (e.g., "2h ago")

To refresh the data, run the CLI command (requires Snowflake access):

python -m cli.refresh_pathways --chart-type all

---

Interface Overview

The application is a single-page layout with the following components:

Header

• NHS branding and application title ("HCD Analysis")
• Green status dot with patient count and last-updated time

Sidebar (Left)

Navigation items including:

• Pathway Overview — main view (always active)
• Drug Selection — opens the drug browser drawer
• Trust Selection — opens the drawer with trust chips
• Indications — opens the drawer with directorate browser

KPI Row

Four summary cards that update dynamically:

• Unique Patients — number of distinct patients matching current filters
• Drug Types — number of distinct drugs in filtered data
• Total Cost — total cost of treatments in the filtered dataset
• Indication Match — GP diagnosis match rate (~93% for indication charts, shown as "—" for directory charts)

Filter Bar

• Chart type toggle: "By Directory" / "By Indication" pills
• Treatment Initiated: All years, Last 2 years, or Last 1 year
• Last Seen: Last 6 months or Last 12 months

Chart Card

• Dynamic subtitle showing the current hierarchy (e.g., "Trust → Directorate → Drug → Pathway")
• Interactive Plotly icicle chart
• Loading spinner during data fetch

---

Filtering Data

Chart Type

Toggle between two views using the pills in the filter bar:

View	Hierarchy	Best For
By Directory	Trust → Directorate → Drug → Pathway	Understanding treatment by medical specialty
By Indication	Trust → GP Diagnosis → Drug → Pathway	Understanding treatment by patient condition

Date Filters

Two dropdowns control the time window:

Filter	Options	Effect
Treatment Initiated	All years, Last 2 years, Last 1 year	When patients started treatment
Last Seen	Last 6 months, Last 12 months	Most recent activity window

The default is "All years / Last 6 months" — showing all patients who have been active in the last 6 months.

Drug and Trust Selection

Open the drawer (right panel) by clicking "Drug Selection" or "Trust Selection" in the sidebar:

• Drug chips: Click to select/deselect specific drugs. Selected drugs filter the chart.
• Trust chips: Click to select/deselect specific NHS trusts.
• Clear All Filters: Button at the bottom resets all drug and trust selections.

No selections = show everything. Leaving chips unselected is the same as selecting all.

---

Using the Drug Browser

The drawer contains three sections:

All Drugs

A flat list of all 42 available drugs as selectable chips. Click one or more to filter the chart to those drugs only.

Trusts

A list of 7 NHS trusts as selectable chips. Click to filter by specific organizations.

By Directorate

An accordion browser organized by clinical directorate:

1. Click a directorate (e.g., "CARDIOLOGY") to expand it
2. Inside, click an indication (e.g., "heart failure") to expand further
3. Each indication shows drug fragment badges (e.g., "SACUBITRIL", "IVABRADINE")
4. Clicking a drug fragment badge selects all full drug names that contain that fragment

For example, clicking the "ADALIMUMAB" badge would select "ADALIMUMAB" in the drug chips above.

Fragment Matching

Drug fragments are substrings, not exact matches. The fragment "INHALED" would match drugs like "INHALED BECLOMETASONE" and "INHALED FLUTICASONE".

Clicking a fragment toggles its matching drugs:

• First click: Selects all matching drugs
• Second click: Deselects all matching drugs (if all were already selected)

---

Understanding the Pathway Chart

Hierarchy Structure

The icicle chart displays a hierarchical breakdown:

Directory view:

Root (Regional Total)
  └─ Trust (e.g., "Norfolk and Norwich University Hospitals")
      └─ Directorate (e.g., "RHEUMATOLOGY")
          └─ Drug (e.g., "ADALIMUMAB")
              └─ Pathway (e.g., "ADALIMUMAB → INFLIXIMAB")

Indication view:

Root (Regional Total)
  └─ Trust
      └─ GP Diagnosis (e.g., "rheumatoid arthritis")
          └─ Drug
              └─ Pathway

Reading the Chart

• Width of each section indicates relative patient count
• Color intensity (NHS blue gradient) indicates proportion of parent group
• Labels show the name and patient count

Interacting with the Chart

Action	Effect
Click a section	Zoom in to show details for that branch
Click the parent/root	Zoom back out
Hover over a section	See tooltip with patient count, cost, dosing frequency, dates

Hover Tooltip Information

When hovering over a chart section, you'll see:

• Patient count and percentage of parent
• Total cost and cost per patient
• First and last seen dates
• Treatment dosing frequency (for drug nodes)
• Cost per patient per annum

---

GP Indication Matching

When viewing "By Indication" charts, the application uses pre-computed GP diagnosis matches:

How It Works

1. During data refresh, each patient's NHS pseudonym is queried against GP primary care records
2. SNOMED cluster codes map clinical conditions to drug indications
3. The most recent GP diagnosis match is used for each patient
4. ~93% of patients are matched to a GP diagnosis

Unmatched Patients

Patients without a GP diagnosis match appear under their directorate with a "(no GP dx)" suffix (e.g., "RHEUMATOLOGY (no GP dx)").

Reasons for unmatched patients:

• GP is outside the data coverage area
• Diagnosis not yet recorded in GP system
• Condition managed only in secondary care
• Off-label prescribing

---

Troubleshooting

No data showing

1. Check the filter bar — are filters too restrictive?
2. Try clearing all drug/trust selections in the drawer
3. Widen the date range (e.g., "All years / Last 12 months")

Chart shows "No matching pathways found"

The current filter combination matches zero patients. Adjust filters or click "Clear All Filters" in the drawer.

App won't start

# Ensure dependencies are installed
uv sync

# Ensure src/ is on Python path
uv run python setup_dev.py

# Run with uv
uv run python run_dash.py

Stale data

Data is as fresh as the last CLI refresh. Check the header's "Last updated" indicator. To refresh:

python -m cli.refresh_pathways --chart-type all

---

Getting Help

If you encounter issues not covered in this guide:

1. Check the README for installation and setup
2. Review DEPLOYMENT.md for server configuration
3. Consult CLAUDE.md for technical architecture details
4. Contact the Medicines Intelligence team for NHS-specific questions