medkit

A Go package providing foundational types and methods for working with health and medical data. medkit gives developers type-safe, validated structures for vital signs, laboratory results, anthropometric measurements, and clinical scoring systems.

Why medkit?

Healthcare applications require precision. A mishandled unit conversion or invalid vital sign can have serious consequences. medkit addresses these concerns by:

• Enforcing validation at construction time (e.g., systolic must be ≥ diastolic)
• Making units explicit to prevent confusion between mg/dL and mmol/L
• Supporting both SI and US measurement systems with built-in conversion utilities
• Following Domain-Driven Design principles for clear, maintainable code

Whether you're building an EHR system, a health monitoring app, or analyzing clinical data, medkit provides reliable building blocks that help prevent common errors.

Features

Core Package (pkg/core)

• Vital Signs: Blood pressure, heart rate, respiratory rate, temperature, SpO₂
• Anthropometrics: Height, weight, and BMI calculation with unit conversion
• Unit System Support: Seamlessly work with SI (metric) and US customary units
• Type-Safe Units: Explicit unit types prevent mixing incompatible measurements

Laboratory Package (pkg/labs)

• Complete Blood Count (CBC): WBC, RBC, hemoglobin, hematocrit, platelets, and indices
• Comprehensive Metabolic Panel (CMP): Glucose, electrolytes, kidney function, liver enzymes
• Lipid Panel: Total cholesterol, HDL, LDL, triglycerides
• HbA1c: Glycated hemoglobin with NGSP (%) and IFCC (mmol/mol) support
• Coagulation Panel: PT, INR, PTT
• Thyroid Panel: TSH, Free T4, Free T3
• Inflammatory Panel: CRP, ESR, Ferritin

Patient-Reported Outcomes (pkg/pain)

• Pain Score: Location and severity tracking (0-10 scale)

Specialty Assessments (pkg/specialty)

• BASDAI: Bath Ankylosing Spondylitis Disease Activity Index

Installation

go get github.com/endlesstrax/medkit

Usage Examples

Working with Vital Signs

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/core"
)

func main() {
    // Create blood pressure (automatically validated)
    bp, err := core.NewBloodPressure(120, 80)
    if err != nil {
        panic(err) // Will error if systolic < diastolic
    }

    // Create temperature in Celsius (SI system)
    temp, _ := core.NewTemperature(37.5, core.UnitSystemSI)

    // Create complete vital signs
    vitals, err := core.NewVitals(
        72,   // heart rate
        16,   // respiratory rate
        98,   // SpO2
        bp,   // blood pressure
        temp, // temperature
    )
    if err != nil {
        panic(err)
    }

    fmt.Printf("HR: %d bpm, BP: %d/%d %s, Temp: %.1f %s\n",
        vitals.HeartRate,
        vitals.BloodPressure.Systolic,
        vitals.BloodPressure.Diastolic,
        vitals.BloodPressure.BPUnit,
        vitals.Temperature.Temp,
        vitals.Temperature.TempUnit)
}

Anthropometric Calculations

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/core"
)

func main() {
    // Create height and weight using SI units
    height := core.NewHeight(175, core.UnitSystemSI) // 175 cm
    weight := core.NewWeight(70, core.UnitSystemSI)  // 70 kg

    // Calculate BMI
    bmi, err := core.CalculateBMI(height, weight)
    if err != nil {
        panic(err)
    }

    fmt.Printf("BMI: %.1f kg/m²\n", bmi)

    // Works with US units too
    heightUS := core.NewHeight(69, core.UnitSystemUS) // 69 inches
    weightUS := core.NewWeight(154, core.UnitSystemUS) // 154 lbs
    
    bmiUS, _ := core.CalculateBMI(heightUS, weightUS)
    fmt.Printf("BMI: %.1f kg/m²\n", bmiUS)
}

Unit Conversion

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/core"
)

func main() {
    // Convert weight from kg to lbs
    kgs := 70.0
    lbs := core.ConvertWeight(kgs, core.Unit_kg, core.Unit_lbs)
    fmt.Printf("%.1f kg = %.1f lbs\n", kgs, lbs)

    // Convert temperature from Celsius to Fahrenheit
    celsius := 37.0
    fahrenheit := core.ConvertTemperature(celsius, core.Unit_celsius, core.Unit_fahrenheit)
    fmt.Printf("%.1f°C = %.1f°F\n", celsius, fahrenheit)

    // Convert height from inches to cm
    inches := 69.0
    cm := core.ConvertLength(inches, core.Unit_inch, core.Unit_cm)
    fmt.Printf("%.1f inches = %.1f cm\n", inches, cm)
}

Laboratory Results

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/core"
    "github.com/endlesstrax/medkit/pkg/labs"
)

func main() {
    // Create a Complete Blood Count
    cbc := bloodwork.NewCBC(
        7.5,  // WBC (K/µL)
        4.8,  // RBC (M/µL)
        14.5, // Hemoglobin (g/dL)
        42.0, // Hematocrit (%)
        90.0, // MCV (fL)
        30.0, // MCH (pg)
        33.0, // MCHC (g/dL)
        250.0, // Platelets (K/µL)
    )

    fmt.Printf("WBC: %.1f %s\n", cbc.WBC.Result, cbc.WBC.Unit)
    fmt.Printf("Hemoglobin: %.1f %s\n", cbc.Hgb.Result, cbc.Hgb.Unit)

    // Create HbA1c with US units (percentage)
    hba1c := bloodwork.NewHBA1C(5.7, core.UnitSystemUS)
    fmt.Printf("HbA1c: %.1f%s\n", hba1c.Value.Result, hba1c.Value.Unit)

    // Create thyroid panel with SI units
    thyroid := bloodwork.NewThyroidPanel(2.5, 1.2, 3.1, core.UnitSystemSI)
    fmt.Printf("TSH: %.1f %s\n", thyroid.TSH.Result, thyroid.TSH.Unit)
    fmt.Printf("Free T4: %.1f %s\n", thyroid.FreeT4.Result, thyroid.FreeT4.Unit)
}

