# health.dose-weight-based
Status: needs review and sign-off by a qualified clinician before it is published. Not a medical device; for decision support only; always follow local clinical guidelines.
Works out a weight-based dose (so much per kilogram), caps it at a maximum
single dose, and turns it into a volume the measuring device can actually
show: a whole number of 0.1 mL, 0.01 mL or 1 mL steps. It holds no drug data.
The prescriber's dose per kg, the maximum single dose and the product strength
all come from the caller, from the prescription and the product in hand.
## Units
Everything is a whole number in small units, so no step drifts. In floating
point, three 0.1 mL steps are 0.30000000000000004 mL. Here they are 300 µL.
| you have | pass |
|----------|---------------------------|
| 1 kg | 1000 g |
| 1 mg | 1000 µg |
| 1 mL | 1000 µL |
| 120 mg/5 mL | strength 120000 µg in 5000 µL |
| 1 g in 3 mL | strength 1000000 µg in 3000 µL (no 333.33… mg/mL rounding) |
A weight of 12.4 is refused, not read as grams, because a slip between
kilograms and grams is a thousand-fold error.
## Worked example
15 mg/kg for a 12.4 kg child is 186 mg. At 120 mg in 5 mL that is 7.75 mL.
The syringe is marked in 0.1 mL, and 7.75 lies exactly between 7.7 and 7.8.
The tie goes down, so the answer is 7.7 mL, which holds 184.8 mg.
`differenceBasisPoints` is -65, meaning the given dose is 0.65% below the
calculated dose.
## Rounding rules
- **Cap first.** When weight × dose per kg is more than the maximum single
dose, the maximum becomes the target and `cappedAtMaximum` is true. A dose
exactly at the maximum is not capped.
- **Nearest measurable volume, a tie goes down.** When the dose is exactly
halfway between two steps, the smaller one is chosen, because that is the
more cautious choice.
- **Never over the maximum.** If rounding to the nearest step would deliver
more than the maximum single dose, the volume drops one step.
- **Never zero.** If the dose rounds to no increments at all, the function
raises an error. The fix is a more dilute product or a finer measure, not
silently giving nothing.
Local policy may round differently. For example, some policies always round
down, and some allow up to ±10%. `differenceBasisPoints` compares the delivered
dose with the target (signed, 100 = 1%), so a caller can enforce its own
tolerance. The integer outputs (`calculatedMicrograms`, `targetMicrograms`,
`deliveredMicrograms`) are rounded half-up to a whole microgram for display.
The comparisons and the difference use the exact fractions.
## Limits (refused, not clamped)
weightGrams 200 to 500000; dosePerKgMicrograms 1 to 1000000;
maxSingleDoseMicrograms 1 to 100000000 or null for none; strengthMicrograms
1 to 100000000; strengthVolumeMicrolitres 1 to 1000000;
measuringIncrementMicrolitres 1 to 100000.
It does not check that the dose per kg, the maximum or the product are right
for the drug, the patient's age or renal function, or the route. It does not
convert to dosing by body surface area, and it does not cap by a daily
maximum.
## Before you rely on this
**Not professional advice.** This capability calculates health figures from published rules. It is a software component for developers, not medical advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a pharmacist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.
**Not a medical device.** It is not intended to diagnose, treat or support clinical decisions about any individual. Anyone building it into clinical software is responsible for that software's regulatory status, and must validate it under their own clinical governance.
**Not for clinical use; regulatory review pending.** Whether publishing this capability makes it a medical device is under regulatory review. Until that is settled it is a developer library only.
**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified pharmacist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.
1.0.1 marks it unreviewed (not for clinical use; regulatory review pending). The code and the tests are unchanged.