graphistry.plugins package

graphistry.plugins package#

Submodules#

graphistry.plugins.cugraph module#

graphistry.plugins.cugraph.compute_cugraph(self, alg, out_col=None, params={}, kind='Graph', directed=True, G=None)#

Run cugraph algorithm on graph. For algorithm parameters, see cuGraph docs.

Parameters:

alg (str) – algorithm name
out_col (Optional[str]) – node table output column name, defaults to alg param
params (dict) – algorithm parameters passed to cuGraph as kwargs
kind (CuGraphKind) – kind of cugraph to use
directed (bool) – whether graph is directed
G (Optional[cugraph.Graph]) – cugraph graph to use; if None, use self
self (Plottable)

Returns:

Plottable

Return type:

Plottable

Example: Pass params to cugraph

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('betweenness_centrality', params={'k': 2})
assert 'betweenness_centrality' in g2._nodes.columns

Example: Pagerank

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('pagerank')
assert 'pagerank' in g2._nodes.columns

Example: Personalized Pagerank

::: edges = pd.DataFrame({‘s’: [‘a’,’b’,’c’,’d’], ‘d’: [‘c’,’c’,’e’,’e’]}) g = graphistry.edges(edges, ‘s’, ‘d’) g2 = g.compute_cugraph(‘pagerank’, params={‘personalization’: cudf.DataFrame({‘vertex’: [‘a’], ‘values’: [1]})}) assert ‘pagerank’ in g2._nodes.columns

Example: Katz centrality with rename

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('katz_centrality', out_col='katz_centrality_renamed')
assert 'katz_centrality_renamed' in g2._nodes.columns

graphistry.plugins.cugraph.compute_cugraph_core(self, alg, out_col=None, params={}, kind='Graph', directed=True, G=None)#

Run cugraph algorithm on graph. For algorithm parameters, see cuGraph docs.

Parameters:

alg (str) – algorithm name
out_col (Optional[str]) – node table output column name, defaults to alg param
params (dict) – algorithm parameters passed to cuGraph as kwargs
kind (CuGraphKind) – kind of cugraph to use
directed (bool) – whether graph is directed
G (Optional[cugraph.Graph]) – cugraph graph to use; if None, use self
self (Plottable)

Returns:

Plottable

Return type:

Plottable

Example: Pass params to cugraph

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('betweenness_centrality', params={'k': 2})
assert 'betweenness_centrality' in g2._nodes.columns

Example: Pagerank

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('pagerank')
assert 'pagerank' in g2._nodes.columns

Example: Personalized Pagerank

::: edges = pd.DataFrame({‘s’: [‘a’,’b’,’c’,’d’], ‘d’: [‘c’,’c’,’e’,’e’]}) g = graphistry.edges(edges, ‘s’, ‘d’) g2 = g.compute_cugraph(‘pagerank’, params={‘personalization’: cudf.DataFrame({‘vertex’: [‘a’], ‘values’: [1]})}) assert ‘pagerank’ in g2._nodes.columns

Example: Katz centrality with rename

edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.compute_cugraph('katz_centrality', out_col='katz_centrality_renamed')
assert 'katz_centrality_renamed' in g2._nodes.columns

graphistry.plugins.cugraph.df_to_gdf(df)#

Parameters:: df (Any)

graphistry.plugins.cugraph.from_cugraph(self, G, node_attributes=None, edge_attributes=None, load_nodes=True, load_edges=True, merge_if_existing=True)#

Take input cugraph.Graph object and load in data and bindings (source, destination, edge_weight)

If non-empty nodes/edges, instead of returning G’s topology, use existing topology and merge in G’s attributes

Parameters:

node_attributes (List[str] | None)
edge_attributes (List[str] | None)
load_nodes (bool)
load_edges (bool)
merge_if_existing (bool)

Return type:

Plottable

graphistry.plugins.cugraph.layout_cugraph(self, layout='force_atlas2', params={}, kind='Graph', directed=True, G=None, bind_position=True, x_out_col='x', y_out_col='y', play=0)#

Layout the grpah using a cuGraph algorithm. For a list of layouts, see cugraph documentation (currently just force_atlas2).

Parameters:

