@precisa-saude/fhir-calculators 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,560 @@
+/**
+ * PhenoAge Calculator Types
+ *
+ * Based on Levine et al. (2018) - "An epigenetic biomarker of aging for lifespan and healthspan"
+ */
+/**
+ * The 9 biomarkers required for PhenoAge calculation (in SI units)
+ */
+interface PhenoAgeBiomarkers {
+    albumin: number;
+    alkalinePhosphatase: number;
+    creatinine: number;
+    crp: number;
+    glucose: number;
+    lymphocytePercent: number;
+    mcv: number;
+    rdw: number;
+    wbc: number;
+}
+/**
+ * Full input for PhenoAge calculation
+ */
+interface PhenoAgeInput extends PhenoAgeBiomarkers {
+    chronologicalAge: number;
+}
+/**
+ * Individual component contribution to the linear predictor
+ */
+interface ComponentBreakdown$1 {
+    coefficient: number;
+    contribution: number;
+    key?: string;
+    name: string;
+    valueWithUnit: string;
+}
+/**
+ * Complete PhenoAge calculation result
+ */
+interface PhenoAgeResult {
+    ageDifference: number;
+    breakdown: ComponentBreakdown$1[];
+    calculatedAt: string;
+    chronologicalAge: number;
+    labResultDate?: string;
+    linearPredictor: number;
+    mortalityScore: number;
+    phenoAge: number;
+}
+/**
+ * Biomarker availability check result
+ */
+interface BiomarkerAvailability$1 {
+    available: string[];
+    isComplete: boolean;
+    missing: string[];
+    values?: PhenoAgeBiomarkers;
+}
+
+/**
+ * PhenoAge Calculator
+ *
+ * Implements the Levine PhenoAge algorithm from:
+ * "An epigenetic biomarker of aging for lifespan and healthspan" (Aging, 2018)
+ */
+
+/**
+ * Main PhenoAge calculation function
+ *
+ * @param input - Biomarker values in SI units plus chronological age
+ * @returns Complete PhenoAge result with breakdown
+ */
+declare const calculatePhenoAge: (input: PhenoAgeInput) => PhenoAgeResult;
+/**
+ * Validates biomarker values are within acceptable ranges
+ */
+declare const validateBiomarkers$1: (input: PhenoAgeInput) => {
+    isValid: boolean;
+    errors: string[];
+};
+
+/**
+ * PhenoAge Calculator Constants
+ *
+ * Coefficients from Levine et al. (2018) Table 1
+ * Units: albumin (g/L), creatinine (μmol/L), glucose (mmol/L),
+ *        CRP (ln of mg/L), lymphocyte (%), MCV (fL), RDW (%),
+ *        ALP (U/L), WBC (10^9/L), age (years)
+ */
+/**
+ * Regression coefficients from the Cox proportional hazards model
+ */
+declare const PHENOAGE_COEFFICIENTS: {
+    readonly age: 0.0804;
+    readonly albumin: -0.0336;
+    readonly alkalinePhosphatase: 0.0019;
+    readonly creatinine: 0.0095;
+    readonly glucose: 0.1953;
+    readonly intercept: -19.9067;
+    readonly logCrp: 0.0954;
+    readonly lymphocytePercent: -0.012;
+    readonly mcv: 0.0268;
+    readonly rdw: 0.3306;
+    readonly wbc: 0.0554;
+};
+/**
+ * Gompertz mortality model parameters
+ */
+declare const GOMPERTZ_PARAMS: {
+    readonly ageCoefficient: 0.090165;
+    readonly baseAge: 141.50225;
+    readonly gamma: 0.0076927;
+    readonly mortalityConstant: 0.00553;
+};
+/**
+ * Biomarker reference ranges for validation
+ */
+declare const BIOMARKER_RANGES$1: {
+    readonly albumin: {
+        readonly max: 60;
+        readonly min: 10;
+        readonly typical: {
+            readonly max: 50;
+            readonly min: 35;
+        };
+        readonly unit: "g/L";
+    };
+    readonly alkalinePhosphatase: {
+        readonly max: 500;
+        readonly min: 10;
+        readonly typical: {
+            readonly max: 130;
+            readonly min: 40;
+        };
+        readonly unit: "U/L";
+    };
+    readonly chronologicalAge: {
+        readonly max: 120;
+        readonly min: 18;
+        readonly typical: {
+            readonly max: 100;
+            readonly min: 18;
+        };
+        readonly unit: "anos";
+    };
+    readonly creatinine: {
+        readonly max: 500;
+        readonly min: 20;
+        readonly typical: {
+            readonly max: 110;
+            readonly min: 60;
+        };
+        readonly unit: "μmol/L";
+    };
+    readonly crp: {
+        readonly max: 200;
+        readonly min: 0.01;
+        readonly typical: {
+            readonly max: 3;
+            readonly min: 0;
+        };
+        readonly unit: "mg/L";
+    };
+    readonly glucose: {
+        readonly max: 30;
+        readonly min: 2;
+        readonly typical: {
+            readonly max: 6;
+            readonly min: 4;
+        };
+        readonly unit: "mmol/L";
+    };
+    readonly lymphocytePercent: {
+        readonly max: 80;
+        readonly min: 1;
+        readonly typical: {
+            readonly max: 40;
+            readonly min: 20;
+        };
+        readonly unit: "%";
+    };
+    readonly mcv: {
+        readonly max: 150;
+        readonly min: 50;
+        readonly typical: {
+            readonly max: 100;
+            readonly min: 80;
+        };
+        readonly unit: "fL";
+    };
+    readonly rdw: {
+        readonly max: 25;
+        readonly min: 8;
+        readonly typical: {
+            readonly max: 15;
+            readonly min: 11;
+        };
+        readonly unit: "%";
+    };
+    readonly wbc: {
+        readonly max: 30;
+        readonly min: 1;
+        readonly typical: {
+            readonly max: 11;
+            readonly min: 4;
+        };
+        readonly unit: "10^9/L";
+    };
+};
+/**
+ * Mapping from FHIR biomarker codes to PhenoAge input fields
+ */
+declare const FHIR_CODE_TO_PHENOAGE: Record<string, keyof typeof BIOMARKER_RANGES$1>;
+/**
+ * Required biomarker codes for PhenoAge calculation
+ */
+declare const REQUIRED_BIOMARKERS: readonly ["Albumin", "Creatinine", "Glucose", "CRP", "Lymphocytes", "MCV", "RDW", "AlkalinePhosphatase", "WBC"];
+/**
+ * Portuguese names for biomarkers (for display)
+ */
+declare const BIOMARKER_NAMES_PT$1: Record<string, string>;
+/**
+ * Short descriptions for biomarkers (for tooltips)
+ * Explains what each biomarker indicates in the context of aging
+ */
+declare const BIOMARKER_DESCRIPTIONS_PT: Record<string, string>;
+/**
+ * Biomarker information for lab order requests
+ * Includes LOINC codes and English names for lab requisitions
+ */
+interface BiomarkerLabInfo {
+    loincCode: string;
+    nameEn: string;
+    namePt: string;
+}
+/**
+ * Lab order information for PhenoAge biomarkers
+ * Mapped by FHIR code
+ */
+declare const BIOMARKER_LAB_INFO: Record<string, BiomarkerLabInfo>;
+
+/**
+ * Unit Converters for PhenoAge Calculator
+ *
+ * Brazilian labs (Weinmann, Fleury, etc.) often report in different units
+ * than the SI units required by the PhenoAge algorithm.
+ */
+/**
+ * Conversion factors for each biomarker
+ * Key: source unit, Value: multiplier to get SI unit
+ */
+declare const CONVERSION_FACTORS$1: Record<string, Record<string, number>>;
+/**
+ * Target units for PhenoAge calculation (SI units)
+ */
+declare const TARGET_UNITS$1: Record<string, string>;
+/**
+ * Convert a biomarker value from source unit to SI unit
+ *
+ * @param biomarker - The biomarker key (e.g., 'albumin', 'glucose')
+ * @param value - The numeric value
+ * @param sourceUnit - The unit of the input value
+ * @returns Converted value in SI units
+ * @throws Error if the unit is not recognized
+ */
+declare const convertToSI: (biomarker: string, value: number, sourceUnit: string) => number;
+/**
+ * Check if a value needs conversion
+ *
+ * @param biomarker - The biomarker key
+ * @param sourceUnit - The current unit
+ * @returns true if conversion is needed
+ */
+declare const needsConversion: (biomarker: string, sourceUnit: string) => boolean;
+/**
+ * Auto-detect unit and convert to SI if needed
+ * Uses heuristics based on typical value ranges
+ *
+ * @param biomarker - The biomarker key
+ * @param value - The numeric value
+ * @param unit - Optional unit hint
+ * @returns Object with converted value and detected unit
+ */
+declare const autoConvertToSI: (biomarker: string, value: number, unit?: string) => {
+    value: number;
+    unit: string;
+    wasConverted: boolean;
+};
+
+declare const index$1_BIOMARKER_DESCRIPTIONS_PT: typeof BIOMARKER_DESCRIPTIONS_PT;
+declare const index$1_BIOMARKER_LAB_INFO: typeof BIOMARKER_LAB_INFO;
+type index$1_BiomarkerLabInfo = BiomarkerLabInfo;
+declare const index$1_FHIR_CODE_TO_PHENOAGE: typeof FHIR_CODE_TO_PHENOAGE;
+declare const index$1_GOMPERTZ_PARAMS: typeof GOMPERTZ_PARAMS;
+declare const index$1_PHENOAGE_COEFFICIENTS: typeof PHENOAGE_COEFFICIENTS;
+type index$1_PhenoAgeBiomarkers = PhenoAgeBiomarkers;
+type index$1_PhenoAgeInput = PhenoAgeInput;
+type index$1_PhenoAgeResult = PhenoAgeResult;
+declare const index$1_REQUIRED_BIOMARKERS: typeof REQUIRED_BIOMARKERS;
+declare const index$1_autoConvertToSI: typeof autoConvertToSI;
+declare const index$1_calculatePhenoAge: typeof calculatePhenoAge;
+declare const index$1_convertToSI: typeof convertToSI;
+declare const index$1_needsConversion: typeof needsConversion;
+declare namespace index$1 {
+  export { index$1_BIOMARKER_DESCRIPTIONS_PT as BIOMARKER_DESCRIPTIONS_PT, index$1_BIOMARKER_LAB_INFO as BIOMARKER_LAB_INFO, BIOMARKER_NAMES_PT$1 as BIOMARKER_NAMES_PT, BIOMARKER_RANGES$1 as BIOMARKER_RANGES, type BiomarkerAvailability$1 as BiomarkerAvailability, type index$1_BiomarkerLabInfo as BiomarkerLabInfo, CONVERSION_FACTORS$1 as CONVERSION_FACTORS, type ComponentBreakdown$1 as ComponentBreakdown, index$1_FHIR_CODE_TO_PHENOAGE as FHIR_CODE_TO_PHENOAGE, index$1_GOMPERTZ_PARAMS as GOMPERTZ_PARAMS, index$1_PHENOAGE_COEFFICIENTS as PHENOAGE_COEFFICIENTS, type index$1_PhenoAgeBiomarkers as PhenoAgeBiomarkers, type index$1_PhenoAgeInput as PhenoAgeInput, type index$1_PhenoAgeResult as PhenoAgeResult, index$1_REQUIRED_BIOMARKERS as REQUIRED_BIOMARKERS, TARGET_UNITS$1 as TARGET_UNITS, index$1_autoConvertToSI as autoConvertToSI, index$1_calculatePhenoAge as calculatePhenoAge, index$1_convertToSI as convertToSI, index$1_needsConversion as needsConversion, validateBiomarkers$1 as validateBiomarkers };
+}
+
+/**
+ * BrDMrisc Calculator Types
+ *
+ * Based on Bracco et al. (2023) - "BrDMrisc: a Brazilian diabetes risk score
+ * for screening of type 2 diabetes mellitus"
+ * DOI: 10.3389/fendo.2023.1166147
+ */
+type RiskCategory = 'low' | 'moderate' | 'high' | 'very-high';
+interface BrDMriscModelDefinition {
+    auc: number;
+    coefficients: Record<string, number>;
+    id: number;
+    intercept: number;
+    isLabOnly: boolean;
+    name: string;
+    namePt: string;
+    requiredBiomarkers: string[];
+}
+interface BrDMriscInput {
+    fpg?: number;
+    hba1c?: number;
+    hdlc?: number;
+    triglycerides?: number;
+}
+interface BrDMriscResult {
+    breakdown: ComponentBreakdown[];
+    calculatedAt: string;
+    labResultDate?: string;
+    modelUsed: BrDMriscModelDefinition;
+    risk10y: number;
+    riskCategory: RiskCategory;
+    riskPercent: number;
+}
+interface ComponentBreakdown {
+    coefficient: number;
+    contribution: number;
+    key: string;
+    name: string;
+    value: number;
+    valueWithUnit: string;
+}
+interface BiomarkerAvailability {
+    available: string[];
+    bestModelId: number | null;
+    hasFpg: boolean;
+    hasHba1c: boolean;
+    hasHdlc: boolean;
+    hasTriglycerides: boolean;
+    missing: string[];
+}
+
+/**
+ * BrDMrisc Calculator
+ *
+ * Implements the BrDMrisc algorithm from:
+ * Bracco et al. (2023) - "BrDMrisc: a Brazilian diabetes risk score
+ * for screening of type 2 diabetes mellitus"
+ * Frontiers in Endocrinology, DOI: 10.3389/fendo.2023.1166147
+ *
+ * Formula:
+ *   x = intercept + Σ(coeff_i × value_i)
+ *   p = 1 / (1 + exp(-x))          — logistic regression probability (~7.4 years)
+ *   risk10y = 1 - (1 - p)^(10/7.4)  — extrapolated to 10-year risk
+ */
+
+/**
+ * Select the best available model based on which biomarkers are present.
+ * Iterates through models in priority order (highest AUC first) and
+ * returns the first one whose requirements are fully met.
+ */
+declare const selectModel: (input: BrDMriscInput, labOnly?: boolean) => BrDMriscModelDefinition | null;
+/**
+ * Classify risk percentage into a category
+ */
+declare const classifyRisk: (riskPercent: number) => RiskCategory;
+/**
+ * Calculate BrDMrisc 10-year diabetes risk
+ */
+declare const calculateBrDMrisc: (input: BrDMriscInput, model?: BrDMriscModelDefinition) => BrDMriscResult;
+/**
+ * Validate biomarker values are within plausible ranges
+ */
+declare const validateBiomarkers: (input: BrDMriscInput) => {
+    isValid: boolean;
+    errors: string[];
+};
+
+/**
+ * BrDMrisc Calculator Constants
+ *
+ * All 14 model definitions with coefficients extracted from:
+ * Bracco et al. (2023) Table 2 & Supplementary Material
+ * DOI: 10.3389/fendo.2023.1166147
+ *
+ * Models 1-6 are lab-only (MVP scope).
+ * Models 7-14 include clinical variables (Phase 2).
+ *
+ * Follow-up period: 7.4 years (ELSA-Brasil median)
+ * Units expected: FPG (mg/dL), HbA1c (%), triglycerides (mg/dL), HDL-c (mg/dL)
+ */
+
+/**
+ * ELSA-Brasil median follow-up in years.
+ * Used to extrapolate the logistic regression probability to 10-year risk.
+ */
+declare const FOLLOW_UP_YEARS = 7.4;
+/**
+ * All 14 BrDMrisc models.
+ * Models ordered by ID. Lab-only models (1-6) are the MVP.
+ *
+ * Coefficients from Supplementary Table S2 of the paper,
+ * verified against the Shiny app demo at:
+ * https://paulabracco.shinyapps.io/BrDMrisc_pt/
+ */
+declare const BRDMRISC_MODELS: BrDMriscModelDefinition[];
+/**
+ * Lab-only models for MVP, ordered by priority (highest AUC first)
+ */
+declare const LAB_ONLY_MODELS: BrDMriscModelDefinition[];
+/**
+ * Model selection priority for lab-only models (highest AUC first)
+ */
+declare const LAB_MODEL_PRIORITY: readonly [6, 5, 3, 4, 1, 2];
+/**
+ * FHIR biomarker code → BrDMrisc input field mapping
+ */
+declare const FHIR_CODE_TO_BRDMRISC: Record<string, keyof BrDMriscInput>;
+/**
+ * Required FHIR biomarker codes (all 4 lab biomarkers)
+ */
+declare const BRDMRISC_BIOMARKER_CODES: readonly ["Glucose", "HbA1c", "Triglycerides", "HDL"];
+/**
+ * Portuguese names for biomarkers
+ */
+declare const BIOMARKER_NAMES_PT: Record<string, string>;
+/**
+ * Biomarker units used by the model
+ */
+declare const BIOMARKER_UNITS: Record<string, string>;
+/**
+ * Biomarker validation ranges (plausible values)
+ */
+declare const BIOMARKER_RANGES: Record<string, {
+    min: number;
+    max: number;
+    unit: string;
+}>;
+/**
+ * Risk category thresholds based on clinical recommendations
+ * from Bracco et al. (2023). The paper notes that 20% triggers
+ * intensive prevention.
+ */
+declare const RISK_THRESHOLDS: {
+    readonly high: 0.2;
+    readonly moderate: 0.1;
+    readonly veryHigh: 0.35;
+};
+
+/**
+ * Unit Converters for BrDMrisc Calculator
+ *
+ * BrDMrisc expects: FPG (mg/dL), HbA1c (%), triglycerides (mg/dL), HDL-c (mg/dL)
+ * Brazilian labs typically report in these units already, but some may
+ * use mmol/L for glucose or mmol/mol for HbA1c (IFCC standard).
+ */
+/**
+ * Conversion factors for each biomarker
+ * Key: source unit, Value: multiplier to get target unit
+ */
+declare const CONVERSION_FACTORS: Record<string, Record<string, number>>;
+/**
+ * Target units for BrDMrisc calculation
+ */
+declare const TARGET_UNITS: Record<string, string>;
+/**
+ * Convert a biomarker value to the target unit expected by BrDMrisc
+ */
+declare const convertToTargetUnit: (biomarker: string, value: number, sourceUnit: string) => number;
+/**
+ * Auto-detect unit and convert to target if needed.
+ * Uses heuristics based on typical value ranges.
+ */
+declare const autoConvertToTarget: (biomarker: string, value: number, unit?: string) => {
+    value: number;
+    unit: string;
+    wasConverted: boolean;
+};
+
+declare const index_BIOMARKER_NAMES_PT: typeof BIOMARKER_NAMES_PT;
+declare const index_BIOMARKER_RANGES: typeof BIOMARKER_RANGES;
+declare const index_BIOMARKER_UNITS: typeof BIOMARKER_UNITS;
+declare const index_BRDMRISC_BIOMARKER_CODES: typeof BRDMRISC_BIOMARKER_CODES;
+declare const index_BRDMRISC_MODELS: typeof BRDMRISC_MODELS;
+type index_BiomarkerAvailability = BiomarkerAvailability;
+type index_BrDMriscInput = BrDMriscInput;
+type index_BrDMriscModelDefinition = BrDMriscModelDefinition;
+type index_BrDMriscResult = BrDMriscResult;
+declare const index_CONVERSION_FACTORS: typeof CONVERSION_FACTORS;
+type index_ComponentBreakdown = ComponentBreakdown;
+declare const index_FHIR_CODE_TO_BRDMRISC: typeof FHIR_CODE_TO_BRDMRISC;
+declare const index_FOLLOW_UP_YEARS: typeof FOLLOW_UP_YEARS;
+declare const index_LAB_MODEL_PRIORITY: typeof LAB_MODEL_PRIORITY;
+declare const index_LAB_ONLY_MODELS: typeof LAB_ONLY_MODELS;
+declare const index_RISK_THRESHOLDS: typeof RISK_THRESHOLDS;
+type index_RiskCategory = RiskCategory;
+declare const index_TARGET_UNITS: typeof TARGET_UNITS;
+declare const index_autoConvertToTarget: typeof autoConvertToTarget;
+declare const index_calculateBrDMrisc: typeof calculateBrDMrisc;
+declare const index_classifyRisk: typeof classifyRisk;
+declare const index_convertToTargetUnit: typeof convertToTargetUnit;
+declare const index_selectModel: typeof selectModel;
+declare const index_validateBiomarkers: typeof validateBiomarkers;
+declare namespace index {
+  export { index_BIOMARKER_NAMES_PT as BIOMARKER_NAMES_PT, index_BIOMARKER_RANGES as BIOMARKER_RANGES, index_BIOMARKER_UNITS as BIOMARKER_UNITS, index_BRDMRISC_BIOMARKER_CODES as BRDMRISC_BIOMARKER_CODES, index_BRDMRISC_MODELS as BRDMRISC_MODELS, type index_BiomarkerAvailability as BiomarkerAvailability, type index_BrDMriscInput as BrDMriscInput, type index_BrDMriscModelDefinition as BrDMriscModelDefinition, type index_BrDMriscResult as BrDMriscResult, index_CONVERSION_FACTORS as CONVERSION_FACTORS, type index_ComponentBreakdown as ComponentBreakdown, index_FHIR_CODE_TO_BRDMRISC as FHIR_CODE_TO_BRDMRISC, index_FOLLOW_UP_YEARS as FOLLOW_UP_YEARS, index_LAB_MODEL_PRIORITY as LAB_MODEL_PRIORITY, index_LAB_ONLY_MODELS as LAB_ONLY_MODELS, index_RISK_THRESHOLDS as RISK_THRESHOLDS, type index_RiskCategory as RiskCategory, index_TARGET_UNITS as TARGET_UNITS, index_autoConvertToTarget as autoConvertToTarget, index_calculateBrDMrisc as calculateBrDMrisc, index_classifyRisk as classifyRisk, index_convertToTargetUnit as convertToTargetUnit, index_selectModel as selectModel, index_validateBiomarkers as validateBiomarkers };
+}
+
+/**
+ * Derived Biomarker Calculator
+ *
+ * Derives biomarkers from existing extracted values when the lab report
+ * doesn't include them directly.
+ *
+ * Currently supports:
+ * - HOMA-IR = (Fasting Glucose × Fasting Insulin) / 405
+ * - VLDL = Triglycerides / 5
+ * - BMI = weight_kg / (height_m)² (requires UserContext with height)
+ */
+interface BiomarkerInput {
+    code: string;
+    value: number | string;
+    unit?: string;
+}
+interface DerivedBiomarker {
+    code: string;
+    loincCode?: string;
+    name: string;
+    unit: string;
+    value: number;
+}
+interface DerivedOptions {
+    codeToLoinc?: (code: string) => string | undefined;
+    userContext?: {
+        heightCm?: number;
+    };
+}
+/**
+ * Compute derived biomarkers from existing extracted values.
+ * Only adds a calculated biomarker if:
+ * - All required inputs are present with numeric values
+ * - The biomarker isn't already present in the results
+ */
+declare function computeDerivedBiomarkers(biomarkers: BiomarkerInput[], options?: DerivedOptions): DerivedBiomarker[];
+
+export { type BiomarkerInput, type DerivedBiomarker, type DerivedOptions, index as brdmrisc, computeDerivedBiomarkers, index$1 as phenoage };