Skip to content

Note extraction dashboard

note_dashboard.py reads note_extractions.csv, written by note extraction, and writes self-contained HTML dashboards showing where ALS content was found in notes, reports and attached documents: ALSFRS-R scores, forced vital capacity (FVC) percent predicted, El Escorial certainty, onset region, family history and genes, the Edinburgh Cognitive and Behavioural ALS Screen (ECAS) and frontotemporal dementia (FTD), and dated treatment milestones. Every match is a candidate that still needs review; the dashboards show where candidates were found and do not confirm any fact.

Open the summary demo Open the review demo Module source (note_dashboard.py)

Two files with different audiences

File Written Contents Where it belongs
note_dashboard.html Always Counts only: participants with candidates in each category, every pattern with its context cues, and value distributions. Counts below k (default 5) are held back for cell size. Dates are never shown as values. reports/; review in full before sharing
note_dashboard_review.html Only with --with-excerpts Everything above plus up to three short excerpts per pattern, each from a different participant restricted/; stays with the review team

The excerpts in the review file have dates, long numbers, phone numbers and email addresses masked and are cut to about 220 characters. Names and other free text can remain, which is why the file stays inside the approved environment.

Tabs

Tab What it shows
Categories Participants with at least one candidate in each content category: ALSFRS-R, Pulmonary, Diagnosis, Family history and genetics, ECAS and FTD, Treatment milestones
All patterns Each pattern with its description, participant and record counts, and the share of matches with a context cue
Captured values For numeric patterns (ALSFRS-R total and domains, ECAS scores, FVC percent predicted), one value per participant summarized as 25th percentile, median and 75th percentile. For text patterns (El Escorial category, onset region, genes), the most common values with participant counts.
Excerpts Review file only: short masked excerpts with EX-NNNN pseudonyms that exist in that file only
About How the candidates were found and the k used

Minimum and maximum values are not shown, because a single extreme value belongs to one participant.

Context cues

The words just before each match are checked for four kinds of cue. A cue does not mean the match is wrong; it marks candidates to read first.

Cue Words checked
Possible negation "no", "not", "without", "negative for", "denies", "free of", "absence of", "ruled out", "resolved", in the same clause before the match
Possible family history a relative such as "mother" or "sibling", "maternal", "paternal" or "family history" anywhere in the sentence
Possible uncertainty "possible", "suspected", "concern for", "rule out", "r/o", "likely", "probable", "consider", "versus" before the match
Possibly historical "history of", "previously", "prior", "remote", "in the past", "years ago" before the match

Running it

run_all.py writes the summary to reports/note_dashboard.html, and with --with-excerpts writes the review file to restricted/. To run it on its own:

python pipeline/note_dashboard.py --extractions note_extractions.csv \
    --out reports/note_dashboard.html --k 5
python pipeline/note_dashboard.py --extractions note_extractions.csv \
    --out reports/note_dashboard.html --k 5 --with-excerpts

When run on its own with --with-excerpts, the review file is written next to the summary; move it into restricted/.

import note_dashboard
note_dashboard.main(
    extractions_csv_path='note_extractions.csv',
    out_path='reports/note_dashboard.html',
    cohort_name='Your cohort name',
    k=5,
    with_excerpts=False,
)

Before using any value

The patterns in note extraction are seed patterns written for ALS clinic notes. Phrasing, EHR templates and dictation habits differ between health systems, so check each pattern against a sample of documents from every contributing system, and have a reviewer confirm candidates against the source before any value (ALSFRS-R, FVC percent predicted, ECAS) is used in analysis. The Captured values tab is the quickest place to spot a pattern that needs tuning: values outside the possible range, or text that is not the expected kind of value.