layout (str) – Name of an cugraph layout method like force_atlas2
params (dict) – Any named parameters to pass to the underlying cugraph method
kind (CuGraphKind) – The kind of cugraph Graph
directed (bool) – During the to_cugraph conversion, whether to be directed. (default True)
G (Optional[Any]) – The cugraph graph (G) to layout. If None, the current graph is used.
bind_position (bool) – Whether to call bind(point_x=, point_y=) (default True)
x_out_col (str) – Attribute to write x position to. (default ‘x’)
y_out_col (str) – Attribute to write x position to. (default ‘y’)
play (Optional[str]) – If defined, set settings(url_params={‘play’: play}). (default 0)
self (Plottable)

Returns:

Plotter

Return type:

Plotter

Example: ForceAtlas2 layout

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_cugraph().plot()

Example: Change which column names are generated

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_cugraph('force_atlas2', x_out_col='my_x', y_out_col='my_y')
assert 'my_x' in g2._nodes
assert g2._point_x == 'my_x'
g2.plot()

Example: Pass parameters to layout methods

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_cugraph('forceatlas_2', params={'lin_log_mode': True, 'prevent_overlapping': True})
g2.plot()

graphistry.plugins.cugraph.layout_cugraph_core(self, layout='force_atlas2', params={}, kind='Graph', directed=True, G=None, bind_position=True, x_out_col='x', y_out_col='y', play=0)#

Layout the grpah using a cuGraph algorithm. For a list of layouts, see cugraph documentation (currently just force_atlas2).

Parameters:

layout (str) – Name of an cugraph layout method like force_atlas2
params (dict) – Any named parameters to pass to the underlying cugraph method
kind (CuGraphKind) – The kind of cugraph Graph
directed (bool) – During the to_cugraph conversion, whether to be directed. (default True)
G (Optional[Any]) – The cugraph graph (G) to layout. If None, the current graph is used.
bind_position (bool) – Whether to call bind(point_x=, point_y=) (default True)
x_out_col (str) – Attribute to write x position to. (default ‘x’)
y_out_col (str) – Attribute to write x position to. (default ‘y’)
play (Optional[str]) – If defined, set settings(url_params={‘play’: play}). (default 0)
self (Plottable)

Returns:

Plotter

Return type:

Plotter

Example: ForceAtlas2 layout

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_cugraph().plot()

Example: Change which column names are generated

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_cugraph('force_atlas2', x_out_col='my_x', y_out_col='my_y')
assert 'my_x' in g2._nodes
assert g2._point_x == 'my_x'
g2.plot()

Example: Pass parameters to layout methods

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_cugraph('forceatlas_2', params={'lin_log_mode': True, 'prevent_overlapping': True})
g2.plot()

graphistry.plugins.cugraph.to_cugraph(self, directed=True, include_nodes=True, node_attributes=None, edge_attributes=None, kind='Graph')#

Convert current graph to a cugraph.Graph object

To assign an edge weight, use g.bind(edge_weight=’some_col’).to_cugraph()

Load from pandas, cudf, or dask_cudf DataFrames

Parameters:

self (Plottable)
directed (bool)
include_nodes (bool)
node_attributes (List[str] | None)
edge_attributes (List[str] | None)
kind (Literal['Graph', 'MultiGraph', 'BiPartiteGraph'])

graphistry.plugins.graphviz module#

graphistry.plugins.graphviz.g_to_pgv(g, directed=True, strict=False, drop_unsanitary=False, include_positions=False)#

Parameters:

g (Plottable)
directed (bool)
strict (bool)
drop_unsanitary (bool)
include_positions (bool)

Return type:

AGraph

graphistry.plugins.graphviz.g_with_pgv_layout(g, graph)#

Parameters:

g (Plottable)
graph (AGraph)

Return type:

Plottable

graphistry.plugins.graphviz.layout_graphviz(self, prog='dot', args=None, directed=True, strict=False, graph_attr=None, node_attr=None, edge_attr=None, skip_styling=False, render_to_disk=False, path=None, format=None, drop_unsanitary=False)#

Use graphviz for layout, such as hierarchical trees and directed acycle graphs

Requires pygraphviz Python bindings and graphviz native libraries to be installed, see https://pygraphviz.github.io/documentation/stable/install.html

See PROGS for available layout algorithms

To render image to disk, set render=True

Parameters:

