CorrelatedContinuousInitializer

class defSim.agents_init.CorrelatedContinuousInitializer.CorrelatedContinuousInitializer(distribution: str = 'uniform', **kwargs)

Bases: defSim.agents_init.agents_init.AttributesInitializer

Implements the AttributesInitializer as a random initialization of correlated random continuous features.

__init__(distribution: str = 'uniform', **kwargs)
Parameters

  • distribution (str='uniform') – Type of continuous distribution to draw feature values from.

  • neighbor_similarity (bool=False) – If set to True, a default application of neighbor similarity is used. Regardless of the value of this parameter, similarity options can always be customized individually

  • neighbor_similarity_concentration (float=10) – How closely concentrated (peaked) the weight distribution is around the mean value of neighbors (minimum value > 2 required to maintain integrity of the distribution)

  • neighbor_similarity_strength (float=0) – Strength of weighting by neighbor value. 0 = no influence of neighbors

  • num_features (int=1) – How many different attributes each node has.

  • neighbor_similarity_feature (str='f01') – Sets the feature on which neighbor similarity will be determined.

  • or numpy.array covariances ([list]) – Complete covariance matrix (see agents_init.generate_correlated_continuous_attributes)

  • correlation (float) – Single correlation value to apply to all pairs of attributes

  • allow_inverse_concentration (bool) – Use to allow concentrations below 2, which result in anticoordination with neighbors

  • or int neighbor_similarity_postprocessing (str) – Sets the number of postprocessing iterations (integer to set max number of iterations, ‘convergence’ to not set a maximum)

  • neighbor_similarity_criterion (float) – Maximum allowable dissimilarity to neighbors during postprocessing

initialize_attributes(network: networkx.classes.graph.Graph, **kwargs)

Randomly initializes a number of continuous features between 0 and 1 for each node. Specify either a covariance matrix or a single correlation value (which is then applied to all pairs of attributes). Correlation values can be used in the covariance matrix as the base data generated will always be N(0, 1) regardless of the distribution which is eventually returned. If both are specified only the covariance matrix is used.

The generated feature values can be spread across the network in a non-random way, by placing more weight on attribute values close to the current mean value of the first attribute among network neighbors. Weights are bsaed on a Beta distribution with its mode set to the mean value among neighbors. The concentration of weights around the mode can be adjusted with the ‘neighbor_similarity_concentration’ parameter. The strength of neighbor influence can be adjusted using the ‘neighbor_similarity_strength’ parameter. When ‘neighbor_similarity_strength’ == 0 (default) attribute values are randomly assigned to agents.

Regardless of whether this non-random distribution has been applied, a minimum level of similarity between neighbors can be enforced by applying a postprocessing procedure which moves nodes whose dissimilarity to neighbors exceeds the value specified as ‘neighbor_similarity_criterion’. Postprocessing can be enabled either running to convergence using ‘neighbor_similarity_postprocessing’: ‘convergence’, or to a maximum number of iterations (if convergence is not reached sooner) using ‘neighbor_similarity_postprocessing’: int.

For a basic neighbor similarity approach where only postprocessing is applied, with a maximum of 10 iterations and a dissimilarity criterion of 0.75, set ‘neighbor_similarity’ to True and don’t make further adjustments. For custom setups, you can select any combination of weighted distribution and postprocessing by setting the relevant parameters.

Parameters

network – The graph object whose nodes’ attributes are modified.

class defSim.agents_init.CorrelatedContinuousInitializer.SimilarityPostprocessor(network: networkx.classes.graph.Graph, dissimilarity_criterion: float, feature_names: list, neighbor_similarity_feature: str)

Bases: object

This class holds functions to perform postprocessing on (correlated) features with the goal of enforcing a minimum level of similarity among neighbors. The main parameter to set here is the dissimilarity criterion. The dissimilarity cirterion works by setting a limit on the maximum dissimilarity between neighbors on the neighbor_similarity_feature.

