TriSeg-Digital-Twins

This repository supports the manuscript "Identification of Digital Twins to Guide Interpretable AI for Diagnosis and Prognosis in Heart Failure" by Feng et al. It contains the identification framework and necessary files for creating digital twins for heart failure patients.

1. File Descriptions

i) Source Data

• AllPatients.mat: A struct containing de-identified clinical measurements of example patients.
• Sims folder: Stores optimization results from supercomputer nodes.

ii) Functions

• Driver.m: Runs a patient simulation. Several boolean options control execution, such as running pre-saved simulations, assigning modifier values, and printing/plotting options.
• targetVals____.m: A series of "targetVals" functions that return target, input structs, and an array of modifier values for adjustable parameters. Non-void versions (e.g., targetVals_HF.m) use patient numbers to assign targets and parameters and validate patient clinical values.
• estiminiParams.m: Accepts targets and inputs for a patient, returning a parameter struct and initial conditions for the model's ODE solver, estimating parameters to replicate clinical measurements.
• optParams.m: Applies a modifier vector (multiplicative scalings of the entries listed in mods) to the initial parameter struct and initial conditions returned by estiminiParams, producing the params/init actually fed to the ODE solver.
• m_bounds.m: Returns the upper/lower bounds (ub, lb) for the modifier vector based on the names listed in mods. Used by the optimizers in HFopt.m / Srdopt.m.
• calc_xm_ym.m and geom_0.m: Functions that estimate heart geometry metrics. geom_0.m calculates wall and lumen volumes, while calc_xm_ym.m computes sarcomere reference length and solves for xm and ym values for consistent initial conditions.
• dXdTDAE.m and dXdTode.m: Defines the DAE or ODE system governing the TriSeg model. Inputs include time, state variables, and model parameters, and outputs constraints and state variable differentials for the MATLAB ODE solver (ode15s). runSim.m tries the DAE form first and falls back to the ODE form on failure.
• triSegEquations.m: Symbolic / algebraic helper for the TriSeg geometric constraints used by the DAE form.
• runSim.m: Runs the model using estimated parameters and initial conditions. It calls the ODE solver to simulate the cardiac cycle, adjusting ODE options as necessary for performance, and computes the weighted cost of o_vals vs targets.
• HFopt.m and Srdopt.m: Used for parameter estimation, incorporating Genetic Algorithm (GA), Pattern Search, and fminsearch. HFopt.m fits HF patients; Srdopt.m fits canonical (standard reference) male/female subjects.
• evaluateModel.m / SrdevaluateModel.m: Accepts a patient number (or canonical subject) and modifier vector, returning the cost of one simulation. Used by optimizers as the objective function.
• NplotFit.m (HF 6-panel), NplotSrd.m (canonical 4-panel), GetMovie.m, and See_TriSeg.m: For graphical outputs of simulations and TriSeg geometry after running runSim.

2. User Guide

i) Running a Patient

1. Choose a patient number and pass it to targetVals_HF.m to obtain target, input, and adjustable parameter data (mods).
2. Feed targets and inputs into estiminiParams.m to get initial model parameters and initial conditions.
3. Apply a modifier vector with optParams.m to obtain the final params/init (or load a saved output struct from SimsUMFinal/P_NO<n>.mat / SimsUWFinal/P_NO<n>.mat).
4. Execute runSim.m with print_sim enabled for target comparison.
5. For graphical outputs, run NplotFit (HF), NplotSrd (canonical), GetMovie, or See_TriSeg.

ii) Optimizing a Patient

1. To fit a patient's targets, use HFopt.m (HF patients) or Srdopt.m (canonical subjects) and choose an optimization algorithm (e.g., global optimizers like GA followed by gradient-based methods like fminsearch).
2. Carefully assign adjustable parameters in targetVals_HF.m (the mods list); bounds for those modifiers come from m_bounds.m.
3. Use previous modifier vectors as starting points when optimizing.
4. Scripts are preconfigured for optimization runs with minimal setup.