Layouts

NodePosition

class graspologic.layouts.NodePosition[source]

Contains the node id, 2d coordinates, size, and community id for a node.

Create new instance of NodePosition(node_id, x, y, size, community)

node_id: str

Alias for field number 0

x: float

Alias for field number 1

y: float

Alias for field number 2

size: float

Alias for field number 3

community: int

Alias for field number 4

static __new__(_cls, node_id, x, y, size, community)

Create new instance of NodePosition(node_id, x, y, size, community)

Parameters:
count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

Automatic Graph Layout

graspologic.layouts.layout_tsne(graph, perplexity, n_iter, max_edges=10000000, weight_attribute='weight', random_seed=None, adjust_overlaps=True)[source]

Automatic graph layout generation by creating a generalized node2vec embedding, then using t-SNE for dimensionality reduction to 2d space.

By default, this function automatically attempts to prune each graph to a maximum of 10,000,000 edges by removing the lowest weight edges. This pruning is approximate and will leave your graph with at most max_edges, but is not guaranteed to be precisely max_edges.

In addition to pruning edges by weight, this function also only operates over the largest connected component in the graph.

After dimensionality reduction, sizes are generated for each node based upon their degree centrality, and these sizes and positions are further refined by an overlap removal phase. Lastly, a global partitioning algorithm (graspologic.partition.leiden()) is executed for the largest connected component and the partition ID is included with each node position.

Parameters:
graphnetworkx.Graph

The graph to generate a layout for. This graph may have edges pruned if the count is too high and only the largest connected component will be used to automatically generate a layout.

perplexityint

The perplexity is related to the number of nearest neighbors that is used in other manifold learning algorithms. Larger datasets usually require a larger perplexity. Consider selecting a value between 4 and 100. Different values can result in significantly different results.

n_iterint

Maximum number of iterations for the optimization. We have found in practice that larger graphs require more iterations. We hope to eventually have more guidance on the number of iterations based on the size of the graph and the density of the edge connections.

max_edgesint

The maximum number of edges to use when generating the embedding. Default is 10000000. The edges with the lowest weights will be pruned until at most max_edges exist. Warning: this pruning is approximate and more edges than are necessary may be pruned. Running in 32 bit environment you will most likely need to reduce this number or you will out of memory.

weight_attribute: str

The edge dictionary data attribute that holds the weight. Default is weight. Note that the graph must be fully weighted or unweighted.

random_seedint

Seed to be used for reproducible results. Default is None and will produce a new random state. Specifying a random state will provide consistent results between runs. In addition the environment variable PYTHONHASHSEED must be set to control hash randomization.

adjust_overlapsbool

Make room for overlapping nodes while maintaining some semblance of the 2d spatial characteristics of each node. Default is True

Returns:
Tuple[nx.Graph, List[NodePosition]]

The largest connected component and a list of NodePositions for each node in the largest connected component. The NodePosition object contains: - node_id - x coordinate - y coordinate - size - community

Parameters:

  • graph (Graph) --

  • perplexity (int) --

  • n_iter (int) --

  • max_edges (int) --

  • weight_attribute (str) --

  • random_seed (int | None) --

  • adjust_overlaps (bool) --

Return type:

Tuple[Graph, List[NodePosition]]

References

[1]

van der Maaten, L.J.P.; Hinton, G.E. Visualizing High-Dimensional Data Using t-SNE. Journal of Machine Learning Research 9:2579-2605, 2008.

graspologic.layouts.layout_umap(graph, min_dist=0.75, n_neighbors=25, max_edges=10000000, weight_attribute='weight', random_seed=None, adjust_overlaps=True)[source]

Automatic graph layout generation by creating a generalized node2vec embedding, then using UMAP for dimensionality reduction to 2d space.

By default, this function automatically attempts to prune each graph to a maximum of 10,000,000 edges by removing the lowest weight edges. This pruning is approximate and will leave your graph with at most max_edges, but is not guaranteed to be precisely max_edges.

In addition to pruning edges by weight, this function also only operates over the largest connected component in the graph.

