Initialising PLZ-Area contexts

Steps

To initialise agents within PLZ areas SesamGIM conducts the following steps as default:

  1. Initialise area shapes according to shape file (GBasicPa.AREAS_SHAPEFILE).
  2. Initialise PLZ area contexts according to shape file (GPlzPa.PLZ_SHAPEFILE) and assign these to surrounding area shapes. Only Plz areas that intersect with an area context are initialised.
  3. All MZ within the given area shape(s) are initialised. In case GBasicPa.USE_CENTROID_TO_INIT_MC is true (default) all MZ whose centroid is within an area context are included. Otherwise, the entire market cell shape needs to be within an area context. Market Cells are then assigned to PLZ areas (more than one PLZ area per MZ is possible).
  4. Agents are initialised, per default for one market cell at a time. For PLZ-based models, GPlzAreaAgentInitialiser is used which extends GAreaAgentInitialiser. To init agents per PLZ GPlzAreaAgentInitialiser.initAgents() needs to be adapted (implement and call an adapted version of GAreaAgentInitialiser.initAgents() and also adapt the helper methods called therein:
    1. Sum up (using GAreaAgentInitialiser#calculateMcSums(mc))
    2. Adapt agent numbers per PLZ area (see GAreaAgentInitialiser#adaptMilieuSums())
    3. Init agents (see GPlzAreaAgentInitialiser#initAgentsPerMc()) and assign them to PLZ areas and market cells
  5. Agent coordinates are determined. As default, the positions are randomly normally distributed around the MZ's center coordinate (using related parameters in GMilieuPa). Uniform distribution within the MZ shape is achieved by setting GMilieuPa.DISTRIBUTE_AGENTS_UNIFORMLY_IN_MC to true. In order to achieve another distribution of agent coordinates extend GPlzAreaAgentInitialiser, override placeAgents(...) and set the new class to GInitialisersPa.INITIALISER_AGENTS. Agent positions are furthermore influenced by GMilieuPa.ALLOW_AGENTS_TO_LEAVE_INHABITED_AREAS, GPlzPa.PLZ_ALLOW_AGENT_TO_LEAVE_PLZ_AREAS, and GMilieuPa.ALLOW_AGENTS_TO_LEAVE_MC_BOUNDARIES).
  6. After definition of agent coordinates, agents are assigned to the PLZ area their coordinate is within. Thus, agents of the same MZ may belong to more than one PLZ area.

Usage

Prepare Shapefiles

A small guide on how to build an area shapefile from Market Cell Shapefile in Quantum GIS:

  1. Open Market Cell Shapefile (Layer > Add vector layer...)
  2. At the layer window on the left hand side select the Market Cell layer
  3. Toggle editing (pencil)
  4. Use "Select single feature" (arrow+(i)-symbol)
  5. Press STRG an select as many market cells as you like to simulate.
  6. Edit > Save selection as vector layer... (specify correct CRS!)

Parameter definitions

First, read section Parameter Settings in the main part of this manual. Then, consider and check all parameters in GPlzPa. The following parameters in other param classes are mandatory:

PmParameterManager.setParameter(GInitialisersPa.INITIALISER_AGENTS, GPlzAreaAgentInitialiser.class);
PmParameterManager.setParameter(GInitialisersPa.INITIALISER_GROUP, null);

Furthermore, the following parameters need some consideration:

PmParameterManager.setParameter(GBasicPa.ADD_MC_TO_AREA, false);
PmParameterManager.setParameter(GBasicPa.AREAS_SHAPEFILE, "./config/shapes/areas/areas.shp");
PmParameterManager.setParameter(GBasicPa.MC_SHAPEFILE, "./config/shapes/mc/mc.shp");
PmParameterManager.setParameter(GMilieuPa.DISTRIBUTE_AGENTS_UNIFORMLY_IN_MC, true);

GInitialisersPa.IS_PLZ only needs to be adapted in case a custom PLZ-area class shall be used.

Initialisation code

GimModelInitialiser<AgentType> gimInitialiser;
gimInitialiser = new GPlzModelInitialiser<Household<?>>();
gimInitialiser.initAll();

See section "Parameter definitions" for required parameter definitions.

NOTE: In case you do not use gimInitialiser.initAll() you need to set the following parameter:

PmParameterManager.setParameter(GBasicPa.ADD_MC_TO_AREA, Boolean.FALSE);

Calculate Agent Numbers on PLZ Level

Usually when Microm (R) data is applied, agent numbers are determined on the market cell level using GimMarketCellContexts. However, sometimes it is required for large model regions to increase the area for which agent numbers are determined at once in order to prevent ugly rounding effects. NOTE: The application of larger areas for the determination of agent numbers reduces accuracy of geographical agent localisation which is especially relevant for spatial social networks. Therefore, it is recommended to check your model's sensitivity towards the size of areas.

In order to apply PLZ areas as the level of agent number determination one basically has to use a special GimAgentInitialiser, namely GPlzWiseAreaAgentInitialiser:

PmParameterManager.setParameter(GInitialisersPa.INITIALISER_AGENTS, GPlzWiseAreaAgentInitialiser.class);

Usually, in this case it is not necessary or desired to initialise market cell contexts. Therefore, for initialisation the following code is sufficient:

GimModelInitialiser<AgentType> gimInitialiser;
gimInitialiser = new GPlzModelInitialiser<Household<?>>();
gimInitialiser.initAreas();
gimInitialiser.initPlzContexts();
gimInitialiser.initAgents();

The procedure reads PLZ-based Microm (R) data from the database (de.cesr.sesamgim.init.plz.GPlzInitialiser). Therefore, the table name needs to be specified:

PmParameterManager.setParameter(GSqlPa.TBLNAME_HHSTRUCT_PLZ, "sesamgim_test_plzwise");

NOTE: In case you apply a custom implementation of GPlzContext make sure that it extends GUpdatablePlzContext or implements GimUpdatableContext

NOTE: In order to speed up the process of fetching data from DB the strategy described in section Custom SQL statements for GimMarketCellInitialiser can be applied here as well. The relevant method to override is GPlzInitialiser#buildSqlQuery().

There is a test for PLZ level agent number determination: de.cesr.sesamgim.testing.init.agent.GPlzWiseAreaAgentInitialiserTest. The SQL code that is required to create dependent tables is also helpful for creating the required model tables. It is found in ./config/test/sql/TestMySQL.sql.

Additional Hints

Hierarchical context organisation

Repast Simphony usually returns objects of the context that is queried and all its sub-context (see also Tipps and Tricks). For PLZ areas this is troublesome since a market cell can belong to more than one PLZ area, and thus its members may occur in the listing of more than one PLZ area. As a work-around, use the following method: 

this.getDirectObjects(Agent.class);

Test

See Checks for tools to test. You may have a look in de.cesr.sesamgim.testing.init.plz.GPlzInitialiserTest to see things working.