Choosing Data for Twinning

Data provided to ReplayBG must comply with strict format requirements and should be selected following some best practices. This page covers both.

Format requirements

ReplayBG consumes a pandas DataFrame with one row every 5 minutes. The data classes read the following columns:

Column	Type / units	Notes
t	datetime	Homogeneous 5-minute grid with no missing rows; must be pd.to_datetime. Drives tsteps and the time-of-day.
glucose	float, mg/dL	CGM. NaN allowed — missing samples are excluded from the fit. The first non-missing value seeds the initial glucose on a cold start.
cho	float, g/min	Carbohydrate rate, held over the row's 5 minutes (a 50 g meal is 10 in one row). 0 when no meal.
bolus	float, U/min	Bolus insulin rate, held over the row's 5 minutes (a 5 U bolus is 1 in one row). 0 when no bolus.
basal	float, U/min	Basal insulin rate, held over the row. Its mean defines u2ss.
bolus_label	str	Label of each bolus event. Read only on rows with a non-zero bolus, so it is required whenever boluses are present.
cho_label	str	Meal type: B/L/D/S/H (breakfast/lunch/dinner/snack/hypo-treatment). Read only on rows with a non-zero cho.

Any other columns are ignored. The grid length comes from the first and last t, but each row is placed on it by its position, so missing rows misalign the inputs or make the data class fail. Keep a row for every 5 minutes, with NaN glucose where the CGM is missing and the actual inputs.

The data classes convert the inputs to model units by multiplying cho, bolus and basal by 1000 / body_weight (mg/kg/min and mU/kg/min); u2ss is mean(basal) * 1000 / body_weight. Pass the patient's weight in kg as body_weight (default 100).

Label handling depends on the blueprint:

• Single meal — cho_label is not read; all carbs are treated as a single meal. SingleMealT1DData also looks rows up by index label, so pass a 0-based RangeIndex (df.reset_index(drop=True)).
• Multi meal — cho_label routes each meal into its meal_B/meal_L/meal_D/meal_S/meal_H channel. Meals with any other label are silently dropped.
• Multi meal extended — additionally routes the second-occurrence labels B2/L2/S2.

Simulation length

The number of integration steps is derived automatically from the t column (and the 5-minute data sampling time). You do not set it explicitly.

Warning

The cho and bolus columns should contain at least one event each when twinning a segment, so the meal-absorption and insulin parameters have something to fit against.

Best practices

The portion of data you select matters as much as its format. Here are the key considerations.

Starting point

The twinning procedure does not estimate the model's initial conditions. Instead, the insulin and meal state variables start at steady state (basal insulin, empty gut, no extra insulin action), and only plasma and interstitial glucose are seeded with the first observed CGM value. That assumption is valid only when the actions of exogenous insulin and carbohydrate intake are "exhausted" — i.e. when the starting point is reasonably distant from the last meal and insulin bolus, e.g. ~4 hours.

Pick a starting point that is sufficiently far from the last recorded input so "the data start from steady state" holds.

Intervals are different

When twinning multi-day intervals, the steady-state assumption only applies to the first segment. Every subsequent segment starts from the previous segment's final state (x0 + theta_prev), so it does not need to start from steady state.

Minimum data length

As a rule of thumb, use portions of data spanning at least 6 hours. As shown in the literature, this yields better parameter estimates and simulation results.

Data gaps

To keep twinning reliable, discard data portions that have:

• significant gaps — more than 10% of missing glucose readings, or
• no reported meal intake or insulin bolus at all.

Twinning such portions risks producing digital twins that do not represent the actual underlying physiology.

During replay

When replaying rather than twinning, some of the above relaxes:

• glucose is not fitted (replay predicts it); only its first non-missing value is used, to seed the initial glucose.
• Meal and insulin inputs can be generated online by callbacks rather than read from the data — e.g. a bolus calculator, a hypo-treatment policy, or a full control algorithm. In that case the corresponding columns are starting points that the callbacks may override step by step.