Indirect Estimation and Simulation Tool (IEST) Parameters

Parameters are used for various purposes by the system. Parameters can specify covariates that will change during simulation or define a demographic characteristic of a subject. They can define constants and other values that can be reused during simulation. They also can be defined by a user-specified function and then used in subsequent functions as a symbol/shorthand for the user specified function; i.e., they may replace complex mathematical expressions or random generators in multiple functions.

Parameters are classified according to Parameter Types and may have different Parameter Validation Rules and data stored within them as explained below.

The following parameter types can be defined by the system.

• Covariate - Specifies a covariate, a variable or a function of variables, that describe a subject; it can be referenced by many entities in the system. Examples of covariates are: Age, Gender, and Blood Pressure. A covariate can also be defined in functional form and contain an expression that references other covariates such as BMI_Over_30 = Max(BMI-30,0). See parameters of type Function below for further information. When specified as a functional form, the parameter is equivalent to a user defined function and, whenever used, it will be replaced by the expression it holds. Note that if this function includes a random number generator, a different value of the generator will be used each time the function is invoked. The default validation rule for this type of parameter is Number.
• Intervention - Reports whether or not the intervention occurs. It names a column in a result table where information will be stored about whether the intervention occurred. For example, if an ACE inhibitor was administered, the value of ACE_inhibitor will be set to one; otherwise, it is zero. Default validation rule for this type of parameter is Integer [0,1].
• Cost - Provides information on costs associated with a specific state. For example the parameter YearlyCost may include all costs associated with it. Cost parameters hold scalar values. Costs are calculated either through a Cost Wizard expression or through a mathematical formula that uses other parameters. Default validation rule for this type of parameter is Number [0,Inf].
• Quality of Life - Provides information about quality of life associated with a specific state. It is the name for a column in a result table where information will be stored about the quality of life. This is similar to cost with a different scale. Quality of life can be calculated either through the Cost Wizard or through a mathematical formula that uses other parameters. Default validation rule for this type of parameter is Number [0,1].
• Probability - May be used to specify a transition or prevalence probability. This may be used in defining characteristics of a sample (i.e., the prevalence of a covariate) or to define a parameter that is used in the simulation. Default validation rule for this type of parameter is Number [0,1].
• Transitions - the probability to move from one state to another; e.g., the probability of transition from Normal CVD to Angina. Default validation rule for this type of parameter is Number [0,1].
• Coefficient - These parameters are used as multipliers of covariates/evaluation/treatment parameters within transition formulas. These can either be determined during the estimation phase or assigned manually in phase 0 of simulation. Default validation rule for this type of parameter is Number.
• Function - gives a name for a function that can be used later during calculations. Each time the function name is used, it will be replaced by the expression that it represents. For example, a function that increases age may be called AgeIncrease and hold the function Age+1. When a function parameter is encountered in an expression, it is replaced by its contents during evaluation. This way the user can specify a user defined function that whenever used, will be replaced with the expression it holds. Note that if this function includes a random number generator, a different value of the generator will be used each time the function is invoked. Consider for example a parameter called CappedGaussian that generates random numbers using a Gaussian distribution with mean=0 and STD =1 that is restricted to the range from -3 to +3. This can be done by the user using the formula Min(Max(Gaussian(0,1),-3),3) to define this function type parameter. After definition in the parameter form, CappedGaussian can be used in any expression in the system during simulation or population generation from distributions. Whenever this parameter is encountered during simulation, a new random number will be generated on the fly; that is, reusing CappedGaussian will generate a new random number rather than return the same value. This is different than most other parameter types that generally hold values that are assigned to them. Default validation rule for this type of parameter is Expression.
• Table - A table parameter will hold both the definition of the table and the values of the table. The table will be defined by a unique name just like any other parameter. For example Table1. The table can hold multidimensional data along with dimension names, dimension ranges and table cell values. When the name of the table is used in an expression, the system will return the entry in the table corresponding to the subject's current values for the dimension names. Default validation rule for this type of parameter is Table.
• Vector/Matrix - Vectors and Matrices can hold arrays of numbers or parameters representing numbers. Vectors are one dimensional and matrices are two dimensional. Their representations are very similar. Default validation rule for this type of parameter is Matrix.
• Constant - Similar to a function, but constant. It is a general way to store constants and assign them a name. Default validation rule for this type of parameter is Number.
• State Indicators - These cannot be changed by the user, but can be used in expressions and other system functions. Parameters represent states in the system. For each state created in the system, there will be five parameters with a similar name and a different postfix. The name of the parameters will be the same as the state where non alphanumeric characters will be replaced with underscore characters and a postfix of 'Diagnosed' or 'Treated' or 'Complied' or 'Entered' will be assigned. For example for the state 'Survive MI' there will be 5 state indicator parameters called Survive_MI, Survive_MI_Diagnosed, Survive_MI_Treated, Survive_MI_Complied and Survive_MI_Entered . These parameters can be used in an expression during simulation and will represent the actual, diagnosed, treated, and entered states respectively. The value in the parameter associated with the state will be set to one if an individual is in this state in a simulation. It will be zero otherwise. For example, if for the state 'Survive MI' the value of the parameters can be Survive_MI=1, Survive_MI_Entered=1, Survive_MI_Diagnosed=0, and Survive_MI_Treated=0 Survive_MI_Complied=0 meaning that the individual is in actual state 'Survive MI' and has just entered it, while this is not the diagnosed or the treated state. For pooled states that represent sub-processes, this will mean that the state indicator parameter values will be set to 1 if the state associated with the sub-process and the individual will be set to 1. For example, if 'CVD' is representing a sub-process containing 'Survive MI'. Then the values of the state indicators can be Survive_MI=1, Survive_MI_Entered=1, meaning as before that the individual actually entered the state of MI_Survive and therefore CVD=1. If CVD=0 this means that it has not been entered and therefore Survive_MI=0. The validation rule for this type of parameter is Integer [0,1].
• Distribution - Provides information on the distribution of characteristics of a population. It is similar to a function and provides the capability of defining a marginal distribution for a covariate or intervention parameter. Note that the form of the function used as a distribution parameter will be similar to that of a random generator function. Constants are allowed, yet general expressions that are not distributions are blocked. Default validation rule for this type of parameter is Distribution.
• System Reserved - The parameter table in the Database may be used by the system to store temporary parameters to help in calculations and may contain reserved names that cannot be used by other parameters. For example Time can be reserved by the system. Also, internal functions names would be in the system reserved list so that a user will not use these by mistake. It is not allowed to change System Reserved parameters.
• System Arrays - May be used to define an initial set of default initial guesses for all parameters for an estimation project. Default validation rule for this type of parameter is Matrix.
• System Options - These names are set by the system by default; their values can be modified by the user to change functionality of the system. Default validation rule for this type of parameter is Number. Here is a short description of these parameters by categories of influence:
  • System Option Parameters Affecting Simulation and Population Generation from Distributions
    • ValidateDataInRuntime: A number that defines the level of validity checking of expressions during simulation and population generation from distributions. The following levels are supported:
      • 0: No validity checking.
      • 1 or greater: Check that probabilities are within 0 and 1 and check that these sum to 1 when leaving event states and joiner states, and check that a value assigned to a parameter fits the validation rules defined for it.
      • 2 or greater: Check that function parameter validity rules are honored during calculation of expressions - this is the default option.
      • 3 or greater: Impose extra redundant validation checks on all phases of calculation.
    • NumberOfErrorsConsideredAsWarningsForSimulation: The number of times the system will accept parameter validity violation errors during simulation as warnings and will not stop simulation. When this number of errors is reached, the system will raise a fatal error to the user and stop simulation. The error messages can be seen on the console window.
    • NumberOfTriesToRecalculateSimulationStep: The number of times that the system will force recalculation of the same time step if an error was raised during this time step. If unsuccessful after this number of recalculations then force recalculation of the entire individual from the first time step.
    • NumberOfTriesToRecalculateSimulationOfIndividualFromStart: The number of times an individual will be recalculated from start in case errors appeared during simulation that forced restarting calculations. If this number of tries is reached, a fatal error is raised that stops simulation.
    • SystemPrecisionForProbabilityBoundCheck: This is a very small tolerance number that defines how accurate will be fatal error checks for probabilities if ValidateDataInRuntime>=1. This number allows overlooking machine precision issues.
    • RepairPopulation: This integer defines the level the system will try to correct a population set to fit a model before simulation. The following levels are supported:
      • 0: No repairs are made and errors are generated. This forces the user to match population set parameters and model parameters very carefully, including process names.
      • 1 or Greater: The system will attempt to figure out values for process state indicators and other states in the process according to the model structure and according to state indicator values defined in the population set.
      • 10 or Greater: The system will remove individuals with empty values in the population data before simulation, and therefore avoid generating an error that will stop the simulation process.
    • VerboseLevel: Defines how much information to output during simulation.
      • Here are supported levels for output from population generation from distributions:
        • 3 or greater: Record random seed number on file that will be created at the start of population generation from distributions.
        • 7 or greater: Record generated population set on file. This would be a pickled python list object.
        • 10 or greater: Print an announcement each time a new individual starts generation. Also print a generation summary at the end of of population generation from distributions.
      • Here are supported levels for output from bridging population set and model definitions before simulation:
        • 1 or greater: Print summary of the bridge process.
        • 5 or greater: Print a message if deleting a record due to a missing value.
        • 10 or greater: Show each process set by the system due to a child state.
      • Here are supported levels for output from simulation:
        • 3 or greater: Record random seed number on file that will be created at the start of simulation.
        • 7 or greater: Record simulation results set on file.
        • 10 or greater: Print an announcement each time a new individual starts simulation. Also print a simulation summary at the end of simulation.
        • 20 or greater: Print an announcement each time an individual starts a new repetition during simulation. Also print a message if recalculation of a repetition was forced due to error.
        • 30 or greater: Print an announcement each time step during simulation. Also print a message if recalculation of a time step was forced due to error.
        • 40 or greater: Print an announcement for each state in the State Processing Queue (SPQ). This is highly advanced and requires deep understanding of the system.
    • RandomSeed: Defines a random seed to start both population generation and simulation. NaN is used to indicate that system time will be used as a random seed - essentially making numbers different each simulation.
    • NumberOfErrorsConsideredAsWarningsForPopulationGeneration: The number of times the system will accept boundary violation errors as warnings and will not stop during population generation from distributions. When this number or errors is reached, the system will raise a fatal error to the user. Error messages can be found on the console window.
    • NumberOfTriesToRecalculateIndividualDuringPopulationGeneration: The number of time the system will try to recalculate the same individual if a non fatal error is encountered during calculation of that individual. Once this number is reached a fatal error will be raised and generation of data from distributions will stop.
  • System Option Parameters Affecting Estimation
    • Opt_SymbolicToNumericTolerance: A small number used by the system as a threshold to test the result before and after optimization by comparing symbolic calculation to numeric calculation.
    • Opt_UseMultiPhaseOptmization: A number from 1 to 3 signifying the number of optimization phases to use. Phases allow using different optimization parameters to reach the best optimization result.
    • Opt_GradientPerturbationH: A small number used as an interval during numerical derivation when calculating likelihood of optimization studies.
    • Opt_SkipDerivativesForLongExpressions: The length of the largest expression for which the system will calculate derivatives and use them during optimization. This calculation will be skipped for longer expressions.
    • Opt_LongExpressionsPrintSize: The maximum number of characters to print from an expression. If an expression print is cut, this will be noted to the user by a symbol.
    • Opt_SkipDerivativesIfMemoryError: Unless this variable is set to zero, the system will ignore memory errors generated if long expressions are derived and create expressions so long that may not fit in memory
    • OptPhase1_fmin_l_bfgs_b_approx_grad, OptPhase2_fmin_l_bfgs_b_approx_grad, OptPhase3_fmin_l_bfgs_b_approx_grad: The parameter approx_grad to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_m, OptPhase2_fmin_l_bfgs_b_m, OptPhase3_fmin_l_bfgs_b_m: The parameter m to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_factr, OptPhase2_fmin_l_bfgs_b_factr, OptPhase3_fmin_l_bfgs_b_factr: The parameter factr to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_pgtol, OptPhase2_fmin_l_bfgs_b_pgtol, OptPhase3_fmin_l_bfgs_b_pgtol: The parameter pgtol to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_epsilon, OptPhase2_fmin_l_bfgs_b_epsilon, OptPhase3_fmin_l_bfgs_b_epsilon: The parameter epsilon to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_iprint, OptPhase2_fmin_l_bfgs_b_iprint, OptPhase3_fmin_l_bfgs_b_iprint: The parameter iprint to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here
    • OptPhase1_fmin_l_bfgs_b_maxfun, OptPhase2_fmin_l_bfgs_b_maxfun, OptPhase3_fmin_l_bfgs_b_maxfun: The parameter maxfun to be passed to the optimization routine during optimization phases 1,2,3 respectively. For further details click here

