Barnes D.J., Chu D. Introduction to Modeling for Biosciences
Подождите немного. Документ загружается.
3.4 Malaria Model in Repast Using Java 113
public interface ContextBuilder<T> {
/**
* Builds and returns a context.
* Building a context consists of filling it with agents,
* adding projects and so forth.
* The returned context does not necessarily have to be the
* context that was passed in as a parameter.
*
* @param context An existing context.
* @return The completed context.
*/
Context build(Context<T> context);
}
Code 3.2 The ContextBuilder interface
import repast.simphony.context.Context;
import repast.simphony.dataLoader.ContextBuilder;
public class MalariaBuilder
implements ContextBuilder<InfectableAgent> {
/**
* Build and return the MalariaModel context.
* Create a continuous space projection, and add humans and
* mosquitoes to it.
*
* @param context The MalariaWorld context.
* @return The completed context.
*/
public Context<InfectableAgent> build(
Context<InfectableAgent> context) {
// Create the projection and agents here ...
...
return context;
}
}
Code 3.3 Implementing ContextBuilder
is not ruled out by using a context builder anyway, although we will not discuss this
in any more detail here. The interested reader is referred to the documentation that
is part of the Repast S distribution.
3.4.5 Accessing Runtime Parameter Values
In Sect. 3.4.2 we described the way in which attributes could be named in the score
file to support runtime parameterization of the model. Some or all of these values
114 3 ABMs Using Repast and Java
are typically accessed when the model is being built, for instance to decide on the
dimensions of a projection.
We have to obtain a Parameters object from the current RunEnvironment
object. The Parameters object stores all of the (label, value) attribute pairs
defined in the score file. A parameter value is then obtained via its label name.
The value is returned as an Object which must be cast to the correct Java type
(Integer, Double, etc.). Here is how we would access the integer size attribute
for the projection, and the floating-point stopTime attribute, which we then use
to set the finishing time for a run:
// Obtain the runtime environment.
RunEnvironment environment = RunEnvironment.getInstance();
// Obtain access to all the attribute/parameters.
Parameters parameters = environment.getParameters();
...
int worldSize = (Integer) parameters.getValue("size");
// Set the stop time.
double stopTime = (Double) parameters.getValue("stopTime");
environment.endAt(stopTime);
This is done in the build method of the context builder class.
3.4.6 Creating a Projection
There are two stages involved in creating a projection
10
:
• Create a factory object for the type of projection required via a factory finder.
• Have the factory object create the projection object.
Here are these two stages within the context builder’s build method:
// Create a factory.
ContinuousSpaceFactory factory =
ContinuousSpaceFactoryFinder.createContinuousSpaceFactory(
null);
// Create a space, with random adder and wraparound borders.
ContinuousSpace<InfectableAgent> world =
factory.createContinuousSpace(
"World",
context,
new RandomCartesianAdder<InfectableAgent>(),
new WrapAroundBorders(),
worldSize, worldSize);
When the projection is created, it is given a name, the context it applies to,
an adder,atranslator and its dimensions. An adder applies particular rules to
10
The approach is slightly different in the case of a Network projection as a NetworkBuilder is
used instead. The full Repast S documentation provides the detail.
3.4 Malaria Model in Repast Using Java 115
where a new agent will be placed within a projection. The continuous space, GIS
and grid projection types all have distinctive Adder classes that take into ac-
count the location properties of the different projection types. We have chosen to
place mosquitoes and humans randomly throughout the available space (Random-
CartesianAdder). Once placed, agents are moved via methods belonging to the
projection and we will see an example of this later on in our model.
Given that agents can move around within a projection, some rules must be put
in place to determine what happens at the borders of a projection. The options are:
strict, sticky, infinite, bouncy and wrap around. The exact effect depends upon a
combination of the translator type and whether the move is a displacement or an
absolute move. In some cases, a runtime exception will result if an agent tries to
move beyond the borders. We have chosen to specify that the borders wrap around
(WrapAroundBorders), as this includes a sense of agents leaving and entering
the world.
With the projection set up, we are now in a position to add the mosquito and hu-
man agents to the context. Each will have a 50% probability of being in the infected
state at the start of the simulation, although the probability could easily have been
parameterized via model attributes. We can make use of the RandomHelper class
from the Repast API for random number generation. By default this offers random
numbers in the unit interval drawn from a uniform distribution. It is also possible to
customize it to provide random numbers from all of the most common distributions.
// Create the humans in a random state of infection.
for(int i = 0; i < numHumans; i++) {
context.add(
new Human(RandomHelper.nextDouble() < 0.5, world));
}
// Create the mosquitoes in a random state of infection.
for(int i = 0; i < numMosquitoes; i++) {
context.add(
new Mosquito(RandomHelper.nextDouble() < 0.5, world));
}
3.4.7 Implementing the Common Elements of the Agents
In Sect. 3.4.3 we noted that the common aspects of state and behavior could be cap-
tured in an InfectableAgent class. For ease of reading we have split the class
into those elements concerned with the initialization (Code 3.4) and those manag-
ing the infection status of both humans and mosquitoes (Code 3.5). Note in the
infect method in Code 3.5 that we have implemented infection in such a way
that re-infection restarts the incubation clock. The main element worth considering
in some detail is the management of an agent’s infection period. When an infectable
agent is created it may already be infected. Rather than having every new agent at the
same stage of infection, we wish to have each at a random point within its full range,
116 3 ABMs Using Repast and Java
/**
* The common elements of humans and mosquitoes.
*/
public abstract class InfectableAgent {
// Whether this agent is currently infected.
private boolean infected;
// How long the agent has been infected for.
private double infectionStage;
// The agent’s projection.
private ContinuousSpace<InfectableAgent> worldProjection;
/**
* Create an infectable agent.
* @param infected Whether the agent starts infected.
* @param worldProjection The agent’s projection.
*/
public InfectableAgent(boolean infected,
ContinuousSpace<InfectableAgent> worldProjection) {
this.worldProjection = worldProjection;
// If the agent is initially infected
// set a random infection stage.
if(infected) {
infect();
// Avoid all agents being at the same
// stage of incubation when created.
infectionStage =
RandomHelper.nextDoubleFromTo(
0, getInfectionPeriod() - 1);
}
else {
setHealthy();
}
}
...
}
Code 3.4 Variables and initialization in the InfectableAgent class, which is abstract
otherwise distortions of infection patterns are likely to result. Hence we generate a
random value to set the infectionStep field in the constructor. The complica-
tion is that mosquitoes and humans have different infection periods and we want to
avoid the code in InfectableAgent having to be aware of the different values
and all the different agent types.
11
This is easily achieved by insisting that each agent
subclass of InfectableAgent provide its own method that returns the length of
its particular infection period. This is the purpose of the getInfectionPeriod
method, which is marked as abstract in InfectableAgent. For instance, the
11
If further infectable agents were to be added at some point it would be easy to forget to add
knowledge of their distinctive infection periods into InfectableAgent, for instance.
3.4 Malaria Model in Repast Using Java 117
/**
* The common elements of humans and mosquitoes.
*/
public abstract class InfectableAgent {
// Variables and constructor omitted ...
...
/**
* Is the agent currently infected?
* @return true if infected, false otherwise.
*/
public boolean isInfected() {
return infected;
}
/**
* Infect this agent.
*/
protected void infect() {
if(!infected) {
infected = true;
}
// Reset the infection stage.
infectionStage = 0;
}
/**
* The agent is not infected.
*/
protected void setHealthy() {
if(infected) {
infected = false;
infectionStage = 0;
}
}
/**
* Get the current stage of infection.
* @return The current stage of the infection.
*/
public double getInfectionStage() {
return infectionStage;
}
/**
* Increase the infection stage by one.
* This might lead to the end of the infection.
*/
public void updateInfectionStage() {
if(infected) {
infectionStage++;
if(infectionStage > getInfectionPeriod()) {
setHealthy();
}
}
}
/**
* Get the infection period for a type of agent.
* @return The infection period for a type of agent.
*/
protected abstract double getInfectionPeriod();
}
Code 3.5 Infection management in the InfectableAgent class
118 3 ABMs Using Repast and Java
implementation of this method in the Human class returns the value that is obtained
from the humanInfectedPeriod attribute by the context builder.
We can use exactly the same technique to manage the movement of agents, given
that humans and mosquitoes have different movement ranges. We define an abstract
getMaximumMovement method in InfectableAgent and use it when gen-
erating a random distance to be moved. The projection class defines a method that
allows an agent to make a displacement move (moveByDisplacement):
/**
* Move within the full range of movement.
*/
public void movementStep()
{
// Decide on a random displacement.
double distance =
RandomHelper.nextDoubleFromTo(0,
getMaximumMovement());
double theta = RandomHelper.nextDoubleFromTo(0, 2*Math.PI);
worldProjection.moveByDisplacement(
this,
distance * Math.cos(theta),
distance * Math.sin(theta));
}
It turns out that there is very little additional code required in the Human class
to complete what it inherits from InfectableAgent,buttheMosquito class
adds the distinctive aspect of transmitting the infection, so we look at that in the
next section.
3.4.8 Completing the Mosquito Agent
At each step of the simulation, each mosquito is considered to bite all of the humans
within its infection range. We clearly need to obtain a list of a mosquito’s neighbors.
In Sect. 3.3.2.5 we saw how a Moore query could be applied within a grid projec-
tion to find neighbors, and a similar technique can be used with a continuous space
projection:
// Create a query object that will return objects
// within the given radius.
ContinuousWithin<T> queryTool =
new ContinuousWithin<T>(projection, agent, radius);
ContinuousWithin is one of a large number of implementations of the Query
interface. Its query method will return an Iterable of all the neighbors within
the given radius, both humans and mosquitoes. For the mosquito’s infection step, the
neighbors must be iterated over to identify the humans, at which point any infection
is transferred in either direction between the two agents. Code 3.6 shows the code
for the mosquito’s infection step. For the sake of efficiency, we actually set up the
Query object in the mosquito’s constructor, and simply call its query method at
3.4 Malaria Model in Repast Using Java 119
/**
* Look for human neighbors and infect any that are close enough.
* Also, become infected from any infected human neighbors.
* NB: Infection takes effect immediately.
*/
public void infectionStep()
{
// Obtain the current list of neighbors.
Iterable<InfectableAgent> neighbors = queryTool.query();
for(InfectableAgent neighbor : neighbors) {
if(neighbor instanceof Human) {
if(isInfected()) {
if(neighbor.isInfected()) {
infect(); // Re-infect the mosquito.
}
neighbor.infect(); // Infect the human.
}
else if(neighbor.isInfected()) {
infect(); // Become infected by the human.
}
}
}
}
Code 3.6 The mosquito’s infection step
each infection step to identify the mosquito’s changing neighborhood, as both it and
other agents move around. Note that care needs to be taken over the order in which
mutual infection between human and mosquito is managed because we have imple-
mented re-infection to restart the infection clock on an agent: The mosquito should
only infect a human if the mosquito was infected prior to biting the human, other-
wise the human would be artificially re-infected following a bite from an uninfected
mosquito.
3.4.9 Scheduling the Actions
There are three repeated actions that govern the outcome of the model:
• Humans and mosquitoes might lose their infection (updateInfection-
Stage).
• Humans and mosquitoes move (movementStep).
• Mosquitoes bite humans (infectionStep).
If we want all movements to take place before infections, say, then we could sched-
ule the actions to take place at different fractional points between integer time steps.
A better approach is to decide on a priority for each type of action and specify that
earlier actions have a higher priority than later ones. That way, all actions of a par-
ticular type will take place together rather than mixed up randomly with other types
of action, yet actions of every type will take place at the same time step.
120 3 ABMs Using Repast and Java
The @ScheduledMethod annotation is placed prior to each method with the
element priority and a floating-point value for the priority. The higher the
value, the higher the priority. So, if we wish health status to be updated before
movement, and movement to take place before infection, we might use the values
3, 2 and 1, respectively. There are also names such as FIRST_PRIORITY and
LAST_PRIORITY defined in the ScheduleParameters class that can be used
with negative and positive offsets for a more transparency. So we might annotate
updateInfectionStage thus:
@ScheduledMethod(start = 1, interval = 1,
priority = ScheduleParameters.FIRST_PRIORITY)
3.4.10 Visualizing the Model
We are now in a position to think about running the model and visualizing the in-
teractions between the agents. Because we did not specify a model initializer in
the model.score file, it is necessary to define a Data Loader in the Scenario
Tree, to indicate that our MalariaBuilder class fulfills the role of an initializer.
Right-clicking over Data Loader and selecting Set Data Loader brings up a list of
alternative sources for the initialization. For instance, we might have set up agent
details in a delimited file to be loaded, or a specification in an XML file. We select,
A Specific Java Class, and are then offered the MalariaBuilder class.
12
We want to visualize the two types of agents distinctly, and we also want to
distinguish between those agents that are healthy and those that are infected. This
really requires that we define either two separate or a single joint style class, in
the same manner as we did for the Game of Life in Sect. 3.3.6. We will choose
to define a single class for both, called AgentStyle2D, and return four differ-
ent colors depending on agent type and health (Code 3.7). This is added to the
project as a standard Java class—a subclass of DefaultStyle2D.Amoreso-
phisticated approach might vary the color depending on the stage of the infection,
for instance.
A display is set up in the Scenario Tree in the usual way via the Displays option,
selecting a 2D display for the World projection, and the AgentStyle2D class for
the agents’ style. When the model is run, circles of the four chosen colors randomly
distributed about the world should appear on the screen—it is probably a good idea
to reduce the number of agents initially, in order to get a better idea of what is
happening. If the display is changing too quickly, then the update rate can be varied
via the Run Options panel and the Schedule Tick Delay slider. With a low number
of agents, it is quite likely that the infection will die out within the simulation time
range.
12
Remember to save the Scenario Tree after doing this, otherwise this setting will be lost.
3.4 Malaria Model in Repast Using Java 121
/**
* Return a color depending on the type of agent and
* its health state.
* @param o The object to be painted.
* @return A color for the agent.
*/
public Paint getPaint(Object o)
{
if(o instanceof Human) {
InfectableAgent agent = (InfectableAgent) o;
if(agent.isInfected()) {
return Color.ORANGE;
}
else {
return Color.MAGENTA;
}
}
else if(o instanceof Mosquito) {
InfectableAgent agent = (InfectableAgent) o;
if(agent.isInfected()) {
return Color.CYAN;
}
else {
return Color.BLUE;
}
}
else {
return null;
}
}
Code 3.7 Selecting a color for the agents
3.4.11 Charts
With a large number of agents, a visualization of every agent is both very slow and
not a particularly good way to obtain an appreciation of what is happening in gen-
eral within the model—consider whether it is easy it is to tell if the infection levels
are growing or diminishing, for instance. What we really need is a summary of the
state of the different agents. This is where the Charts feature of Repast can help
us. We will abandon the display, therefore, and create a chart of the infected num-
bers of each type of agent. To support this, we add the method shown in Code 3.8
to InfectableAgent so that it will be easy to work out how many agents are in-
fected.
Firstly, it is necessary to gather a data set, that can then be plotted on a chart
and output to file, if required. In the Scenario Tree select Data Sets, right-click
and select Add Data Set. A panel will be shown offering the chance to name the
data set and give it an ID. We will use Mosquito Infection Level for both. A data
set is created from information gathered from agents, so the drop down list named
Agent Class will only offer classes that have been listed as agents in model.score.
122 3 ABMs Using Repast and Java
public int getHealth()
{
return infected ?1:0;
}
Code 3.8 Return a countable indication of an agent’s health
We select Mosquito. We will see in Sect. 3.4.13 how the need to collect data from
a model sometimes leads to us adding ‘artificial’ agents to the score file for this
purpose.
The next panel invites us to create the data mappings in this data set. The Add
button is slightly confusing in that it provides two different operations depending on
whether the small triangle is clicked or not.
• If it is not clicked then a mapping to record the simulation tick is added as a
mapping, although this can then be edited to give the effect of a simple mapping—
see immediately below.
• If it is clicked then a set of three options is offered:
– Add Simple Mapping: For when it is wished to record the value of a property
for each individual agent, such as its infection stage.
– Add Aggregate Mapping: For when it is wished to record a single value for all
agents of this particular class, such as the number of infected mosquitoes.
– Add Using Wizard: For when a more complex function is to be used than can
be obtained from a simple accessor call, or an aggregation operation. These
can be applied at both the individual and aggregate level.
In gathering details about infection levels, we are not interested in the infection
status of individual mosquitoes but the population as a whole. Therefore, in addition
to adding the tick mapping to the data set we add an aggregate mapping. A dialog
invites selection of the per-agent method to be called when data gathering, and the
aggregation function. We select the getHealth method, shown in Code 3.8, and
sum. The function will sum all the 1 and 0 values returned from getHealth to tell
us how many mosquitoes are infected. Once added, we edit the Column Name field
to be Number Infected.
The next panel allows us to configure when and how often this data set will be
gathered. We can also specify whether it should be collected just once or repeatedly,
and a priority for the gathering. The default values are fine for our purposes at this
stage, although over very long runs we might consider collecting only periodically
with likely little loss in validity. Data sets can be edited from the scenario tree, with
mappings removed, adjusted by clicking in the columns, or further mappings added.
Once the mosquito data set has been added, we add a similar one for humans and
save the scenario tree.
Once the data sets have been established, the charts can be designed via the
Charts element of the scenario tree. Right-clicking offers Add Chart which leads
to a selection of the chart type: static or dynamic histogram, line, bar chart or scat-
ter plot. The most appropriate type will clearly depend both on what data is being