FIDDLE Functions

FIDDLE.BFA(start_model, possible_extensions, simulation_runs, simulation_length, output_directory)

The Breadth First Addition (BFA) extension methodology takes an model with missing information, possible extensions, and a simulation scheme to find the optimal combination of extensions that lowers the score.

Parameters

• start_model (string) – A name of the network file you want to extend using BFA.

• possible_extensions (list of lists) – A list of lists in which each list entry contains possible extensions used to extend the model.

• simulation_runs (integer) – The number of simulations to run. This is necessary as the simulator is stochastic, and you can observe different behavior with each simulation. Example = 10

• simulation_length (integer) – The number of time-steps or simulation updates performed during a simulation run. Example = 100

• output_directory (string) – The name of the folder in which the extension traces will be saved.

FIDDLE.DFA(start_model, possible_extensions, simulation_runs, simulation_length, output_directory)

The Depth First Addition (DFA) extension methodology takes a model with missing information, possible extensions, and a simulation scheme to find the optimal combination of extensions that lowers the score.

Parameters

• start_model (string) – A name of the network file you want to extend using BFA.

• possible_extensions (list of lists) – A list of lists in which each list entry contains possible extensions used to extend the model.

• simulation_runs (integer) – The number of simulations to run. This is necessary as the simulator is stochastic, and you can observe different behavior with each simulation. Example = 10

• simulation_length (integer) – The number of time-steps or simulation updates performed during a simulation run. Example = 100

• output_directory (string) – The name of the folder in which the extension traces will be saved.

FIDDLE.add_direction_to_undirected_network(G)

Adds directionality to an undirected graph G.

Parameters

G (nx.Graph()) – A randomly created graph using one of networkx’s many random graph generators.

Returns

H – This function returns a directed graph.

Return type

nx.DiGraph()

FIDDLE.add_regulation_to_directed_network(G, positive_probability)

Adds positive and negative regulation attributes to each edges of graph G.

Parameters

• G (nx.Graph()) – A randomly created graph using one of networkx’s many random graph generators.

• positive_probability (float [0-1]) – The probability that a edge in the network is positive.

Returns

H – This function returns a directed graph with a regulation attribute for each edge based on the positive_probability specified.

Return type

nx.DiGraph()

FIDDLE.create_extendable_models(G, output_folder, removal_probabilities, expected_end_values, model_name='network', positive_probability=0.5)

Function to create identical copies of the graph G, with different probabilities of missing edges. This is done in one function to ensure that an edges missing in a copy of G at low probability is also missing from a copy of G at a higher probability. This allows us to control for some edges being more “important” to model performance than others.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• output_folder (file path (string)) – A relative or absolute filepath that will house the new models

• removal_probabilities (list) – A list of probabilities (floats) in ascending order of edge removal Example: removal_probabilities = [0.1, 0.5] -> to have two models created missing about 10% and 50% of their edges. BE AWARE: removal_probabilities = [0.5, 0.1] -> WRONG… not in ascending order #TODO maybe I should just sort the list myself.

• expected_end_values (dictionary) – A dictionary with keys for each node in the true network file, and values for the node’s end value after simulation.

• model_name (string [default = 'network']) – Optional name to serve as base of created files.

• positive_probability (float [0-1]) – The probability that a newly created fake edge in the network is positive. This parallels the notation of network creation functions.

Returns

end_values – A dictionary with keys for each node in the network file, and values for the node’s end value after simulation.

Return type

dictionary

FIDDLE.create_initial_values(G, initial=1)

Returns a dictionary with SET initial values for each node in G.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• initial (integer [default = 1]) – An integer value to assign as the initial value for all of the nodes in the network.

Returns

initial_val_dic – A dictionary with keys for each node in G, and values for the initial value for the simulator.

Return type

dictionary

FIDDLE.create_initial_values_random(G, lower_bound=0, upper_bound=2)

Returns a dictionary with RANDOM initial values for each node in G.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• lower_bound (integer [default = 0]) – An integer value which serves as the lowest possible initial value permitted for a node in the network.

• upper_bound (integer [default = 2]) – An integer value which serves as the highest possible initial value permitted for a node in the network.

Returns

initial_val_dic – A dictionary with keys for each node in G, and values for the initial value for the simulator.

Return type

dictionary

FIDDLE.do_the_sub_stuff(H, data_file, count, edges, edge_num_1, edge_num_2, model_name, outPath, simRun, simLen, correct_val_dic)

FIDDLE.extend_model_file(filename, edge_group, output_name)

Function to to extend a model file with a list of edges and save it as a new model file. Used to be “extend_model”

Parameters

• filename (string) – The filename of the network excel file.

• edge_group (list) – List of edges with which to extend the model. Example: edge_group = [0, [‘1’,’2’,’+’], [‘2’,’3’,’-‘]] edge_group[0] is an artifact of edge group creation. Typically used to identify the extension group.

• output_name (string) – The filename for the new extended network excel file.

FIDDLE.extend_unit_breadth_sing(mdl, edges, ignore, simRun, simLen, outPath)

FIDDLE.extension_network_to_excel(filename, expected_end_values)

