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.
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
TRUEwhen 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 dosingSI_TT_RATE- Set infusion inputsSI_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 parametersSIMINT_cfg- system configuration sent into the titration routineSIMINT_cfgtt- system configuration at the current titration event timeSIMINT_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 titrationSIMINT_history- data frame tracking the history of conditions that evaluated true with the following structure:tname- name of titration rulevalue- value indicating condition that was satisfiedsimtime- simulation time when that rule/value were triggeredtimescale- 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 triggeredtt.rname.simtime- Simulation time where the last condition became activett.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 namevalue- Value of the rule for the active condition or -1 if not triggeredsimtime- Simulation time where the last condition became activetimescale- 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 triggeredtt.rname.simtime- Simulation time where the last condition became activett.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.