src package

Submodules

src.auxiliary_functions module

Auxiliary Functions, (f_abm.src.auxiliary_functions)

Description

This module contains auxiliary functions that are use throughout the program.

Functions

• matrix_exp

• digraph2topology

• add_random_edges

• add_rs_weights2matrix

• add_signs2matrix

• matrix2digraph

• create_random_numbers

• opinion2color

• modify_opinions_method_1

• modify_opinions_method_2

• histogram_classification

• modify_mean

• make_row_stochastic

src.auxiliary_functions.add_random_edges(adjacency_matrix=None, num_iterations=10, default_type=0)

Function to add random edges to the adjacency matrix ‘adjacency_matrix’, the edges have no weight or sign. The function does not guarantee that these are new edges, it randomly selects cells of the adjacency matrix and adds edges

Parameters

adjacency_matrix: the adjacency matrix to be modified num_iterations: the number of iterations default_type: the ID of the default digraph

Returns

The same adjacency matrix with random edges. This is a side effect function.

src.auxiliary_functions.add_rs_weights2matrix(adjacency_matrix)

Function that adds the stochastic weights to an adjacency matrix

The result is a row-stochastic matrix

A row stochastic matrix is one with all non-negative weights and the sum of elements along a row is always 1

Parameters

adjacency_matrix: original adjacency matrix

Returns

there is no need to return anything, as the adjacency matrix is transformed in the function

src.auxiliary_functions.add_signs2matrix(adjacency_matrix, positive_edge_ratio)

Function that adds the signs to the adjacency matrix of a signed digraph

Parameters

adjacency_matrix: current adjacency matrix, presumably with only non-negative weights positive_edge_ratio: ratio of positive edges

Returns

There is no need to return anything, since the function modifies the adjacency matrix as desired

src.auxiliary_functions.create_random_numbers(num_agents=100, number_parameters=None, limits=(-1, 1))

This function creates and returns a list of random ‘num_agents’ numbers. This function is used to create initial opinions and also to create agent parameters. Its default use is to create initial opinions.

This function can also be used for the creation of agent parameters.

Parameters

num_agents: number of opinions that are returned, by default 100 number_parameters: a lists of lists, every element corresponds to a different set of initial opinions to be created. Each element of this list contains 4 elements: [0] signals the type of distribution to create. ‘0’ is a uniform distribution ‘any non 0’ is a normal distribution [1] if the distribution is uniform, this is the minimum value. If the distribution is normal, this is the mean [2] if the distribution is uniform, this is the maximum value. If the distribution is normal, this is the variance [3] the fraction of all the agents. The sum does not have to add to one, as it will be normalized limits: a tuple of two numbers, the first is the lower bound and the second the upper bound

Returns

numpy array of ‘num_agents’ rows and 1 column (a list of lists) of opinions

src.auxiliary_functions.digraph2topology(adjacency_matrix=None, default_type=0)

Function to convert from any adjacency matrix to the corresponding topology (that is, the associated adjacency matrix without signs or weights)

Parameters

adjacency_matrix: the adjacency matrix default_type: ID of the default digraph

Returns

A matrix of the same size as ‘adjacency_matrix’ but with only 0 or 1 corresponding to the topology.

src.auxiliary_functions.histogram_classification(opinion_distribution, classification_parameters=(10, 3, 4, 6, 50, 12, 40))

A function that classifies opinion distributions with any number of agents.

Parameters

opinion_distribution: the opinion distribution to be classified. classification_parameters: the classification parameters.

Returns

A number that encodes the classification, 0 is perfect consensus, 1 is consensus, 2 is polaristion, 3 is clustering, and 4 is dissensus.

src.auxiliary_functions.make_row_stochastic(matrix)

Function that takes a matrix and makes it row-stochastic

Parameters

matrix: original matrix

Returns

This function does not return anything, as it modifies the passed matrix

src.auxiliary_functions.matrix2digraph(adjacency_matrix=None, default_type=0)

Function that converts from an adjacency matrix to a digraph object it is mainly used to plot

Parameters

adjacency_matrix: the adjacency matrix, by default it is a simple ring digraph default_type: ID of the default digraph

Returns

ID of the default digraph

src.auxiliary_functions.matrix_exp(matrix, order=10)

