Misleading InfoText entries for remainingCarbFraction and remainingCarbsCap in PreferencesEditorStateModel.swift

[dsut4392]

Describe the bug
The InfoText entries for remainingCarbFraction and remainingCarbsCap in PreferencesEditorStateModel.swift do not correspond to how these fields are used in determine-basal.js
, or how they are described in the docs https://docs.diy-trio.org/en/latest/settings/configuration/preferences/othersettings.html#remaining-carbs-fraction.

remainingCarbFraction
From PreferencesEditorStateModel.swift

                infoText: NSLocalizedString(
                    "This is the fraction of carbs we’ll assume will absorb over 4h if we don’t yet see carb absorption.",
                    comment: "Remaining Carbs Fraction"

This implies that if the variable is set =1 (default), "the fraction of carbs we’ll assume will absorb over 4h" = 100%, i.e. all carbs will be absorbed.
However, in determine-basal.js

if (profile.remainingCarbsFraction) { remainingCarbsFraction = Math.min(1,profile.remainingCarbsFraction); }
var remainingCarbsIgnore = 1 - remainingCarbsFraction;
var remainingCarbs = Math.max(0, meal_data.mealCOB - totalCA - meal_data.carbs*remainingCarbsIgnore);

i.e. if the remainingCarbsFraction is set to the default of 1 then meal_data.carbs*remainingCarbsIgnore=0, and any carbs not detected as absorbed will remain - up to 100% of the meal carbs if there is no carb absorption seen.

remainingCarbsCap
From PreferencesEditorStateModel.swift

                displayName: NSLocalizedString("Remaining Carbs Cap", comment: "Remaining Carbs Cap"),
                type: .decimal(keypath: \.remainingCarbsCap, minVal: 90),
                infoText: NSLocalizedString(
                    "This is the amount of the maximum number of carbs we’ll assume will absorb over 4h if we don’t yet see carb absorption.",

This implies that at most 90g carbs will be absorbed over 4h if no carb absorption is seen.
However, in determine-basal.js line 1244:

remainingCarbs = Math.min(remainingCarbsCap,remainingCarbs);

I.e. the remaining carbs will be set to the lower of the remainingCarbsCap, or the calculated remaingcarbs from above after the remainingCarbsFraction is applied. In other words, "at most 90 carbs will remain", not "at most 90 carbs will be absorbed"

This also suggests that limiting this value to a minimum of 90 as per #189 is not appropriate, as many people on lower-carb diets will never have a COB of 90g even immediately after a meal.

Suggested re-wording of infoText:
remainingCarbsFraction: "This is the fraction of carbs that will remain after 4h if no carb absorption is seen. At the default =1, this setting will not cause carbs to expire after 4h. Changing this to a value of less than 1 will cause some carbs to expire without absorption, e.g. using 0.75 will see 25% of the carbs expire even if no absorption is detected"

remainingCarbsCap: "This is the maximum number of carbs that will remain 4 hours after a meal even if no absorption is detected. Default = 90"

[bjornoleh]

Just dropping the link to the OpenAPS docs, no mention of a minimum value there:

https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html?highlight=remainingCarbsCap#understanding-your-preferences-and-safety-settings

remainingCarbsCap:

This is the amount of the maximum number of carbs we’ll assume will absorb over 4h if we don’t yet see carb absorption.

[dsut4392]

Doesn't mention a minimum, but text doesn't correspond to how determine-basal actually uses this value either.

[bjornoleh]

@dsut4392 , I think your understanding is correct, and that the OpenAPS docs doesn’t quite describe the algorithm correctly. Perhaps @scottleibrand could weigh in on this?

[SjpStanley]

Hi I have tried setting ‘remainingCarbsFraction’ to 0.1, ie 10% and have observed that it appears to cause bolus calculator to massively lower recommended doses.

Addendum. I have also just tested the ‘remaining carbs cap’ with values of 10 and 90. For a 40g carb input the bolus calc returns 1.1u and 4.85u recommendations respectively.

[bjornoleh]

@SjpStanley, your observation with setting ‘remainingCarbsFraction’ to 0.1 seems consistent with the proposed changes by @dsut4392?

A if I understand correctly, a lower value will cut more of the meal from COB, and then affect dosing suggestions. If you don’t want this to happen, you can keep remainingCarbsFraction at the default of 1?

[SjpStanley]

Hi BjornNot appropriate to get into the code behind this as I’m sure you and the other developers have far more important things to do for main release.However, I do think both the infotext and documentation should warn that changing ‘remainingcarbfraction’ can significantly impact accuracy of bolus calculator and to be careful.BR Steve Sent from my iPhoneOn 22 Jun 2024, at 13:00, bjornoleh ***@***.***> wrote: @SjpStanley, your observation with setting ‘remainingCarbsFraction’ to 0.1 seems consistent with the proposed changes by @dsut4392? A if I understand correctly, a lower value will cut more of the meal from COB, and then affect dosing suggestions. If you don’t want this to happen, you can keep remainingCarbsFraction at the default of 1? —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[dsut4392]

What I’m trying to say is that it’s not the bolus calculator that is inaccurate in this case, it’s your input value of 0.1 for remaining carbs fraction. E.g. if you know the answer to a calculation 14= 4, you don’t complain that “multiplication doesn’t work” if you try 0.14 and find it’s not 4…the 0.1 input is the problem.

[aug0211]

remainingCarbsFraction doesn’t actually expire the carbs in terms of reported COB, it just assumes COB will expire very quickly when running calculations - is this accurate?

(Question, not a statement)

I’m interested in this because a while ago I had cut our remainingCarbsFraction to 0.1. I had forgotten I did this, until I saw this issue and checked our settings. My primary goal was to get COB to expire sooner than 6h if not yet absorbed, I think - but it has been a while!

[scottleibrand]

https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html

remainingCarbsCap:

This is the amount of the maximum number of carbs we’ll assume will absorb over 4h if we don’t yet see carb absorption.

remainingCarbsFraction:

This is the fraction of carbs we’ll assume will absorb over 4h if we don’t yet see carb absorption.

So if you have a remainingCarbsCap of 90 and enter 120g of carbs with a remainingCarbsFraction of 1, then immediately afterward (before any BG rise is observed) it will assume that 90 carbs worth of BG rise will be seen over the next 4h.

If you set remainingCarbsFraction to 0.5, then it will only assume that 60 carbs worth of BG rise will be seen.

Once BG starts to rise sufficiently fast (relative to what would be expected from insulin alone), these settings stop mattering: it assumes that the observed rate of rise will continue or linearly decrease for up to 4 hours or until the entered carbs are used up.

[bjornoleh]

Thanks for your input, @scottleibrand!

So these settings does not affect carb decay, only COB predictions in the early stages after carb entry?

[scottleibrand]

I believe that is correct, but it’s been ~5 years since I wrote that code, so if the code shows otherwise, I’ll have to reread it.

[bjornoleh]

I believe that is correct, but it’s been ~5 years since I wrote that code, so if the code shows otherwise, I’ll have to reread it.

I think this should match the code, but that we had misread it into relating to carb decay and not predictions. I'll let @dsut4392 revisit this to see if he agrees :)

[SjpStanley]

Yes now understand why bolus calculator was being affected. Should we raise separate issue for Trio docs as I think that could be improved now with Scott’s clarifications? I would be happy to do and draft updated text.

[aug0211]

For what it's worth, I adjusted my 0.1 Remaining Carbs Fraction up to 0.5 and saw no difference in typical looping behavior with SMBs or temp Badals.

I then increased to 1 after a day testing at 0.5, and again saw no difference.

I did see differences in the recommended dosing in bolus calculator, as expected. I went from ~0u recommendations to more reasonable recommendations.

[scottleibrand]

The expected differences in dosing would be in the situation where you enter and eating soon Temp target and/or enter carbs well in advance of seeing the carb absorption. In those scenarios, the variable would control whether or not, and how much, it doses before, it sees the blood sugar rise.

[dnzxy]

We can address this with info texts during settings redesign and refactor. @dsut4392 I'd love for you to give input to that.