Graphs API Reference

This page provides API reference documentation for the Graphs module, which contains functions for network graph analysis and visualization.

Graph Generation Functions

bmtool.graphs.generate_graph(config, source, target)

Generate a NetworkX graph from BMTK network configuration.

Parameters:

config : str Path to a BMTK simulation config file. source : str Network name for source nodes. target : str Network name for target nodes.

Returns:

nx.DiGraph A directed graph representing the network with nodes containing position and population information.

Source code in bmtool/graphs.py

def generate_graph(config, source, target):
    """
    Generate a NetworkX graph from BMTK network configuration.

    Parameters:
    -----------
    config : str
        Path to a BMTK simulation config file.
    source : str
        Network name for source nodes.
    target : str
        Network name for target nodes.

    Returns:
    --------
    nx.DiGraph
        A directed graph representing the network with nodes containing 
        position and population information.
    """
    nodes,edges = u.load_nodes_edges_from_config(config)
    nodes_source = nodes[source]
    nodes_target = nodes[target]
    if source != target:
        # Concatenate the DataFrames if source and target are different nodes
        nodes = pd.concat([nodes_source, nodes_target])
    else:
        nodes = nodes[source]
    edge_to_grap = source+"_to_"+target
    edges = edges[edge_to_grap]

    # Create an empty graph
    G = nx.DiGraph()

    # Add nodes to the graph with their positions and labels
    for index, node_data in nodes.iterrows():
        G.add_node(index, pos=(node_data['pos_x'], node_data['pos_y'], node_data['pos_z']), label=node_data['pop_name'])

    # Add edges to the graph
    for _, row in edges.iterrows():
        G.add_edge(row['source_node_id'], row['target_node_id'])

    return G

Graph Export Functions

bmtool.graphs.export_node_connections_to_csv(Graph, filename)

Generate a CSV file with node type and all incoming connections that node has.

Parameters:

Graph : nx.DiGraph A directed graph object from NetworkX. filename : str Path and filename for the output CSV file (must end in .csv).

Returns:

None The function saves the results to the specified CSV file.

Notes:

The resulting CSV file will have the node label as the first column, followed by columns for each type of incoming connection.

Source code in bmtool/graphs.py

def export_node_connections_to_csv(Graph, filename):
    """
    Generate a CSV file with node type and all incoming connections that node has.

    Parameters:
    -----------
    Graph : nx.DiGraph
        A directed graph object from NetworkX.
    filename : str
        Path and filename for the output CSV file (must end in .csv).

    Returns:
    --------
    None
        The function saves the results to the specified CSV file.

    Notes:
    ------
    The resulting CSV file will have the node label as the first column,
    followed by columns for each type of incoming connection.
    """
    # Create an empty dictionary to store the connections for each node
    node_connections = {}

    # Iterate over each node in the graph
    for node in Graph.nodes():
        # Initialize a dictionary to store the outgoing connections for the current node
        connections = {}
        node_label = Graph.nodes[node]['label']

        # Iterate over each presuccessor (ingoing neighbor) of the current node
        for successor in Graph.predecessors(node):
            # Get the label of the successor node
            successor_label = Graph.nodes[successor]['label']

            # Increment the connection count for the current node and successor label
            connections[f'{successor_label} incoming Connections'] = connections.get(f'{successor_label} incoming Connections', 0) + 1

        # Add the connections information for the current node to the dictionary
        connections['Node Label'] = node_label
        node_connections[node] = connections

    # Convert the dictionary to a DataFrame
    df = pd.DataFrame(node_connections).fillna(0).T

    # Reorder columns so that 'Node Label' is the leftmost column
    cols = df.columns.tolist()
    cols = ['Node Label'] + [col for col in cols if col != 'Node Label']
    df = df[cols]

    # Write the DataFrame to a CSV file
    df.to_csv(filename)