This is a function to approximate a matrix exponential to the order ‘order’

Parameters

matrix: matrix to calculate the exponential order: the order of the approximation, by default it is 10

Returns

returns the approximation of the matrix exponential

src.auxiliary_functions.modify_mean(weights, des_mean, epsilon=0.05, max_counter=100, limits=(0, 1))

Parameters

weights: initial weights. des_mean: desired weight mean. epsilon: tolerance. max_counter: maximum number of iterations. limits: the limits of the weights.

Returns

modified weights with the desired mean.

src.auxiliary_functions.modify_opinions_method_1(opinions, des_mean, des_abs_mean, epsilon=None, max_counter=100, show_process=False, limits=(-1, 1))

This function modifies a given opinion distribution to create an opinion distribution with the desired mean and absolute value mean using method 1

Parameters

opinions: the original opinions des_mean: the desired opinion mean des_abs_mean: the desired opinion mean absolute value epsilon: the tolerance for the infinity norm max_counter: the maximum number of iterations to find the desired opinions show_process: boolean determining whether to show the creation process or not limits: a tuple with the upper and lower limits of the opinions

Returns

the new, modified opinions

src.auxiliary_functions.modify_opinions_method_2(opinions, des_mean, des_abs_mean, epsilon=None, max_counter=100, show_process=False, limits=(-1, 1))

This function modifies a given opinion distribution to create an opinion distribution with the desired mean and absolute value mean using method 2

Parameters

opinions: the original opinions des_mean: the desired opinion mean des_abs_mean: the desired opinion mean absolute value epsilon: the tolerance for the infinity norm max_counter: the maximum number of iterations to find the desired opinions show_process: boolean determining whether to show the creation process or not limits: a tuple with the upper and lower limits of the opinions

Returns

the new, modified opinions

src.auxiliary_functions.opinion2color(opinion_model, agent_parameter)

This function transforms agent parameter to colors, depending on the model.

Parameters

opinion_model: the model name or identifier agent_parameter: the agent parameters

Returns

a color in a form of an RGB triplet

src.basic_creation module

Basic Creation, (f_abm.src.basic_creation)

Description

This module contains all the basic creation functions. It is primarily aimed at creating opinion distributions and agent parameters, since for digraph creation there is a separate module

Functions

• a_random_digraph

• a_random_initial_opinion_distribution

• a_random_inner_trait_assignation

• create_inner_traits_local

• create_many_opinions

• create_many_inner_traits

src.basic_creation.a_random_digraph(num_agents=10)

This function returns a random digraph, NOT a digraph with random topology, but digraph with a topology chosen at random, currently the possible topologies include.

Update: currently, this function only returns digraphs with the small-world topology.

Parameters

num_agents: number of agents, by default 10

Returns

a random digraph

src.basic_creation.a_random_initial_opinion_distribution(num_agents=10)

This function returns a random initial opinion distribution

Parameters

num_agents: number of agents, by default 10

Returns

A random initial opinion distribution

src.basic_creation.a_random_inner_trait_assignation(num_agents=10)

This function returns a random inner trait assignation

Parameters

num_agents: number of agents

Returns

Inner trait assignation

src.basic_creation.create_inner_traits_local(num_agents=100)

Function to create randomly inner trait assignations, these are the agent parameters of the Classification-based model

Parameters

num_agents: number of agents, by default 100

Returns

inner traits, it is a list of lists, the first element is alpha, the second is beta (the weights of the conformist and radical trait, respectively)

src.basic_creation.create_many_inner_traits(num_agents=100, file_name='standard_inner_traits', grid=None, show_result=False)

This function creates and saves many inner traits to be used later

Parameters

num_agents: the number of agents file_name: name of the file created grid: it is the reference grid to create the inner traits show_result: a boolean determining of the resulting inner traits are shown

Returns

A list of numpy arrays with ‘num_agents’ rows and 2 columns

src.basic_creation.create_many_opinions(num_agents=100, file_name='standard_initial_opinions', grid=None, show_result=False)

This function creates and saves many initial opinions to be used later

Parameters

num_agents: the number of agents, by default 100 file_name: name of the file created, by default ‘standard_initial_opinions’ grid: it is the reference grid to create the initial opinions show_result: show the Agreement Plot of the resulting opinions. By default, it is false