__init__(network: networkx.classes.graph.Graph, dissimilarity_criterion: float, feature_names: list, neighbor_similarity_feature: str)
Parameters

  • network (nx.Graph) – The graph object whose nodes’ attributes are modified.

  • dissimilarity_criterion (float) – maximum allowable attribute value distance between neighbors.

  • feature_names (list) – List of all feature names as strings

  • neighbor_similarity_feature (str) – Name of feature on which neighbor similarity is to be enforced

check_convergence(swaps, current_dissimilar_nodes, nodes_involved_previous, num_dissimilar_previous)

Checks whether the postprocessing procedure has converged. If convergence is detected but there are still agents who are too dissimilar from their neighbor according to the dissimilarity criterion, a warning is given. Convergence is detected when: - no swaps were made and no nodes are too dissimilar OR - no swaps were made but there are still some nodes too dissimilar –> warning OR - the set of agents who ware too dissimilar has not changed for 10 iterations –> warning OR - the set of agents who are too dissimilar is not constant but the number of agents too dissimilar has not changed

for 50 iterations –> warning

Returns bool

True if one of the convergence conditions detected, else false.

create_dissimilarity_data()

Finds the dissimilarity data for each node in the network and stores data for all nodes as a numpy array.

dissimilarity_data_for_node(node: str)

Looks up the neighbors of a given node in the current network, and finds the maximum dissimilarity. Returns the node identifier, maximum dissimilarity, and the node’s own value on the similarity feature. :param str node: Node identifier to look up in the network :returns list: node identifier, maximum observed dissimilarity to neighbors, node’s own attribute value

improvement_if_swapped(node1_data, node2_data)

Check whether dissimilarity in the network would be improved if two given nodes are swapped. First, attribute values for each node’s neighbors are gathered. Then, dissimilarity is calculated as if the two nodes swapped position. Then, improvement is checked by comparing the total dissimilarity in the current position to the total dissimilarity in the new positions. The idea is that a swap is not an improvement if reducing dissimilarity for one node means increaing dissimilarity for the other node more. More weight is given to large dissimilarities by squaring all absolute dissimilarity values.

Parameters

  • node1_data – row from the np.array containing dissimilarity data. Contains node identifier, current dissimilarity and attribute value for the first node

  • node2_data – row from the np.array containing dissimilarity data. Contains node identifier, current dissimilarity and attribute value for the second node

Returns bool

True if swapping these nodes would improve dissimilarity, else false

process(postprocessing_iterations: str)

Apply the postprocessing procedure to a network. Postprocessing can either run to convergence or to a maximum number of iterations. Even if a maximum number of iterations is set, convergence will still end postprocessing.

Parameters

or int postprocessing_iterations (str) – Maximum number of postprocessing iterations (int) or ‘convergence’ to run without limiting maximum number of iterations

swap_dissimilar_nodes()

Finds nodes in the network whose dissimilarity to neighbors on the neighbor similarity feature exceeds the dissimilarity criterion, and swaps these nodes if swapping would improve dissimilarity. Tracks the number of swaps made. :returns tuple: Number of swaps made, np.array containing data for all nodes which exceeded dissimilarity criterion

swap_nodes(node1: str, node2: str)

Swap attribute values for two network nodes. (Effectively swapping the network position of two agents.) :param str node1: Node identifier for first node :param str node2: Node identifier for second node

update_dissimilarity(node1: str, node2: str)

For two given nodes, and all their neighbors, recalculate dissimilarity data. Use after swapping nodes to bring data up to date with new network position. The stored dissimilarity data is modified in place. :param str node1: Node identifier for first node :param str node2: Node identifier for second node

defSim.agents_init.CorrelatedContinuousInitializer.apply_neighbor_similarity_beta_weights(network, feature_values, feature_names, neighbor_similarity_feature, neighbor_similarity_concentration, neighbor_similarity_strength)

Distributes feature values across nodes in a network in a non-random way. The method starts by creating a random distribution and then redistributes semi-randomly by weighting the average attribute values of neighbors values.