Design #35 — nepExplorer migration: the KDIGO kidney-safety explorer

1. Summary

nepExplorer screens trial lab data for acute declines in renal function using the KDIGO acute-kidney-injury staging criteria. Its main object is a scatter — one point per participant, maximum fold change in serum creatinine on x against maximum absolute change on y, over coloured L-shaped stage zones — paired with a stage summary table and a click-through patient profile. That is the same shape as hep-explorer's eDISH quadrant plot, one organ over, so the architecture question was settled by the assessment: it is a canvas-first safety.viz module on the proven lifecycle, and the stage zones are a Chart.js background plugin like quadrantPlugin.

This design does four things:

• Re-derives the staging from KDIGO intent rather than porting the R implementation, and pins down exactly where the source disagrees with itself (§3). The known DELTA_STAGE trap turns out to have a sharper form than "an ordering bug": the R app's chart and its own table stage the same participant differently.
• Makes the module unit-aware with an explicit mg/dL contract and a refuse-to-guess fallback, because the fold axis is unit-safe and the absolute axis is not (§4).
• Settles the demo data, which is the part of this requirement that actually moved. Measured on the real files, today's pharmaverseadam demo cannot demonstrate this chart — not one of its 208 stageable participants crosses the Stage-1 line. Phase 1 therefore ships a deterministic synthetic AKI cohort injected into the shared adbds.csv (D8), designed to exercise every zone including the ≥ 4.0 mg/dL rule no real dataset here can reach; the RhoInc set stays Phase 2's source, as D1 decided (§5).
• Breaks Phase 1 into eight increments, the last two being the done gate and the requirement matrix, each small enough that one session can take it and stop (§8).

2. What is already decided (D1–D3)

D8–D7 below are new and open. D8 and D9 are refinements of D1 in light of §5's measurements; D4–D7 are the clinical-logic calls the port has to make and the source does not answer cleanly.

3. The clinical logic, re-derived

3.1 What KDIGO actually says about creatinine

The KDIGO AKI criteria stage a participant on serum creatinine three ways:

Two consequences the port has to respect. First, the absolute-change axis carries exactly one KDIGO cut-point — 0.3 mg/dL, and it only ever produces Stage 1. There is no KDIGO Stage 2 or Stage 3 defined on absolute change. Second, the ≥ 4.0 mg/dL rule is about the absolute value reached, not a change, so it is not a region of the (fold, delta) plane at all.

3.2 Where the R source disagrees with itself

Reading R/creatinine_data_fcn.R and R/creatinine_scatter_charts.R side by side:

The table stages absolute change with

DELTA_STAGE = case_when(
  DELTA_C > .3  ~ "Stage 1",
  DELTA_C > 1.5 ~ "Stage 2",
  DELTA_C > 2.5 ~ "Stage 3",
  TRUE ~ "Did not trigger Delta Creatinine Stage"
)

and because case_when returns the first match, every delta above 0.3 is labelled Stage 1 — the Stage 2 and Stage 3 branches are unreachable. That much was already flagged on #35. The sharper finding is what the chart does with the same numbers: draw_creatinine_scatter paints nested rectangles, largest first, so the visible zone boundaries are descending — Stage 3 fills the panel, Stage 2 is overpainted at x<3 ∧ y<2.5, Stage 1 at x<2 ∧ y<1.5, and white at x<1.5 ∧ y<0.3.

So in the shipped app, a participant with a 2.0 mg/dL rise and no fold change plots inside the orange Stage-2 zone and is labelled "Stage 1" in the table beside it. The chart geometry is right and the table is wrong; they were written from the same cut-points in opposite order. Porting either one alone would carry the disagreement forward.

Two smaller fidelity notes from the same file, offered as observations rather than defects to fix upstream:

• Baseline is positional. The baseline value is value[1L] after arrange(desc(baseline_flag)) — it works because "Y" sorts before "N", but it silently picks an arbitrary record when a participant has two flagged rows, and it depends on the flag's coding. The port takes an explicit baseline setting instead (D7).
• Negative deltas leave the plot. scale_y_continuous(limits = c(0, max_delta)) starts the axis at zero, so a participant whose creatinine only ever fell — max delta < 0 — is dropped by ggplot rather than drawn at the floor. In the RhoInc data that is a real population: the minimum per-participant max-delta is −0.71 mg/dL (D6).

4. Units: the mg/dL contract