Returns

src.basic_creation_test module

Basic Creation Test, (f_abm.src.basic_creation_test)

Description

This module contains all the test functions for the ‘basic_creation.py’ module

Functions

• test_create_random_numbers

src.basic_creation_test.test_create_random_numbers()

Test function for the ‘create_random_numbers’ function, it checks that the returned values are within the desired interval

src.basic_creation_test.test_get_parameter_value_1()

Test function for the ‘get_parameter_value’ function

Returns

Nothing

src.basic_creation_test.test_get_parameter_value_2()

Test function for the ‘get_parameter_value’ function

Returns

Nothing

src.basic_creation_test.test_get_parameter_value_3()

Test function for the ‘get_parameter_value’ function

Returns

Nothing

src.code_test module

Code Test, (f_abm.src.code_test)

Description

This module contains example functions aimed at showing newcomers how to use some of the functions in the program

Functions

• example_1

• example_2

• example_3

• example_4

src.code_test.example_1(num_agents=100)

Example 1, which plots the histogram of some opinion distribution created at random

Parameters

num_agents: number of agents of the initial opinion distribution, by default 100

Returns

Nothing

src.code_test.example_2(num_agents=10)

Example 2. It shows the opinion evolution of ‘num_agents’ agents according to the Classification-based model. The initial opinions, agent parameters, and underlying digraph are created at random.

Parameters

num_agents: number of agents in the simulation.

Returns

Nothing

src.code_test.example_3()

Example 3. This example simply plots a digraph, it is better to make it more interesting, such as plotting various digraphs with different topologies and colors.

Returns

Nothing

src.code_test.example_4()

Example 4. This is for data analysis, needs to be improved

Returns

Nothing

src.data_analysis_functions module

Data Analysis, (f_abm.src.data_analysis_functions)

Description

This module contains all the data analysis related functions

Functions

• gather_data

• obtain_features

• feature_computation

• compute_mean_opinion_difference

• compute_opinion_metrics_by_agent_type

• compute_trait_allocation_metrics

• compute_opinion_metrics

• compute_inner_trait_metrics

• compute_digraph_metrics

• compute_balance_index

• compute_bidirectional_coefficient

• compute_degrees

• compute_clustering

src.data_analysis_functions.compute_balance_index(adjacency_matrix=None, default_type=0, print_information=False)

Function to approximate the balance index of a signed network

Parameters

adjacency_matrix: the adjacency matrix default_type: ID of the default digraph print_information: Boolean determining if the computed values are printed

Returns

The balance index

src.data_analysis_functions.compute_bidirectional_coefficient(adjacency_matrix=None, default_type=0, print_information=False)

This function computes the bidirectional coefficient of a given adjacency matrix

Parameters

adjacency_matrix: the adjacency matrix. default_type: ID of the default digraph print_information: Boolean determining if the computed values are printed

Returns

A float between 0.0 and 1.0 with the bidirectional coefficient

src.data_analysis_functions.compute_clustering(adjacency_matrix=None, default_type=0, print_information=False)

This is a function to compute the clustering mean and variance.

Parameters

adjacency_matrix: the adjacency matrix default_type: ID of the default digraph print_information: Boolean determining if the computed values are printed

Returns

A numpy array with the mean and the variance of the clustering

src.data_analysis_functions.compute_degrees(adjacency_matrix=None, default_type=0, print_information=False)

Function used to compute the metrics related to the degree of the nodes, namely, the mean and variance of the in and out degrees

Parameters

adjacency_matrix: the adjacency matrix default_type: ID of the default digraph print_information: Boolean determining if the computed values are printed

Returns

A numpy array with 4 numbers corresponding, in order, to the mean in-degree, in-degree variance, mean out-degree, and out-degree variance

src.data_analysis_functions.compute_digraph_metrics(adjacency_matrix=None, default_type=0, print_information=False)

This is a function used to compute several digraph metrics at once

Parameters

adjacency_matrix: the adjacency matrix for which the metrics will be computed default_type: ID of the default adjacency matrix print_information: whether to print information or not

Returns

The digraph metrics

src.data_analysis_functions.compute_inner_trait_metrics(inner_traits=None, num_agents=10, print_information=False)

