| Title: | A Framework for Designing and Running Agent Based Models |
|---|---|
| Description: | This is a package for creating and running Agent Based Models (ABM). It provides a set of base classes with core functionality to allow bootstrapped models. For more intensive modeling, the supplied classes can be extended to fit researcher needs. |
| Authors: | Thomas Thelen [aut, cre], Gerardo Aldana [aut], Marcus Thomson [aut], Toni Gonzalez [aut] |
| Maintainer: | Thomas Thelen <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.0.0 |
| Built: | 2024-11-04 04:52:05 UTC |
| Source: | https://github.com/zizroc/villager |
This is an object that represents a villager (agent).
This class acts as an abstraction for handling villager-level logic. It can take a number of functions that run at each timestep. It also has an associated
as_table()Represents the current state of the agent as a tibble
get_age()Returns age in terms of years
get_gender()get_days_sincelast_birth()Get the number of days since the agent last gave birth
initialize()Create a new agent
propagate()Runs every day
Create a new agent
identifierA unique identifier that can be used to identify and find the agent
first_nameThe agent's first name
last_nameThe agent's last name
ageThe agent's age
mother_idThe identifier of the agent's mother
father_idThe identifier of the agent's father
professionThe agent's profession
partnerThe identifier of the agent's partner
genderThe agent's gender
aliveA boolean flag that represents whether the villager is alive or dead
childrenA list of children identifiers
healthA percentage value of the agent's current health
new()
Used to created new agent objects.
agent$new( identifier = NA, first_name = NA, last_name = NA, age = 0, mother_id = NA, father_id = NA, partner = NA, children = vector(mode = "character"), gender = NA, profession = NA, alive = TRUE, health = 100 )
identifierThe agent's identifier
first_nameThe agent's first name
last_nameThe agent's last name
ageThe age of the agent
mother_idThe identifier of the agent's mother
father_idThe identifier of the agent' father
partnerThe identifier of the agent's partner
childrenAn ordered list of of the children from this agent
genderThe gender of the agent
professionThe agent's profession
aliveBoolean whether the agent is alive or not
healthA percentage value of the agent's current health
A new agent object A function that returns true or false whether the villager dies This is run each day
is_alive()
agent$is_alive()
A boolean whether the agent is alive (true for yes) Gets the number of days from the last birth. This is also the age of the most recently born agent
get_days_since_last_birth()
agent$get_days_since_last_birth()
The number of days since last birth Connects a child to the agent. This method ensures that the 'children' vector is ordered.
add_child()
agent$add_child(child)
childThe agent object representing the child
None Returns a data.frame representation of the agent
as_table()
I hope there's a more scalable way to do this in R; Adding every new attribute to this function isn't practical
agent$as_table()
The village_state holds a copy of all of the villagers at each timestep; this method is used to turn the agent properties into the object inserted in the village_state.
A data.frame representation of the agent
clone()
The objects of this class are cloneable with this method.
agent$clone(deep = FALSE)
deepWhether to make a deep clone.
A class that abstracts the management of aggregations of agent classes. Each village should have an instance of a agent_manager to interface the agents inside.
add_agent()Adds a single agent to the manager.
get_average_age()Returns the average age, in years, of all the agents.
get_living_agents()Gets a list of all the agents that are currently alive.
get_states()Returns a data.frame consisting of all of the managed agents.
get_agent()Retrieves a particular agent from the manager.
get_agent_index()Retrieves the index of a agent.
initialize()Creates a new manager instance.
load()Loads a csv file defining a population of agents and places them in the manager.
remove_agent()Removes a agent from the manager
Creates a new agent manager instance.
agentsA list of agents objects that the agent manager manages.
agent_classA class describing agents. This is usually the default villager supplied 'agent' class
new()
agent_manager$new(agent_class = villager::agent)
agent_classThe class that's being used to represent agents being managed Given the identifier of a agent, sort through all of the managed agents and return it if it exists.
get_agent()
Return the R6 instance of a agent with identifier 'agent_identifier'.
agent_manager$get_agent(agent_identifier)
agent_identifierThe identifier of the requested agent.
An R6 agent object Returns a list of all the agents that are currently alive.
get_living_agents()
agent_manager$get_living_agents()
A list of living agents Adds a agent to the manager.
add_agent()
agent_manager$add_agent(...)
...One or more agents
None Removes a agent from the manager
remove_agent()
agent_manager$remove_agent(agent_identifier)
agent_identifierThe identifier of the agent being removed
None Returns a data.frame of agents
get_states()
agent_manager$get_states()
Each row of the data.frame represents a agent object
A single data.frame of all agents Returns the index of a agent in the internal agent list
get_agent_index()
agent_manager$get_agent_index(agent_identifier)
agent_identifierThe identifier of the agent being located
The index in the list, or R's default return value Connects two agents together as mates
connect_agents()
agent_manager$connect_agents(agent_a, agent_b)
agent_aA agent that will be connected to agent_b
agent_bA agent that will be connected to agent_a Returns the total number of agents that are alive
get_living_population()
agent_manager$get_living_population()
The number of living agents Returns the average age, in years, of all of the agents
get_average_age()
agent_manager$get_average_age()
This is an example of the kind of logic that the manager might handle. In this case, the manager is performing calculations about its aggregation (agents). Note that the 364 days needs to work better
The average age in years Takes all of the agents in the manager and reconstructs the children
add_children()
agent_manager$add_children()
This is typically called when loading agents from disk for the first time. When children are created during the simulation, the family connections are made through the agent class and added to the manager via add_agent.
None Loads agents from disk.
load()
agent_manager$load(file_name)
file_nameThe location of the file holding the agents.
Populates the agent manager with a set of agents defined in a csv file.
None
clone()
The objects of this class are cloneable with this method.
agent_manager$clone(deep = FALSE)
deepWhether to make a deep clone.
A class responsible for the simulation data to disk.
This class can be subclasses to provide advanced data writing to other data sources. This should also be subclassed if the agent and resource classes are subclasses, to write any additional fields to the data source.
write()Writes the agent and resources to disk.
Create a new data writer.
results_directoryThe folder where the simulation results are written to
agent_filenameThe location where the agents are written to
resource_filenameThe location where the resources are written to
new()
Creates a new data writer object that has optional paths for data files.
data_writer$new( results_directory = "results", agent_filename = "agents.csv", resource_filename = "resources.csv" )
results_directoryThe directory where the results file is written to
agent_filenameThe name of the file for the agent data
resource_filenameThe name of the file for the resource data
A new agent object Writes a village's state to disk.
write()
Takes a state an the name of a village and writes the agents and resources to disk
data_writer$write(state, village_name)
stateThe village's village_state that's being written
village_nameThe name of the village. This is used to create the data directory
None
clone()
The objects of this class are cloneable with this method.
data_writer$clone(deep = FALSE)
deepWhether to make a deep clone.
R6 Class representing data that's external from resources and agents
It contains a single variable, 'events' for when the data holds a list of events
eventsAny events that need to be tracked
new()
Creates a new model_data object
model_data$new()
A new model data object
clone()
The objects of this class are cloneable with this method.
model_data$clone(deep = FALSE)
deepWhether to make a deep clone.
This is an object that represents a single resource.
initialize()Create a new resource
as_table()Represents the current state of the resource as a tibble
Creates a new resource.
nameThe name of the resource
quantityThe quantity of the resource that exists
new()
Creates a new resource object
resource$new(name = NA, quantity = 0)
nameThe name of the resource
quantityThe quantity present Returns a data.frame representation of the resource
as_table()
resource$as_table()
A data.frame of resources
clone()
The objects of this class are cloneable with this method.
resource$clone(deep = FALSE)
deepWhether to make a deep clone.
This object manages all of the resources in a village.
initialize()Creates a new manager
get_resources()Gets all of the resources that the manager has
get_resource()Retrieves a resource from the manager
add_resource()Adds a resource to the manager
remove_resource()Removes a resource from the manager
get_resource_index()Retrieves the index of the resource
get_states()Returns a list of states
load()Loads a csv file of resources and adds them to the manager.
resourcesA list of resource objects
resource_classThe class used to represent resources Creates a new , empty, resource manager for a village.
new()
Get a new instance of a resource_manager
resource_manager$new(resource_class = villager::resource)
resource_classThe class being used to describe the resources being managed Gets all of the managed resources
get_resources()
resource_manager$get_resources()
A list of resources Gets a resource given a resource name
get_resource()
resource_manager$get_resource(name)
nameThe name of the requested resource
A resource object Adds a resource to the manager.
add_resource()
resource_manager$add_resource(...)
...The resources to add
None Removes a resource from the manager
remove_resource()
resource_manager$remove_resource(name)
nameThe name of the resource being removed
None Returns the index of a resource in the internal resource list
get_resource_index()
resource_manager$get_resource_index(name)
nameThe name of the resource being located
The index in the list, or R's default return value Returns a data.frame where each row is a resource.
get_states()
resource_manager$get_states()
Subclasses should not have to override this method because it takes all member variables into account
A single data.frame Loads a csv file of resources into the manager
load()
resource_manager$load(file_name)
file_nameThe path to the csv file
None
clone()
The objects of this class are cloneable with this method.
resource_manager$clone(deep = FALSE)
deepWhether to make a deep clone.
Advances one or more villages through time
run_model()Runs the simulation
Creates a new Simulation instance
lengthThe total number of time steps that the simulation runs for
villagesA list of villages that the simulator will run
writerAn instance of a data_writer class for writing village data to disk
new()
Creates a new simulation object to control the experiment
simulation$new(length, villages, writer = villager::data_writer$new())
lengthThe number of steps the simulation takes
villagesA list of villages that will be simulated
writerThe data writer to be used with the villages Runs the simulation
run_model()
simulation$run_model()
None
clone()
The objects of this class are cloneable with this method.
simulation$clone(deep = FALSE)
deepWhether to make a deep clone.
This is an object that represents the state of a village at a particular time.
This class acts as a type of record that holds the values of the different village variables. This class can be subclassed to include more variables that aren't present.
initialize()Creates a new village
propagate()Advances the village a single time step
set_initial_state()Initializes the initial state of the village
nameAn optional name for the village
initial_conditionA function that sets the initial state of the village
current_stateThe village's current state
previous_stateThe village's previous state
modelsA list of functions or a single function that should be run at each timestep
model_dataOptional data that models may need
agent_mgrThe manager that handles all of the agents
resource_mgrThe manager that handles all of the resources Initializes a village
new()
This method is meant to set the variables that are needed for a village to propagate through time.
village$new( name, initial_condition, models = list(), agent_class = villager::agent, resource_class = villager::resource )
nameAn optional name for the village
initial_conditionA function that gets called on the first time step
modelsA list of functions or a single function that should be run at each time step
agent_classThe class that's being used to represent agents
resource_classThe class being used to describe the resources Propagates the village a single time step
propagate()
village$propagate(current_step, village_mgr)
current_stepThe current time step
This method is used to advance the village a single time step. It should NOT be used to set initial conditions. See the set_initial_state method.
None Runs the user defined function that sets the initial state of the village
set_initial_state()
Runs the initial condition model
village$set_initial_state()
clone()
The objects of this class are cloneable with this method.
village$clone(deep = FALSE)
deepWhether to make a deep clone.
This object manages all of the villages. It acts as an interface to them
initialize()Creates a new manager
get_villages()Gets all of the villages that the manager has
get_village()Retrieves a specific village from the manager, by name
add_village()Adds a village to the manager
villagesA list of village objects Creates a new, village manager
new()
Get a new instance of a village_manager Gets all of the managed villages
village_manager$new(villages)
get_villages()
village_manager$get_villages()
A list of resources Gets a village given a village name
get_village()
village_manager$get_village(name)
nameThe name of the requested village
A village object Adds a village to the manager.
add_resource()
village_manager$add_resource(...)
...The villages to add
None
clone()
The objects of this class are cloneable with this method.
village_manager$clone(deep = FALSE)
deepWhether to make a deep clone.
This is an object that represents the state of a village at a particular time.
This class acts as a type of record that holds the values of the different village variables. This class can be subclassed to include more variables that aren't present.
Creates a new State
stepThe time step that the state is relevant to
agent_statesA list of agent states
resource_statesA list of resource states
new()
Initializes all of the properties in the state to the ones passed in. This should be called by subclasses during initialization.
village_state$new( step = 0, agent_states = vector(), resource_states = vector() )
stepThe time step that the state is relevant to
agent_statesA vector of tibbles representing the states of the agents
resource_statesA vector of tibbles representing the states of the resources
When adding a new property, make sure to add it to the tibble representation.
clone()
The objects of this class are cloneable with this method.
village_state$clone(deep = FALSE)
deepWhether to make a deep clone.