Vector Agent

 Vector Agent

The Vector Agent is an agent component that creates agents from a gis shapefile. The shapefile is used as a template for creating the agents. An agent will be created for each feature in the shapefile such that the attributes in the shapefile become accessible fields in the agent. At the time of agent creation, the shapefile is read and a number of agents equal to the number of features in the shapefile are created. The values of the fields in each agent is set to the value of the corresponding attribute of that feature.

Appropriate Parent Component

GIS Model. The Vector Agent is added to a GIS Model.

Properties

Properties are the items that appear in the property pane when you click on a component in the project tree. For more information of properties, see here.

Name     Description
Actions See the section on Actions and editing them if you are unfamiliar with Actions.

Vector Agent defines one action by default.

  • step. The step action is where you define the behavior of your agents. Of course, you can have your step action call other actions, but the step action of every agent created from your agent component is by default executed every iteration of your simluation.
Data Source The data source property defines the shapefile that is used as a template for creating your agents. You can use the data source editor to select the shapefile and define a symbology for displaying your agents. See the Usage section below for more information.
Group Name The name of the Default Group into which all the agents created from this Vector Agent Component will be put. This group becomes an implicit field in the model. See the section on Agent Groups in the GIS Model documentation.
Name The name of the agent. This property is used internally by RepastPy and must not contain any spaces or quote characters. The name of the agent will be used in any errors associated with the agent's code. You can use this to name your agent's type to something more descriptive of its function. For example, if the agent represents a zip code region on a map, then you set the name property to ZipRegion.
Fields See the the Fields section of the help docs for information on creating and editing fields. Here you can define any fields you want your agent to have.
Schedule See the schedule help and tutorial 3 for more information on the schedule property. The schedule property defines the execution schedule of any actions defined in your model.



Implicit Fields

Fields are variables that the component exposes for your use in code. For example, if there is a field named agentList, you can refer to that field with self.agentList in your NQPy code.

Name     Description
Model Every agent has a reference to the model with which it is associated. You can use this in your own code as self.model.
Data Source Fields The fields from the shapefile that you select as your data source will become implicit fields in your model. See the Usage section below for more information.



GIS Packages

The major difference between the two GIS packages supported by repastpy is that depending on which you chose the geometry object that you will be working with is different.

  • If you choose ArcGIS, the underlying geometry object will be in the com.vividsolutions.jts.geom package, and mostly likely of the MultiPolygonType. You can get more information about these sorts of geometry types at http://www.vividsolutions.com/JTS/doc.htm

  • If you choose OpenMap, the underlying geometry object will be of the com.bbn.openmap.omGraphics.OMGraphic. You can find more information about this type at http://openmap.bbn.com/doc/api/.

Depending on which GIS package you are using, ArcGIS or OpenMap, RepastPy and Repast provide two GIS utility classes. These are GeotoolsData and OpenMapData. The first used with the ArcGIS package and the second with OpenMap. Using these class, you can, for example, read and write VectorAgents to a shapefile and so forth. Further documention of these are at OpenMapData and GeotoolsData.

You use these classes in your own actions just as you would any other class. For example, to determine the center of a VectorAgent using the OpenMapData class, you would do

center = OpenMapData.getInstance().getCenter(self)

where self is the VectorAgent. Note that the getCenter method returns its result as a LatLonPoint. More information about LatLonPoints can be found at http://openmap.bbn.com/doc/api/.



Java Parent Class

Many of the RepastPy components are based on Java code. What this means is that these components come with built-in fields and methods inherited from their Java parent classes. The docs below describe these built in fields and methods.

The agents produced by VectorAgent are based on the Java class AbstractGISAgent. Most of the fields and methods (actions) of this class are used internally by RepastPy. Some, however, are available to you to use in your own code.



The fields of a Java parent class can be used just as if they were fields in your own model. For example, self.omGraphic and so on. The format used below is

field name : field type
description

where the field type is a Java class type.

Java Parent Class Fields
omGraphic : OMGraphic
Contains graphical and geometric data used by OpenMap when drawing the agent on the map. Note that this field is ignored if you are using ArcGIS as your GIS package. See OMGraphic in the OpenMap API docs for more information.


The methods or actions of a Java parent class can be used just as if they were actions in your own model. For example, self.setRngSeed(33) and so on. The format used below is

method name(argument types, if any) : return type - an optional explanation of the return type
description

where the return type is a Java class type.

Java Parent Class Methods (Actions)
All the parent class methods of Vector Agent are reserved for internal use by RepastPy

Usage

A good example of using a Vector Agent is provided in the demonstration schelling_gis project.

As mentioned above, the VectorAgent components creates agents from a shapefile. You select a shapefile with the data source editor which is pictured below.



You can use the browse button pop up a file dialog and then select the shapefile through that. Once you've selected your shapefile the fields in that shapefile will appear in the data source fields table. These data source fields will become implicit fields in your agents with the appropriate type and will be listed in the variables pane of your VectorAgent's action editor.

You can use the symbology tab of the data source editor to set how you wish your agents to be displayed in the GIS view. Note that this only works if you are using the OpenMap GIS package



In the fields combobox you select the field that you want base the display off of. The general idea here is that a field will have some set of values and you can change the color of the display based on the value of that field. In the example above, the PO_NAME field has three values and the GIS object (e.g. polygon, line, point, etc.) that represents each agent that have those values will display with that color. In the above, if the value of the PO_NAME field is GREEN, then the polygon will be colored green.

You can use the "Add Value" button to query the shapefile for all the possible values of that field and to select among those values for setting symbology. The "Remove Value" button will remove that value from the table. Any agents whose field value is not displayed in the symbol value table will be displayed in the default value color. Once the data source is set you can run the simulation. When the simulation is run, a number of agents equal to the number of features in the shapefile will be created and placed in a DefaultAgentGroup with the name specified by the Group Name property.

You can use the step method to define any behavior that you want your agents to have. In particular you may wish to manipulate the agent's geometry. You can do this using the agent's implicit Geometry field. You can find the geometry type in the data soure editor. The geometry type will be either in an OpenMap package in which case, see the http://openmap.bbn.com/doc/api/ for more information about what you can do with that type. Or the type will be part of the vividsolutions JTS package in which case see JTS API for more information.