API Overview

Below is the list of all functions available in py-graspi:

Descriptor Functions
py_graspi.descriptors.compute_descriptors(graph_data, filename, pixelSize=1)[source]

This function computes all the descriptors for the graph given and saves them in a dictionary.

Parameters:

  • graph_data (GraphData) – The graph data.

  • filename (str) – The file used to generate graphs to compute on.

  • pixelsize (float) – The pixel size of the graph.

Returns:

A dictionary containing all the descriptors. The dictionary stores the outputted data in key:value pairs, the unique keys are linked to the associated value.

The keys of the descriptors are as follow: STAT_n, STAT_e, STAT_n_D, STAT_n_A, STAT_CC_D, STAT_CC_A, STAT_CC_D_An, STAT_CC_A_Ca, ABS_wf_D, ABS_f_D, DISS_f10_D, DISS_wf10_D, CT_f_e_conn, CT_f_conn_D_An, CT_f_conn_A_Ca, CT_e_conn, CT_e_D_An, CT_e_A_Ca, CT_n_D_adj_An, CT_n_A_adj_Ca, CT_f_D_tort1, CT_f_A_tort1. For full definitions see the “Descriptors” tab on the Py-Graspi documentation website.

Return type:

descriptors_dict

py_graspi.descriptors.descriptorsToTxt(descriptors_dict, fileName)[source]

This function writes a dictionary of descriptors to the specified text file.

Parameters:

  • descriptors_dict (dict) – The dictionary of descriptors.

  • fileName (str) – The name of the file to write to.

Returns:

None

py_graspi.descriptors.readDescriptorsFromTxt(fileName)[source]

This function reads a text file and returns a dictionary of descriptors to standard output.

Parameters:

fileName (str) – The name of the file to read from.

Returns:

None

py_graspi.descriptors.printDescriptors(dict)[source]

This function prints descriptors to standard output.

Parameters:

dict (dict) – The dictionary of descriptors.

Returns:

None, but standard outputs descriptors.

py_graspi.descriptors.CC_descriptors(graph_data)[source]

This function computes the connected component descriptors that correspond to the following descriptors: STAT_CC_D, STAT_CC_A, STAT_CC_D_An, STAT_CC_A_Ca, CT_f_conn_D_An, CT_f_conn_A_Ca, countBlack_Red_conn, and countWhite_Blue_conn. Auxiliary quantities such as, ‘countBlack_Red_conn’ and ‘countWhite_Blue_conn’ are only used to compute CT_f_conn_D_An and CT_f_conn_A_Ca.

Parameters:

graph_data (graph_data_class) – The input graph object.

Returns:

The updated graph object.

Return type:

graph_data (graph_data_class)

py_graspi.descriptors.shortest_path_descriptors(graph_data, filename, pixelSize=1)[source]

This function computes descriptors related to shortest paths with vertex and metavertex colorations that correspond to the following descriptors: DISS_f10_D, DISS_wf10_D, CT_f_D_tort1, CT_f_A_tort1 and ABS_wf_D. The inputs countBlack_Red_conn and countWhite_Blue_conn are stored in the graph_data_class object generated by the ‘CC_descriptors’ function.

Parameters:

  • graph_data (graph_data_class) – The graph data object.

  • filename (str) – Base filename for output text files storing the results.

  • pixelSize (float) – The pixel size of the graph in pixels.

Returns:

The updated graph data object with shortest path descriptors

Return type:

graph_data (graph_data_class)

py_graspi.descriptors.filterGraph_metavertices(graph)[source]

This function filters a graph by only keeping the edges that connect vertices of the same color and metavertices.

Parameters:

graph (ig.Graph) – The input graph.

Returns:

The filtered graph of vertices of the same color and green metavertex. ig.Graph: The filtered graph of vertices of the same color and blue metavertex. ig.Graph: The filtered graph of vertices of the same color and green metavertex. ig.Graph: The filtered graph of vertices of the same color and red metavertex.

Return type:

ig.Graph

py-graspi Functions
py_graspi.graph.generateGraph(file, PERIODICITY=False)[source]