After dimensionality reduction, sizes are generated for each node based upon their degree centrality, and these sizes and positions are further refined by an overlap removal phase. Lastly, a global partitioning algorithm (graspologic.partition.leiden()) is executed for the largest connected component and the partition ID is included with each node position.

Parameters:
graphnetworkx.Graph

The graph to generate a layout for. This graph may have edges pruned if the count is too high and only the largest connected component will be used to automatically generate a layout.

min_distfloat

The effective minimum distance between embedded points. Default is 0.75. Smaller values will result in a more clustered/clumped embedding where nearby points on the manifold are drawn closer together, while larger values will result on a more even dispersal of points. The value should be set relative to the spread value, which determines the scale at which embedded points will be spread out.

n_neighborsint

The size of local neighborhood (in terms of number of neighboring sample points) used for manifold approximation. Default is 25. Larger values result in more global views of the manifold, while smaller values result in more local data being preserved.

max_edgesint

The maximum number of edges to use when generating the embedding. Default is 10000000. The edges with the lowest weights will be pruned until at most max_edges exist. Warning: this pruning is approximate and more edges than are necessary may be pruned. Running in 32 bit environment you will most likely need to reduce this number or you will out of memory.

weight_attribute: str

The edge dictionary data attribute that holds the weight. Default is weight. Note that the graph must be fully weighted or unweighted.

random_seedint

Seed to be used for reproducible results. Default is None and will produce random results.

adjust_overlapsbool

Make room for overlapping nodes while maintaining some semblance of the 2d spatial characteristics of each node. Default is True

Returns:
Tuple[nx.Graph, List[NodePosition]]

The largest connected component and a list of NodePositions for each node in the largest connected component. The NodePosition object contains: - node_id - x coordinate - y coordinate - size - community

Parameters:

  • graph (Graph) --

  • min_dist (float) --

  • n_neighbors (int) --

  • max_edges (int) --

  • weight_attribute (str) --

  • random_seed (int | None) --

  • adjust_overlaps (bool) --

Return type:

Tuple[Graph, List[NodePosition]]

References

[1]

McInnes, L, Healy, J, UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction, ArXiv e-prints 1802.03426, 2018

[2]

Böhm, Jan Niklas; Berens, Philipp; Kobak, Dmitry. A Unifying Perspective on Neighbor Embeddings along the Attraction-Repulsion Spectrum. ArXiv e-prints 2007.08902v1, 17 Jul 2020.

Colors

graspologic.layouts.categorical_colors(partitions, light_background=True, theme_path=None)[source]

Generates a node -> color mapping based on the partitions provided.

The partitions are ordered by population descending, and a series of perceptually balanced, complementary colors are chosen in sequence.

If a theme_path is provided, it must contain a path to a json file generated by Thematic, otherwise it will use the theme packaged with this library.

Colors will be different when selecting for a light background vs. a dark background, using the principles defined by Thematic.

If more partitions than colors available (100) are selected, the colors will be cycled through again.

Parameters:
partitionsDict[Any, int]

A dictionary of node ids to partition ids.

light_backgroundbool

Default is True. Colors selected for a light background will be slightly different in hue and saturation to complement a light or dark background.

theme_pathOptional[str]

A color scheme is provided with graspologic, but if you wish to use your own you can generate one with Thematic and provide the path to it to override the bundled theme.

Returns:
Dict[Any, str]

Returns a dictionary of node id -> color based on the partitions provided.

Parameters:

  • partitions (Dict[Any, int]) --

  • light_background (bool) --

  • theme_path (str | None) --

Return type:

Dict[Any, str]

graspologic.layouts.sequential_colors(node_and_value, light_background=True, use_log_scale=False, theme_path=None)[source]

Generates a node -> color mapping where a color is chosen for the value as it maps the value range into the sequential color space.

If a theme_path is provided, it must contain a path to a json file generated by Thematic, otherwise it will use the theme packaged with this library.

Colors will be different when selecting for a light background vs. a dark background, using the principles defined by Thematic.

If more partitions than colors available (100) are selected, the colors will be cycled through again.