Saves the Network G to an excel file in a standardized format.

Parameters

• filename (string) – The filename of the network excel file.

• expected_end_values (dictionary) – A dictionary with keys for each node in the true network file, and values for the node’s end value after simulation.

FIDDLE.find_element_locations(filename)

Function to locate each model element in the model file. Used to be “getRow”

Parameters

filename (string) – The filename of the network excel file.

Returns

row_location_of_element – A dictionary with keys for each node in the network file, and values for the node’s row index.

Return type

dictionary

FIDDLE.get_model_edges(G)

Returns a list of all of G’s edges.

Parameters

G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

Returns

list_of_edges – A list of lists with all of the edges in G. Each edge is represented as a list of [source, target, regulation]. For example 1 -> 2 would be represented as [1,2,”+”]. For example 1 -| 2 would be represented as [1,2,”-“].

Return type

list of lists

FIDDLE.get_model_expected_values(filename)

Function to quickly retrieve the expected values for a model’s simulation. Used to be “get_golden” :param filename: The filename of the network excel file. :type filename: string

Returns

end_values – A dictionary with keys for each node in the network file, and values for the node’s end value after simulation.

Return type

dictionary

FIDDLE.get_score_between_expected_and_actual(expected_values, simulation_end_values)

Function to calculate the difference between the expected values for a perfect model’s simulation and the actual values on an unextended model.

Used to be “get_diff”

Parameters

• expected_values (dictionary) – The dictionary containing the expected end values for each element in the model.

• simulation_end_values (dictionary) – The dictionary containing a simulation’s end values for each element in the model.

Returns

total_difference – The absoluate difference between the expected values and the simulation end values as a rough calculation for how different a model is from expectation.

Return type

float

FIDDLE.get_simulation_end_values(filename, simulation_runs)

Returns the end values of the network simulation, based on the simulation trace file. The variable ‘simulation_runs’ is necessary to normalize the end_values based on the number of simulations performed.

Parameters

• filename (string) – The name of the txt file with the simulation trace output. Example = “network_trace.txt”

• simulation_runs (integer) – The number of simulations to run. This is necessary as the simulator is stochastic, and you can observe different behavior with each simulation. Example = 10

Returns

end_values – A dictionary with keys for each node in the network file, and values for the node’s end value after simulation.

Return type

dictionary

FIDDLE.graph_maker(network_type, nodes, positive_probability, edge_probability=0.5, attaching_edges=2)

Automatically creates a directed network with positive and negative edges of a particular type.

Parameters

• network_type (int) –

  A quick and easy manner to specify the type of graph you would like created:

  1 = networkx.gn_graph() = a growing network (GN) digraph with n nodes. 2 = networkx.gnr_graph() = a growing network with redirection (GNR) digraph with n nodes and redirection probability p. 3 = networkx.gnc_graph() = a growing network with copying (GNC) digraph with n nodes. 4 = networkx.gnp_random_graph() = an Erdős-Rényi graph or a binomial graph. 5 = networkx.barabasi_albert_graph() = a random graph according to the Barabási–Albert preferential attachment model. More information is available at: https://networkx.org/documentation/stable/reference/generators.html

• nodes (int) – The desired number of nodes in the network.

• positive_probability (float [0-1]) – The probability that a edge in the network is positive.

