Contributing¶

Corrections, new studies, better models and code are all welcome. This page says where each kind of contribution goes, the rules that apply everywhere, and the steps for the common cases.

Where things live¶

All of these repositories are public. To report a problem or suggest a change, open an issue on the repository concerned, naming the page or file; for an atlas page, that is metrology-atlas. Questions and wider discussion are welcome in its Discussions.

Rules that apply everywhere¶

• Name a case only when it is the point. VitalDB's case ids are public, and a study may name a case when it discusses a specific example: an edge case, a clear illustration of a mechanism, or a comparison of two cases. Write it as [[case:1234]]; the atlas lists every named case on Cases discussed with the pages that name it, and refuses a case number written any other way, so no id appears by accident. Population and group results, and figures of a general principle, carry no ids; a figure that shows specific cases lists them under records:. The code repositories follow the same rule; what they must not publish is bulk per-case output, which their test_no_per_case_files.py checks.
• Per-case results stay on the analysis machine. Only aggregates and figures are published. A script writes its per-case output to a local work folder, then a second step aggregates it.
• Each fact lives in one place. A model's numbers live in its library; the atlas pins a snapshot and reads them from it. A number the atlas holds is a parameter with its study, so other pages refer to it rather than repeat it.
• Every number says how it is known: measured (from the data, by a study), derived, estimated or assumed. Never state a number without its status and where it came from.
• History is kept, not overwritten. When a result changes, the old study or observation is marked superseded, and the new one says what it supersedes.
• Contributions are made under the repository's licence; atlas text and figures are CC BY 4.0 (see Data and licence).

Correcting or extending an atlas page¶

Every page is built from one YAML file in datasets/vitaldb/, in a folder named after its kind (variables/, clocks/, studies/ ...). The schema, with a help text for every field, is in metrology_atlas/model.py.

1. Edit or add the YAML file. Its id must equal the file name. Link other items with [[kind:id]], and code with [[code:software-id/path/to/file.py]].
2. Check it: python -m metrology_atlas check datasets/vitaldb. This finds every broken reference, unknown field, missing figure, code path that does not exist, and forbidden pattern.
3. Build the site and look at the page: python -m metrology_atlas site datasets/vitaldb --out build/vitaldb, then zensical build in that folder.
4. Open a pull request that says what changed and why.

Two folders are never edited by hand. _sources/ holds pinned snapshots of other libraries, and _generated/ holds items written from them by the import scripts in _import/. To add to a generated page (a discussion, a better name, a measurand), write a file with the same id in the normal folder: its fields are merged over the generated ones and win.

Updating a study¶

A study is a short report: background, data (in aggregate), method, results, discussion, limitations, and the code that ran it. Its numbers are parameters (parameters/), each naming the study.

• A correction that does not change the conclusion (a typo, a clearer method, a missing limitation): edit the study in place.
• A new result: write a new study, list the old one under supersedes:, and set the old one's status: to superseded. Give changed numbers new parameters and set superseded_by: on the old ones. Pages then show both, with the old marked.
• An observation (a general fact about the data) moves between established, likely, open and withdrawn as evidence comes in. Withdraw rather than delete.
• List the scripts under code:, as software-id/path, so the page links to them. The check warns when a script is not yet committed, because its link will not work until it is pushed.

Improving or correcting a value model¶

The value models (rounding modes, heaping, charted times) live in vitaldb-resolution. The atlas shows them, one study per model, read from a pinned snapshot. Each model is meant to be examined on its own: its study page gives the data, the fit, the figures and what is still open, and anyone can propose a better fit or point out a wrong one.

How models are versioned. Each model has its own version (aneend v1, v2 …). A published model file is never edited: a refit or a correction becomes a new version, and the old one stays in the library and can still be called (model="aneend@1"), so results made with it can be reproduced. Each model file records a hash of its fitted numbers and what it was fitted on (data release, exclusion rules, fitting code and seed). Each package release ships a models.lock listing the version and hash of every model; most users pin a release, and anyone can pin a single model. Every result the library returns names the model version that made it. (This scheme is being introduced from the next release; until then the atlas pins the library by commit.)

If you only have a suggestion, open an issue on vitaldb-resolution naming the model and what you think is wrong, or settle one of the open questions on its study page. Evidence helps most: a figure, a count, or a better-fitting alternative.

