Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Initializing Disease Compartments"

(Infector)
(External Data Source Disease Initializer)
 
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:
When a certain disease model should be used in scenario, the initial conditions for the isease have to be specified. The following components in STEM enable the user to do so.
+
For a certain disease model to be used in a scenario, the initial conditions for the disease have to be specified. Several components in STEM enable the user to do so. The Disease Initializer component provides the combined functionality of the Infector and Inoculator components. For initialization from an external file, the External Data Source Disease Initializer must be used.
  
= Infector =
+
== Infector ==
 +
[[Image:InnoculatorWiz.png|right]]
 +
Infectors are a simple and intuitive tool that can be used to set ''initial conditions'' when you want to start a simulation with a specific number or percentage of people in the ''infectious state''.  Please see '''[http://wiki.eclipse.org/Creating_a_STEM_Scenario#Create_an_Infector Creating a STEM Scenario]''' to see a step-by-step example of how infectors can be used.  The infector, at simulation start, takes the specified number from the Susceptible state and moves them to the infectious state. You can configure an inoculator to set the initial condition for a specific regions, at node containing sub-regions (e.g., a state or country) or your entire graph.  The wizard for creating an infector is shown to the right. Infectors also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere). Disease initializers (see below) provide an even more powerful way to specify the initial state for every compartment in one step.
  
In '''[http://http://wiki.eclipse.org/Creating_a_STEM_Scenario#Create_an_Infector Creating a STEM Scenario]''' it is shown how infectors are used.
+
== Inoculator ==
  
= Innoculator =
+
Inoculators are very similar to infectors. They are used to set the initial condition or initial state of a population when you want to set the herd immunity at simulation start. They work by moving a specified number or percentage of people from Susceptible to Recovered. Like infectors, an inoculator can be configured to set the initial condition for a specific regions, at node containing sub-regions (e.g., a state or country) or your entire graph. The wizard for creating an inoculator is the same as the wizard for creating an infector (shown to the right).
  
= Initializer =
+
Inoculators also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere). Inoculators also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere).
  
To create an initializer for a specific disease the user has to right click on the disease and select "Create new Initializer".
+
== Disease Initializer ==
 +
 
 +
Disease Initializers are a much more flexible and powerful way to set initial conditions. You can specify and set or target compartments to initialize so a Disease Initializer can play the role of Infector, Inoculator, and more. For example, you can set the initial number of Exposed people in an SEIR model. To create an initializer for a specific disease, you need to right click on the disease and select "Create new Initializer".
  
 
[[Image:StemCreateInitializer.png|500px]]
 
[[Image:StemCreateInitializer.png|500px]]
  
Since initializers also work for diseases with multiple populations the population to initialize has to be selected. For the selected population the absolute number or percentage of individuals for all compartments can be specified. At last the user has to select a location for the initializer. If for example France is selected, any region in France is initialized with the chosen values. The new initializer will show up under the "Decorators" folder in the Project explorer. You can drag the population initializer right into a scenario.
+
Since initializers can work for diseases with multiple populations, you need to select the population to initialize. For the selected population the absolute number or percentage of individuals for all compartments can be specified. At you need to select a location for the initializer. If for example France is selected, any region in France is initialized with the chosen values. The new initializer will show up under the "Decorators" folder in the Project explorer. You can drag the initializer right into a scenario.
  
 
[[Image:StemInitializer.png|450px]]
 
[[Image:StemInitializer.png|450px]]
 +
 +
 +
 +
 +
== External Data Source Disease Initializer ==
 +
 +
If you have many locations where the values for the disease state initialization need to be different, using a separate infector for each location is not always the most effective method. Using an External Data Source Disease Initializer produces one decorator which can assign specific values to each node in your graph. 
 +
 +
NOTE: If you want to assign values from csv files logged in a previous run of a scenario, then skip steps 4 and 5. If you want to assign your own unique values then follow all steps.
 +
 +
(1) Create a logger, which logs the compartments that you wish to initialize. For example, if you have an SIR model then this might be the S, I and R compartments. For more information on how to create a logger go to https://wiki.eclipse.org/STEM_Loggers
 +
 +
(2) Add this logger to your scenario and then run it for a number of cycles. Check that the logger recorded everything correctly by navigating to the "Recorded Simulations" folder in your project. Each time you run the scenario, a folder within the "Recorded Simulations" folder titled with the scenario name and run number is created. 
 +
 +
(3) Select the folder with the scenario name and run number that you want, then click on the folder with your disease name and then the folder with the population that you want to set initial values for. There should be a csv file for each compartment of your model that you set to be logged.
 +
 +
(4) If you want to initialize with your own unique values then open up these files for editing. You can delete rows which are not relevant e.g if you just want to set the initial state, then delete all rows other than the column headings (first row) and iteration 0 (second row). The column headings row will have a URL for each node in your graph. Changing anything in this row usually creates problems so leave this the same. Insert any values that you need to in other rows e.g in the file for “I” (infected), you can add the number of individuals infected at iteration 0 for each node.
 +
 +
(5) Save the file, overwriting the original. If you want to keep the data from the original file, then save it under a different name and move it to a different folder. It is important that the files you edit have exactly the same names as those generated by the logger and that the folder only contains the files that you need.
 +
 +
Now, either using your edited file, or an original…
 +
 +