Patient-Reported Outcomes

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/pain"
)

func main() {
    // Create a pain score (validated 0-10)
    pain, err := pain.NewPainScore("Lower back", 7)
    if err != nil {
        panic(err) // Will error if severity not in 0-10 range
    }

    fmt.Printf("Pain location: %s, severity: %d/10\n",
        pain.Location, pain.Severity)
}

Clinical Scoring Systems

Below is an example for BASDAI score for Ankylosing Spondylitis.

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/specialty"
)

func main() {
    // Calculate BASDAI score for Ankylosing Spondylitis
    b := basdai.NewBASDAI()

    // Set responses to questions (0-10 scale for Q1-Q5, 0-2 for Q6)
    b.SetScore(basdai.Q1, 4.0) // Fatigue
    b.SetScore(basdai.Q2, 5.0) // Spinal pain
    b.SetScore(basdai.Q3, 3.0) // Peripheral joint pain
    b.SetScore(basdai.Q4, 2.0) // Areas of tenderness
    b.SetScore(basdai.Q5, 6.0) // Morning stiffness severity
    b.SetScore(basdai.Q6, 1.5) // Morning stiffness duration (hours)

    score, err := b.Calculate()
    if err != nil {
        panic(err)
    }

    fmt.Printf("BASDAI Score: %.1f\n", score)
    if score >= 4.0 {
        fmt.Println("Disease activity is considered active")
    }
}

Below is an example for DAS28 (Rheumatoid Arthritis) using the DAS28-ESR formula.

package main

import (
    "fmt"
    "github.com/endlesstrax/medkit/pkg/specialty/rheumatology"
)

func main() {
    d := rheumatology.NewDAS28()
    _ = d.Set(rheumatology.TJC, 10)
    _ = d.Set(rheumatology.SJC, 8)
    _ = d.Set(rheumatology.PGA, 40)
    _ = d.Set(rheumatology.ESR, 30)

    res, err := d.Classification()
    if err != nil {
        panic(err)
    }
    fmt.Printf("DAS28-ESR: %.2f (%s)\n", res.Score, res.Category)
}

Roadmap

Implemented ✅

Core Vital Signs & Anthropometrics

• Blood Pressure (BP) with validation
• Heart Rate (HR)
• Respiratory Rate (RR)
• Body Temperature (Celsius/Fahrenheit)
• Oxygen Saturation (SpO₂)
• Weight (kg/lbs with conversion)
• Height (cm/inch with conversion)
• Body Mass Index (BMI) calculation

Laboratory Tests

• Complete Blood Count (CBC)
• Comprehensive Metabolic Panel (CMP)
• Lipid Panel
• Glycated Hemoglobin (HbA1c)
• Coagulation Panel (PT/INR/PTT)
• Thyroid Panel (TSH/FreeT4/FreeT3)
• Inflammatory Panel (CRP/ESR/Ferritin)

Patient-Reported Outcomes

• Pain Score (0-10 scale)

Specialty Clinical Scores

• BASDAI (Bath Ankylosing Spondylitis Disease Activity Index)

Planned Features 🚀

Patient-Reported Outcomes

• Fatigue Score (standardized assessment)
• PHQ-9 (Patient Health Questionnaire for Depression)
• GAD-7 (Generalized Anxiety Disorder assessment)

Specialty Clinical Scores

• DAS28 (Disease Activity Score for Rheumatoid Arthritis)
• Glasgow Coma Scale (GCS)
• APACHE II (ICU severity scoring)
• Wells Score (DVT/PE probability)

Additional Anthropometrics

• Body Fat Percentage
• Waist Circumference
• Hip Circumference
• Waist-to-Hip Ratio
• Body Surface Area (BSA)
• Ideal Body Weight calculations

Additional Laboratory Tests

• Urinalysis
• Liver Function Tests (expanded)
• Renal Function (eGFR calculations)
• Cardiac Markers (Troponin, BNP)
• Tumor Markers (PSA, CEA, CA-125, etc.)
• Vitamin Levels (D, B12, Folate)
• Iron Studies (expanded)

Data Quality & Validation

• Timestamp/observation tracking
• Data source attribution

Contributing

We welcome contributions! Whether you're fixing bugs, adding new metrics, improving documentation, or suggesting features, your input helps make medkit better for everyone.

Ways to Contribute

• Report Issues: Found a bug or have a feature request? Open an issue
• Submit Pull Requests: Ready to contribute code? Submit a pull request
• Improve Documentation: Help others understand and use medkit better
• Share Use Cases: Tell us how you're using medkit in your projects

Development Guidelines

1. Validation First: All medical measurements should validate inputs at construction time
2. Explicit Units: Always make units clear and type-safe
3. Error Handling: Return meaningful errors when validation fails
4. Testing: Include comprehensive tests for all new features
5. Documentation: Add godoc comments and examples

Running Tests

go test ./...

Code Formatting

go fmt ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Note: medkit provides tools for working with medical data but is not a substitute for professional medical advice, diagnosis, or treatment. Always consult qualified healthcare providers for medical decisions.