This function takes in graph data and determines if it’s in .txt or .graphe format in order to represent the graph using an adjacency list and the correct dimensionality.

Parameters:

  • file (str) – The name of the file containing graph data.

  • periodicity (bool) – Boolean representing if graph has periodic boundary conditions

Returns:

This function generates a graph based on the input so the return type depends on the format of graph data that was given. See “generateGraphAdj” if in .txt, or “generateGraphGraphe” if in .graphe.

py_graspi.graph.generateGraphAdj(file, PERIODICITY=False)[source]

This function takes in graph data in the .txt format and constructs the graph with adjacency list representation. It also generates additional graph data stored in the graph_data object.

Parameters:

file (str) – The name of the file containing the graph data.

Returns:

The graph data.

Return type:

graph_data (graph_data_class)

py_graspi.graph.generateGraphGraphe(file)[source]

This function takes in graph data in the .graphe format and constructs the graph with adjacency list representation.

Parameters:

file (str) – The name of the file containing graph data.

Returns:

The graph representation of the given data is_2D (bool): This is true if the graph represents a 2D structure, and false if it represents a 3D

Return type:

g (igraph.Graph)

py_graspi.graph.adjList(fileName)[source]

This function creates an adjacency list based on the graph data provided. An adjacency list represents a set of edges in the graph. It also generates additional graph data stored in the graph_data object. It also counts the vertices connected to interface edges.

Parameters:

filename (str) – The name of the file containing the graph data.

Returns:

The graph data. edges_with_green({vertex : edge_info}dictionary): Storing edges connected with green vertex)

Return type:

graph_data (graph_data_class)

py_graspi.graph.graphe_adjList(filename)[source]

This function creates the adjacency list for graph data given in .graphe format, it categorizes neighbors of vertices into first, second, and third order. This function is called inside the “generateGraphGraphe” function to help create the necessary information to generate the final graph.

Parameters:

filename (str) – The name of the file containing the graph data.

Returns:

The graph data containing graph, is_2D, first_order_neighbors, second_order_neighbors, and third_order_neighbors attributes

Return type:

graph_data (graph_data_class)

py_graspi.graph.adjvertexColors(fileName)[source]

This function assigns each vertex a color label based on the data in the specified file and returns a list where each index corresponds to a vertex’s color.

Parameters:

fileName (str) – The name of the file containing the vertex color data.

Returns:

This list contains color labels (‘black’, ‘white’, ‘red’, or ‘blue’) for each vertex or metavertex in the graph.

Return type:

labels (list)

py_graspi.graph.visualize(graph, is_2D)[source]

This function shows a visualization of the given graph in either 2D or 3D depending on the is_2D boolean.

Parameters:

  • graph (igraph.Graph) – The given graph to visualize.

  • is_2D (bool) – This is true if the graph represents a 2D structure, and false if it represents a 3D

Returns:

This function does not return a value, it performs an action by outputting the visualization of the given graph using plt.

py_graspi.graph.connectedComponents(graph)[source]

This function identifies the connected components of a filtered graph and returns lists that contain the vertices that are part of the connected components. It filters based on ‘black’ vertices that connect to the ‘red’ metavertex and ‘white’ vertices that connect to the ‘blue’ metavertex.

Parameters:

graph (ig.Graph) – The input graph.

Returns:

The list will contain a list or several lists, depending on how many connected components there are. Each list contains the vertices that are part of the connected component.

Return type:

connected_comp (list)

py_graspi.graph.filterGraph(graph)[source]

This function returns a subgraph that is created by filtering the given graph to only contain edges that connect vertices of the same color.

Parameters:

graph (ig.Graph) – The input graph.

Returns:

The filtered graph with only edges between the same color vertices.

Return type:

filteredGraph (igraph.Graph)

py_graspi.graph.filterGraph_metavertices(graph)[source]

This function filters the given graph into two subgraphs, one that contains all the edges that connect vertices of the same color or involve the ‘blue’/cathode metavertex, and one that contains all the edges that connect the vertices of the same color or involve the ‘red’/anode metavertex.