self (Plottable) – Base graph
prog (graphistry.plugins_types.graphviz_types.Prog) – Layout algorithm - “dot”, “neato”, …
args (Optional[str]) – Additional arguments to pass to the graphviz commandline for layout
directed (bool) – Whether the graph is directed (True, default) or undirected (False)
strict (bool) – Whether the graph is strict (True) or not (False, default)
graph_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.GraphAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Graphviz graph attributes, see https://graphviz.org/docs/graph/
node_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.NodeAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Graphviz node attributes, see https://graphviz.org/docs/nodes/
edge_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.EdgeAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Graphviz edge attributes, see https://graphviz.org/docs/edges/
skip_styling (bool) – Whether to skip applying default styling (False, default) or not (True)
render_to_disk (bool) – Whether to render the graph to disk (False, default) or not (True)
path (Optional[str]) – Path to save the rendered image when render_to_disk=True
format (Optional[graphistry.plugins_types.graphviz_types.Format]) – Format of the rendered image when render_to_disk=True
drop_unsanitary (bool) – Whether to drop unsanitary attributes (False, default) or not (True), recommended for sensitive settings

Returns:

Graph with layout and style settings applied, setting x/y

Return type:

Plottable

Example: Dot layout for rigid hierarchical layout of trees and directed acyclic graphs

import graphistry
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_graphviz('dot').plot()

Example: Neato layout for organic layout of small graphs

import graphistry
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_graphviz('neato').plot()

Example: Set graphviz attributes at graph level

import graphistry
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_graphviz(
    prog='dot',
    graph_attr={
        'ratio': 10
    }
).plot()

Example: Save rendered image to disk as a png

import graphistry
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g.layout_graphviz(
    'dot',
    render_to_disk=True,
    path='graph.png',
    format='png'
)

Example: Save rendered image to disk as a png with passthrough of rendering styles

import graphistry
edges = pd.DataFrame({
    's': ['a','b','c','d'],
    'd': ['b','c','d','e'],
    'color': ['red', None, None, 'yellow']
})
nodes = pd.DataFrame({
    'n': ['a','b','c','d','e'],
    'shape': ['circle', 'square', None, 'square', 'circle']
})
g = graphistry.edges(edges, 's', 'd')
g.layout_graphviz(
    'dot',
    render_to_disk=True,
    path='graph.png',
    format='png'
)

graphistry.plugins.graphviz.layout_graphviz_core(g, prog='dot', args=None, directed=True, strict=False, graph_attr=None, node_attr=None, edge_attr=None, drop_unsanitary=False, include_positions=False)#

Parameters:

g (Plottable)
prog (Literal['acyclic', 'ccomps', 'circo', 'dot', 'fdp', 'gc', 'gvcolor', 'gvpr', 'neato', 'nop', 'osage', 'patchwork', 'sccmap', 'sfdp', 'tred', 'twopi', 'unflatten'])
args (str | None)
directed (bool)
strict (bool)
graph_attr (Dict[Literal['_background', 'bb', 'beautify', 'bgcolor', 'center', 'charset', 'class', 'clusterrank', 'colorscheme', 'comment', 'compound', 'concentrate', 'Damping', 'defaultdist', 'dim', 'dimen', 'diredgeconstraints', 'dpi', 'epsilon', 'esep', 'fontcolor', 'fontname', 'fontnames', 'fontpath', 'fontsize', 'forcelabels', 'gradientangle', 'href', 'id', 'imagepath', 'inputscale', 'K', 'label', 'label_scheme', 'labeljust', 'labelloc', 'landscape', 'layerlistsep', 'layers', 'layerselect', 'layersep', 'layout', 'levels', 'levelsgap', 'lheight', 'linelength', 'lp', 'lwidth', 'margin', 'maxiter', 'mclimit', 'mindist', 'mode', 'model', 'newrank', 'nodesep', 'nojustify', 'normalize', 'notranslate', 'nslimit', 'nslimit1', 'oneblock', 'ordering', 'orientation', 'outputorder', 'overlap', 'overlap_scaling', 'overlap_shrink', 'pack', 'packmode', 'pad', 'page', 'pagedir', 'quadtree', 'quantum', 'rankdir', 'ranksep', 'ratio', 'remincross', 'repulsiveforce', 'resolution', 'root', 'rotate', 'rotation', 'scale', 'searchsize', 'sep', 'showboxes', 'size', 'smoothing', 'sortv', 'splines', 'start', 'style', 'stylesheet', 'target', 'TBbalance', 'tooltip', 'truecolor', 'URL', 'viewport', 'voro_margin', 'xdotversion'], str | int | float | bool] | None)
node_attr (Dict[Literal['area', 'class', 'color', 'colorscheme', 'comment', 'distortion', 'fillcolor', 'fixedsize', 'fontcolor', 'fontname', 'fontsize', 'gradientangle', 'group', 'height', 'href', 'id', 'image', 'imagepos', 'imagescale', 'label', 'labelloc', 'layer', 'margin', 'nojustify', 'ordering', 'orientation', 'penwidth', 'peripheries', 'pin', 'pos', 'rects', 'regular', 'root', 'samplepoints', 'shape', 'shapefile', 'showboxes', 'sides', 'skew', 'sortv', 'style', 'target', 'tooltip', 'URL', 'vertices', 'width', 'xlabel', 'xlp', 'z'], str | int | float | bool] | None)
edge_attr (Dict[Literal['arrowhead', 'arrowsize', 'arrowtail', 'class', 'color', 'colorscheme', 'comment', 'constraint', 'decorate', 'dir', 'edgehref', 'edgetarget', 'edgetooltip', 'edgeURL', 'fillcolor', 'fontcolor', 'fontname', 'fontsize', 'head_lp', 'headclip', 'headhref', 'headlabel', 'headport', 'headtarget', 'headtooltip', 'headURL', 'href', 'id', 'label', 'labelangle', 'labeldistance', 'labelfloat', 'labelfontcolor', 'labelfontname', 'labelfontsize', 'labelhref', 'labeltarget', 'labeltooltip', 'labelURL', 'layer', 'len', 'lhead', 'lp', 'ltail', 'minlen', 'nojustify', 'penwidth', 'pos', 'samehead', 'sametail', 'showboxes', 'style', 'tail_lp', 'tailclip', 'tailhref', 'taillabel', 'tailport', 'tailtarget', 'tailtooltip', 'tailURL', 'target', 'tooltip', 'URL', 'weight', 'xlabel', 'xlp'], str | int | float | bool] | None)
drop_unsanitary (bool)
include_positions (bool)