This function computes the metrics of the inner trait assignation

Parameters

inner_traits: the inner trait assignation num_agents: the number of agents print_information: boolean that determines if the information is printed

Returns

The inner trait metrics

src.data_analysis_functions.compute_mean_opinion_difference(adjacency_matrix=None, opinion_distribution=None, num_agents=10, print_information=False)

This function computes the mean opinion difference, given an adjacency matrix and an opinion distribution

Parameters

adjacency_matrix: adjacency matrix opinion_distribution: opinion distribution num_agents: number of agents print_information: boolean determining whether the metric is shown or not

Returns

Mean opinion difference

src.data_analysis_functions.compute_opinion_metrics(opinion_distribution=None, num_agents=10, print_information=False)

This function computes the mean and mean of the absolute value of the opinion distribution

Parameters

opinion_distribution: the opinion distribution num_agents: number of agents print_information: boolean determining whether the print the information or not

Returns

The mean and mean of the absolute value of the opinion distribution

src.data_analysis_functions.compute_opinion_metrics_by_agent_type(opinion_distribution=None, inner_traits=None, num_agents=10, print_information=False)

This function computes the opinion metric by agent type

Parameters

opinion_distribution: the opinion distribution inner_traits: the inner traits num_agents: the number of agents print_information: boolean determining whether the metric is shown or not

Returns

The opinion metric by agent type

src.data_analysis_functions.compute_trait_allocation_metrics(adjacency_matrix=None, inner_traits=None, num_agents=10, print_information=False)

This function computes the mean inner trait difference between neighbours in the digraph

Parameters

adjacency_matrix: the corresponding digraph inner_traits: the corresponding inner trait assignation num_agents: the number of agents print_information: boolean determining whether the metric is shown or not

Returns

The mean inner trait difference between neighbours in the digraph

src.data_analysis_functions.feature_computation(num_agents=10, print_information=False, adjacency_matrix=None, opinion_distribution=None, inner_trait_assignations=None)

Function that computes the features for each sample

Parameters

num_agents: number of agents print_information: whether to print the information or not adjacency_matrix: the adjacency matrix opinion_distribution: the initial opinion distribution inner_trait_assignations: the inner trait assignation

Returns

The computed features

src.data_analysis_functions.gather_data(num_agents=1000, num_iterations=1000, global_name='default_name')

This function perform the three steps to gather the data for the training of the algorithms to predict the opinions. The three steps are to 1. create the inner traits, 2. create the initial opinions, and 3. compute the features

Parameters

num_agents: number of agents in the simulations, by default 1000 num_iterations: number of iterations or ‘samples’ by default 1000 global_name: the start of the name of the files where the resulting data will be saved

Returns

Nothing

src.data_analysis_functions.obtain_features(num_agents=1000, num_iterations=100, file_name=None, traits_file_name=None, opinions_file_name=None)

File to create the data for the training, validation, and testing

Parameters

num_agents: number of agents in all the simulations num_iterations: number of iterations file_name: name of the Excel data to print the output to traits_file_name: name of the file with the inner traits opinions_file_name: name of the file with the initial opinions

Returns

None

src.digraph_creation module

Digraph Creation, (f_abm.src.digraph_creation)

Description

This module contains all the digraph creation functions.

Functions

• default_digraph

• complete_digraph

• ring_digraph

• small_world_digraph

• random_digraph

src.digraph_creation.complete_digraph(num_agents=100, row_stochastic=False, positive_edge_ratio=1.0, print_text=False)

This is a function that returns a complete digraph

Parameters

num_agents: Is the number of agents (and therefore vertices) of the digraph. By default, it is 100 row_stochastic: A boolean that determines if the returned digraph must have a row-stochastic matrix. By default, this is False positive_edge_ratio: A floating number between 0 and 1 that determines the ratio of positive edges in the digraph. By default, it is 1 print_text: boolean to control whether the creation text information is shown

Returns

The adjacency matrix of the corresponding generalised ring digraph

src.digraph_creation.default_digraph(default_type=0, num_agents=10)

This function returns pre-made digraphs to be used primarily as default for functions. The pre-made digraph that will be called for default will always be the one with default_type=0

Parameters

