Unit problems of simbiology model

As a newbie of simbiology, I'm often plagued by unit problems. My code and the error reported are as follows，I don't know how to improve it.

1.Is it because of the unit settings in addcompartment() and adspecies()?

2.How are the units in compartments ('CapacityUnits') related and different from the units in species ('InitialAmountUnits')?

3. Will the value and units of the compartments have an effect on subsequent modeling?

4.“P_IL6*TUMOR_C.B_PB*CART_P.CARTE_PB”--->"picogram/(cell*cell*milliliter*day)*cell*cell"---> picogram/(milliliter*day)...I multiplied the units in ReactionRate and felt there was no error...

5.Maybe I wrote my "Reaction" wrong? CART cells killed the tumor-cells and secreted IL6 into the blood to induce the inflammatory responses. Reaction_5 is used to describe the secretion of IL6-producing

m1 = sbiomodel('CART_model');

%tumor compartment

comp_TUMOR = addcompartment(m1, 'TUMOR_C',1,'CapacityUnits','milliliter' );

%cart compartment

comp_CART_P = addcompartment(m1, 'CART_P',1,'CapacityUnits','milliliter');

%cytokine compartment

comp_CRS = addcompartment(m1, 'CRS_C',1,'CapacityUnits','milliliter');

%species

S1 = addspecies(comp_TUMOR, 'B_PB', 0 ,'InitialAmountUnits','milliliter');

set(S1,'Notes','Cancer cells in the tumour compartment');

S2 = addspecies(comp_CRS, 'IL6', 7.55 , 'InitialAmountUnits', 'picogram/milliliter');

set(S2,'Notes','IL6 in the CRS compartment');

S3 = addspecies(comp_CART_P, 'CARTE_PB', 0 ,'InitialAmountUnits', 'cell');

set(S3,'Notes',' CARTE in the CART peripheral blood compartment');

P_IL6 = addparameter(m1, 'P_IL6', 'ValueUnits','picogram/(cell*cell*milliliter*day)','ConstantValue',false);

set(P_IL6,'Notes','CART induced IL6 secretion');

R5 = addreaction(m1, 'TUMOR_C.B_PB + CART_P.CARTE_PB -> CRS_C.IL6');

set(R5,'ReactionRate','P_IL6*TUMOR_C.B_PB*CART_P.CARTE_PB')

--> Error reported from Dimensional Analysis:

Dimensional analysis failed for reaction 'reaction 'Reaction_5''. The species participating in the reaction do not have consistent

substance units. Change all species units to a mass basis (e.g. gram or gram/liter), or change all species units to an amount basis (e.g. mole or mole/liter).

Answer 1

[Jeremy Huard]

Dear Bohao,

compartments are containers that are typically defined by their volume, so their unit will be e.g. liter, whereas species define the concentration or amount of a chemical contained in this compartment. This, species must have units of amount, concentration or mass.

In your code, the issue comes from species B_PB defined in object S1, which has units of volume (milliliter).

Depending on the species units, volume scaling might be applied to the reaction rates and ODEs. So, compartment volumes will indeed affect the final ODEs. Please refer to the following documentation page for more information: Derive ODEs from SimBiology Reactions.

FYI: instead of 'InitialAmountUnits' for species and 'CapacityUnits' for compartments, you can now use 'Units' for both in their definition.

e.g.:

comp_TUMOR = addcompartment(m1, 'TUMOR_C',1,Units='milliliter' );

S2 = addspecies(comp_CRS, 'IL6', 7.55 , Units='picogram/milliliter');

Best regards,

Jérémy

[Bohao]

Dear Jérémy,

@Jeremy Huard

Thank you for your insightful feedback and clarification on the units for compartments and species in SimBiology. I adjusted the units, but the problem still persists.

Best regards,

Bohao

m1 = sbiomodel('CART1117');
comp_TUMOR = addcompartment(m1, 'TUMOR_C',1,'Units','milliliter' );
comp_CART_P = addcompartment(m1, 'CART_P',1,'Units','milliliter');
comp_CRS = addcompartment(m1, 'CRS_C',1,'Units','milliliter');
S1 = addspecies(comp_TUMOR, 'B_PB', 0 ,'Units','cell');
    set(S1,'Notes','Cancer cells in the tumour compartment');
S2 = addspecies(comp_CRS, 'IL6', 7.55 , 'Units', 'picogram/milliliter');
    set(S2,'Notes','IL6 in the CRS compartment');
  
S3 = addspecies(comp_CART_P, 'CARTE_PB', 0 ,'Units', 'cell');
    set(S3,'Notes','  CARTE in the CART peripheral blood compartment');
P_IL6 = addparameter(m1, 'P_IL6', 'Units','picogram/(cell*cell*milliliter*day)','ConstantValue',false);
    set(P_IL6,'Notes','CART induced IL6 secretion');
R1 = addreaction(m1, 'TUMOR_C.B_PB + CART_P.CARTE_PB -> CRS_C.IL6');%
    set(R1,'ReactionRate','P_IL6*TUMOR_C.B_PB*CART_P.CARTE_PB')

[Jeremy Huard]

Dear @Bohao,

there are two issues with your reaction:

1. The binding occurs across compartments. It is recommended to have at least both reactants in the same compartment or even better, all 3 species in the same compartment. You can then add a reaction to transport the product to another one. This is more in line with the physical system where both reactants need to be in the space to react and will create a product in this same space.
2. Reactants and product have different dimensions. Dimensional analysis requires all species in a aeraction to have the same dimension: either mass (gram or gram/liter) or amount (mole, mole/liter, cell, cell/liter). In your case I would rather use mole or mole/liter.

I would also recommend to use the built-in MassAction kinetics instead of a custom reaction rate representing a mass action kinetics. It makes it easier for SimBiology to apply volume scaling when needed (=multiply concentrations by the volume when needed).

Finally, I strongly recommend to activate unit conversion. This will ensure that units are consistent and avoid potential issues when for example, the simulation time unit is different from the time units used in the model.

Here is a code snippet to use the built-in Mass-Action kinetics and activate unit conversion:

R1 = addreaction(model, 'B_PB + CARTE_PB -> IL6');
kObj = addkineticlaw(R1,"MassAction");
kObj.ParameterVariableNames = "P_IL6";

cs = model.getconfigset();
cs.CompileOptions.UnitConversion = true;

I hope this helps.

Best regards,

Jérémy