clinical_calc: معادلات سريرية موثّقة المصادر بلغة Dart مع وحدات صريحة

المعادلات السريرية قصيرة. معادلة Cockcroft-Gault تُكتب في سطر واحد. وهنا الفخ: الحساب سهل، والأخطاء في مكان آخر. قيمة كرياتينين مُدخلة بـ µmol/L تدخل معادلة تنتظر mg/dL. قيمة eGFR منسوبة إلى 1.73 م² تُستعمل حيث المطلوب تصفية مطلقة بـ mL/min. معادلة للبالغين تُطبَّق على طفل. لا شيء من هذا يُسقط البرنامج. كل حالة تُرجع رقمًا يبدو معقولًا.

clinical_calc حزمة (package) بلغة Dart خالصة مبنية حول هذه الأخطاء. الكميات تحمل وحدتها، والمدخلات المستحيلة ترمي أخطاء محددة الأنواع (typed errors)، والمعادلات ترفض العمل خارج الفئة التي تم التحقق منها فيها، وكل معادلة تذكر المنشور الأصلي الذي جاءت منه.

شيء واحد قبل كل شيء، لأن الـ README يضعه في البداية: هذه الحزمة موجّهة للمهنيين المؤهلين، وليست جهازًا طبيًا، ويجب التحقق من النتائج. هي تقدّم معادلات فقط. لا تحتوي جداول جرعات أدوية ولا تقدّم أي توصية. النتائج قد تكون خاطئة إذا كانت المدخلات خاطئة أو إذا استُعملت المعادلة خارج الفئة التي طُوّرت عليها.

ماذا تقدّم

الكلى. CKD-EPI 2021 بالكرياتينين (المعادلة الخالية من معامل العِرق)، وCKD-EPI 2021 بالكرياتينين مع cystatin C، وMDRD بأربعة متغيرات IDMS (175)، وCockcroft-Gault بالوزن الفعلي أو المثالي أو المعدَّل، ومعادلة Schwartz السريرية (bedside)، وفئات KDIGO من G1 إلى G5، وتحويل القيمة المنسوبة إلى mL/min.

مقاييس الجسم. مساحة سطح الجسم BSA بخمس معادلات (Mosteller، DuBois، Haycock، Gehan-George، Boyd)، ومؤشر كتلة الجسم BMI مع فئات WHO، والوزن المثالي (Devine)، والوزن المعدَّل، والوزن الخالي من الدهون (Janmahasatian).

الوحدات. الكرياتينين (mg/dL، µmol/L، mg/L، بالمعامل 88.4)، والغلوكوز، واليوريا وBUN، والكالسيوم، والألبومين، والبيليروبين، والطول (cm، m، in، ft+in)، والوزن (kg، lb، g).

حسابات الجرعات. الجرعة لكل كيلوغرام ولكل متر مربع، الحجم المطلوب سحبه، عدد القوارير مع الباقي، معدل التسريب بـ mL/h، معدل التقطير بالقطرات في الدقيقة، التركيز، تركيز محلول التسريب، ومدة الثبات. هذه عمليات حسابية على أرقام تعطيها أنت. الحزمة لا تعرف أي دواء.

أخرى. الكالسيوم المصحَّح، فجوة الأنيونات (anion gap)، فجوة الأنيونات المصحَّحة بالألبومين، الصوديوم المصحَّح (Katz وHillier)، QTc (Bazett، Fridericia، Framingham)، Child-Pugh، CHA2DS2-VASc وHAS-BLED.

ثلاثة اختيارات في التصميم تجمع كل هذا:

• وحدات صريحة. الكميات أنواع قيمة (value types) تُبنى بوحدة مسمّاة: Creatinine.mgPerDl(1.2) وCreatinine.umolPerL(106) وHeight.cm(172) وWeight.lb(180). وقيمة eGFR المنسوبة (IndexedGfr، بـ mL/min/1.73 m²) نوع مستقل عن التصفية المطلقة بـ mL/min، فيمنعك المترجم (compiler) من الخلط بينهما.
• أخطاء محددة الأنواع. InvalidInputException للقيم السالبة أو غير المنتهية أو غير الفيزيولوجية. وOutOfValidatedRangeException عندما تُستعمل المعادلة خارج الفئة التي تم التحقق منها، مثل CKD-EPI تحت 18 سنة. كلاهما يرث من ClinicalCalcException ويحمل parameter وvalue وmessage.
• Dart خالصة بلا اعتماديات (dependencies). تعمل في Flutter، وعلى الخادم، وعلى الويب.

