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.gexf module#

GEXF import/export helpers.

graphistry.plugins.gexf.from_gexf(self, source, name=None, description=None, bind_node_viz=None, bind_edge_viz=None, parse_engine='auto')#

Load a GEXF file/URL/stream into a PyGraphistry plotter.

Parameters:

self (Plottable)
source (str | bytes | bytearray | IO[bytes] | IO[str])
name (str | None)
description (str | None)
bind_node_viz (Iterable[Literal['color', 'size', 'opacity', 'position', 'icon']] | None)
bind_edge_viz (Iterable[Literal['color', 'size', 'opacity']] | None)
parse_engine (Literal['auto', 'defused', 'stdlib'])

Return type:

Plottable

graphistry.plugins.gexf.gexf_to_dfs(source, node_col='node_id', source_col='source', destination_col='target', edge_id_col='edge_id', parse_engine='auto')#

Parameters:

source (str | bytes | bytearray | IO[bytes] | IO[str])
node_col (str)
source_col (str)
destination_col (str)
edge_id_col (str)
parse_engine (Literal['auto', 'defused', 'stdlib'])

Return type:

Tuple[DataFrame, DataFrame, Dict[str, str | None]]

graphistry.plugins.gexf.to_gexf(self, path=None, *, version='1.2draft', directed=True, include_viz=True, include_meta=True, meta_creator='graphistry', meta_description=None, meta_lastmodifieddate=None, node_attributes=None, edge_attributes=None)#

Export the current graph to a GEXF string (optionally writing to disk).

Parameters:

self (Plottable)
path (str | None)
version (str)
directed (bool)
include_viz (bool)
include_meta (bool)
meta_creator (str | None)
meta_description (str | None)
meta_lastmodifieddate (str | None)
node_attributes (List[str] | None)
edge_attributes (List[str] | None)

Return type:

str

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

Graphviz is a CPU-only library. cuDF DataFrames are automatically converted to pandas before calling graphviz, and the result is converted back.

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

igraph is a CPU-only library. cuDF DataFrames are automatically converted to pandas before calling igraph, and the result is converted back. For a GPU-native alternative, see compute_cugraph().

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.ensure_pandas(df)#

Convert to pandas if not already (e.g. cuDF). No-op for pandas.

Delegates to graphistry.compute.engine_coercion.ensure_pandas(). Defined here to avoid a circular import at module load time.

Parameters:: df (Any)
Return type:: DataFrame

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.

igraph is a CPU-only library. cuDF DataFrames are automatically converted to pandas before calling igraph, and the result is converted back. For a GPU-native alternative, see layout_cugraph().

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.restore_engine(g, original_nodes, original_edges)#

Convert result DataFrames back to the original engine if needed.

Delegates to graphistry.compute.engine_coercion.restore_engine(). Defined here to avoid a circular import at module load time.

Parameters:

g (Plottable)
original_nodes (Any)
original_edges (Any)

Return type:

Plottable

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.

igraph is a CPU-only library. cuDF DataFrames are automatically converted to pandas before being passed to igraph. For a GPU-native alternative, see to_cugraph().

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.gexf module#

graphistry.plugins.graphviz module#

graphistry.plugins.igraph module#

graphistry.plugins.kusto module#

graphistry.plugins.spanner module#

Module contents#