The FAQs page provides answers to users' questions, along with links to other relevant articles within the User Guide.
How can I define a variable where the value depends on strategy?
You can easily define variables with values dependent on strategy using the by_strategy(…) function. When you use this function, you must specify a value for each strategy defined on the Strategies page, even if multiple strategies share the same value. If you don’t, the model will generate an error when you run it.
For example, if your model includes three strategies, ‘New_Rx’, ‘Old_Rx’, and ‘No_Tx’, and you want to assign the values 150, 75, and 75, respectively, to a particular variable, your by_strategy(…) function would look like:
Please remember to use the exact names that you assigned to strategies on the Strategies page. Also, please keep in mind R is case sensitive.
How can I define a variable where the value depends on group?
You can easily define variables with values dependent on group using the by_group(…) function. When you use this function, you must specify a value for each group defined on the Groups page, even if multiple groups share the same value. If you don’t, the model will generate an error when you run it.
For example, if your model includes two groups, ‘Children’ and ‘Adults’, and you want to assign the values 0.45 and 0.81, respectively, to a particular variable, your by_group(…) function would look like:
Please remember to use the exact names that you assigned to groups on the Groups page. Also, please keep in mind R is case sensitive.
How can I reference a value stored in a table in my model?
You can reference a value stored in a hēRo3 table by using the function, look_up(…). This function works similarly to the function, INDEX(…), in Excel, and uses both a row and column reference to identify and extract a value from a table. The arguments of this function, in order, are: (1) the name of the table; (2) a lookup value to indicate the row of interest and the column in which to look for a value; and (3) the name of the column from which you would like to extract the relevant value.
For example, if you wanted to extract the value, 990.3, which is the estimated cost of the adverse event, nausea, from the ‘Adverse_Events’ table shown below,
you would use the function, look_up(…), with syntax as follows:
Please be sure to spell the name of the table, as well as the names of the columns and values, the same way they are spelled in the table itself. Also, please keep in mind R is case sensitive.
How can I calculate a patient’s current age in my model?
You can easily calculate current age during any given cycle in a model using a simple formula that references patients’ starting age and the time that has elapsed since model entry. While you can hard code a numeric value for the former, it is best practice to create a variable, ‘start_age’, to refer to this value in formulas. To calculate current age in a given cycle, add the number of years elapsed since model start, which is represented by the hēRo3 keyword, ‘model_year’, to the age of patients at model entry. Because the first year of a model is assigned the value of 1 (and not 0) in hēRo3, it is important to subtract the hēRo3 keyword, ‘cycle_length_years’, from ‘model_year’ in your formula (if you don’t, patient age will be off by 1 year). The formula you would use would be as follows:
Please note that if you are not using annual cycles in your model, current age will not always be an integer.
I want to calculate general population mortality rates in a model from a life table. Is there an easy way to do this in hēRo3?
You can use the function, define_surv_lifetable(…) to calculate general population mortality rates from a life table (life tables can be copied from any convenient source and pasted into a table in hēRo3). When you use define_surv_lifetable(…), you need to reference the name of the life table, the starting age, the percentage of males in the population at the start of your model, and the unit of time in which mortality rates should be expressed.
Life tables in hēRo3 have to conform to a specific format. They must have a column labelled ‘age’ that contains patient age in years, a column labelled ‘male’ that contains the probability of death for males at each age, and a column labelled ‘female’ that contains the probability of death for females at these ages, in that order.
For example, if you had a life table called 'GP_Life_Table', your variable for starting age is ‘start_age’, and 'pct_male' represents the percentage of males in the cohort at the beginning of the model, your formula for calculating general population mortality rates would be as follows:
The final argument in the formula above, ‘output_unit’, refers to the unit of time in which mortality rates should be expressed. For example, if you want to use monthly mortality rates, set ‘output_unit’ to ‘months’. If you want to use annual mortality rates, set ‘output_units’ to ‘years’. You cannot generate quarterly mortality rates, however, since calendar quarters are not a fixed unit of time (ie, there are 92 days between 1 January and 31 March [except in leap years], but there are 91 days between 1 April and 30 June). If your model has quarterly periodicity, however, you can generate quarterly mortality rates by rescaling monthly mortality rates, by using the hēRo3 function, rescale_prob(…).
It is best practice to define and work with survival distributions on the Survival Distributions page, and then refer to them on the Transitions page by the variable names that you have given to them. (If you prefer to perform your survival calculations directly on the Transitions page, you may do so.)
Is there an easy way to make sure my transitions from a given state sum to 1?
Although there is no foolproof method to ensure that transitions from a given state sum to 1, hēRo3 has a helpful keyword, ‘C’, to simplify this task. The hēRo3 keyword, ‘C’, is a function that evaluates to 1 minus the sum of all other transitions from a given state (ie, the complement). (It is important to remember that hēRo3 is case-sensitive, and you must enter this function as ‘C’ and not ‘c’.) While you may use the hēRo3 keyword, ‘C’, to express the value of any transition, we think it is most helpful to use it for the probability that patients do not leave their current state for another one. Please note that the hēRo3 keyword, ‘C’, may only be used for one transition from a given state; if you use it for more than one transition out of a given state, your model will generate an error and will not run.
I want to make a variable dependent on time; how can I do that in hēRo3?
Variables can be made dependent on time simply by referencing one of the hēRo3 keywords for model time. The principal hēRo3 keywords for this are ‘model_day’, ‘model_week’, ‘model_month’, and ‘model_year’.
Assume you have a model that uses monthly periodicity, and you would like assign different costs to patients receiving a particular drug based on how long they have been taking it—for example, to assign the cost of induction therapy (‘induction_cst’) to the first 6 months, and thereafter, to assign the cost of maintenance therapy (‘maintenance_cst’) in all subsequent months. You would use the hēRo3 keyword, ‘model_month’, in a formula for drug cost that would look as follows:
This formula evaluates to ‘indcution_cst’ for the first 6 cycles of your model, and evaluates to ‘maintenance_cst’ for all subsequent cycles.
When I try to run my model, I get an error message and my model will not run. What should I do?
The User Guide provides a listing of many common error messages and what might be causing them, available here. There is also a slide deck on this topic, called “Tips & Tricks to Use When Debugging Models in hēRo3”, that you might find helpful. If after consulting these resources, you still are unable to get your model to run, you can always reach out to firstname.lastname@example.org for assistance.
If I want to apply a cost during the first year of my model, but not during any subsequent years, how can I do this?
You can easily assign patients a cost only during the first year of your model by referencing one of the hēRo3 keywords for model time—specifically, ‘model_day’, ‘model_week’, ‘model_month’, or ‘model_year’.
For example, if your model has monthly periodicity and you would like to assign patients a monitoring cost only during the first year of treatment, you could use the hēRo3 keyword, ‘model_month’, in a formula that looks as follows:
In this example, patients would be assigned a monthly cost of monitoring, ‘cst_monitoring_m’, during the first 12 cycles of your model (ie, one year) and a cost of 0 in all subsequent cycles. You could enter this formula directly on the Values page, or you could create a variable on the Parameters page and reference it on the Values page. Either method is acceptable, so long as you use a consistent approach.
If your model uses annual cycles, rather than monthly cycles, your formula might look as follows:
By multiplying the monthly monitoring cost by the hēRo3 keyword, ‘cycle_length_months’, you are multiplying the monthly cost by the number of months in an annual cycle in this model. This calculates a total cost of monitoring over one year, based on the value specified for ‘cst_monitoring_m’ (ie, the monthly cost of monitoring). If you do not multiply the monthly cost by the hēRo3 keyword, ‘cycle_length_months’, you will apply the monthly cost of monitoring only once during the entire first year of your model.
How can I calculate a sum product using the values stored in a table?
There is an easy way to do a sum product in hēRo3, much as you can do so in Excel.
Assume you would like to calculate a total cost of all adverse events for a particular strategy in your model (say, ‘New_Rx’), and your adverse event data is stored in a hēRo3 table that contains, for several different types of adverse events, their probabilities of occurrence and their associated costs; your table might look as follows:
In table above, column A contains the names of all adverse events in your model, columns B, C, and D contain the probabilities of experiencing these events among patients receiving ‘No_Tx’, ‘Old_Rx’, and ‘New_Rx’, respectively, and column E contains the estimated cost of each adverse event.
Since there are no adverse events associated with ‘No_Tx’, you do not need to calculate the total cost of adverse events for this strategy. You can calculate a total expected cost of adverse events for ‘Old_Rx’ by multiplying the probability of each adverse event for this strategy (column C) times the corresponding cost of each event (column E), which is the same for all strategies. Your formula would look as follows:
You would have a similar formula for ‘New_Rx’, which would differ from the formula above only in the respect that the probabilities of each event would be drawn from the ‘New_Rx’ column; this formula would therefore look as follows:
Both of these formulas return the sum product of the relevant column containing probabilities for a given strategy and the cost of each adverse event, which does not vary between the strategies. If the unit costs of adverse events differed between strategies (eg, due to differences in severity), your table would contain two columns of costs—one to be used for ‘Old_Rx’, and the other to be used for ‘New_Rx’.
I’m uncertain what method of half-cycle correction to use in my model; what’s the difference between the three methods on the Settings page?
The method of half-cycle correction that you choose determines when during model cycles patients will transit between health states―at the beginning of each cycle, at the end of each cycle, or at the midpoint of each cycle. The three methods of half-cycle correction that you may choose from are as follows:
- With the Start method, patients are assumed to transition between health states at the beginning of every cycle; state membership during any given cycle is calculated after health-state transitions have occurred.
- With the End method, patients are assumed to transition between health states at the end of every cycle; state membership during any given cycle is calculated before health-state transitions have occurred.
- With the Life-Table method, which hēRo3 defaults to unless you select another method, patients are assumed to transit between health states at the midpoint of each cycle, and state membership during any given cycle is calculated as the average of health-state membership before and after transitions have occurred.
If you have a model that has very short cycles (eg, daily or weekly), nominal differences between the three methods are typically small. If you have a model with very long cycles (eg, annual), however, the three methods can produce noticeably different results. It also is important to know that if you use the Start method and your model incorporates mortality, some patients will immediately die at model entry and not contribute any membership time to any state other than ‘dead’.
I don’t know which method of discounting to choose on the Settings page in my model; what’s the difference between the three methods?
The discounting method that you choose determines how outcomes and costs are discounted in your model to reflect the time value of money (as well as health). The three methods of discounting that you may choose from are as follows:
- With the Start method, which hēRo3 defaults to unless you select another method, discount factors for outcomes and costs during each model cycle are based on the value of time at the beginning of every cycle.
- With the End method, discount factors for outcomes and costs during each model cycle are based on the value of time at the end of every cycle.
- With the Midpoint method, discount factors for outcomes and costs are based on the value of time at the midpoint of every cycle.
If you have a model that has very short cycles (eg, daily or weekly), nominal differences between the three methods of discounting are typically small. If you have a model with very long cycles (eg, annual), however, the three methods can produce noticeably different results. Notably, with the End method, the discount factors for outcomes and costs in the first model cycle will be a number less than one. If you select the Start method, the discount factors for outcomes and costs during the first model cycle will be equal to one.
If I want to apply one-time cost at the beginning of a model, how would I do that?
You can easily apply a one-time cost at the beginning of a model on the Values page. Because this cost is incurred only when patients enter your model, you would not discount it as you would costs that occur in future periods. To add this one-time cost to your model, after you have defined it on the Values page, use the dropdown menu labeled, ‘Type’, to select ‘Model Start’.
I am not sure how to use ‘User Override Values’ that I see on Results pages. What is this functionality all about?
The User Override Menu allows you to pin input parameters to the Results pages of a model. If you pin a parameter to the User Override Menu, you can change the value for this parameter ‘on the fly’ on any Results page of a model (ie, you don’t have to return to the Parameters page to make such changes). This functionality can be very useful when you would like to see how a particular parameter affects findings of a model in ‘real time’.
To pin a parameter to the User Override Menu:
- Click the ‘Manage Override Values’ button in the Configuration Sidebar on any Results screen. In the pop-up menu, check every variable that you would like to be pinned to the User Override Menu.
- Use the drag handles to place the selected variables in the order that you would like them to be displayed in the ‘User Override Menu’.
- If you would like to restrict the possible values that an input parameter can have―for example, a set of integers or a list of category names―in the ‘Options’ column for this parameter, set forth the values that this variable may take on as a comma-separated list.
- When done, click ‘OK’.
Another common use case for the User Override Menu would be when you want to share a model with others who will be allowed access to it with View-Only privileges. While users with View-Only privileges ordinarily can run a model but not change values for model parameters, they are able to change the values of model parameters that you pin to the User Override Menu.
If you would like to change the value of a variable in the User Override Menu, simply click on the input field next to it, enter the desired new value, and hit the ‘Enter’ key or click outside the input field. Base case results will be automatically recalculated when you do this. (Note: sensitivity analyses must be rerun manually, however; this ensures that a model does not automatically recalculate multiple times when you might be planning to change the values of several parameters in the User Override Menu.)
I want to apply a hazard ratio to a survival distribution defined on the Survival Distributions page of a model. Is there an easy way to do this?
Yes―if you want to apply a hazard ratio to a survival distribution that has already been defined on the Survival Distributions page of a model, there is a hēRo3 function, apply_hr(…), that allows you to do so easily.
For example, if you used an exponential curve to depict progression-free survival (PFS) in patients who are receiving standard of care (SOC), you might have a survival distribution defined on your Survival Distributions page called ‘SOC_PFS_exp’, with a formula that looks something like this:
Now, imagine that a new therapy was expected to extend PFS by 15% compared with SOC. If you created a variable, ‘NEW_pfs_hr’, and set its value to 0.85, you can specify the PFS distribution for the new treatment using the apply_hr(…) function in a formula as follows:
I have a series of annual probabilities that I want to convert into monthly probabilities. Is there an easy way to do this in hēRo3?
Yes―there is a hēRo3 function, rescale_prob(…), that allows you to easily convert probabilities from one measure of time to another.
For example, if you have an annual probability ('event_prob’) that you would like to convert to a monthly probability, you can do so with the following formula: