Using Epiflex: Basic tutorial and notes. 

General about files: 
When a model completes, 3 files result: .RPX, .LOG and .SNAP. Together they are used to show you results. They are all put into a "Results" subdirectory under the directory that the EPDM file was found. The EPDM file is the Epiflex epidemic model file. 

The .SNAP file is a viable model. However, it will not allow you to save over it, so you have to rename it. The ,SNAP is there so that you can go back and see what all the parameters were for a run. I suggest, that if you decide to use a .SNAP as the basis for a new run, rather than the original EPDM file to put it into a different directory than the Results subdirectory. That will prevent confusion with completed models. I also suggest that you edit the name of the model when you save it for a new EPDM. This is because when a model runs, the files all have the name of the configuration and the Greenwich Mean Time date and time appended to the end. File names can get very long and hard to understand if you don't eliminate that suffix from .SNAP files. 

RPX files have data results. This is in a simple comma delimited text format explained in the header of the file. 
LOG files show you everything that happened during the model run. 

Whenever you open a .SNAP file, a LOG file is created in a Results subdirectory below it. 

Basic tutorial: 

1. After unzipping the attached files onto your computer, start Epiflex one of two ways: 
    A. Start by clicking on "Epiflex.exe" in the Epiflex directory. 

2. In the File menu, open one of the *.epdm files that are in the Epiflex\Data\Epiflex-manuscript-runs directory. I suggest first choosing "TestModel 35000 - USADemographics-Influenza-Best2.epdm", since it is not a large model to run, to get a feel for things. 

3. Click on the Run Model menu. Start by opening the Area Definitions. Click on a city in the list box on the right, and see what the population setting is. 
	As a general note: on all panels, when you make a change in a text field, you have to hit the apply button, (or set button) in order for the change to take effect. If you change something and it "doesn't take" this is why. 
                Also, you have access to all panels while models are running. It is strongly recommended not to try modifying anything in the Edit Model menu while a model is live. It shouldn't change what is in the model, and I have done testing, but at the end when the model snapshot is taken, the snapshot will not agree with the run of the model. Access to all panels is there so that if you are running something and want to remember what something was set at, you can go in and see. 

4. Go ahead and look at the Disease panel and each of the others. The appendix to the paper has discussion of each panel in turn. Go ahead and create a new disease and set up its parameters if you like. H5N1 is not a bad idea. 

5. Click on the Run Model menu. Choose Configuration (the only allowed choice now.) Click on Influenza in the list box. You will see a full configuration for the run come up. This configuration has a city called "Milwaukee WI". You can examine the tree control to see what vector is active and what areas and locations within the area are active. If you like, you can add a response to the  epidemic, but before doing that take a look at the Responses panel to get an understanding of what it is. 

6. The Run parameters show number of cycles, days per cycle and some minor display items. The model will run a little faster if it does not display. Note that if you set the display interval to greater than 1, you will see a compressed graph that does not fill the space allocated to it on the panel. What that means is that afterward, when you replay it, you will need to change the configuration to the standard "1" display interval. 

Note that since number of cycles per day is a critical parameter for the system, do not change it without understanding what you are doing. The number of cycles per day interacts with the movement of people from location to location within the model. Their cycles of activity and visiting of locations is set up for a certain number of cycles in their day. If you change cycles per day, the model behaves differently. 

7. The big exception to changing a parameter at run time is "Number of Cycles for Run". You can modify this during run time, and if you then hit the Set button, the number of cycles for your currently active run will change. This is there so that if you see something interesting and decide you want to extend it, or if you have a long run that you decide you want to to shorten, you can do so. sometimes, with a large, long running model, which takes a long time, this is desirable. Note, however, that currently the display calculates width at the beginning. So if you extend a model run, you won't be able to see the end of it until you finish, close the file, and open it again from the .snap file.  

8. Note that in the Run Model menu are controls for pausing your model. If you pause your model, you can then do things like add or delete responses to an epidemic. You can also change a Vector definition in the Edit Model menu. What this allows you to do is perform on-the-fly what-if scenarios. This feature was made so that Epiflex could be used as part of an instructional game for public health training. When you pause, a green line is drawn vertically on your display. You cannot get rid of that later. It is there to inform you of exactly where changes were made during a run. 

9. There are two types of models. Files ending in .EPDM are regular models. Files ending in .SNAP are snapshots taken at the end of a run. Open the .SNAP file for a run in the "Results" subdirectory to replay something. 

10. All but one of the run snapshots used for the Epiflex paper are present. You can "Replay" them by opening the .SNAP files. The one that is not present is the 3.5 million person multi-city run. The reason is that in the process of importing the RPX file into Excel, I forgot to make a copy of the RPX before I modified city names cosmetically. (There were some typos and inconvenient spaces in city names. Yes, I know that I should know better.) Unfortunately, that broke the handshake between the RPX file and the SNAP file. I tried to remember exactly how I had modified them all but gave up trying to resynchronize them. However, the data is included in the supporting material directory as an Excel file. Please note that the .SNAP file, like the .EPDM file is in XML format and can be edited by hand. The resynch could be done, but I just haven't had the time to fiddle with it. 

System requirements: 
You want the fastest CPU you can find to run this software. All runs to date have been done on computers with at least 1 GB of RAM. More RAM is better, since this software consumes a lot of memory.  System paging will cause it to slow to a crawl, so usually this is the rate limiting factor. I am told that this will not run on an Apple computer in Windows emulation. If I had budget to do so, I would convert it be able to run on Linux and Apple. 

Known bugs and oddities: 
There was a toolbar before, but it has been disabled for this release version. You will have to use the View menu to bring up the little dialog to change display options. The reason for this is that on long runs, the toolbar resulted in crashes sometimes. Not worth it. 

There used to be a Replay menu item under File before. That has been removed, and all files are just opened in the normal way now. Nobody will get confused, and you can make full use of the recent files list. 

End notes: 
There is a feature for changing to a white background in the View/Display Options menu. This is used for taking screen shots for posters and such. 

The .RPX file has the data from your run. You can look at it in SAS, SPSS, R, or Excel by importing it. It is a simple, self explanatory format. 
If there is call for it, I may write a little piece to create an Excel file from the RPX. That would simplify the import process which can be a little onerous if you did something really big. 

 
With very large models with a million or so or more running a thousand cycles or more, Epiflex can run across Microsoft MFC "easter eggs" that will try to shut down the program. This is because of the number of times Epiflex executes certain basic operations like malloc to get memory, then give it back. Somebody in the MFC team at Microsoft decided that if you do that too many times they should make sure you know. It's a rather uncivilized way to do it. I think I got most of those, but if you run into one, you should be able to say "Ignore" and the program should run on. If not, please let me know and I will try to make your model work for you. In other words, if you get a message like that, don't panic and reboot. First try ignoring it.  

Email: brian.hanley@ieee.org 