Return type:

AGraph

graphistry.plugins.graphviz.pgv_styling(g)#

Parameters:: g (Plottable)
Return type:: Plottable

graphistry.plugins.graphviz.render_graphviz(self, prog='dot', format='svg', args=None, directed=True, strict=False, graph_attr=None, node_attr=None, edge_attr=None, drop_unsanitary=False, max_nodes=None, max_edges=None, path=None, include_positions=False)#

Render a graph to an image via graphviz and return the rendered bytes.

This wraps layout_graphviz_core() to compute positions, then draws with pygraphviz. Optionally enforces caps to keep renders small/deterministic for docs/examples.

When include_positions is True and the plot has bound x/y values, the existing layout is preserved rather than recomputed by Graphviz.

Parameters:

self (Plottable) – Base graph
prog (graphistry.plugins_types.graphviz_types.Prog) – Layout algorithm
format (graphistry.plugins_types.graphviz_types.Format) – Render format
directed (bool) – Whether the graph is directed
strict (bool) – Whether to treat the graph as strict
graph_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.GraphAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Graph-level attributes
node_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.NodeAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Node-level attributes
edge_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.EdgeAttr, graphistry.plugins_types.graphviz_types.GraphvizAttrValue]]) – Edge-level attributes
drop_unsanitary (bool) – Reject unsanitary attrs
max_nodes (Optional[int]) – Optional cap on nodes for rendering
max_edges (Optional[int]) – Optional cap on edges for rendering
path (Optional[str]) – Optional path to also write the render
args (str | None)
include_positions (bool)

Returns:

Rendered bytes (SVG/PNG/etc.)

Return type:

bytes

graphistry.plugins.igraph module#

graphistry.plugins.igraph.compute_igraph(self, alg, out_col=None, directed=None, use_vids=False, params={}, stringify_rich_types=True)#

Enrich or replace graph using igraph methods

Parameters:

alg (str) – Name of an igraph.Graph method like pagerank
out_col (Optional[str]) – For algorithms that generate a node attribute column, out_col is the desired output column name. When None, use the algorithm’s name. (default None)
directed (Optional[bool]) – During the to_igraph conversion, whether to be directed. If None, try directed and then undirected. (default None)
use_vids (bool) – During the to_igraph conversion, whether to interpret IDs as igraph vertex IDs (non-negative integers) or arbitrary values (False, default)
params (dict) – Any named parameters to pass to the underlying igraph method
stringify_rich_types (bool) – When rich types like igraph.Graph are returned, which may be problematic for downstream rendering, coerce them to strings
self (Plottable)

