de.cesr.more.rs.building
Class MGeoRsHomophilyDistanceFfNetworkService<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>>

java.lang.Object
  de.cesr.more.building.network.MNetworkService<AgentType,EdgeType>
      de.cesr.more.rs.building.MRsNetworkService<AgentType,EdgeType>
          de.cesr.more.rs.building.MGeoRsNetworkService<AgentType,EdgeType>
              de.cesr.more.rs.building.MGeoRsHomophilyDistanceFfNetworkService<AgentType,EdgeType>

All Implemented Interfaces:

MoreNetworkBuilder<AgentType,EdgeType>, MoreNetworkService<AgentType,EdgeType>, MoreGeoNetworkBuilder<AgentType,EdgeType>, MoreGeoNetworkService<AgentType,EdgeType>, MoreNetworkEdgeModifier<AgentType,EdgeType>, MoreNetworkModifier<AgentType,EdgeType>, MoreGeoRsNetworkBuilder<AgentType,EdgeType>, MoreGeoRsNetworkService<AgentType,EdgeType>, MoreRsNetworkBuilder<AgentType,EdgeType>, MoreRsNetworkService<AgentType,EdgeType>, MoreRuntimeAnalysable

public class MGeoRsHomophilyDistanceFfNetworkService<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>>
extends MGeoRsNetworkService<AgentType,EdgeType>
implements MoreRuntimeAnalysable

MORe TODO test and make component of RS version (?) This network builder considers baseline homophily [1] and distance distributions [2]. The network is build as follows:

1. Read hexagon shapefile, init MGeoHexagons, and add them to the geography and the root context.
2. Assign agents to hexagons and determine distances between hexagons
3. Init degree distributions for milieu groups and degree target for each agent
4. Shuffle agents
5. Do as long as agents' degree targets are not fulfilled:
   1. For every agents with degree less than degree target
      1. Draw a distance from milieu-specific distance distribution, identify the according distant hexagon, and randomly choose an agent within that hexagon according to milieu preferences (inbreeding homophily) using MMilieuPartnerFinder
      2. Link the agent to that ambassador, update degree target and explore its neighbours (breadth first traversing):
         1. Add predecessor neighbours to a list
         2. Add successor neighbours to the list
         3. Traverse the list in a random order until degree target fulfilled or list's end
         4. Check a preceding neighbour as backward link considering distance, partner milieu, and backward probability
         5. If check is positive, create an edge and add to exploration queue
         6. Check a succeeding neighbour as forward link considering distance, partner milieu, and forward probability
         7. If check is positive, create an edge and add to exploration queue
         Repeat the steps under 2. with the queue's head and remove it until queue is empty or degree target fulfilled.
   2. Shuffle agents with respect to MNetBuildHdffPa.AGENT_SHUFFLE_INTERVAL.

See MoRe Network Building for a guide to create hexagon shapefiles. The class is such constructed that it enables the building of several networks with same parameters one after another.

Property	Value
#Vertices	N (via collection of agents)
#Edges:	undefined

Considered PmParameterDefinitions:

• MNetBuildHdffPa.HEXAGON_SHAPEFILE
• MNetworkBuildingPa.BUILD_DIRECTED
• MNetBuildHdffPa.K_DISTRIBUTION_CLASS (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.K_PARAM_A (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.K_PARAM_B (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa#DISTANCE_PROBABILITY_EXPONENT (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.MAX_SEARCH_RADIUS (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.P_MILIEUS (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.PROB_FORWARD (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.PROB_BACKWARD (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.DIM_WEIGHTS_GEO (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.DIM_WEIGHTS_MILIEU (via MNetworkBuildingPa.MILIEU_NETWORK_PARAMS)
• MNetBuildHdffPa.AGENT_SHUFFLE_INTERVAL (specifies the number of turns - selection of new ambassador for each agent - after which agents are shuffled)

NOTE: The hexagon shapefile must cover all agent positions and should not be much larger since it is used to calculated the area's diameter which is used to initialised the distance distributions.

[1] McPherson, M.; Smith-Lovin, L. & Cook, J. Birds of a feather: Homophily in social networks Annual Review of Sociology, Annual Reviews, 2001, 27, 415-444
[2] Onnela, J.-P.; Arbesman, S.; Gonzalez, M. C.; Barabasi, A.-L. & Christakis, N. A. Geographic Constraints on Social Network Groups, PLOS ONE, PUBLIC LIBRARY SCIENCE, 2011, 6

Date:

20.06.2013

Field Summary

protected double	areaDiameter
protected boolean	considerBackwardLinks
protected boolean	considerDistance
protected boolean	considerForwardLinks
protected boolean	considerMilieus
protected Map<Integer,MIntegerDistribution>	degreeDistributions
static int	DISTANCE_FACTOR_FOR_DISTRIBUTION
protected Map<Integer,MRealDistribution>	distanceDistributions
protected double	distanceStep
protected String	name
protected MMilieuNetworkParameterMap	paraMap
protected MMilieuPartnerFinder<AgentType,EdgeType>	partnerFinder
protected cern.jet.random.Uniform	rand
protected MRuntimeDbWriter	runtimeWriter
static double	TOLERANCE_VALUE_DIM_WEIGHTS

Fields inherited from class de.cesr.more.rs.building.MGeoRsNetworkService

geoFactory, geography, geoRequestClass, pm

Fields inherited from class de.cesr.more.rs.building.MRsNetworkService

context

Fields inherited from class de.cesr.more.building.network.MNetworkService

edgeFac, edgeModifier

Constructor Summary

MGeoRsHomophilyDistanceFfNetworkService(repast.simphony.space.gis.Geography<Object> geography, MoreEdgeFactory<AgentType,EdgeType> edgeFac, String name)
Uses main instance of PmParameterManager.

MGeoRsHomophilyDistanceFfNetworkService(repast.simphony.space.gis.Geography<Object> geography, MoreEdgeFactory<AgentType,EdgeType> edgeFac, String name, de.cesr.parma.core.PmParameterManager pm)
- builder constructor - edge modifier - builder set - parma

MGeoRsHomophilyDistanceFfNetworkService(MoreEdgeFactory<AgentType,EdgeType> edgeFac, String name)
Takes the geography from MBasicPa.ROOT_GEOGRAPHY.

Method Summary

boolean	addAndLinkNode(MoreNetwork<AgentType,EdgeType> network, AgentType node) Removes an agent from the given network and deletes all its links.
protected void	adjustProbabilityWeights() TODO test
protected void	assignMilieuParamMap()
MoreRsNetwork<AgentType,EdgeType>	buildNetwork(Collection<AgentType> agents) The returned network is always directed!
protected void	checkParameter() Checks...
protected ArrayList<AgentType>	createRandomAgentList(Collection<AgentType> agents, Map<AgentType,Integer> degreeTargets)
protected void	explorePartner(AgentType agent, LinkedList<AgentType> toExplore, MoreNetwork<AgentType,EdgeType> network, Map<AgentType,Integer> degreeTargets) Assumes that the distance distribution's density is highest at supported lower bound (p_local / x_min).
protected double	getAreaDiameter() Calculates the area diameter from hexagon shapefiles.
protected double	getDistance(int milieu)
protected double	getDistanceProb(AgentType ego, AgentType partner)
protected Map<AgentType,Integer>	initDegreeTargets(Collection<AgentType> agents)
protected void	initHexagons() Init hexagons from shapefile into geography.
void	initRuntimeDbWriter(MoreRunIdProvider provider) Initialises the MRuntimeDbWriter.
protected void	linkPartner(AgentType agent, AgentType partner, MoreNetwork<AgentType,EdgeType> network, Map<AgentType,Integer> degreeTargets)
String	toString()

Methods inherited from class de.cesr.more.rs.building.MGeoRsNetworkService

getGeoRequestClass, logEdges, setContext, setGeography, setGeoRequestClass, shuffleCollection

Methods inherited from class de.cesr.more.building.network.MNetworkService

addAgents, checkAgentCollection, createEdge, getEdgeFactory, getEdgeModifier, logEdges, removeEdge, removeNode, setEdgeModifier

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.cesr.more.manipulate.network.MoreNetworkModifier

removeNode, setEdgeModifier

Methods inherited from interface de.cesr.more.manipulate.edge.MoreNetworkEdgeModifier

createEdge, getEdgeFactory, removeEdge

Field Detail

DISTANCE_FACTOR_FOR_DISTRIBUTION

public static final int DISTANCE_FACTOR_FOR_DISTRIBUTION

See Also:

Constant Field Values

TOLERANCE_VALUE_DIM_WEIGHTS

public static final double TOLERANCE_VALUE_DIM_WEIGHTS

See Also:

Constant Field Values

name

protected String name

paraMap

protected MMilieuNetworkParameterMap paraMap

partnerFinder

protected MMilieuPartnerFinder<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>> partnerFinder

rand

protected cern.jet.random.Uniform rand

degreeDistributions

protected Map<Integer,MIntegerDistribution> degreeDistributions

distanceDistributions

protected Map<Integer,MRealDistribution> distanceDistributions

distanceStep

protected double distanceStep

areaDiameter

protected double areaDiameter

runtimeWriter

protected MRuntimeDbWriter runtimeWriter

considerBackwardLinks

protected boolean considerBackwardLinks

considerForwardLinks

protected boolean considerForwardLinks

considerMilieus

protected boolean considerMilieus

considerDistance

protected boolean considerDistance

Constructor Detail

MGeoRsHomophilyDistanceFfNetworkService

public MGeoRsHomophilyDistanceFfNetworkService(MoreEdgeFactory<AgentType,EdgeType> edgeFac,
                                               String name)

Takes the geography from MBasicPa.ROOT_GEOGRAPHY.

Parameters:

edgeFac -

name -

MGeoRsHomophilyDistanceFfNetworkService

public MGeoRsHomophilyDistanceFfNetworkService(repast.simphony.space.gis.Geography<Object> geography,
                                               MoreEdgeFactory<AgentType,EdgeType> edgeFac,
                                               String name)

Uses main instance of PmParameterManager.

Parameters:

areasGeography -

MGeoRsHomophilyDistanceFfNetworkService

public MGeoRsHomophilyDistanceFfNetworkService(repast.simphony.space.gis.Geography<Object> geography,
                                               MoreEdgeFactory<AgentType,EdgeType> edgeFac,
                                               String name,
                                               de.cesr.parma.core.PmParameterManager pm)

- builder constructor - edge modifier - builder set - parma

Parameters:

areasGeography -

Method Detail

initRuntimeDbWriter

public void initRuntimeDbWriter(MoreRunIdProvider provider)

Initialises the MRuntimeDbWriter. Runtimes are only recorded when this method was called before this#buildNetwork(Collection).

Specified by:

initRuntimeDbWriter in interface MoreRuntimeAnalysable

Parameters:

provider -

buildNetwork

public MoreRsNetwork<AgentType,EdgeType> buildNetwork(Collection<AgentType> agents)

The returned network is always directed!

Specified by:

buildNetwork in interface MoreNetworkBuilder<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>>

Specified by:

buildNetwork in interface MoreRsNetworkBuilder<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>>

Returns:

network

See Also:

MoreRsNetworkBuilder.buildNetwork(java.util.Collection)

getDistance

protected double getDistance(int milieu)

See Also:

http://mathworld.wolfram.com/RandomNumber.html

getAreaDiameter

protected double getAreaDiameter()

Calculates the area diameter from hexagon shapefiles.

Returns:

diameter

initDegreeTargets

protected Map<AgentType,Integer> initDegreeTargets(Collection<AgentType> agents)

Parameters:

agents -

Returns:

explorePartner

protected void explorePartner(AgentType agent,
                              LinkedList<AgentType> toExplore,
                              MoreNetwork<AgentType,EdgeType> network,
                              Map<AgentType,Integer> degreeTargets)

Assumes that the distance distribution's density is highest at supported lower bound (p_local / x_min).

Parameters:

agent - agent/ambassador

partner -

network -

orderedAgents -

degreeTargets -

linkPartner

protected void linkPartner(AgentType agent,
                           AgentType partner,
                           MoreNetwork<AgentType,EdgeType> network,
                           Map<AgentType,Integer> degreeTargets)

Parameters:

agent -

partner -

network -

orderedAgents -

degreeTargets -

getDistanceProb

protected double getDistanceProb(AgentType ego,
                                 AgentType partner)

Parameters:

ego -

partner -

Returns:

adjustProbabilityWeights

protected void adjustProbabilityWeights()

TODO test

checkParameter

protected void checkParameter()

Checks...

• ...context
• ...random distribution (rand)
• ...whether MNetworkBuildingPa.MILIEU_NETWORK_PARAMS has been initialised.

assignMilieuParamMap

protected void assignMilieuParamMap()

createRandomAgentList

protected ArrayList<AgentType> createRandomAgentList(Collection<AgentType> agents,
                                                     Map<AgentType,Integer> degreeTargets)

Parameters:

agents -

addAndLinkNode

public boolean addAndLinkNode(MoreNetwork<AgentType,EdgeType> network,
                              AgentType node)

Description copied from interface: MoreNetworkModifier

Removes an agent from the given network and deletes all its links. Basically, this method reverses all the action that #addAgent(Object, MoreRsNetwork) performed.

Specified by:

addAndLinkNode in interface MoreNetworkModifier<AgentType extends MoreMilieuAgent & MoreNetworkAgent<AgentType,EdgeType>,EdgeType extends MRepastEdge<AgentType> & MoreEdge<AgentType>>

Parameters:

network - the network to remove the given agent from

Returns:

true if the agent could be completely removed

See Also:

MoreNetworkModifier.addAndLinkNode(de.cesr.more.basic.network.MoreNetwork, java.lang.Object)

initHexagons

protected void initHexagons()

Init hexagons from shapefile into geography.

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()