createInterventions should detect if fitness uses "rel" or if it is not freq-dep and abort

[rdiaz02]

Two issues

1. createInterventions allows passing whatHappens with relative fitness

When using interventions, specifically "WhatHappens", the what should not be changes in relative frequencies. This is implicit, since all of the examples in the vignette (and all of the code) always specify whathappens using "n_", not "f_" and it is said in the vignette: "Note that, for now, the fitness must have frequencyDependentFitness as TRUE and frequencyTypeas “abs” (it can be )."

But createInterventions is defined as:

 createInterventions
function (interventions, genotFitness, frequencyType = "auto")
{
    if ((frequencyType == "abs") || (frequencyType == "auto")) {
        return(adapt_interventions_to_cpp(verify_interventions(interventions),
            frequencyType, genotFitness))
    }
    else if (frequencyType == "rel") {
        stop("Frequency type as relative is not implemented... yet.")
    }
    else {
        stop("You have specified the freqType wrong. Review it please.")
    }
}

So we can easily define a genotFitness with "rel", and not pass an argument to "frequencyType" in createInterventions and it will go unnoticed and crash later.

Solution

At least we should check in createInterventions: verify genotFitness$frequencyType and stop if "rel".

Also: say this a few more times in the vignette and the help for createInterventions.

Example

fitness_df <- data.frame(
    Genotype = c("WT", "S", "R"),
    Fitness = c(
        "1 * f_ + 0.5 * f_S + 0.2 * f_R",  
        "if (T < 50) 0.8; else 1.2",   
        "if (T < 50) 1.1; else 0.9"    
    ),
    stringsAsFactors = FALSE
)

model <- allFitnessEffects(
    genotFitness = fitness_df,
    frequencyDependentFitness = TRUE,
    frequencyType = "rel"
)

i1 <- list(
    list(ID = "resistantTreatment",
         Trigger = "N > 100",
         WhatHappens = "f_R = f_R * 0.7",
         Periodicity = 10, Repetitions = Inf)
)

i1 <- createInterventions(i1, model)

simulation <- oncoSimulIndiv(
    model,
    model = "McFL",
    mu = 1e-4,
    initSize = 5000,
    finalTime = 200,
    keepEvery = 1,
    interventions = i1
)

## Error:
## exprtk parser error: 

## Error[00] Position: 00 Type: [  Syntax Error] Msg: ERR202 - Undefined symbol: 'f_R' Expression: f_R = f_R * 0.7

##  Unrecoverable exception: The expression was imposible to parse.. Aborting. 

Why not WhatHappens with relative numbers?