Returns:

Plotter

Return type:

Plotter

Example: Pagerank

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd').materialize_nodes()
g2 = g.compute_igraph('pagerank')
assert 'pagerank' in g2._nodes.columns

Example: Pagerank with custom name

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd').materialize_nodes()
g2 = g.compute_igraph('pagerank', out_col='my_pr')
assert 'my_pr' in g2._nodes.columns

Example: Pagerank on an undirected

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd').materialize_nodes()
g2 = g.compute_igraph('pagerank', directed=False)
assert 'pagerank' in g2._nodes.columns

Example: Pagerank with custom parameters

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd').materialize_nodes()
g2 = g.compute_igraph('pagerank', params={'damping': 0.85})
assert 'pagerank' in g2._nodes.columns

Example: Personalized Pagerank

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['c','c','e','e']})
g = graphistry.edges(edges, 's', 'd').materialize_nodes()
g2 = g.compute_igraph('personalized_pagerank')
assert 'personalized_pagerank' in g2._nodes.columns

graphistry.plugins.igraph.from_igraph(self, ig, node_attributes=None, edge_attributes=None, load_nodes=True, load_edges=True, merge_if_existing=True)#

Convert igraph object into Plotter

If base g has _node, _source, _destination definitions, use them

When merge_if_existing with preexisting nodes/edges df and shapes match ig, combine attributes

For merge_if_existing to work with edges, must set g._edge and have corresponding edge index attribute in igraph.Graph

Parameters:

ig (igraph) – Source igraph object
node_attributes (Optional[List[str]]) – Subset of node attributes to load; None means all (default)
edge_attributes (Optional[List[str]]) – Subset of edge attributes to load; None means all (default)
load_nodes (bool) – Whether to load nodes dataframe (default True)
load_edges (bool) – Whether to load edges dataframe (default True)
merge_if_existing (bool) – Whether to merge with existing node/edge dataframes (default True)
merge_if_existing – bool

Returns:

Plotter

Return type:

Plottable

Example: Convert from igraph, including all node/edge properties

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a', 'b', 'c', 'd'], 'd': ['b', 'c', 'd', 'e'], 'v': [101, 102, 103, 104]})
g = graphistry.edges(edges, 's', 'd').materialize_nodes().get_degrees()
assert 'degree' in g._nodes.columns
g2 = g.from_igraph(g.to_igraph())
assert len(g2._nodes.columns) == len(g._nodes.columns)

Example: Enrich from igraph, but only load in 1 node attribute

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a', 'b', 'c', 'd'], 'd': ['b', 'c', 'd', 'e'], 'v': [101, 102, 103, 104]})
g = graphistry.edges(edges, 's', 'd').materialize_nodes().get_degree()
assert 'degree' in g._nodes
ig = g.to_igraph(include_nodes=False)
assert 'degree' not in ig.vs
ig.vs['pagerank'] = ig.pagerank()
g2 = g.from_igraph(ig, load_edges=False, node_attributes=[g._node, 'pagerank'])
assert 'pagerank' in g2._nodes
asssert 'degree' in g2._nodes

graphistry.plugins.igraph.layout_igraph(self, layout, directed=None, use_vids=False, bind_position=True, x_out_col='x', y_out_col='y', play=0, params={})#

Compute graph layout using igraph algorithm. For a list of layouts, see layout_algs or igraph documentation.

Parameters:

layout (str) – Name of an igraph.Graph.layout method like sugiyama
directed (Optional[bool]) – During the to_igraph conversion, whether to be directed. If None, try directed and then undirected. (default None)
use_vids (bool) – Whether to use igraph vertex ids (non-negative integers) or arbitary node ids (False, default)
bind_position (bool) – Whether to call bind(point_x=, point_y=) (default True)
x_out_col (str) – Attribute to write x position to. (default ‘x’)
y_out_col (str) – Attribute to write x position to. (default ‘y’)
play (Optional[str]) – If defined, set settings(url_params={‘play’: play}). (default 0)
params (dict) – Any named parameters to pass to the underlying igraph method
self (Plottable)

Returns:

Plotter

Return type:

Plotter

Example: Sugiyama layout

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_igraph('sugiyama')
assert 'x' in g2._nodes
g2.plot()