The fold-change axis is a ratio and therefore unit-free. Everything else on this chart is not: 0.3 mg/dL and 4.0 mg/dL are absolute quantities, and creatinine is reported in µmol/L across most of the world — including in both demo datasets. The conversion is 1 mg/dL = 88.4 µmol/L.

Three requirements follow:

• Convert per record, not per dataset. Mixed units within one measure are not hypothetical: the current demo BDS file carries bilirubin in both mg/dL (256 records) and µmol/L (1654). Creatinine happens to be single-unit in both demo sets today, which is exactly why a per-dataset shortcut would pass review and then fail on a real study.
• Normalize the unit string before matching. The RhoInc set writes μmol/L with U+03BC (Greek small mu); pharmaverseadam writes umol/L. Match case-insensitively after folding µ/μ/u and trimming whitespace.
• Refuse to guess. When a record's unit is absent or unrecognised, the module does not assume mg/dL. It keeps the fold-change axis (always valid), suppresses the absolute cut-lines, the ≥ 4.0 mg/dL rule and the delta staging, labels the y-axis in the native unit, and says so in one line above the chart. A wrong staging is worse than an incomplete one.

units: {
  target: 'mg/dL',
  factors: { 'mg/dl': 1, 'umol/l': 1 / 88.4 }   // keys are normalized before lookup
}

Sponsor-specific factors vary, which nepExplorer itself warns about, so factors is a setting rather than a constant.

5. Data requirement

5.1 The record contract

Phase 1 needs one tall lab domain and nothing else. Phase 2 adds vitals (blood pressure) and the kidney-specialized measures.

Phase 1 requires only id, measure, value, unit and a way to find baseline. That is a deliberately small contract — it is what makes the KDIGO scatter portable to a study that has nothing but a chemistry panel.

5.2 The finding: pharmaverseadam cannot demonstrate this chart

The assessment recorded Phase 1 as "demoable on today's data" because creatinine is present. It is present, and the chart renders — but it does not demonstrate. Computed over the current site/data/adbds.csv:

On the current demo data every point lands in the white no-stage box, the three coloured zones stay empty, and the summary table reads 208 / 0 / 0 / 0. The renderer would ship with a gallery hero that shows a blob in a corner and an evidence page that cannot exercise the staging at all — the same "the demo has no signal" problem already filed for the hepatic data as safety.viz#89, but total rather than partial.

5.3 The Phase-1 demo cohort (D8)

A deterministic AKI cohort injected into site/data/adbds.csv after the main pharmaverseadam build, on the mechanism scripts/build-hep-composite-cohort.mjs already uses: fixed seed, idempotent, clearly-labelled participant IDs (AKI-* beside the existing CLD-*), labelled site and arm, provenance in docs/DATA_SOURCES.md.

What the cohort has to contain, given the decisions above — this is a chart-driven spec, not a plausible-population one:

• Creatinine in µmol/L, matching every other lab in the file. Writing the synthetic rows in mg/dL would let the demo bypass the unit-conversion path entirely (§4) — and that path is the one place a silent staging error can hide.
• All four stages populated on the fold axis, with enough participants per stage that the summary table's percentages mean something.
• At least one participant tripping the ≥ 4.0 mg/dL rule (D5), which no real dataset here can supply.
• At least one participant whose creatinine only falls, so D6's below-zero domain is visible rather than merely implemented.
• No baseline flag — adbds.csv has no such column, so the demo runs on D7's fallback, which is the path most real studies will take too.
• Enough visits per participant to trace a path, since the maximum is taken over the post-baseline series.

Plan for the blast radius. adbds.csv is shared by ten renderers, so injecting rows regenerates canonical Linux evidence baselines across all of them inside a PR that is otherwise about the kidney. That is the accepted cost of the CLD-* mechanism and #89's DEMO-6 asks for exactly this regeneration — but it belongs in the PR description up front, not as a surprise in the diff. Two further guards worth having: the injected participants must not perturb the other renderers' displays beyond the new rows (the CLD-* precedent shows how), and the cohort's data-shape assertions (the stage cases exist and land where intended) are their own tests, per DEMO-6.

5.4 Phase-2 data: the RhoInc set, and what is wrong with it

D8 settles Phase 1 and leaves Phase 2 where D1 put it: the RhoInc renderer-specific dataset — RhoInc/data-library, MIT-licensed, and safety.viz's own demo data before the v1.1.0 pharmaverse migration. It is the only source here of the measures pharmaverseadam lacks: cystatin C, eGFR, eGFRcys, urine albumin/creatinine and bicarbonate, alongside creatinine, BUN, the electrolytes and blood pressure. Two things to carry forward when Phase 2 starts:

