Şahin ParlakPediatric surgery resident · Clinical software
Türkçe

TPN Calculator

One engine, every center’s own protocol

Open source · MIT · June 2026 · v0.1.0

Parenteral nutrition for neonates and children is calculation-heavy, error-prone, and different at every center. TPN Calculator keeps the arithmetic in one tested engine and every clinical value in the center’s own profile.

TPN Calculator — result screen with safety warnings
sahinparlak.github.io/tpn-calculator

Try it live ↗GitHub ↗

Clinical decision-support tool — not a medical device. The shipped profile is guideline-based, not center-validated.

Different at every center

Total parenteral nutrition (TPN) for neonates and children is calculation-heavy, error-prone, and different at every center — different dose schedules, limits, product concentrations, and units. Most calculators bake one institution’s protocol into the code.

TPN is part of its author’s daily clinical routine as a pediatric surgery resident — exactly the kind of repetitive, high-stakes calculation that deserves better, safer tooling. So the project flips the usual approach: instead of hardcoding one hospital’s protocol, it pairs a pure, tested calculation engine with a per-center configuration profile. The same engine powers every center; only the profile changes.

The TPN Calculator web app: the patient form on the left (1.5 kg, day 5, peripheral line); on the right a red banner — must not be used without independent verification, two hard safety limits exceeded — over the total volume, glucose, amino acid and lipid
The web app with its bundled ESPGHAN 2018 reference profile and the app’s own example patient (1.5 kg, day 5). On a peripheral line two hard limits are exceeded — the final dextrose concentration and the osmolarity — and the result opens with a red banner: must not be used without independent verification. The form recalculates as it is typed.

An engine and a profile

The engine knows no clinical constants. It takes a patient input and a center profile, and returns a prescription plus safety warnings. A profile defines fluid schedules, energy targets, glucose/GIR limits, amino-acid and lipid dosing, electrolytes, additives, and safety rules (hard = block, soft = warn). Units (kcal/kJ, mmol/mEq) are configurable for international use.

The engine, @tpn/engine, is pure TypeScript and tied to no interface, so the same calculation runs in the phone app (Expo, iOS and Android), in the web app (React + Vite, on GitHub Pages) and in the tests. The interface layers hold no clinical logic.

Three phone screens: Before you start, the disclaimer gate; Result, with a red banner listing two hard safety limits; Profiles, with the ESPGHAN 2018 reference active
The phone app, from the repository README: the disclaimer gate, accepted once and kept visible on every result; a result with hard safety warnings; profile management.

The model, written down

Every formula is universal; every number comes from the profile. The project’s plan writes the model down, together with the choices a clinician should review:

  • Advancement. GIR and macronutrient doses follow one pattern: value(day) = min(start + advance × (day − 1), max). Day 1 yields the start.
  • Volume balance. The fluid total is the budget. Lipid is a separate emulsion drawn from it, leaving an aqueous admixture; amino acid, electrolytes and additives take their volumes from it, and the remaining water carries the dextrose — which fixes the final dextrose concentration.
  • Glucose. grams/day = GIR × weight × 1440 ÷ 1000.
  • Osmolarity. A linear estimate over the aqueous admixture, every coefficient from the profile; lipid is excluded.
  • Calcium–phosphate. The simple solubility product (Ca × P) against a profile threshold — an approximation, not a curve.
  • Safety. The profile’s rules are checked against the computed values. A hard violation does not stop the program; it comes back as a warning, and the interface decides whether to block. A built-in check flags components that overflow the total volume.

A reference that cites itself

The app ships one profile: a reference built from the 2018 European guidelines on pediatric parenteral nutrition (ESPGHAN/ESPEN/ESPR/CSPEN), for a preterm infant over 1500 g. Its dosing is traceable to the guidelines’ recommendation numbers, and the app shows them beside the values. What the guidelines do not give as a single number — dextrose limits, stock concentrations, product details, osmolarity coefficients — is marked representative: a center must replace and validate it. The peripheral-line osmolarity limit, 900 mOsm/L, follows A.S.P.E.N.; the profile lists it among the representative values too.

Dosing — guideline-traceable: GIR 4/2/12 (R 5.4), amino acid 1.5 to 3.5 g/kg (R 3.1–3.3), lipid 1.0 to 4.0 g/kg (R 4.2–4.3), fluid 70 to 150 mL/kg (Jochum 2018), energy target 90–120 (R 2.6), Na/K/Cl 3/2/3 (Table 3), Ca/P/Mg 1.6/1.6/0.2 (R 8.9); below, a note on the representative values
The reference profile in the app: every dose beside its source — the recommendation numbers of the ESPGHAN 2018 modules, Jochum 2018 for fluids — and a note on the values that are not the guideline’s.

A center turns the reference into its own protocol inside the app: clone it, edit every field, export or import the result as JSON. The built-in reference itself cannot be edited or deleted.

The profile editor: GIR start 4, GIR advance 2, GIR max 3 outlined in red — Maximum GIR must be greater than or equal to the starting GIR; the Save button is disabled
The profile editor checks every change with the engine’s own validation: a maximum GIR below the starting GIR is caught, and the profile cannot be saved until it is fixed.

How it was checked

  • Engine tests. At the first release (v0.1.0, 17 June 2026) the engine had 87 tests with 98% coverage.
  • Source-traceable cases. Regression tests against the ESPGHAN 2018 reference profile — the dosing trajectory by day of life, the energy target, line safety — so that every expected output can be traced to a citation.
  • The apps. Integration and render tests for the phone app (jest-expo).
  • Validation. Every profile, edited or imported, passes the engine’s validateProfile before it can be used.
  • CI. On every change, lint and type-check on Node 22, build and coverage on Node 22 and 24; the web app is rebuilt and published from the same repository.

Limits

  • A clinical decision-support tool, not a medical device: it has not been evaluated, cleared or registered by any authority (FDA, EU MDR, TİTCK). The ordering clinician is solely responsible; every result must be verified independently.
  • The shipped profile is guideline-based, not center-validated; a center-validated profile is still pending. Each center must supply and validate its own numbers.
  • Modelling gaps recorded in the project’s backlog: the phototherapy and radiant-warmer adjustments are absolute mL/kg, while the guideline gives a percentage; the fluid schedule has no birth-weight band; the guideline expresses calcium–phosphate risk as a molar Ca:P ratio and pharmacy-tested compatibility, not as a product threshold; the final dextrose concentration is computed over the aqueous phase only, and labelled so on screen.
  • Early development: English only; other languages, a documentation site and community work are the next phase.

Documents

Version
v0.1.0 (17 June 2026). The web app and CI came after it and are not in a numbered release yet; live from the main branch: sahinparlak.github.io/tpn-calculator
Licence
MIT
Engine
@tpn/engine — TypeScript, Vitest
Apps
Phone: Expo (React Native), iOS and Android · Web: React + Vite, GitHub Pages
Reference
ESPGHAN/ESPEN/ESPR/CSPEN 2018; A.S.P.E.N. for safety thresholds
Citation
CITATION.cff in the repository

Sources

Notes

  • The phone screens are the repository README’s own images. The web screens were taken on 17 November 2026 from the web app built from the repository’s main branch, with the bundled reference profile and the app’s own example patient.
  • The numbers in the screens are the output of a guideline reference for an example patient, not a prescription.

Compiled from the project’s own repository and documents; last checked 18 November 2026.

← All software