(6) Open the "Decorators" folder in your project, right-click on your disease and select “Create new External Data Initializer”.
 +
 +
[[Image:StemCreateDataInitializer.png|350px]]
 +
 +
(7) Give it a name, select the population, and set the Row Number that you want it to read.
 +
 +
(8) Click “Select Directory…” and navigate to the folder that contains your logged disease state files (originals or edits). This usually involves going into your STEM folder, selecting …/workspace/your_project_name/Recorded simulations/Disease_name/Population
 +
 +
[[Image:StemDataInitializer.png|450px]]
 +
 +
The last folder you should select will have the name of the population.
 +
 +
(9) Click finish. The resulting Disease Initializer can be found in the "Decorators" folder. Add this to your scenario. 
 +
 +
(10) Run your scenario

Latest revision as of 13:23, 12 June 2019

For a certain disease model to be used in a scenario, the initial conditions for the disease have to be specified. Several components in STEM enable the user to do so. The Disease Initializer component provides the combined functionality of the Infector and Inoculator components. For initialization from an external file, the External Data Source Disease Initializer must be used.

Infector

InnoculatorWiz.png

Infectors are a simple and intuitive tool that can be used to set initial conditions when you want to start a simulation with a specific number or percentage of people in the infectious state. Please see Creating a STEM Scenario to see a step-by-step example of how infectors can be used. The infector, at simulation start, takes the specified number from the Susceptible state and moves them to the infectious state. You can configure an inoculator to set the initial condition for a specific regions, at node containing sub-regions (e.g., a state or country) or your entire graph. The wizard for creating an infector is shown to the right. Infectors also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere). Disease initializers (see below) provide an even more powerful way to specify the initial state for every compartment in one step.

Inoculator

Inoculators are very similar to infectors. They are used to set the initial condition or initial state of a population when you want to set the herd immunity at simulation start. They work by moving a specified number or percentage of people from Susceptible to Recovered. Like infectors, an inoculator can be configured to set the initial condition for a specific regions, at node containing sub-regions (e.g., a state or country) or your entire graph. The wizard for creating an inoculator is the same as the wizard for creating an infector (shown to the right).

Inoculators also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere). Inoculators also allow you to initialize the disease state from an external file (or a previous set of run files). This is useful when you want to specify specific values for many individual locations (as opposed to the same percentage everywhere).

Disease Initializer

Disease Initializers are a much more flexible and powerful way to set initial conditions. You can specify and set or target compartments to initialize so a Disease Initializer can play the role of Infector, Inoculator, and more. For example, you can set the initial number of Exposed people in an SEIR model. To create an initializer for a specific disease, you need to right click on the disease and select "Create new Initializer".

StemCreateInitializer.png

Since initializers can work for diseases with multiple populations, you need to select the population to initialize. For the selected population the absolute number or percentage of individuals for all compartments can be specified. At you need to select a location for the initializer. If for example France is selected, any region in France is initialized with the chosen values. The new initializer will show up under the "Decorators" folder in the Project explorer. You can drag the initializer right into a scenario.

StemInitializer.png



External Data Source Disease Initializer

If you have many locations where the values for the disease state initialization need to be different, using a separate infector for each location is not always the most effective method. Using an External Data Source Disease Initializer produces one decorator which can assign specific values to each node in your graph.

NOTE: If you want to assign values from csv files logged in a previous run of a scenario, then skip steps 4 and 5. If you want to assign your own unique values then follow all steps.

(1) Create a logger, which logs the compartments that you wish to initialize. For example, if you have an SIR model then this might be the S, I and R compartments. For more information on how to create a logger go to https://wiki.eclipse.org/STEM_Loggers

(2) Add this logger to your scenario and then run it for a number of cycles. Check that the logger recorded everything correctly by navigating to the "Recorded Simulations" folder in your project. Each time you run the scenario, a folder within the "Recorded Simulations" folder titled with the scenario name and run number is created.

(3) Select the folder with the scenario name and run number that you want, then click on the folder with your disease name and then the folder with the population that you want to set initial values for. There should be a csv file for each compartment of your model that you set to be logged.

(4) If you want to initialize with your own unique values then open up these files for editing. You can delete rows which are not relevant e.g if you just want to set the initial state, then delete all rows other than the column headings (first row) and iteration 0 (second row). The column headings row will have a URL for each node in your graph. Changing anything in this row usually creates problems so leave this the same. Insert any values that you need to in other rows e.g in the file for “I” (infected), you can add the number of individuals infected at iteration 0 for each node.

(5) Save the file, overwriting the original. If you want to keep the data from the original file, then save it under a different name and move it to a different folder. It is important that the files you edit have exactly the same names as those generated by the logger and that the folder only contains the files that you need.

Now, either using your edited file, or an original…

(6) Open the "Decorators" folder in your project, right-click on your disease and select “Create new External Data Initializer”.

StemCreateDataInitializer.png

(7) Give it a name, select the population, and set the Row Number that you want it to read.

(8) Click “Select Directory…” and navigate to the folder that contains your logged disease state files (originals or edits). This usually involves going into your STEM folder, selecting …/workspace/your_project_name/Recorded simulations/Disease_name/Population

StemDataInitializer.png

The last folder you should select will have the name of the population.

(9) Click finish. The resulting Disease Initializer can be found in the "Decorators" folder. Add this to your scenario.

(10) Run your scenario

Back to the top