Example: Change which column names are generated

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.layout_igraph('sugiyama', x_out_col='my_x', y_out_col='my_y')
assert 'my_x' in g2._nodes
assert g2._point_x == 'my_x'
g2.plot()

Example: Pass parameters to layout methods - Sort nodes by degree

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'd': ['b','c','d','e']})
g = graphistry.edges(edges, 's', 'd')
g2 = g.get_degrees()
assert 'degree' in g._nodes.columns
g3 = g.layout_igraph('sugiyama', params={'layers': 'degree'})
g3.plot()

graphistry.plugins.igraph.to_igraph(self, directed=True, include_nodes=True, node_attributes=None, edge_attributes=None, use_vids=False)#

Convert current item to igraph Graph . See examples in from_igraph.

Parameters:

directed (bool) – Whether to create a directed graph (default True)
include_nodes (bool) – Whether to ingest the nodes table, if it exists (default True)
node_attributes (Optional[List[str]]) – Which node attributes to load, None means all (default None)
edge_attributes (Optional[List[str]]) – Which edge attributes to load, None means all (default None)
use_vids (bool) – Whether to interpret IDs as igraph vertex IDs, which must be non-negative integers (default False)
self (Plottable)

Return type:

Any

graphistry.plugins.kusto module#

class graphistry.plugins.kusto.KustoMixin(*args, **kwargs)#

Bases: Plottable

KustoMixin is a Graphistry Mixin that allows you to plot data from Kusto.

configure_kusto(cluster, database='NetDefaultDB', client_id=None, client_secret=None, tenant_id=None)#

Configure Azure Data Explorer (Kusto) connection settings.

Sets up the connection parameters for accessing a Kusto cluster. Authentication can be done via service principal (client_id, client_secret, tenant_id) or managed identity (omit authentication parameters).

Parameters:

cluster (str) – Kusto cluster URL (e.g., ‘https://mycluster.westus2.kusto.windows.net’)
database (str) – Database name (defaults to ‘NetDefaultDB’)
client_id (Optional[str]) – Azure AD application (client) ID for service principal auth
client_secret (Optional[str]) – Azure AD application secret for service principal auth
tenant_id (Optional[str]) – Azure AD tenant ID for service principal auth

Returns:

Self for method chaining

Return type:

Plottable

Example: Service principal authentication

import graphistry
g = graphistry.configure_kusto(
    cluster="https://mycluster.westus2.kusto.windows.net",
    database="SecurityDatabase",
    client_id="your-client-id",
    client_secret="your-client-secret",
    tenant_id="your-tenant-id"
)

Example: Managed identity authentication

import graphistry
g = graphistry.configure_kusto(
    cluster="https://mycluster.westus2.kusto.windows.net",
    database="SecurityDatabase"
    # No auth params - uses managed identity
)

kql(query: str, *, unwrap_nested: bool | None = None, single_table: Literal[True] = True) → List[DataFrame]#

kql(query: str, *, unwrap_nested: bool | None = None, single_table: Literal[False]) → DataFrame

kql(query: str, *, unwrap_nested: bool | None = None, single_table: bool = True) → DataFrame | List[DataFrame]

Execute KQL query and return result tables as DataFrames.

Submits a Kusto Query Language (KQL) query to Azure Data Explorer and returns the results. By default, expects a single table result and returns it as a DataFrame. If multiple tables are returned, only the first is returned with a warning. Set single_table=False to always get a list of all result tables.

Parameters:

query (str) – KQL query string to execute
unwrap_nested (Optional[bool]) – Strategy for handling nested/dynamic columns
single_table (bool) – If True, return single DataFrame (first table if multiple); if False, return list

Returns:

Single DataFrame if single_table=True, else list of DataFrames

Return type:

Union[pd.DataFrame, List[pd.DataFrame]]

unwrap_nested semantics:

True: Always attempt to unwrap nested columns; raise on failure
None: Use heuristic - unwrap if the first result looks nested
False: Never attempt to unwrap nested columns

Example: Basic security query (single table mode)

import graphistry
g = graphistry.configure_kusto(...)

query = '''
SecurityEvent
| where TimeGenerated > ago(1d)
| where EventID == 4624  // Successful logon
| project TimeGenerated, Account, Computer, IpAddress
| take 1000
'''

# Single table mode returns DataFrame directly (default)
df = g.kql(query)
print(f"Found {len(df)} logon events")

Example: Get all tables as list

# Always get a list of all tables
dfs = g.kql(query, single_table=False)
df = dfs[0]

Example: Multi-table query

query = '''
SecurityEvent | take 10;
Heartbeat | take 5
'''

# With single_table=True (default), returns first table with warning
df = g.kql(query)  # Returns SecurityEvent data, warns about multiple tables

# With single_table=False, returns all tables
frames = g.kql(query, single_table=False)
security_df = frames[0]
heartbeat_df = frames[1]

property kusto_client: Any#

kusto_close()#

Close the active Kusto client connection.

Properly closes the underlying Kusto client connection to free resources. This should be called when you’re done using the Kusto connection.

Example

import graphistry
g = graphistry.configure_kusto(...)
# ... perform queries ...
g.kusto_close()  # Clean up connection

Return type:: None

kusto_from_client(client, database='NetDefaultDB')#

Configure Kusto using an existing client connection.

Use this method when you already have a configured Kusto client connection and want to reuse it with Graphistry.

Parameters:

client (azure.kusto.data.KustoClient) – Pre-configured Kusto client
database (str) – Database name to query against

Returns:

Self for method chaining

Return type:

Plottable

Example

from azure.kusto.data import KustoClient, KustoConnectionStringBuilder
import graphistry

# Create Kusto client
kcsb = KustoConnectionStringBuilder.with_aad_device_authentication(
    "https://mycluster.kusto.windows.net"
)
kusto_client = KustoClient(kcsb)

# Use with Graphistry
g = graphistry.kusto_from_client(kusto_client, "MyDatabase")

kusto_graph(graph_name, snap_name=None)#

Fetch a Kusto graph entity as a Graphistry visualization object.

Retrieves a named graph entity (and optional snapshot) from Kusto using the graph() operator and graph-to-table transformation. The result is automatically bound as nodes and edges for visualization.

Parameters:

graph_name (str) – Name of the Kusto graph entity to fetch
snap_name (Optional[str]) – Optional snapshot/version identifier

Returns:

Plottable object ready for visualization or further transforms

Return type:

Plottable

Example: Basic graph visualization

import graphistry
g = graphistry.configure_kusto(...)

# Fetch and visualize a named graph
graph_viz = g.kusto_graph("NetworkTopology")
graph_viz.plot()

Example: Specific snapshot

# Fetch a specific snapshot of the graph
graph_viz = g.kusto_graph("NetworkTopology", "2023-12-01")
graph_viz.plot()

kusto_health_check()#

Perform a health check on the Kusto connection.

Executes a simple query (.show tables) to verify that the connection to the Kusto cluster is working properly.

Raises:: RuntimeError – If the connection test fails
Return type:: None

Example

import graphistry
g = graphistry.configure_kusto(...)
g.kusto_health_check()  # Verify connection works

graphistry.plugins.kusto.init_kusto_client(cfg)#

Parameters:: cfg (KustoConfig)
Return type:: Any

graphistry.plugins.spanner module#

class graphistry.plugins.spanner.SpannerMixin(*args, **kwargs)#

Bases: Plottable

SpannerMixin is a Graphistry Mixin that allows you to plot data from Spanner.

static add_type_from_label_to_df(df)#

Add type column from label for Graphistry type handling.

Creates a type column from the label column for proper visualization in Graphistry. If a type column already exists, it is renamed to type_ before creating the new type column.

Parameters:: df (pd.DataFrame) – DataFrame containing node or edge data with label column
Returns:: Modified DataFrame with the updated type column
Return type:: pd.DataFrame

configure_spanner(instance_id, database_id, project_id=None, credentials_file=None)#

Configure Google Cloud Spanner connection settings.

Sets up the connection parameters for accessing a Spanner database instance. Either project_id or credentials_file must be provided for authentication.

Parameters:

instance_id (str) – The Spanner instance identifier
database_id (str) – The Spanner database identifier
project_id (Optional[str]) – Google Cloud project ID (optional if using credentials_file)
credentials_file (Optional[str]) – Path to service account credentials JSON file

Returns:

Self for method chaining

Return type:

Plottable

Raises:

ValueError – If neither credentials_file nor project_id is provided

Example: Using project ID

import graphistry
g = graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

Example: Using service account credentials

import graphistry
g = graphistry.configure_spanner(
    instance_id="my-instance",
    database_id="my-database",
    credentials_file="/path/to/credentials.json"
)

static convert_spanner_json(data)#

Convert Spanner JSON query results to structured graph data.

Transforms raw Spanner JSON query results into a standardized format with separate nodes and edges arrays for graph processing.

Parameters:: data (List[Any]) – Raw JSON data from Spanner query results
Returns:: Structured graph data with ‘nodes’ and ‘edges’ arrays
Return type:: List[Dict[str, Any]]

static get_edges_df(json_data)#

Convert Spanner JSON edges into a pandas DataFrame.

Extracts edge data from structured JSON results and creates a DataFrame with columns for label, identifier, source, destination, and all edge properties.

Parameters:: json_data (list) – Structured JSON data containing graph edges
Returns:: DataFrame containing edge data with properties as columns
Return type:: pd.DataFrame

static get_nodes_df(json_data)#

Convert Spanner JSON nodes into a pandas DataFrame.

Extracts node data from structured JSON results and creates a DataFrame with columns for label, identifier, and all node properties.

Parameters:: json_data (list) – Structured JSON data containing graph nodes
Returns:: DataFrame containing node data with properties as columns
Return type:: pd.DataFrame

property spanner_client: Any#

spanner_close()#

Close the active Spanner database connection.

Properly closes the underlying Spanner client connection to free resources. This should be called when you’re done using the Spanner connection.

Example

import graphistry
g = graphistry.configure_spanner(...)
# ... perform queries ...
g.spanner_close()  # Clean up connection

Return type:: None

property spanner_config: SpannerConfig#

spanner_from_client(client)#

Configure Spanner using an existing client connection.

Use this method when you already have a configured Spanner client connection and want to reuse it with Graphistry.

Parameters:: client (google.cloud.spanner_dbapi.connection.Connection) – Pre-configured Spanner database connection
Returns:: Self for method chaining
Return type:: Plottable

Example

from google.cloud import spanner
import graphistry

# Create Spanner client
spanner_client = spanner.Client(project="my-project")
instance = spanner_client.instance("my-instance")
database = instance.database("my-database")

# Use with Graphistry
g = graphistry.spanner_from_client(database)

spanner_gql(query)#

Execute GQL path query and return graph visualization.

Executes a Graph Query Language (GQL) path query on the configured Spanner database and returns a Plottable object ready for visualization. The query must return path data using SAFE_TO_JSON(p) format.

Parameters:: query (str) – GQL path query string with SAFE_TO_JSON(path) format
Returns:: Plottable object with nodes and edges populated from query results
Return type:: Plottable

Example: Basic path query

import graphistry
graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

query = '''
GRAPH FinGraph
MATCH p = (a:Account)-[t:Transfers]->(b:Account)
LIMIT 10000
RETURN SAFE_TO_JSON(p) as path
'''

g = graphistry.spanner_gql(query)
g.plot()

spanner_gql_to_df(query)#

Execute GQL/SQL query and return results as DataFrame.

Executes a Graph Query Language (GQL) or SQL query on the configured Spanner database and returns the results as a pandas DataFrame. This method is suitable for tabular queries that don’t require graph visualization.

Parameters:: query (str) – GQL or SQL query string
Returns:: DataFrame containing query results with column names
Return type:: pd.DataFrame

Example: Aggregation query

import graphistry
graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

query = '''
GRAPH FinGraph
MATCH (p:Person)-[:Owns]-(:Account)->(l:Loan)
RETURN p.id as PersonID, p.name AS Name, 
       SUM(l.loan_amount) AS TotalBorrowed
ORDER BY TotalBorrowed DESC
LIMIT 10
'''

df = graphistry.spanner_gql_to_df(query)
print(df.head())

Example: SQL query

query = "SELECT * FROM Account WHERE type = 'checking' LIMIT 1000"
df = graphistry.spanner_gql_to_df(query)

graphistry.plugins.spanner.init_spanner_client(cfg)#

Lazily establish a DB-API connection using the parameters in session.config.

Parameters:: cfg (SpannerConfig)
Return type:: Any

graphistry.plugins package

Contents

graphistry.plugins package#

Submodules#

graphistry.plugins.cugraph module#

graphistry.plugins.graphviz module#

graphistry.plugins.igraph module#

graphistry.plugins.kusto module#

graphistry.plugins.spanner module#

Module contents#