To propose a new version, in vitaldb-resolution:

1. Change the model, or the decision that sets it. Decisions about each variable's resolution are recorded where tools/build_registry.py says; rebuild the registry with that script after a decision changes.
2. Refit as a new version of that model; leave the current file as it is.
3. Validate against the data with tools/validate.py: every fitted model must reproduce its stored log-likelihood, and every value must return a status.
4. Compare the new version with the current one on the same data: log-likelihood and BIC, the propensities, and any figure that shows the difference. Say what changed and why in the pull request.
5. Run the tests (pytest -q tests, including the per-case files check), regenerate the variables page with tools/gen_variables_page.py, and open a pull request. Once it is merged, the new version becomes current in the next release.

Then in the atlas:

1. Refresh the snapshot: python datasets/vitaldb/_import/resolution.py <path to vitaldb-resolution>. This copies the registry and models, records the commit in _sources/vitaldb-resolution/SOURCE.yaml, and rewrites the generated variables and model studies.
2. Recompute how wide each variable's distributions are in the release: python datasets/vitaldb/_import/resolution_spread.py <path to vitaldb-resolution> <VitalDB release folder> (aggregates only; run it until it reports nothing left), then run the import in step 6 again so the variable pages pick it up. For the fitted models, also redraw the worked examples and joint maps on the variable pages: python datasets/vitaldb/_import/value_slices.py <path to vitaldb-resolution> <VitalDB release folder> (aggregates only; it uses the snapshot's commit, never uncommitted changes; run it until nothing is left).
3. Copy the commit and date from SOURCE.yaml into sources: in dataset.yaml, so every page states which version of the model it shows.
4. Say what changed in a hand-written file for that model's study (for example studies/value-model-height.yaml, with a discussion:), and credit whoever proposed it. Check and build as above.

Contributing code to vitaldb-bench¶

vitaldb-bench holds the analysis behind most studies. Set it up with pip install -e ".[tools,test]", copy scripts/local.env.example to local.env (which git ignores), and point VITALDB_ROOT at your copy of the VitalDB release and VITALDB_WORK at a work folder for per-case output.

Where code goes:

• The package (vitaldb_bench/): code others import, such as builds, stores, the clock model, corrected times and labels. Python 3.11 or later, formatted and linted with ruff (line length 120), with Google-style docstrings and tests in tests/.
• Analysis scripts (tools/): one script per analysis. Start it with a module docstring whose first paragraph says what it does and what leaves the machine ("Per case, this machine only; aggregates leave."): that paragraph becomes its entry in the scripts reference, regenerated by tools/gen_tools_page.py. Follow the two-step pattern: a resumable per-case pass that writes to the work folder, then an aggregate or plot step that writes to results/. Add each published file to the table in …/how-to/reproduce-results.md.
• Short helpers kept only because a number came from them go in tools/adhoc/, with a one-line docstring.

Before a pull request, run pytest -q (which includes the per-case files check) and ruff. Then link the script from the atlas study it supports, under code:.

Checklist¶

• [ ] Case ids only where a specific case is discussed (in the atlas as [[case:N]]); no bulk per-case files committed.
• [ ] Only aggregates and figures published.
• [ ] Every new number has a status and a study.
• [ ] Changed results supersede the old ones rather than overwrite them.
• [ ] Code linked from the study that uses it, and committed.
• [ ] The atlas check and build pass.

Open questions¶

The studies so far have left questions of four kinds. Some results are seen clearly but nobody can yet explain them. Some have a working explanation that the evidence only weakly supports. Some rest on assumptions that the data in the release cannot test, so they hold only until someone finds outside evidence. And in a few places two studies give answers that disagree. Each entry below names the question, links to the study where it is discussed, and says briefly what is known. Settling one, or showing that one of these assumptions is wrong, is among the most useful contributions you can make; the study page usually says what would settle it. Checks still to run and decisions still to make are listed on each study page and on the Open questions page, not here.

Unexplained phenomena¶

• 34 files whose records overlap throughout · Records out of order at SNUADC resets, and where the lost time goes
  Mostly explained since: records written twice and two interleaved streams (Eight recordings store whole messages twice, In some recordings two unrelated streams are interleaved in one track); whether these account for all 34 is not checked (In 34 files the SNUADC records overlap throughout).