• Build from the upstream file, not the old vendored copy. The source carries AGE and DY, which the v1.0.0 projection dropped — CKD-EPI needs age and sex, and the profile needs a study-day axis.
• It stages well too. Over its 110 stageable participants the fold ladder fills 73 / 24 / 10 / 3, maximum 5.60× — so if the synthetic cohort ever proves unconvincing for the scatter, this is a real-data fallback rather than a dead end.

But it solves the availability gap and exposes a coherence gap. Pairing every measure by participant and visit:

The measures were simulated independently. The medians are plausible — the shipped eGFR has median 88.8, a CKD-EPI-2021 recomputation from the same file's creatinine gives 85.5 — which is exactly why this needed checking per record rather than by summary. And the unit column confirms the columns were never derived: it labels eGFR μmol/L, which is not a filtration rate at all; the values (median 88.9, range 21–186) are mL/min/1.73m².

The Phase-1 scatter is untouched by this — it reads creatinine and nothing else. The Phase-2 profile is not: as shipped, it would show a participant whose creatinine tripled beside a flat eGFR panel and an unrelated cystatin C trace. That is a demo that teaches the wrong thing.

6. Module design — Phase 1

6.1 Shape

src/nep-explorer.js plus src/nep-explorer/, following the delta-delta / hep-explorer layout exactly: checkInputs → configure → structureData → getScales / getPlugins → new Chart, over the shared shell, with the standard lifecycle (init / setData / setSettings / render / resize / destroy) and registration in src/main.js as nepExplorer.

src/nep-explorer.js          public factory + lifecycle + shell wiring
src/nep-explorer/
  configure.js               DEFAULT_SETTINGS, syncSettings, the stages + units settings
  checkInputs.js             required columns, the creatinine measure, unit resolvability
  structureData.js           records → one staged participant per point
  getScales.js               axis domains, the 3.5× / 0.3-visible floors, tick labels
  getPlugins.js              stageZonesPlugin, the ≥4 mg/dL mark, selection borders
src/data/schema/nep-explorer.json   the data schema, per the house convention

6.2 structureData

One reduce per setData, producing one row per participant:

{ id, baseline, baselineVisit, max, maxVisit, maxDay,
  fold, delta,            // delta in mg/dL, or null when the unit is unknown
  foldStage, deltaStage, stage,   // stage = worse of the two, plus the ≥4 rule
  absoluteRule }          // true when max ≥ 4.0 mg/dL

Records drop, counted and exportable, when: the value is non-numeric; the participant has no resolvable baseline; the participant has no post-baseline record. The unit is resolved per record before any comparison (§4).

6.3 The chart