Parameters can be assigned validation rules to verify that the result of the formula is of the specified type. They do not modify the Parameter in any way. a Validation Rule can be:

• Number - accepts any floating point number such as 1.23345 or -0.123 or 1.2e3, subject to specified limits.
• Integer - accepts integers, such as 1,2,3.
• Expression - accepts system or user defined functions and parameters in general mathematical expressions such as Age+1, or Exp(-1.234), or Max(Age,20) +1. Parameters in a validation rule expression are different than other parameters that generally hold values after assigned to them. A parameter validated as an expression is actually a function that forces evaluation of a defined expression rather than hold a value. See Expressions for additional information.
• Matrix - checks the syntax of the matrix and allows only vectors of dimension 1 and matrices of dimension 2. Examples of vectors can be [1,2,3,4] or [1,Age,BP], whereas matrices will have the format [ [ 1,2,3], [ 4,5,6], [7,8,9] ] . Vectors and matrices are used during Estimation.
• Distribution - checks the syntax of the expression for a valid definition of the statistical distribution expressions. Distributions are used during Estimation. The expression will be limited to be a Distribution function name used in a function form to generate random numbers. See Expressions for additional information.
• Table - checks that the parameter holds a multi-dimensional table entity. This forces additional syntax checks limited to tables. See Expressions for additional information.

When defining a parameter with the validation rule Number, Integer, Expression, Table, the user can define additional validation rule parameters of the type [min, max] that will define bounds for this parameter. For example a user who wishes to define a Boolean parameter, should define an integer with the validation rule parameters of [0,1]. Another example is a user who wishes to define a positive integer should define a parameter of the type integer with the validation rule parameter of [0,Inf]. By default and unless specifically requested otherwise by the user by changing the appropriate system options, validation rules and validation rule parameters are checked during simulation at each step to verify values are within the allowed ranges.

Default validation rules and validation rule parameters are defined by the parameter type as stated above.

Creating Parameters

1. From the main form, click the 'Parameters' button on the left-hand navigation panel. The following form will appear:

2. To see all parameters, make sure 'ALL User Accessible' is selected, and press 'OK'. You can also decide to check only the parameter types of interest to view instead seeing all parameters. Then the parameter form will appear:

For a video demonstration on creating parameters, click here.

Note that the parameters form can accessed from other forms by double clicking a field that requires a parameter. This allows creating parameters on the fly while working from another form.