default_type: ID of the default digraph num_agents: number of agents

Returns

The corresponding adjacency matrix

src.digraph_creation.random_digraph(num_agents=100, row_stochastic=False, positive_edge_ratio=1.0, edge_probability=0.5, print_text=False)

This function creates a digraph with random topology. Note that not all the edges are random. The resulting adjacency matrix always has non-zero elements in the diagonal, indicating the self-loop

Parameters

num_agents: number of agents of the digraph, by default 100 row_stochastic: boolean indicating if the adjacency matrix is row-stochastic positive_edge_ratio: the positive edge ratio edge_probability: the probability that an edge will exist print_text: boolean to control whether the creation text information is shown

Returns

the adjacency matrix

src.digraph_creation.ring_digraph(num_agents=100, topology_signature=None, row_stochastic=False, positive_edge_ratio=1.0, num_random_edges_it=0, print_text=False)

This is a function that returns a ring digraph

Parameters

num_agents: Is the number of agents (and therefore vertices) of the digraph. By default, it is 100 topology_signature: Is a list with the relative indices of the vertices that influence each agent. By default, it is [0, 1] row_stochastic: A boolean that determines if the returned digraph must have a row-stochastic matrix. By default, this is False positive_edge_ratio: A floating number between 0 and 1 that determines the ratio of positive edges in the digraph. By default, it is 1 num_random_edges_it: number of iterations to add random edges print_text: boolean to control whether the creation text information is shown

Returns

The adjacency matrix of the corresponding generalised ring digraph

src.digraph_creation.small_world_digraph(num_agents=100, topology_signature=None, row_stochastic=False, positive_edge_ratio=1.0, change_probability=0.0, reverse_probability=0.0, bidirectional_probability=0.0, num_random_edges_it=0, print_text=False)

This is a function that creates a digraph with small-world topology

Parameters

num_agents: number of agents, by default 100 topology_signature: the topology signature of the underlying ring digraph row_stochastic: whether the adjacency matrix is row-stochastic, by default False positive_edge_ratio: the positive edge ratio, by default 1 change_probability: the probability of edges changing target, it accepts a number between 0.0 and 1.0 or a list of ‘num_agents’ numbers between 0.0 and 1.0. Each element in the list corresponds to the change probability of the corresponding vertex reverse_probability: the probability of edges reversing target, it accepts a number between 0.0 and 1.0 or a list of ‘num_agents’ numbers between 0.0 and 1.0. Each element in the list corresponds to the reverse probability of the corresponding vertex bidirectional_probability: the probability of edges being bidirectional, it accepts a number between 0.0 and 1.0 or a list of ‘num_agents’ numbers between 0.0 and 1.0. Each element in the list corresponds to the probability of the corresponding vertex being bidirectional num_random_edges_it: number of iterations to add random edges print_text: boolean to control whether the creation text information is shown

Returns

The adjacency matrix associated with the corresponding small-world digraph

src.model_functions module

Model Functions, (f_abm.src.model_functions)

Description

This module contains all the model related functions, it includes all the functions to execute models, as well as functions to execute any model

Functions

• model_evolution

• cb_model_step

src.model_functions.cb_model_step(initial_opinions, adjacency_matrix, agent_parameters, model_parameters=(0.4, 2, 5))

This function takes a step with the Classification-based model

Parameters

initial_opinions: a list (or numpy array) of initial conditions adjacency_matrix: a list of lists representing the adjacency matrix agent_parameters: a list of lists containing the agent parameters, the first parameter is alpha and the second one is beta model_parameters: the parameter tuple lambda, xi, and mu

Returns

src.model_functions.model_evolution(initial_opinions=None, adjacency_matrix=None, agent_parameters=None, model_parameters=None, model_function=None, num_steps=50, default_type=0)

This function evolves a given model, with the give initial opinions, adjacency matrix, agent parameters, model parameters, and number of steps

Parameters

initial_opinions: numpy list of initial opinions. By default, it calls the function ‘create_opinions()’ adjacency_matrix: numpy 2d adjacency matrix. agent_parameters: agent parameters, what this is depends on the model. By default, it is ‘[[0.33, 0.33]]*100’ model_parameters: model parameters, what this is depends on the model. By default, it is ‘[0.4, 2, 5]’ model_function: function that evolves the steps of the model. By default, it is ‘cb_model_step’, i.e. it evolves the Classification-based model num_steps: prediction horizon, it is an integer. By default, it is 50 default_type: ID of the default digraph