• Axes. x = fold change, domain [0, max(3.5, observed)] so all three fold cut-points are always on screen — the R chart's floor, worth keeping because it is what makes an all-Stage-0 study readable as "nothing here" rather than "nothing plotted". y = absolute change in mg/dL, domain [min(0, observed), max(0.4, observed)] per D6. Ticks are labelled at the cut-points (1.5×, 2.0×, 3.0×; 0.3 mg/dL).
• stageZonesPlugin — a beforeDatasetsDraw plugin painting the zones from §3's geometry, largest stage first, so points are always drawn on top. Same hook and the same "read the live scales, paint in pixel space" technique as hep-explorer's quadrantPlugin and outlier-explorer's normal-range band; the difference is filled regions rather than cut-lines. Zone labels sit in the left margin of each band and can be hidden, as quadrant_labels already does.
• Colours. The source uses ColorBrewer YlOrRd (#ffeda0 / #feb24c / #f03b20). Stage is ordinal severity, so it takes the house status ramp rather than a categorical slot, at a background-appropriate opacity, and every zone is labelled — never colour alone.
• Marks. One point per participant. The ≥ 4.0 mg/dL rule gets a distinct marker (D5). Click selects, dispatching the shell's participantsSelected event — which is the seam Phase 2 mounts onto, so Phase 1 wires it even though the profile is not built yet.
• Tooltip. The source's nine lines, kept: participant, KDIGO stage, fold change, delta stage, absolute change, baseline creatinine, maximum creatinine, and the study day and visit the maximum came from.

6.4 The summary table

The R app's table is not a cross-tabulation, as the assessment described it — it is two marginal distributions sharing a stage row label: Stage 0–3 down the side, then N and % for the fold-change staging and N and % for the delta staging. Keep that shape, in the shell's listing area, with a third pair for the combined stage (the one the zones show), because with D4's ladder the combined column is what a reviewer reads off the chart.

7. Phase 2 preview — the patient profile

Not in scope for Phase 1 and gated on D9, but two things belong on the record now because they change what Phase 1 should leave behind.

It should be the participant-profile module, not a bespoke panel. #75 shipped the shared profile as a right rail with a labs-over-time chart, a measure table and an AE block, adopted by eight renderers. nepExplorer's profile is five small-multiple panels grouped by measure family (creatinine + cystatin C, eGFR + eGFRcys, related electrolytes, blood pressure, urine ACR) with KDIGO reference lines. The right question at the Phase-2 gate is whether that becomes a measure-group option on the shared profile rather than a second profile implementation. Phase 1 keeps the seam open by dispatching the standard selection event.

A third source trap, for whoever picks Phase 2 up. drawPercentChange plots (value − baseline) / baseline — a percent change, where a 1.5× rise is 0.5 — and then draws its KDIGO reference lines at y = 1.5, 2 and 3, which on that scale are 2.5×, 3× and 4×. The "KDIGO Stage 1" line is drawn where Stage 2 nearly begins. Whichever scale Phase 2 picks, the thresholds have to be expressed on the same one.

8. Delivery and the done gate

Each row is meant to be shippable on its own. The whole of Phase 1 is one safety.viz implementation issue (drafted, awaiting the design gate) and, per the one-PR-per-session convention, likely one PR to dev.

One evidence note. The unknown-unit fallback (§4) cannot be reached from a demo whose units are all known, so it needs a unit test on synthetic input — the kind of branch that ships untested precisely because the demo looks complete. The ≥ 4.0 mg/dL rule was the other one, and D8 removes it from that list: the cohort is specified to carry a participant who trips it, so it earns browser evidence like everything else.

9. Requirement matrix plan

safety.viz/requirements/nep-explorer.md, on the NEP-<AREA>-<NNN> base-ID scheme so the evidence pages resolve each row by exact ID, structured like qt-explorer.md — the closest precedent, being the other phased port of a SafetyGraphics Shiny app.

Where a row exists because the port diverges from the R source — the staging ladder, the negative-delta domain, the mark-based ≥ 4 rule — the matrix row says so in its Notes, with §3 as the citation. That is the record that keeps "we fixed their bug" from reading like "we got it wrong" at review time three months from now.

10. Risks and what this design does not settle

• The Phase-1 demo is simulated injury. D8 buys a chart that exercises every zone, and a single shared extract, at the price of a flagship kidney demo in which no participant is real. The CLD-* precedent means the mechanism and its labelling are proven, but the guide page should be as plain about it as the hepatic composite view is — and the RhoInc set (§5.4) remains the real-data fallback if the synthetic cloud reads as too tidy.
• The Phase-1 PR now touches every renderer's evidence. Injecting into adbds.csv regenerates canonical baselines across ten modules. That is expected and #89 asks for it, but it makes the diff large and the review harder, and it couples this work to whatever else is in flight against those baselines. Sequencing it against #89 rather than racing it is the cheap mitigation.
• Phase 2's dataset question is still open, where the recommendation would have closed it. D1 and §5.4 point at the RhoInc set, but nothing is built or vendored, and Phase 2 also needs the coherence fix in D9. Worth confirming at the Phase-2 gate rather than assuming §5.4 is a plan.
• The KDIGO time window is not implemented, here or upstream. KDIGO stages an acute injury — the 0.3 mg/dL rise is defined within 48 hours, the fold change within 7 days. Neither the R app nor this design applies a window; both take the maximum over the whole study. That is a screening simplification, not the criteria, and the guide page has to say so plainly, the way the QT guide says its ΔΔ CI is not the regulatory bound.
• Clinical sign-off on the ladder. D4 changes the staging a nepExplorer user sees. It is defensible from the criteria and from the source's own chart, but it is a clinical call presented by an agent reading R code, and it should be confirmed by someone who owns the clinical content before the evidence page claims KDIGO conformance.
• Cystatin C coherence stays broken under D9's recommendation, and Phase 2's profile will show it. The fix is a synthetic regeneration nobody has scoped.
• The gsm.safety widget binding is out of scope for both phases, on that package's own cadence, as with every renderer so far.

Drafted by Claude Code using Opus 5 and reviewed by @jwildfire.