It is confusing and the outcome can depend on order of evaluation if an intervention change population sizes of several genotypes. Relative fitness can be trivially defined using things like n_A/N and similar (see section 10.5 of the vignette: https://rdiaz02.github.io/OncoSimul/OncoSimulR.html#105_Frequency-dependent_fitness:_can_I_mix_relative_and_absolute_frequencies), so one can define fitness using n_ and whatHappens with absolute number changes.

(This was reported by Sheila Santomé Latas, from PRSTR 2024-25).

2. createInterventions allows passing fitness specifications that are not frequency dependent

It should fail immediately

Solution

At least we should check in createInterventions: verify genotFitness$frequencyType and stop if not frequency-dependent.

Also: say this a few more times in the vignette and the help for createInterventions.

Example

rT <- data.frame(parent = c("Root", rep("TP53", 2)),
                 child = c("TP53", "MDM2", "ATM"),
                 s = 0.5,
                 sh = c(-Inf, 0, 0),
                 typeDep = "MN")

epvecx <- c("TP53:MDM2" = -0.4)

FitEff <- allFitnessEffects(rT = rT, epistasis = epvecx)

ex3 <- oncoSimulIndiv(
    FitEff,
    model = "McFLD",
    mu = 1e-4,
    sampleEvery = 0.01,
    initSize = 5000,
    finalTime = 500,
    onlyCancer = FALSE
)


ix <- list(
    list(ID = "i1",
         Trigger = "T > 10",
         WhatHappens = "n_TP53_ATM = n_TP53_ATM*0.8",
         Periodicity = 1,
         Repetitions = Inf
         )
)

## This should have failed
ix <- createInterventions(ix, FitEff)


ex3ix <- oncoSimulIndiv(
    FitEff,
    model = "McFLD",
    mu = 1e-4,
    sampleEvery = 0.01,
    initSize = 5000,
    finalTime = 20,
    onlyCancer = FALSE,
    interventions = ix)

(This was reported by Sara Verde Camacho, from PRSTR 2024-25).

[ArashPartow]

wrt: Undefined symbol: 'f_R' Expression: f_R = f_R * 0.7 ignoring the undefined symbol for now, should the expression instead be: f_R := f_R * 0.7

[rdiaz02]

Thanks! I haven't updated yet to the newest version of ExprTk (maybe this is related), but in this case this example should give an error.

[ArashPartow]

@rdiaz02 assignment and equality are different things and have been like this for about 20 years wrt EprTk.

Assignment is denoted by ":=" and equality is either "==" or "="

Assuming f_R is defined, the expression would be valid, in short the expression would provide the result of: is f_R equal to f_R * 0.7.

My thinking however is that perhaps you instead want the value of f_R * 0.7 to be assigned to f_R

[rdiaz02]

@ArashPartow: thanks for pointing this out. I am aware that assignment and equality are different things, but the problem is not due to the expression having = instead of := . (And, yes, my comment was very confusing, and mentioning ExprTk versions made no sense since this is unrelated to it, so apologies for the confusion).

The expression f_R = f_R * 0.7 is not passed, as such, to ExprTk. What we do (e.g., see

OncoSimul/OncoSimulR/src/UnityOncoSimul/intervention_private.cpp

Line 62 in b9b77ec

if (!parser_rwh.compile(rightMostWhatHappens, expression)){

) is:

1. Split the expression on the =. (Yes, it is unfortunate we've used = instead of := or even <-, as in R itself, to denote assignment ---I've opened an issue WhatHappens should use, as syntax for assignment, ":=" or "<-" #34).

2. Check if what the user wants can be done. Anything with an f_ on the left of the = is not allowed. (We use f_ to mean relative frequencies, and we refuse to try to manipulate those directly ---see above "Why not WhatHappens with relative numbers").

3. If the intervention is allowed, we pass that to ExprTk so it evaluates the expression on the right of the = and that gives us a number (for example, a new total population size).

4. Depending on what the user asked for, that number might be assigned to the thing on the left (e.g.,

   OncoSimul/OncoSimulR/src/UnityOncoSimul/intervention_private.cpp

   Line 112 in b9b77ec

   it->second = res;

   ), but as I said not using ExprTk directly in that assignment.
   In other cases we use that number from step 3 as the N to sample from a multivariate hypergeometric distribution (

   OncoSimul/OncoSimulR/src/UnityOncoSimul/intervention_private.cpp

   Line 108 in b9b77ec

   reduceTotalPopulation(iif, res);

   ) and we use the new population sizes obtained from this sample to fill up the appropriate values.

My thinking however is that perhaps you instead want the value of f_R * 0.7 to be assigned to f_R

Yes, indeed, had the expression been n_R = n_R * 0.7 what we would have wanted is to assign n_R * 0.7 to the new value of n_R (and we would have done that as in 4. above, after having ExprTk compute n_R * 0.7).

Thanks for these comments, because they make it very clear that the use of = in these expressions (our choice of syntax for the "WhatHappens") has been a bad idea and we have to change it (#34).

[ArashPartow]

Thanks for the detailed explanation. It now does make sense. I think what confused me initially was the log message in the comment: #31 (comment)

Error[00] Position: 00 Type: [ Syntax Error] Msg: ERR202 - Undefined symbol: f_R Expression: f_R = f_R * 0.7

It looked similar to how errors are logged in the ExprTk examples, where it's the error diagnostic then the complete string representation of the expression that was compiled. But in your case you're logging the entire configured value of the WhatHappens property, both tokens and the '=' delimiter.

[rdiaz02]

Yes, you are right. The messages could be confused with errors given by ExprTk itself. I created an issue to fix this (#35). Thanks for pointing it out!