• A residual of −13 ppm · SNUADC against the PC-stamped heart rate
  On the corrected SNUADC line the ECG-to-HR delay still ramps by −13.0 ± 4.0 ppm. It may be the Solar8000's own processing, an error in the stamp model's rate, or the PC; a larger run (all step-mode cases without gaps) would narrow it. The whole-release run (The SNUADC clock through the Solar8000 numerics, whole release) cannot settle it: per recording it is too noisy, and in recordings under about 4 h its rate is biased toward zero.
• About 50 s more than rounding · Anaesthesia record times are rounded up
  The anaesthesia record times sit later than rounding alone explains. Documentation lag and an offset between the EMR clock and the recorder cannot be separated with these data.
• Anaesthesia start ignores the 5-minute rule · How the anesthesia start time was charted
  Why does anaesthesia start not follow the 5-minute rule the paper describes? Were there two entry methods, or a change of system partway through?
• Is 150 mg a ceiling? · Rounding and heaping of propofol bolus
  Is 150 mg a ceiling people write for any large dose, or are larger doses usually given as a second bolus and summed? The upper tail is right only in the first case. Adding 200 mg to the set did not pass BIC.
• Long regular runs that may be paced · Paced ECG as an independent clock
  About 40 cases have long regular runs (370–920 ms) whose interval wanders by about 1 ms between stretches. Whether they are paced is not settled.
• Misfits at 90 mg and 130 mg · Rounding and heaping of propofol bolus
  The misfits at 90 mg and 130 mg are unexplained.
• Recordings that change correction mode partway · The stamp sawtooth model for SNUADC and BIS
  Recordings that change correction mode partway still fail the model (p99 about 250 ms). Why a recording changes mode, and how to fit both parts, is open.
• Recordings that never correct their clocks · Clock corrections in every file
  Some recordings never correct their clocks within the 2 s test. Slower units, a third recorder mode, or both, could explain it. The shared bursts point to slower units (about −36 ppm where the BIS rate is known; Long SNUADC recordings with no correction at all); their drift units have not been compared with the rest. Followed up on The stamp sawtooth model for SNUADC and BIS.
• The filler sample · Records out of order at SNUADC resets, and where the lost time goes
  Why most resets hold one extra zero sample, a little after the gap, is not known.
• The ventilation loop only partly closes · Closing loops in the timing graph
  The ventilation loop only partly closes: its two physiological arms differ by 37–46 ppm.
• Thoracic records are much finer than gynaecology's · Rounding and heaping of intraoperative urine output
  Thoracic surgery charts urine output mostly to 10 or 5 mL, gynaecology and urology mostly to 50 or 100 mL, even at the same volumes. The model now lets the rounding propensities depend on department (it improves BIC by 87), but why they differ is not known: a urometer with fine graduations in some theatres and a drainage bag in others would explain it. The urology split rests on 41 records.
• Twelve unmatched resets · Records out of order at SNUADC resets, and where the lost time goes
  Twelve unmatched resets have small interleaved steps of 8–12 ms. Whether they are resets of a different size or something else is not known.
• Vigileo rarely aligns · Rare devices against SNUADC
  Vigileo aligns in only 25 of 343 cases; whether its values are too smooth or its clock too unstable is not known.
• What event anaesthesia start marks · How the anesthesia start time was charted
  Partly answered: device-marked induction (BIS loss of consciousness, else the propofol pump start) comes a median 14 minutes after the charted start (10th–90th percentile 6 to 25 minutes) in 2,913 cases (Post-induction hypotension, from the charted start and from the devices), so the charted time marks the start of anaesthesia care, not induction. Which event of care it records (arrival, monitoring, pre-oxygenation) is open.
• What replaces the sawtooth · Where the PPG sawtooth stops
  At the start and end of some recordings the PPG lag is not flat but ramps by several ms per minute against arterial pressure. Its cause is not known.
• What sets the steps at the AWP pauses · The Primus ventilator against SNUADC, by breaths
  Partly answered by The Primus stamp step at each airway-pressure pause (2,491 pauses): where CO₂ carries on through the AWP pause the stamps barely step (median −1 ms, p10–p90 −164 to +187 ms); the large steps, up to seconds, come where CO₂ stops too (26% of pauses). None undoes the drift built up. Open: what the stamps re-anchor to when both waveforms stop.