Parameters:
node_and_valueDict[Any, float]

A node to value mapping. The value is a single entry in a continuous range, which is then mapped into a sequential color space.

light_backgroundbool

Default is True. Colors selected for a light background will be slightly different in hue and saturation to complement a light or dark background.

use_log_scalebool

Default is False.

theme_pathOptional[str]

A color scheme is provided with graspologic, but if you wish to use your own you can generate one with Thematic and provide the path to it to override the bundled theme.

Returns:
Dict[Any, str]

Returns a dictionary of node id -> color based on the original value provided for the node as it relates to the total range of all values.

Parameters:

  • node_and_value (Dict[Any, float]) --

  • light_background (bool) --

  • use_log_scale (bool) --

  • theme_path (str | None) --

Return type:

Dict[Any, str]

Rendering

graspologic.layouts.save_graph(output_path, graph, positions, node_colors, vertex_line_width=0.01, vertex_alpha=0.55, edge_line_width=0.5, edge_alpha=0.02, figure_width=15.0, figure_height=15.0, light_background=True, vertex_shape='o', arrows=False, dpi=100)[source]

Renders a graph to file.

Edges will be displayed with the same color as the source node.

Parameters:
output_pathstr

The output path to write the rendered graph to. Suggested file extension is .png.

graphnx.Graph

The graph to be displayed. If the networkx Graph contains only nodes, no edges will be displayed.

positionsList[graspologic.layouts.NodePosition]

The positionsfor every node in the graph.

node_colorsDict[Any, str]

A mapping of node id to colors. Must contain an entry for every node in the graph.

vertex_line_widthfloat

Line width of vertex outline. Default is``0.01``.

vertex_alphafloat

Alpha (transparency) of vertices in visualization. Default is``0.55``.

edge_line_widthfloat

Line width of edge. Default is``0.5``.

edge_alphafloat

Alpha (transparency) of edges in visualization. Default is``0.02``.

figure_widthfloat

Width of figure. Default is 15.0.

figure_heightfloat

eight of figure. Default is``15.0``.

light_backgroundbool

Light background or dark background. Default is``True``.

vertex_shapestr

Matplotlib Marker for the vertex shape. See https://matplotlib.org/api/markers_api.html for a list of allowed values . Default is o (i.e: a circle)

arrowsbool

For directed graphs, if True, draw arrow heads. Default is False

dpifloat

Dots per inch of the figure. Default is 100.

Returns:
Parameters:
Return type:

None

graspologic.layouts.show_graph(graph, positions, node_colors, vertex_line_width=0.01, vertex_alpha=0.55, edge_line_width=0.5, edge_alpha=0.02, figure_width=15.0, figure_height=15.0, light_background=True, vertex_shape='o', arrows=False, dpi=500)[source]

Renders and displays a graph.

Attempts to display it via the platform-specific display library such as TkInter

Edges will be displayed with the same color as the source node.

Parameters:
graphnx.Graph

The graph to be displayed. If the networkx Graph contains only nodes, no edges will be displayed.

positionsList[graspologic.layouts.NodePosition]

The positionsfor every node in the graph.

node_colorsDict[Any, str]

A mapping of node id to colors. Must contain an entry for every node in the graph.

vertex_line_widthfloat

Line width of vertex outline. Default is``0.01``.

vertex_alphafloat

Alpha (transparency) of vertices in visualization. Default is``0.55``.

edge_line_widthfloat

Line width of edge. Default is``0.5``.

edge_alphafloat

Alpha (transparency) of edges in visualization. Default is``0.02``.

figure_widthfloat

Width of figure. Default is 15.0.

figure_heightfloat

eight of figure. Default is``15.0``.

light_backgroundbool

Light background or dark background. Default is``True``.

vertex_shapestr

Matplotlib Marker for the vertex shape. See https://matplotlib.org/api/markers_api.html for a list of allowed values . Default is o (i.e: a circle)

arrowsbool

For directed graphs, if True, draw arrow heads. Default is False

dpifloat

Dots per inch of the figure. Default is 500.

Parameters:
Return type:

None