Model Interface & User Manual

Installation
In order to run this program, users must install the open-source programming language Python, version 2.7.3 (note that version 3.3.0 is not compatible with all functionality), available at: http://www.python.org/download/.  Additional packages must also be installed, including NumPy and SciPy (www.scipy.org/Download/), with detailed instructions on installation available at: www.scipy.org/Installing_SciPy.  For most users, the easiest way to install these packages will be to use a free pre-packaged suite, such as Enthought Canopy Express (https://www.enthought.com/downloads).  

Under Mac OS X or other Unix-like operating systems, Python is pre-installed.  The program can run by opening a terminal, changing to the directory where the script file is located (using the 'cd' command), and then entering 'python scriptname.py', where ‘python scriptname’ is the name under which the user downloads the file.  Under Mac OS X, Terminal.app can be found in the Utilities folder in Applications.  The program can then be modified with a text editor such as gedit (Linux) or TextWrangler (Mac).

Under Windows systems, upon downloading these packages and saving the program to an appropriate location, users should be able to right-click the program and select “Edit with IDLE.”  This will enable users to both run the program (by selecting “F5” or “Run -> Run Module” from the drop-down menu) and edit it for personalized use. The program can also be run simply by double-clicking the corresponding icon.



Running the Program
Upon running the program, an interactive window opens (screen shot shown in Supplementary Figure 2A).  Users are asked to input the intervention of interest (including an option for all interventions), and then to provide the 4 key variables for calculation of the equilibrium population: TB incidence, MDR-TB prevalence among new cases, HIV prevalence among adults, and the cost of first-line TB treatment (from which other TB treatment costs are derived).  The program then generates the equilibrium population and launches the selected intervention, providing output (Supplementary Figure 2B) on TB incidence, prevalence, and mortality according to HIV and MDR status.



Editing Input Parameters
End users have flexibility to alter any parameter value (from Table 1) desired.  This is done by opening the program and finding the section (near line 110) that is labeled, “The following parameters can all be modified according to user preferences:”.  Over the subsequent 60 lines, all parameters are displayed, as well as a description of each parameter.  To change the value of a parameter (with the exception of the four parameters that are fitted to user targets), simply delete the number currently listed and replace it with a new number (note that numbers need to have decimals attached).  Thus, for example, if a user wished to change the rate of seeking diagnosis from 5 attempts per year to 2 attempts per year, s/he would go to the line corresponding to the parameter “dx_rate” and replace “5.” with “2.”  The program must then be saved before running again.  Upon running the program after making this adjustment, the model would again calculate an equilibrium population with user-specified values, but would use a slower diagnostic rate to attain this equilibrium.  (Thus, in this case, the program would fit a lower transmission parameter β for a given TB incidence input, to compensate for the fact that individuals remain infectious for a longer period of time before successful diagnosis.)  Multiple parameters may be changed simultaneously. 



Creating Non-Equilibrium Scenarios: User Instructions
The program has flexibility, as above, to create non-equilibrium scenarios for both TB incidence and MDR-TB prevalence.  In its current version, the program generates equilibrium populations 50 years in the past, and allows for a parameter to be changed at that time to generate a non-equilibrium condition at the present time; the 50-year time frame is alterable by those with knowledge of python, but description of that alteration is beyond the scope of this brief manual.  The ability to create non-equilibrium populations is best illustrated for populations in which MDR-TB is increasing over time.  To generate such a population, users need only to change “target_mdr” in the line that reads “target_mdr2 = target_mdr” to the target MDR prevalence (in new cases) at the end of the 5-year study period.  Thus, to generate a population in which the MDR-TB prevalence was increasing from 4.0% to 6.0% over a 5-year analysis period, users would change this line to read, “target_mdr2 = 0.06”.  Then, when prompted for a target MDR-TB prevalence in the interface window, the user should input the value “0.04”.  This will result in a population that is initiated at equilibrium (year 0) at an MDR-TB prevalence of 4% among new cases, and that increases to 6% by the end of year 5.