• What the kidney-surgery colloid values record · Colloid container rules
  What do the kidney-surgery values record: a different product, a fixed small dose, or albumin in grams? Until confirmed, values of 50 mL or less are flagged unit_uncertain at native resolution. The VitalDB team or local protocols would settle it.
• What the Primus's small corrections correct · How often each device is corrected
  The corrections imply 1–11 ppm, but breath matching measures the Primus drifting about +104 ppm against the recorder PC (Primus drift against the recorder PC, from breath matching), and the stamps also step at the AWP pauses by amounts unrelated to the drift built up. What the small steps correct, if not the drift, is open. (This replaces the earlier conflict between 1–11 ppm and the assumed 115 ppm, which breath matching settled.)
• Where the sawtooth stops · Pulse arrival time in two correction steps
  In some stretches no slip comes although several were due, and the delay is flat (Where the PPG sawtooth stops). The model treats the stretch before and after a pause as creep then hold, of unknown length, which leaves up to one frame of uncertainty there.
• Which firmware ran · The SNUADC firmware
  The deployed version, and which converter channel feeds which track, are not known.
• Which unit is which device · Physical units, shared drift and time order
  Units are inferred from drift alone, and busy ports carried several units. The physical boards behind each unit are not identified.
• Why 12% of files run at a different slope · SNUADC stamp arithmetic
  747 files sit between −0.90 and −0.55 ppm instead of −0.954, with no trend through the release. A different recorder build or a different stamp increment are the obvious candidates; comparing these files' header version, device list and correction mode with the rest would test it.
• Why imputed op ends cluster in thoracic and non-general cases · Imputed times, conformance failures and exclusion rules
  Imputed op ends are twice as common in thoracic surgery as in general surgery, and four to six times as common under sedation or spinal anaesthesia as under general anaesthesia. Cases without a charted op end are not spread at random; why these groups lack one (a different charting workflow, a different person recording, the operation's end not being marked) is not known, and the VitalDB team could say.
• Why some PaO₂ records are whole numbers · Pre-operative PaO₂ decimal rule
  Which of the two candidate explanations (two analysers or a manual transcription step) is behind the whole- number records is not known.
• Why the artefact shows in only some cases · The cardiac artefact in the BIS EEG
  A clear averaged artefact appears in 13 of 30 cases. What decides whether it is visible (electrode placement, signal quality, filtering) is not known.
• Why the constant offset differs between modes · The stamp sawtooth model for SNUADC and BIS
  The EEG lags the ECG by −0.80 s in step mode and −0.66 s in frequent mode after the model (whole release; −0.69 s in the pilot); why the constant differs between modes is not known.

Weakly supported hypotheses¶

• A fixed-point stamp behind −0.954 ppm · SNUADC stamp arithmetic
  A 0.2 s increment held at a resolution of 2⁻²⁰ s fits, but is unproven; the recorder's source or one controlled recording would settle it.
• Analyte p as phosphorus · Heaping screen of all variables
  The analyte coded p (16,440 results) is missing from lab_parameters.csv. Its median of 3.2 (IQR 2.7–3.8, p5–p95 1.9–5.0) fits phosphorus in mg/dL, the only common analyte with that range, but only the VitalDB team can confirm it.
• The BIS constant as processing latency · Closing loops in the timing graph
  The loop closes in drift and steps but leaves −0.80 s (step mode) or −0.69 s (frequent mode; −0.66 s over the whole release). A processing latency in the BIS is the working explanation; it fits the sign and size but has no direct evidence, and it does not explain why the constant differs between modes.
• The recording PC sets the fast path · Two heart-rate delay groups, one poll apart
  Some recordings get the Solar8000 heart rate one 2 s poll earlier, and on a given recording sometimes do not. The PC key predicts the group for 94% of cases, so the working explanation is the PC's polling path; what makes an early-majority PC deliver late in some recordings is not in the release.
• Two firmware versions behind the reset order · Records out of order at SNUADC resets, and where the lost time goes
  1,785 files write their reset clusters out of order and 820 in order, and no file does both. Two recorder or firmware versions would explain the clean split, but nothing in the release shows which file ran which; file headers and recording dates (hidden in the release) would tell.
• Two out-of-range end times as 12-hour or date errors · How the anesthesia end time was charted
  Two anaesthesia-end records lie at 720 and 1,441 minutes, outside the modelled range. A 12-hour clock slip and a one-day date error are the obvious explanations; neither is confirmed.
• What the stamps re-anchor to when both waveforms stop · The Primus stamp step at each airway-pressure pause
  Steps of up to seconds come where AWP and CO₂ stop together. A re-opened connection re-anchoring the stamps to the PC's arrival time is the working explanation; the recorder's message log around those gaps would test it.
• Why 10 bits from a 12-bit converter? · Value resolution of every signal
  Either the SNUADC used in the release was a 10-bit design, or a 12-bit converter's readings are reduced to 10 bits before they are sent (which the observed truncation would fit). The SNUADC firmware or the VitalDB team could settle it.
• Why does the SNUADC appear to speed up when the BIS slows down? · When each device's clock is corrected, in every recording
  Within a recording, the SNUADC and BIS drift deviations against the recorder PC are anticorrelated (r = −0.54, 133 recordings; shuffled null −0.01), the opposite of what a shared PC excursion would give. Candidates: a common factor acting on the two oscillators with opposite signs (temperature, on crystals of different cuts), or a coupling in how the two drifts are measured. Test against each recording's time course (temperature itself is not recorded; operating-room events and recording length are proxies) and in the joint clock model.

Untestable assumptions¶

• Age as completed years · Blood products, age and ICU days
  Age is taken as completed years (floor). The release documents only "years"; whole-number adults, infants in tenths of a year and the cap at 89 point to an exact age cut down, but the data cannot test it. Rounded age would shift every value by half a year.
• Blood products in millilitres · Intraoperative fluid balance as a distribution
  The release gives red cells and plasma in units. A unit's volume (typically 250–350 mL for red cells) is not recorded, so the balance leaves these cases out; an assumed range would bring them in with a wider distribution.
• Every instrument within its calibration · Instrument accuracy and calibration
  The atlas treats each instrument as accurate: no bias, no drift between calibrations, imprecision ignored. The release cannot test this. Calibration and quality-control records for every measuring device used in the VitalDB cases (laboratory analysers, monitors, infusion pumps, ventilators, scales and stadiometers) would replace the assumption with a measured accuracy for each variable. This is beyond the scope of this work, but the hospital will hold the records, and publishing them in a metrology atlas like this one would make every variable's uncertainty complete.
• How ICU days are counted · Blood products, age and ICU days
  The release does not say. The counts argue against calendar days touched (815 one-day stays against 98 two-day stays, where that rule would make 2 the commonest value), so the atlas reads them as nights in the ICU or completed days, which the data cannot tell apart. The VitalDB team could settle it.
• Is 90 ms from radial artery to finger plausible? · One device delay for the PLETH across the release
  With the global 385 ms, finger PAT exceeds radial-artery PAT by about 90 ms foot to foot. Published values for the radial-to-fingertip pulse transit (and for the volume pulse lagging the pressure pulse) would check the adopted 270 ms independently; a larger or smaller gap there would move the global delay by the same amount.
• Is a recording without a BIS on the same PC as its key's other recordings? · Identifying the recording setup of every case
  The assignment assumes that a recording made without a BIS used the same PC as the complete recordings that share its other ports. Validation hides the BIS of recordings that had one, so it cannot test this; a BIS-free recording on a PC kept only for such cases would be assigned to the wrong setup. Clock fingerprints would test it.
• Is SaO₂ measured or calculated? · End-tidal to arterial CO₂, and pulse oximetry against blood gas, at the right moment
  Many blood-gas analysers calculate SaO₂ from PO₂ and pH rather than measuring it by co-oximetry. Which was used decides whether SaO₂ − SpO₂ compares two measurements or a measurement with a model.
• No time axis for era effects · How the anesthesia start time was charted
  Resolution cannot be checked by era: case IDs are random (the release says so, and they are uncorrelated with anything dated), and dates are removed. The models assume rounding habits were constant over the years the data cover. Department makes no difference; emergency cases are rounded a little more often.
• One PC key, one PC · Identifying the recording setup of every case
  The register treats each PC key as one recorder PC. Two PCs cabled identically would share a key; the release cannot show it directly, though Two heart-rate delay groups, one poll apart found keys that separate their cases almost perfectly (purity 0.90–0.97), and clock fingerprints could find exceptions.
• PC clock steps, not slews · Recorder PC clock steps and recording pauses
  The analysis assumes the recorder PC's clock corrects in steps. Slow slewing would look like device drift and cannot be told apart from it with these data.
• The adopted 0.27 s · Pulse arrival time in two correction steps
  The global delay is the release's median stored delay to the pulse foot (655 ms) minus 0.27 s, a mean R-to-foot finger PAT for anaesthetised adults from studies that sampled ECG and PPG on one clock (The PPG hardware delay and the adopted pulse arrival time). Differences between patients and changes within a case are measured; the absolute level of every case moves with the adopted value. It implies a finger-minus-radial difference of about 90 ms foot to foot, which a literature value could check.
• The PC-to-UTC link · Recovering the time of day
  Every route from a device clock to UTC passes through the recorder PC's clock, which is assumed to have been kept on UTC by network time. The release holds no second, independent clock against which to test it, so this link is assumed, not measured.
• The recorder PC's time zone · Recovering the time of day
  Whether its Unix time was true UTC, or local time read as UTC, cannot be tested in the release.
• Turnaround after the timestamp · What the lab timestamp marks
  The release has no result times, so the turnaround from the lab timestamp to the result is assumed, not measured.
• What plausible PAT range should be shown for anaesthetised adults? · Pulse arrival time in two correction steps
  The figure shades 200–285 ms to the foot (shifted by 59 ms to the upstroke), the range of means in shared-clock studies of awake adults (The PPG hardware delay and the adopted pulse arrival time). That is a range of study averages, not of individual windows, and anaesthesia lengthens PAT by about 40 ms. A verified range for adults under anaesthesia, ideally of individual values, is still needed; Ruffolo et al. 2025 gives one for critically ill children.

Conflicts between studies¶

• Does the setup still fix the drift on the whole release? · Identifying the recording setup of every case
  The register's drifts come from the correction scan's cases (472 SNUADC step-mode and 1,627 BIS recordings, one duration-weighted rate per recording, including the −0.95 ppm stamp arithmetic). There the PC key puts 97% of SNUADC and 83% of BIS drifts within 3 ppm of their setup's median. Rerun on the whole release's correction intervals (When each device's clock is corrected, in every recording: 642 SNUADC and 1,939 BIS recordings), the same test gives 71% and 60% (against 25% and 17% for the release median). The setup still narrows the drift a great deal, but less than the register says; the difference may be the drift's variation within a recording (a median 3.5 ppm for the BIS), which a single interval does not average out. Which rate per recording the register should use is not decided.
• How far does the SNUADC drift in frequent-correction mode? · SNUADC stamp arithmetic
  Between corrections the frequent-mode stamps show only the −0.95 ppm of stamp arithmetic, which is why the real drift in that mode is put under about 1 ppm. But the small forward corrections that keep those stamps on the PC add up to more: about one an hour of +5 to +15 ms (SNUADC frequent-correction steps), and the correction scan's per-recording drift for the 82 frequent-mode recordings it could fit has a median of +2.7 ppm (10th percentile −0.9; Clock corrections in every file). The drift against the PC is what the corrections remove, so it may be a few ppm rather than under one. Not reconciled.
• Rounded up or to the nearest: two studies disagree · Anaesthesia record times are rounded up
  For anaesthesia start, the device markers here favour rounding up, but only by a small margin, while the value model, which compares the charted time with the recording start, prefers the nearest mark by 47 BIC points (How the anesthesia start time was charted). For anaesthesia end the two agree (rounded up). Operation start and end were not measured here; their value models give the nearest mark and rounding down (How the operation end time was charted, Bias in charted intervals), while the EMR timing entry (Anaesthesia record events) treats every 5-minute entry as rounded up. Not reconciled.
• Vigilance: 13 cases or 52 · Rare devices against SNUADC
  Vigilance fits differ between the two analyses (13 cases in the rare-device scan, 52 in the window study); the difference has not been reconciled.