system_set_tt_cond: Define Titration Triggers and Actions

In ubiquity: PKPD, PBPK, and Systems Pharmacology Modeling Tools

Define Titration Triggers and Actions

Description

Once a rule has been defined using system_new_tt_rule, it can then be used by specifying checks at each of the titration time points that, when true, will perform some actions.

Usage

system_set_tt_cond(cfg, name, cond, action, value = "-1")

Arguments

cfg	ubiquity system object
name	string containing the name for the titration rule to which this condition applies
cond	string that evaluates a boolean value that is TRUE when the action should be triggered
action	stringing that evaluates to what should be done when the condition is met (e.g. changing the dose, state change, etc)
value	code to be stored in the titration history to track when this condition has been triggered

Details

The general syntax for setting a new condition is:

cfg = system_new_tt_cond(cfg,
                        name   = "rname",
                        cond   = "BOOLEAN EXPRESSION",
                        action = "EXPRESSION",
                        value  = "VALUE")

The name input will associate this condition with a previously defined rule. For each time defined when the rule was created, the condition (cond) will be evaluated. If that condition evaluates as TRUE then the action will be evaluated. Lastly, when a condition action is evaluated, the value is stored in the titration history.

Multiple conditions can be associated with a rule. The internal titration history will track each one where a condition has been evaluated as true, but the simulation output will only show the last condition to be evaluated as true.

The cond field is a string that, when evaluated, will produce a boolean value (TRUE or FALSE). If you simply want to force an action at each of the times for a given rule you can use: cond = "TRUE". Alternatively you can provide mathematical expressions or even complicated user defined functions.

The action field is evaluated when cond is true. To modify how a simulation is going to be performed, you will want to modify the SIMINT_cfgtt variable using the different system commands. Certain common tasks have prototype functions created to make it easier for the user:

• SI_TT_BOLUS - Set bolus dosing

• SI_TT_RATE - Set infusion inputs

• SI_TT_STATE - Reset system states

Note: Protype functions are strings but sometimes it is necessary to specify strings within this string. For the main string use double quotes (") and for the internal strings use single quotes (')

SI_TT_BOLUS

The simplest way to apply a bolus when the condition is true is to use the following:

action = "SI_TT_BOLUS[state=’At’, 
                     values=c(10, 10, 10), 
                     times=c(0, 1, 2)]"

The values and times are vectors of numbers of equal length. The dosing and time units are those specified in the system.txt file for the <B:?> delimiter. The times are relative to the titration time. So 0 above means at the titration time.

It’s possible to specify an interval and a number of times to repeat the last dose using the following:

action = "SI_TT_BOLUS[state    = ’At’, 
                     values   = c(5, 5, 10), 
                     times    = c(0, 2, 4), 
                     repdose  = ’last’, 
                     number   = 7, 
                     interval = 4]"

This will give a dose of 5 at the titration point and 2 time units later. The dose of 10 at time 4 will be repeated 7 times every 4 time units. So a total of 8 (7 + 1) doses at 10 will be administered. Remember the time units were those defined in <B:?>. The input repdose can be either ’last’ or ’none’.

Note: The main string is in double quotes " " but the strings in the protype argument (e.g. ’last’) are in single quotes ’ ’.

SI_TT_RATE

If you created an infusion named Dinf using <R:?> and the infusion units are min (times) and mg/min (rates). To have a 60 minute infusion of 20 mg/min then we would do the following:

action = "SI_TT_RATE[rate=’Dinf’, times=c(0, 60), levels=c(20.0, 0)]"

If we wanted to do this every day for 9 more days (a total of 10 days) we can repeat the sequence:

action = "SI_TT_RATE[rate     = ’Dinf’, 
                    times    = c(0, 60), 
                    levels   = c(20, 0), 
                    repdose  = ’sequence’, 
                    number   = 9, 
                    interval = 24*60]"

The input repdose can be either ’sequence’ or ’none’.

Note: The time units and dosing rate are those specified using <R:?>.

SI_TT_STATE

To provide fine control over states at titration points the state reset prototype is provided. For example, if you are modeling an assay where there is a wash step and you want to drop a concentration to zero. If you have a state named Cc defined in your system.txt and you want to set it to 0.0 in a condition the following action would work.

action = "SI_TT_STATE[Cc][0.0]"

The value here is a number but you can use any mathematical combination of variables available in the titration environment. Also you can create your own user function and place the function call within the brackets above.

Titration Environment

The cond, action, and value statements can use any variables available in the titration environment. If you want to perform complicated actions, you can simply create a user defined functions and pass it the variables from the titration environment that you need. These include named variables from the model as well as internal variables used to control the titration.

States and Parameters

System parameters (<P>), static secondary parameters (<As>) and the initial value of covariates are available. Also the state values (at the current titration time) can be used. These are all available as the names specified in the system.txt file. Since system resets (SI_TT_STATE) are processed first, any changes made to states are the values that are active for other actions.

Internal Simulation Variables

Internal variables are used to control titration activities. These variables can also be used in the conditions and actions.

• SIMINT_p - list of system parameters

• SIMINT_cfg - system configuration sent into the titration routine

• SIMINT_cfgtt- system configuration at the current titration event time

• SIMINT_ttimes - vector of titration times (in simulation units)

• SIMINT_ttime - current titration time (in simulation units)

• SIMINT_tt_ts - list of time scales for the current titration

• SIMINT_history - data frame tracking the history of conditions that evaluated true with the following structure:

• • tname - name of titration rule

  • value - value indicating condition that was satisfied

  • simtime - simulation time when that rule/value were triggered

  • timescale - time at the rule timescale when that rule/value were triggered

Individual Simulations

To run an individual titration simulation use the following:

som = run_simulation_titrate(parameters, cfg)

This provides the same output as run_simulation_ubiquity with two extra fields. The first, som$titration, contains three columns for each titration rule. The columns will have a length equal and corresponding to the simulation times. If the rule name is rname, then the column headers will have the following names and meanings:

• tt.rname.value - Value of the rule for the active condition or -1 if not triggered

• tt.rname.simtime - Simulation time where the last condition became active

• tt.rname.timescale - Simulation time in the time scale the rule was specified in

The second field is som$titration_history which contains a summary list of all of the titration events that were triggered.

• tname - Titration rule name

• value - Value of the rule for the active condition or -1 if not triggered

• simtime - Simulation time where the last condition became active

• timescale - Simulation time in the time scale the rule was specified in

To convert this structured list into a data frame the som_to_df command can be used:

sdf = som_to_df(cfg, som)

To run stochastic titration simulations, the same function is used:

som = simulate_subjects(parameters, cfg)

This will add a data a list element called som$titration with three fields for each titration rule:

• tt.rname.value - Value of the rule for the active condition or -1 if not triggered

• tt.rname.simtime - Simulation time where the last condition became active

• tt.rname.timescale - Simulation time in the time scale the rule was specified in

Each of these fields is a matrix with an entry for each simulation time (column) and each subject (row). This data structure can also be converted to a data frame using som_to_df.

Value

Ubiquity system object with the titration condition defined

See Also

system_new_tt_rule, run_simulation_titrate, som_to_df, simulate_subjects

ubiquity documentation built on Nov. 2, 2023, 6:26 p.m.