Returns

A 2d numpy array with as many rows as agents, and as many columns as num_steps. Each row contains the opinion evolution of every agent.

src.plot_functions module

Functions for Plotting, (f_abm.src.plot_functions)

Description

This is the module that takes care of all the plotting, whether it is for opinion distributions (histograms), or digraphs, or whatever it is required.

Functions

• plot_digraph

• plot_opinions

• plot_histogram

• plot_inner_traits

• plot_all_opinions

src.plot_functions.plot_all_opinions(file_name='standard_initial_opinions.npy', color_by_type=False, figure_size=(10, 7), figure_title='Agreement Plot of all Opinions', figure_x_label='mean(abs(opinions))', figure_y_label='mean(opinions)', title_font_size=20, x_label_font_size=15, y_label_font_size=15)

Function to plot a set of opinion distributions in the Agreement Plot

Parameters

file_name: name of the file that contains all the initial opinion distributions color_by_type: boolean specifying how to color the plot figure_size: size of the figure to be produced figure_title: title of the plot figure_x_label: x label of the figure figure_y_label: y label of the figure title_font_size: size of the title x_label_font_size: x label text size y_label_font_size: y label text size

Returns

Nothing

src.plot_functions.plot_digraph(digraph=None, file_name=None, visual_style=None, close_figure=False, figure_size=(10, 7), figure_title='Underlying Digraph', title_font_size=20)

Function to plot the digraph

Parameters

digraph: Digraph to be plotted, by default it is a simple ring digraph file_name: string that is the name of the file to be plotted visual_style: optional visual style close_figure: boolean determining if the figure must be closed figure_size: size of the figure to be produced figure_title: title of the plot title_font_size: size of the title

Returns

src.plot_functions.plot_histogram(ax, opinions, num_bins=10, histogram_title='Histogram of the opinions', file_name=None, close_figure=False, figure_size=(10, 7), figure_x_label='Opinions', figure_y_label='Count', title_font_size=20, x_label_font_size=15, y_label_font_size=15)

This function creates and plots the histogram for a set of opinions

Parameters

ax: the axis where the histogram is plotted opinions: the set of opinions num_bins: the number of bins of the histogram, by default it is 10 histogram_title: title of the histogram file_name: string that is the name of the file to be plotted close_figure: boolean determining if the figure must be closed figure_size: size of the figure to be produced figure_x_label: x label of the figure figure_y_label: y label of the figure title_font_size: size of the title x_label_font_size: x label text size y_label_font_size: y label text size

Returns

Nothing

src.plot_functions.plot_inner_traits(file_name='standard_inner_traits.npy', figure_size=(10, 7), figure_title='Inner Traits', figure_x_label='Average conformist parameter', figure_y_label='Average radical parameter', title_font_size=20, x_label_font_size=15, y_label_font_size=15)

Function to plot the inner traits for the Classification-based model

Parameters

file_name: name of the file that contains the inner traits figure_size: size of the figure to be produced figure_title: title of the plot figure_x_label: x label of the figure figure_y_label: y label of the figure title_font_size: size of the title x_label_font_size: x label text size y_label_font_size: y label text size

Returns

Nothing

src.plot_functions.plot_opinions(opinion_evolution, agent_parameters, opinion_model, axes=None, file_name=None, close_figure=False, figure_size=(10, 7), figure_title='Opinion evolution', figure_x_label='Time steps', figure_y_label='Opinions', title_font_size=20, x_label_font_size=15, y_label_font_size=15)

Function to plot the opinion evolution

Parameters

opinion_evolution: matrix with the opinion evolution data agent_parameters: parameters for each agent opinion_model: the label of the opinion model axes: the axes for the plot file_name: string that is the name of the file to be plotted close_figure: boolean determining if the figure must be closed figure_size: size of the figure to be produced figure_title: title of the plot figure_x_label: x label of the figure figure_y_label: y label of the figure title_font_size: size of the title x_label_font_size: x label text size y_label_font_size: y label text size

Returns

Nothing

Module contents