Parameters:

graph (ig.Graph) – The input graph.

Returns:

This is a subgraph that only contains the edges that either connect vertices of the same color or involve a ‘blue’ vertex. fg_red (igraph.Graph): This is a subgraph that only contains the edges that either connect vertices of the same color or involve a ‘red’ vertex.

Return type:

fg_blue (igraph.Graph)

py_graspi.graph.filterGraph_blue_red(graph)[source]

This function filters the given graph into two subgraphs, one that contains all the edges that connect vertices of the same color or involve the ‘blue’ cathode metavertex, and one that contains all the edges that connect the vertices of the same color or involve the ‘red’ anode metavertex.

Parameters:

graph (ig.Graph) – The input graph.

Returns:

This is a subgraph that only contains the edges that either connect vertices of the same color or involve a ‘blue’ metavertex. fg_red (igraph.Graph): This is a subgraph that only contains the edges that either connect vertices of the same color or involve a ‘red’ metavertex.

Return type:

fg_blue (igraph.Graph)

Graph Class
class py_graspi.graph_data_class.graph_data_class(graph: Graph, is_2D: bool)[source]

Bases: object

Class to store all graph parameters in a single object, reducing redundant function returns.

Attributes:

  • graph (ig.Graph): Stores the igraph graph object.

  • is_2D (bool): Indicates whether the graph is 2D.

  • black_vertices (list): A list to store black vertices in the graph.

  • white_vertices (list): A list to store white vertices in the graph.

  • shortest_path_to_red (Optional[list]): Stores the shortest path to the red vertex.

  • shortest_path_to_blue (Optional[list]): Stores the shortest path to the blue vertex.

  • black_green (int): Computed descriptor for black-green interaction.

  • black_interface_red (int): Computed descriptor for the black-red interface.

  • white_interface_blue (int): Computed descriptor for the white-blue interface.

  • dim (int): Dimension descriptor for the graph.

  • interface_edge_comp_paths (int): Number of interface edges in computed paths.

  • STAT_n_D (int): Number of black vertices.

  • STAT_n_A (int): Number of white vertices.

  • STAT_CC_D (int): Components with at least one black vertex.

  • STAT_CC_A (int): Components with at least one white vertex.

  • STAT_CC_D_An (int): Black components connected to red vertex.

  • STAT_CC_A_Ca (int): White components connected to blue vertex.

  • CT_f_conn_D_An (float): Fraction of black vertices connected to red.

  • CT_f_conn_A_Ca (float): Fraction of white vertices connected to blue.

  • CT_n_D_adj_An (int): Some computed descriptor.

  • CT_n_A_adj_Ca (int): Another computed descriptor.

  • countBlack_Red_conn (int): Black vertices in red-connected components.

  • countWhite_Blue_conn (int): White vertices in blue-connected components.

  • DISS_f10_D (float): Fraction of black vertices <10px from green.

  • DISS_wf10_D (float): Weighted fraction of black vertices <10px from green.

  • CT_f_D_tort1 (float): Fraction of black vertices with tortuosity to red < tol.

  • CT_f_A_tort1 (float): Fraction of white vertices with tortuosity to blue < tol.

  • ABS_wf_D (float): Weighted distance of black vertices from red.

  • redVertex (Optional[Any]): Reference to the red vertex.

  • blueVertex (Optional[Any]): Reference to the blue vertex.

  • first_order_neighbors (list): This is a list of all the first-order pairs.

  • second_order_neighbors (list): This is a list of all the second-order pairs.

  • third_order_neighbors (list): This is a list of all the third-order pairs.

Parameters:

  • graph (ig.Graph) – The igraph graph object representing the structure.

  • is_2D (bool) – Boolean indicating whether the graph is 2D

__init__(graph: Graph, is_2D: bool)[source]

Initialize the graph_data_class object with a graph and its properties.

compute_shortest_paths(red_vertex, blue_vertex)[source]

Compute and store shortest paths from red and blue vertices.