طريقة الاستعمال

أضِفها من GitHub:

dependencies:
  clinical_calc:
    git: https://github.com/AbdeldjalilChougui/clinical_calc

ثم، من الـ README:

import 'package:clinical_calc/clinical_calc.dart';

void main() {
  final scr = Creatinine.umolPerL(106);
  final height = Height.cm(172);
  final weight = Weight.kg(84);

  final egfr = Kidney.ckdEpi2021Creatinine(
    creatinine: scr,
    ageYears: 67,
    sex: Sex.male,
  );
  print(egfr.mlPerMinPer173m2); // mL/min/1.73 m2
  print(egfr.kdigoCategory.label); // G2

  final bsa = BodySize.bsaMosteller(height, weight);
  print(egfr.deindex(bsa)); // absolute GFR, mL/min

  final crcl = Kidney.cockcroftGault(
    creatinine: scr,
    ageYears: 67,
    sex: Sex.male,
    weight: weight,
    height: height,
    weightBasis: CockcroftGaultWeight.adjusted,
  );
  print(crcl); // mL/min

  final dose = Dosing.doseForBsa(mgPerM2: 75, bsaM2: bsa);
  final plan = Dosing.vials(
    doseMg: dose,
    vialContentMg: 80,
    concentrationMgPerMl: 20,
  );
  print(plan.vialCount);
  print(plan.leftoverMl);

  print(Qtc.fridericia(qtMs: 440, heartRateBpm: 88));

  try {
    Creatinine.mgPerDl(-1);
  } on InvalidInputException catch (e) {
    print(e.parameter); // creatinine
  }
}

لاحظ ما تفعله الأنواع في هذا المثال. الكرياتينين مُدخل بـ µmol/L والمعادلة تأخذ ما تحتاجه دون تحويل في كودك. قيمة eGFR ترجع بنوع IndexedGfr، وعليك استدعاء deindex(bsa) للحصول على mL/min. وخطة القوارير تعطيك العدد والباقي معًا.

في الـ README جدول لكل معادلة فيه الصيغة بالضبط ومصدرها، مثل Kidney.ckdEpi2021Creatinine (Inker LA et al., N Engl J Med 2021) أو BodySize.bsaMosteller (Mosteller RD, N Engl J Med 1987). والمرجع نفسه موجود في تعليق التوثيق لكل دالة، فيظهر لك في المحرّر.

كيف تم التحقق منها

مجموعة الاختبارات فيها 160 اختبارًا. كل معادلة تُفحص مقابل أمثلة محلولة بهوامش خطأ (tolerances) مصرَّح بها.

• قيم مرجعية خارجية. أمثلة محلولة مشتقة من MDCalc ومنشورة في MedCalc-Bench v1.0 (Khandekar N. et al., NeurIPS 2024 Datasets and Benchmarks) تغطي CKD-EPI 2021 وMDRD وCockcroft-Gault وBSA بمعادلة Mosteller وBMI والوزن المثالي Devine والوزن المعدَّل والكالسيوم المصحَّح وفجوة الأنيونات وفجوة الأنيونات المصحَّحة بالألبومين والصوديوم بمعادلة Hillier ومعادلات QTc الثلاث وChild-Pugh وCHA2DS2-VASc وHAS-BLED. كل اختبار يذكر رقم السطر في مجموعة البيانات، وكل قيمة أُعيد التحقق منها يدويًا مقابل المعادلة الأصلية. والأسطر التي كانت قيمها خاطئة بسبب تحويل غير دقيق للوحدات في مجموعة البيانات لم تُستعمل.
• قيم مرجعية مشتقة. CKD-EPI بالكرياتينين مع cystatin C، وSchwartz، وDuBois، وHaycock، وGehan-George، وBoyd، وJanmahasatian، وKatz، وحالات التفرّع والحدود فُحصت مقابل قيم حُسبت بشكل مستقل من المعادلات المنشورة. لم يتوفر لهذه أي مثال محلول منشور. والـ README واضح في معنى ذلك: الاختبارات تؤكد المعادلة كما كُتبت، لكنها لا تثبتها مقابل حاسبة من طرف ثالث.
• هوامش الخطأ مذكورة في كل مجموعة اختبارات: عادةً 0.001 mL/min/1.73 m² لـ eGFR، و1e-4 m² لـ BSA، ومن 0.001 إلى 0.01 ms لـ QTc، وتطابق تام للمقاييس.