• edge_probability (float [0-1] #TODO) – A network-type parameter which changes based on the type of network selected. Only affects type 2 and 4. In network_type == 2: ‘edge_probability’ referes the the probability and edge is redirected. In network_type == 4: ‘edge_probability’ referes the the probability that an edge is created.

• attaching_edges (int [must be >=1 but <nodes]) – Only affectes network_type == 5. This parameter specifies the number of edges to attach from a new node to existing nodes.

Returns

Network – This function returns a directed network with positive and negative edges based on the input parameters specified. If the network cannot be created based on your specifications, ‘Network’ is returned as ‘None’.

Return type

nx.DiGraph()

FIDDLE.network_to_excel(G, filename='network_full.xlsx')

Saves the Network G to an excel file in a standardized format.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• filename (string [default = 'network_full.xlsx']) – The filename for the output to be save to.

FIDDLE.parallelize_get_diff(ext, trace, golden, simRun)

FIDDLE.plot_network(G, save=False, filename='test.png')

Plots Network G in a quick and easy function.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• save (Bool [default = False]) – Whether or not to save the plot of the network to a file. True = Yes False = No

• filename (string [default = 'test.png']) – If save == True, you can specify a filename for the output to be save to.

FIDDLE.recursive_addition_for_DFA(current_best_model, simulation_end_values, possible_extensions, already_added_extensions, simulation_runs, simulation_length, iteration, current_score, output_directory, diff_trend, start_time)

This recursive function continues to extend a baseline model with the first extenion to improve the model until no extension improves the model. This function is exclusively used by the DFA() function.

Parameters

• current_best_model (string) – The name of the current network file you want to extend using DFA.

• simulation_end_values (dict) – A dictionary

• possible_extensions (list of lists) – A list of lists in which each list entry contains possible extensions used to extend the model.

• already_added_extensions (set) – A set of numbers indicating which extensions have already been added to the model.

• simulation_runs (integer) – The number of simulations to run. This is necessary as the simulator is stochastic, and you can observe different behavior with each simulation. Example = 10

• simulation_length (integer) – The number of time-steps or simulation updates performed during a simulation run. Example = 100

• iteration (integer) – A number representing the number of recursions that have gone been gone through. Mostly used in notation/nomenclature.

• current_score (float) – A float indicating the current best score obtained during the extension process. Used to measure if a new extension improves the model.

• output_directory (string) – The name of the folder in which the extension traces will be saved.

• diff_trend (list) – A list collecting the incremental improvement in the score. Used to report the steps taken to improve the model.

• start_time (datetime.datetime.now() object) – The time the extension method started. Used to record the total elapsed time.

FIDDLE.return_extension_stats(base_name, G, real_edges, fake_edges, verbose=True, save=False, filename='model_stats.txt')

Returns descriptive statistics of the network for extension.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• real_edges (list) – A list of edges that were removed from the baseline model.

• fake_edges (list) – A list of edges that were never in the baseline model but used to test extension fidelity.

• verbose (Bool [default = True]) – Whether or not to return network’s descriptive statistics to the console. True = Yes False = No

• save (Bool [default = False]) – Whether or not to save the network’s descriptive statistics in a file. True = Yes False = No

• filename (string [default = 'model_stats.txt']) – If save == True, you can specify a filename for the output to be save to.

FIDDLE.return_model_stats(G, network_type, nodes, positive_probability, edge_probability=0.5, attaching_edges=2, verbose=True, save=False, filename='model_stats.txt')

Returns descriptive statistics of the network. Follows similar input scheme as graph_maker.

Parameters

• G (nx.DiGraph()) – A randomly created graph using one of networkx’s many random graph generators.

• network_type (int) –

  A quick and easy manner to specify the type of graph you would like created:

  1 = networkx.gn_graph() = a growing network (GN) digraph with n nodes. 2 = networkx.gnr_graph() = a growing network with redirection (GNR) digraph with n nodes and redirection probability p. 3 = networkx.gnc_graph() = a growing network with copying (GNC) digraph with n nodes. 4 = networkx.gnp_random_graph() = an Erdős-Rényi graph or a binomial graph. 5 = networkx.barabasi_albert_graph() = a random graph according to the Barabási–Albert preferential attachment model. More information is available at: https://networkx.org/documentation/stable/reference/generators.html

• nodes (int) – The desired number of nodes in the network.

• positive_probability (float [0-1]) – The probability that a edge in the network is positive.

• edge_probability (float [0-1] #TODO) – A network-type parameter which changes based on the type of network selected. Only affects type 2 and 4. In network_type == 2: ‘edge_probability’ referes the the probability and edge is redirected. In network_type == 4: ‘edge_probability’ referes the the probability that an edge is created.

• attaching_edges (int [must be >=1 but <nodes]) – Only affectes network_type == 5. This parameter specifies the number of edges to attach from a new node to existing nodes.

• verbose (Bool [default = True]) – Whether or not to return network’s descriptive statistics to the console. True = Yes False = No

• save (Bool [default = False]) – Whether or not to save the network’s descriptive statistics in a file. True = Yes False = No

• filename (string [default = 'model_stats.txt']) – If save == True, you can specify a filename for the output to be save to.

FIDDLE.score_actual_against_expected_values(expected_dict, actual_dict)

Function to quickly retrieve the expected values for a model’s simulation. Used to be “get_diff_score”

Parameters

• expected_dict (dictionary) – A dictionary with keys for each node in the network file, and values for the node’s end value after simulation. Typically this is the “end_vals” dictionary taken from simulating the original network model.

• actual_dict (dictionary) – A dictionary with keys for each node in the network file, and values for the node’s end value after simulation. Typically this is the “end_vals” dictionary taken from simulating a network model with missing edges.

Returns

score – The absolute error/difference between the expected simulation end values and the actual simulation end values.

Return type

float

FIDDLE.sim_and_get_diff(G, outPath, model_name, simRun, simLen, correct_val_dic)

FIDDLE.simulate_network(filename, simulation_runs, simulation_length, output_file='network_trace.txt')

Simulate an initialized network file.

Parameters

• filename (string) – The name of the excel file with the initialized network. Example = “network_full.xlsx”

• simulation_runs (integer) – The number of simulations to run. This is necessary as the simulator is stochastic, and you can observe different behavior with each simulation. Example = 10

• simulation_length (integer) – The number of time-steps or simulation updates performed during a simulation run. Example = 100

• output_file (string [default = "network_trace.txt"]) – The name of the file in which the simulation trace will be saved.

FIDDLE.update_network_file(filename, update_column, update_values)

Function to quickly input initial and final values for simulations.

Parameters

• filename (string) – The filename of the network excel file.

• update_column (integer) – The column location you wish to update. Frequently this is the initial values column (6), or the final values column (7).

• update_values (dictionary) – A dictionary with keys for each node in the network file, and the corresponding values you wish to input for that row (values).