الحزمة لا تتضمّن أي مجموعة بيانات. الاختبارات تقتبس عددًا قليلًا من المدخلات الرقمية والنتائج المنتظرة من MedCalc-Bench v1.0 (المنشورة برخصة CC BY-SA 4.0)، مع نسبتها برقم السطر.

ما يجب معرفته

• معادلات فقط. لا نشرات أدوية، ولا جداول تعديل الجرعات حسب وظيفة الكلى، ولا عتبات للتصرف. نتائج المقاييس أرقام أو فئات، وتفسيرها مسؤولية الطبيب والتوصيات الحالية.
• الفئات التي تم التحقق منها. CKD-EPI وMDRD وCockcroft-Gault ترمي OutOfValidatedRangeException تحت 18 سنة. معادلة Schwartz طُوّرت على أطفال بين سنة و16 سنة مصابين بمرض كلوي مزمن. الوزن المثالي Devine غير معرَّف تحت 152.4 cm ويرمي خطأ. ومعادلات eGFR تفترض كرياتينين مستقرًا ومعايَرًا وفق IDMS، وهي غير موثوقة في القصور الكلوي الحاد، والحالات القصوى للكتلة العضلية، والبتر، والحمل، وما شابه.
• معامل العِرق في MDRD. المعامل المنشور 1.212 يُطبَّق فقط إذا مرّرت black: true. وتوصيات KDIGO وNKF-ASN الحالية تنصح بمعادلات CKD-EPI 2021 الخالية من معامل العِرق.
• Child-Pugh يستعمل عتبات INR الشائعة (أقل من 1.7، من 1.7 إلى 2.3، أكثر من 2.3) بدل إطالة زمن البروثرومبين بالثواني عند Pugh، وعتبات البيليروبين الخاصة بالأمراض غير الركودية.
• نطاقات الإدخال المقبولة ليست قيمًا مرجعية سريرية. كرياتينين حتى 40 mg/dL، وطول من 20 إلى 275 cm، ووزن من 0.2 إلى 700 kg، ونبض من 20 إلى 300 في الدقيقة: هذه حدود لرفض الإدخال المستحيل فقط.
• التقريب. النتائج ترجع بدقة double كاملة. قرّب عند العرض فقط.

لماذا بنيته

المشكلة التي يصفها الـ README ليست الرياضيات. هي كل ما حولها: وحدات تختلط، وقيم منسوبة ومطلقة تتشارك نفس النوع double، ومعادلات تُطبَّق خارج فئتها، ومعاملات لا يُكتب مصدرها بجانبها.

دالة مثل double egfr(double creatinine, int age, bool male) لا تحميك من أي شيء من هذا. أما نوع Creatinine، ونوع IndexedGfr مستقل، وصنفان للأخطاء، ومرجع بجانب كل معامل، فتحميك. وأردت أيضًا أن يكون التحقق صريحًا في حدوده، ولهذا يفصل الـ README بين المعادلات التي فُحصت مقابل أمثلة محلولة خارجية والمعادلات التي فُحصت مقابل المعادلة المنشورة فقط.

الكود

الكود، وجداول المعادلات والمراجع، وملف example/main.dart قابل للتشغيل، والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/clinical_calc. الرخصة MIT، والبرنامج مقدَّم "كما هو" دون أي ضمان. تحقق من النتائج بشكل مستقل قبل أي قرار سريري.

نُشر في الأصل على abdeldjalilchougui.biz.