Plotter API Reference

Contents

Plotter API Reference#

The below Python API reference documentation is for three views of the core graph abstraction, Plottable:

Plotter Class#

Main Plotter class for Graphistry.

This class represents a graph in Graphistry and serves as the primary interface for plotting and analyzing graphs. It inherits from multiple mixins, allowing it to extend its functionality with additional graph computation, layouts, conditional formatting, and more.

Inherits:
Attributes:

All attributes are inherited from the mixins and base classes.

Plottable Interface#

class graphistry.Plottable.Plottable(*args, **kwargs)#

Bases: object

DGL_graph: Any | None#
base_url_client(v=None)#
Parameters:

v (str | None)

Return type:

str

base_url_server(v=None)#
Parameters:

v (str | None)

Return type:

str

bind(source=None, destination=None, node=None, edge=None, edge_title=None, edge_label=None, edge_color=None, edge_weight=None, edge_size=None, edge_opacity=None, edge_icon=None, edge_source_color=None, edge_destination_color=None, point_title=None, point_label=None, point_color=None, point_weight=None, point_size=None, point_opacity=None, point_icon=None, point_x=None, point_y=None)#
chain(ops)#

ops is Union[List[ASTObject], Chain]

Parameters:

ops (Any | List[Any])

Return type:

Plottable

chain_remote(chain, api_token=None, dataset_id=None, output_type='all', format=None, df_export_args=None, node_col_subset=None, edge_col_subset=None, engine=None)#

chain is Union[List[ASTObject], Chain]

Parameters:
  • self (Plottable)

  • chain (Any | Dict[str, None | bool | str | float | int | List[None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]] | Dict[str, None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]]])

  • api_token (str | None)

  • dataset_id (str | None)

  • output_type (Literal['all', 'nodes', 'edges', 'shape'])

  • format (Literal['json', 'csv', 'parquet'] | None)

  • df_export_args (Dict[str, Any] | None)

  • node_col_subset (List[str] | None)

  • edge_col_subset (List[str] | None)

  • engine (Literal['pandas', 'cudf'] | None)

Return type:

Plottable

chain_remote_shape(chain, api_token=None, dataset_id=None, format=None, df_export_args=None, node_col_subset=None, edge_col_subset=None, engine=None)#

chain is Union[List[ASTObject], Chain]

Parameters:
  • self (Plottable)

  • chain (Any | Dict[str, None | bool | str | float | int | List[None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]] | Dict[str, None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]]])

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • df_export_args (Dict[str, Any] | None)

  • node_col_subset (List[str] | None)

  • edge_col_subset (List[str] | None)

  • engine (Literal['pandas', 'cudf'] | None)

Return type:

DataFrame

client_protocol_hostname(v=None)#
Parameters:

v (str | None)

Return type:

str

collapse(node, attribute, column, self_edges=False, unwrap=False, verbose=False)#
Parameters:
  • node (str | int)

  • attribute (str | int)

  • column (str | int)

  • self_edges (bool)

  • unwrap (bool)

  • verbose (bool)

Return type:

Plottable

compute_cugraph(alg, out_col=None, params={}, kind='Graph', directed=True, G=None)#
Parameters:
  • alg (str)

  • out_col (str | None)

  • params (dict)

  • kind (Literal['Graph', 'MultiGraph', 'BiPartiteGraph'])

  • G (Any | None)

compute_igraph(alg, out_col=None, directed=None, use_vids=False, params={}, stringify_rich_types=True)#
Parameters:
  • alg (str)

  • out_col (str | None)

  • directed (bool | None)

  • use_vids (bool)

  • params (dict)

  • stringify_rich_types (bool)

Return type:

Plottable

copy()#
drop_nodes(nodes)#
Parameters:

nodes (Any)

Return type:

Plottable

edges(edges, source=None, destination=None, edge=None, *args, **kwargs)#
Parameters:
  • edges (Callable | Any)

  • source (str | None)

  • destination (str | None)

  • edge (str | None)

Return type:

Plottable

encode_axis(rows=[])#
Return type:

Plottable

fa2_layout(fa2_params=None, circle_layout_params=None, singleton_layout=None, partition_key=None, engine=EngineAbstract.AUTO)#
Parameters:
  • fa2_params (Dict[str, Any] | None)

  • circle_layout_params (Dict[str, Any] | None)

  • singleton_layout (Callable[[Plottable, Tuple[float, float, float, float] | Any], Plottable] | None)

  • partition_key (str | None)

  • engine (EngineAbstract | str)

Return type:

Plottable

filter_edges_by_dict(filter_dict=None)#
Parameters:

filter_dict (dict | None)

Return type:

Plottable

filter_nodes_by_dict(filter_dict=None)#
Parameters:

filter_dict (dict | None)

Return type:

Plottable

from_cugraph(G, node_attributes=None, edge_attributes=None, load_nodes=True, load_edges=True, merge_if_existing=True)#
Parameters:
  • node_attributes (List[str] | None)

  • edge_attributes (List[str] | None)

  • load_nodes (bool)

  • load_edges (bool)

  • merge_if_existing (bool)

from_igraph(ig, node_attributes=None, edge_attributes=None, load_nodes=True, load_edges=True, merge_if_existing=True)#
Parameters:
  • node_attributes (List[str] | None)

  • edge_attributes (List[str] | None)

  • load_nodes (bool)

  • load_edges (bool)

  • merge_if_existing (bool)

from_networkx(G)#
Parameters:

G (Any)

Return type:

Plottable

get_degrees(col='degree', degree_in='degree_in', degree_out='degree_out')#
Parameters:
  • col (str)

  • degree_in (str)

  • degree_out (str)

Return type:

Plottable

get_indegrees(col='degree_in')#
Parameters:

col (str)

Return type:

Plottable

get_outdegrees(col='degree_out')#
Parameters:

col (str)

Return type:

Plottable

get_topological_levels(level_col='level', allow_cycles=True, warn_cycles=True, remove_self_loops=True)#
Parameters:
  • level_col (str)

  • allow_cycles (bool)

  • warn_cycles (bool)

  • remove_self_loops (bool)

Return type:

Plottable

hop(nodes, hops=1, to_fixed_point=False, direction='forward', edge_match=None, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, return_as_wave_front=False, target_wave_front=None)#
Parameters:
  • nodes (DataFrame | None)

  • hops (int | None)

  • to_fixed_point (bool)

  • direction (str)

  • edge_match (dict | None)

  • source_node_match (dict | None)

  • destination_node_match (dict | None)

  • source_node_query (str | None)

  • destination_node_query (str | None)

  • edge_query (str | None)

  • return_as_wave_front (bool)

  • target_wave_front (DataFrame | None)

Return type:

Plottable

keep_nodes(nodes)#
Parameters:

nodes (List | Any)

Return type:

Plottable

layout_cugraph(layout='force_atlas2', params={}, kind='Graph', directed=True, G=None, bind_position=True, x_out_col='x', y_out_col='y', play=0)#
Parameters:
  • layout (str)

  • params (dict)

  • kind (Literal['Graph', 'MultiGraph', 'BiPartiteGraph'])

  • G (Any | None)

  • bind_position (bool)

  • x_out_col (str)

  • y_out_col (str)

  • play (int | None)

layout_igraph(layout, directed=None, use_vids=False, bind_position=True, x_out_col='x', y_out_col='y', play=0, params={})#
Parameters:
  • layout (str)

  • directed (bool | None)

  • use_vids (bool)

  • bind_position (bool)

  • x_out_col (str)

  • y_out_col (str)

  • play (int | None)

  • params (dict)

Return type:

Plottable

layout_settings(play=None, locked_x=None, locked_y=None, locked_r=None, left=None, top=None, right=None, bottom=None, lin_log=None, strong_gravity=None, dissuade_hubs=None, edge_influence=None, precision_vs_speed=None, gravity=None, scaling_ratio=None)#
Parameters:
  • play (int | None)

  • locked_x (bool | None)

  • locked_y (bool | None)

  • locked_r (bool | None)

  • left (float | None)

  • top (float | None)

  • right (float | None)

  • bottom (float | None)

  • lin_log (bool | None)

  • strong_gravity (bool | None)

  • dissuade_hubs (bool | None)

  • edge_influence (float | None)

  • precision_vs_speed (float | None)

  • gravity (float | None)

  • scaling_ratio (float | None)

materialize_nodes(reuse=True, engine=EngineAbstract.AUTO)#
Parameters:
  • reuse (bool)

  • engine (EngineAbstract | str)

Return type:

Plottable

networkx2pandas(G)#
Parameters:

G (Any)

Return type:

Tuple[DataFrame, DataFrame]

nodes(nodes, node=None, *args, **kwargs)#
Parameters:
  • nodes (Callable | Any)

  • node (str | None)

Return type:

Plottable

pipe(graph_transform, *args, **kwargs)#
Parameters:

graph_transform (Callable)

Return type:

Plottable

plot(graph=None, nodes=None, name=None, description=None, render='auto', skip_upload=False, as_files=False, memoize=True, extra_html='', override_html_style=None, validate=True)#
Parameters:
  • render (bool | Literal['auto'] | ~typing.Literal['g', 'url', 'ipython', 'databricks', 'browser'] | None)

  • validate (bool)

Return type:

Plottable

protocol(v=None)#
Parameters:

v (str | None)

Return type:

str

prune_self_edges()#
Return type:

Plottable

python_remote_g(code, api_token=None, dataset_id=None, format='parquet', output_type='all', engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • output_type (Literal['all', 'nodes', 'edges', 'shape'] | ~typing.Literal['table', 'shape'] | ~typing.Literal['json'] | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

Plottable

python_remote_json(code, api_token=None, dataset_id=None, engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

Any

python_remote_table(code, api_token=None, dataset_id=None, format='parquet', output_type='table', engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • output_type (Literal['table', 'shape'] | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

DataFrame

scene_settings(menu=None, info=None, show_arrows=None, point_size=None, edge_curvature=None, edge_opacity=None, point_opacity=None)#
Parameters:
  • menu (bool | None)

  • info (bool | None)

  • show_arrows (bool | None)

  • point_size (float | None)

  • edge_curvature (float | None)

  • edge_opacity (float | None)

  • point_opacity (float | None)

Return type:

Plottable

server(v=None)#
Parameters:

v (str | None)

Return type:

str

settings(height=None, url_params={}, render=None)#
Parameters:
  • height (float | None)

  • url_params (Dict[str, Any])

  • render (bool | Literal['auto'] | ~typing.Literal['g', 'url', 'ipython', 'databricks', 'browser'] | None)

Return type:

Plottable

to_cudf()#
Return type:

Plottable

to_cugraph(directed=True, include_nodes=True, node_attributes=None, edge_attributes=None, kind='Graph')#
Parameters:
  • directed (bool)

  • include_nodes (bool)

  • node_attributes (List[str] | None)

  • edge_attributes (List[str] | None)

  • kind (Literal['Graph', 'MultiGraph', 'BiPartiteGraph'])

Return type:

Any

to_igraph(directed=True, use_vids=False, include_nodes=True, node_attributes=None, edge_attributes=None)#
Parameters:
  • directed (bool)

  • use_vids (bool)

  • include_nodes (bool)

  • node_attributes (List[str] | None)

  • edge_attributes (List[str] | None)

Return type:

Any

to_pandas()#
Return type:

Plottable

upload(memoize=True, validate=True)#
Parameters:
  • memoize (bool)

  • validate (bool)

Return type:

Plottable

PlotterBase Class#

class graphistry.PlotterBase.PlotterBase(*args, **kwargs)#

Bases: Plottable

Graph plotting class.

Created using Graphistry.bind().

Chained calls successively add data and visual encodings, and end with a plot call.

To streamline reuse and replayable notebooks, Plotter manipulations are immutable. Each chained call returns a new instance that derives from the previous one. The old plotter or the new one can then be used to create different graphs.

When using memoization, for .register(api=3) sessions with .plot(memoize=True), Pandas/cudf arrow coercions are memoized, and file uploads are skipped on same-hash dataframes.

The class supports convenience methods for mixing calls across Pandas, NetworkX, and IGraph.

Parameters:
  • args (Any)

  • kwargs (Any)

DGL_graph: Any | None#
addStyle(fg=None, bg=None, page=None, logo=None)#

Set general visual styles

See .bind() and .settings(url_params={}) for additional styling options, and style() for another way to set the same attributes.

To facilitate reuse and replayable notebooks, the addStyle() call is chainable. Invocation does not effect the old style: it instead returns a new Plotter instance with the new styles added to the existing ones. Both the old and new styles can then be used for different graphs.

addStyle() will extend the existing style settings, while style() will replace any in the same group

Parameters:
  • fg (dict) – Dictionary {‘blendMode’: str} of any valid CSS blend mode

  • bg (dict) – Nested dictionary of page background properties. {‘color’: str, ‘gradient’: {‘kind’: str, ‘position’: str, ‘stops’: list }, ‘image’: { ‘url’: str, ‘width’: int, ‘height’: int, ‘blendMode’: str }

  • logo (dict) – Nested dictionary of logo properties. { ‘url’: str, ‘autoInvert’: bool, ‘position’: str, ‘dimensions’: { ‘maxWidth’: int, ‘maxHeight’: int }, ‘crop’: { ‘top’: int, ‘left’: int, ‘bottom’: int, ‘right’: int }, ‘padding’: { ‘top’: int, ‘left’: int, ‘bottom’: int, ‘right’: int}, ‘style’: str}

  • page (dict) – Dictionary of page metadata settings. { ‘favicon’: str, ‘title’: str }

Returns:

Plotter

Return type:

Plotter

Example: Chained merge - results in color, blendMode, and url being set
g2 =  g.addStyle(bg={'color': 'black'}, fg={'blendMode': 'screen'})
g3 = g2.addStyle(bg={'image': {'url': 'http://site.com/watermark.png'}})
Example: Overwrite - results in blendMode multiply
g2 =  g.addStyle(fg={'blendMode': 'screen'})
g3 = g2.addStyle(fg={'blendMode': 'multiply'})
Example: Gradient background
g.addStyle(bg={'gradient': {'kind': 'linear', 'position': 45, 'stops': [['rgb(0,0,0)', '0%'], ['rgb(255,255,255)', '100%']]}})
Example: Page settings
g.addStyle(page={'title': 'Site - {{ name }}', 'favicon': 'http://site.com/logo.ico'})
base_url_client(v=None)#
Parameters:

v (str | None)

Return type:

str

base_url_server(v=None)#
Parameters:

v (str | None)

Return type:

str

bind(source=None, destination=None, node=None, edge=None, edge_title=None, edge_label=None, edge_color=None, edge_weight=None, edge_size=None, edge_opacity=None, edge_icon=None, edge_source_color=None, edge_destination_color=None, point_title=None, point_label=None, point_color=None, point_weight=None, point_size=None, point_opacity=None, point_icon=None, point_x=None, point_y=None, dataset_id=None, url=None, nodes_file_id=None, edges_file_id=None)#

Relate data attributes to graph structure and visual representation. To facilitate reuse and replayable notebooks, the binding call is chainable. Invocation does not effect the old binding: it instead returns a new Plotter instance with the new bindings added to the existing ones. Both the old and new bindings can then be used for different graphs.

Parameters:
  • source (Optional[str]) – Attribute containing an edge’s source ID

  • destination (Optional[str]) – Attribute containing an edge’s destination ID

  • node (Optional[str]) – Attribute containing a node’s ID

  • edge (Optional[str]) – Attribute containing an edge’s ID

  • edge_title (Optional[str]) – Attribute overriding edge’s minimized label text. By default, the edge source and destination is used.

  • edge_label (Optional[str]) – Attribute overriding edge’s expanded label text. By default, scrollable list of attribute/value mappings.

  • edge_color (Optional[str]) – Attribute overriding edge’s color. rgba (int64) or int32 palette index, see palette definitions for values. Based on Color Brewer.

  • edge_source_color (Optional[str]) – Attribute overriding edge’s source color if no edge_color, as an rgba int64 value.

  • edge_destination_color (Optional[str]) – Attribute overriding edge’s destination color if no edge_color, as an rgba int64 value.

  • edge_weight (Optional[str]) – Attribute overriding edge weight. Default is 1. Advanced layout controls will relayout edges based on this value.

  • point_title (Optional[str]) – Attribute overriding node’s minimized label text. By default, the node ID is used.

  • point_label (Optional[str]) – Attribute overriding node’s expanded label text. By default, scrollable list of attribute/value mappings.

  • point_color (Optional[str]) –

    Attribute overriding node’s color.rgba (int64) or int32 palette index, see palette definitions for values. Based on Color Brewer.

  • point_size (Optional[str]) – Attribute overriding node’s size. By default, uses the node degree. The visualization will normalize point sizes and adjust dynamically using semantic zoom.

  • point_x (Optional[str]) – Attribute overriding node’s initial x position. Combine with “.settings(url_params={‘play’: 0}))” to create a custom layout

  • point_y (Optional[str]) – Attribute overriding node’s initial y position. Combine with “.settings(url_params={‘play’: 0}))” to create a custom layout

  • dataset_id (Optional[str]) – Remote dataset id

  • url (Optional[str]) – Remote dataset URL

  • nodes_file_id (Optional[str]) – Remote nodes file id

  • edges_file_id (Optional[str]) – Remote edges file id

  • edge_size (str | None)

  • edge_opacity (str | None)

  • edge_icon (str | None)

  • point_weight (str | None)

  • point_opacity (str | None)

  • point_icon (str | None)

Returns:

Plotter

Return type:

Plotter

Example: Minimal

import graphistry
g = graphistry.bind()
g = g.bind(source='src', destination='dst')

Example: Node colors

import graphistry
g = graphistry.bind()
g = g.bind(source='src', destination='dst',
           node='id', point_color='color')

Example: Chaining

import graphistry
g = graphistry.bind(source='src', destination='dst', node='id')

g1 = g.bind(point_color='color1', point_size='size1')

g.bind(point_color='color1b')

g2a = g1.bind(point_color='color2a')
g2b = g1.bind(point_color='color2b', point_size='size2b')

g3a = g2a.bind(point_size='size3a')
g3b = g2b.bind(point_size='size3b')

In the above Chaining example, all bindings use src/dst/id. Colors and sizes bind to:

g: default/default
g1: color1/size1
g2a: color2a/size1
g2b: color2b/size2b
g3a: color2a/size3a
g3b: color2b/size3b
bolt(driver)#
chain(ops)#

ops is Union[List[ASTObject], Chain]

Parameters:

ops (Any | List[Any])

Return type:

Plottable

chain_remote(chain, api_token=None, dataset_id=None, output_type='all', format=None, df_export_args=None, node_col_subset=None, edge_col_subset=None, engine=None)#

chain is Union[List[ASTObject], Chain]

Parameters:
  • self (Plottable)

  • chain (Any | Dict[str, None | bool | str | float | int | List[None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]] | Dict[str, None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]]])

  • api_token (str | None)

  • dataset_id (str | None)

  • output_type (Literal['all', 'nodes', 'edges', 'shape'])

  • format (Literal['json', 'csv', 'parquet'] | None)

  • df_export_args (Dict[str, Any] | None)

  • node_col_subset (List[str] | None)

  • edge_col_subset (List[str] | None)

  • engine (Literal['pandas', 'cudf'] | None)

Return type:

Plottable

chain_remote_shape(chain, api_token=None, dataset_id=None, format=None, df_export_args=None, node_col_subset=None, edge_col_subset=None, engine=None)#

chain is Union[List[ASTObject], Chain]

Parameters:
  • self (Plottable)

  • chain (Any | Dict[str, None | bool | str | float | int | List[None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]] | Dict[str, None | bool | str | float | int | List[JSONVal] | Dict[str, JSONVal]]])

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • df_export_args (Dict[str, Any] | None)

  • node_col_subset (List[str] | None)

  • edge_col_subset (List[str] | None)

  • engine (Literal['pandas', 'cudf'] | None)

Return type:

DataFrame

client_protocol_hostname(v=None)#

Get or set the client protocol and hostname, e.g., “https://hub.graphistry.com” .

By default, uses {protocol()}://{server()}. Typically used when public browser routes are different from backend server routes, e.g., enterprise WAF routes for browser use and internal firewalls routes for server use.

Note that sets are global as PyGraphistry._config entries, so be careful in multi-user environments.

Parameters:

v (str | None)

Return type:

str

collapse(node, attribute, column, self_edges=False, unwrap=False, verbose=False)#
Parameters:
  • node (str | int)

  • attribute (str | int)

  • column (str | int)

  • self_edges (bool)

  • unwrap (bool)

  • verbose (bool)

Return type:

Plottable

compute_cugraph(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

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
compute_igraph(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

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
copy()#
Return type:

Plottable

cypher(query, params={})#

Execute a Cypher query against a Neo4j, Memgraph, or Amazon Neptune database and retrieve the results.

This method runs a Cypher query on a Neo4j, Memgraph, or Amazon Neptune graph database using a BOLT driver. The query results are transformed into DataFrames for nodes and edges, which are then bound to the current graph visualization context. You can also pass parameters to the Cypher query via the params argument.

Parameters:
  • query (str) – The Cypher query string to execute.

  • params (dict, optional) – Optional dictionary of parameters to pass to the Cypher query.

Returns:

Plotter with updated nodes and edges based on the query result.

Return type:

PlotterBase

Raises:

ValueError – If no BOLT driver connection is available.

Example (Simple Neo4j Query)

import graphistry
from neo4j import GraphDatabase

# Register with Neo4j connection details
uri = "bolt://localhost:7687"
driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))

graphistry.register(bolt=driver)

# Run a basic Cypher query
g = graphistry.cypher('''
    MATCH (node1)-[connection]-(node2)
    RETURN node1, connection, node2;
''')

# Visualize the results
g.plot()

Example (Simple Amazon Neptune Query)

from neo4j import GraphDatabase

# Register with Amazon Neptune connection details
uri = f"bolt://{url}:8182"
driver = GraphDatabase.driver(uri, auth=("ignored", "ignored"), encrypted=True)

graphistry.register(bolt=driver)

# Run a simple Cypher query
g = graphistry.cypher('''
    MATCH (node1)-[connection]-(node2)
    RETURN node1, connection, node2;
''')

# Visualize the results
g.plot()

Example (Simple Memgraph Query)

import graphistry
from neo4j import GraphDatabase

# Register with Memgraph connection details
MEMGRAPH = {
    'uri': "bolt://localhost:7687", 
    'auth': (" ", " ")
}

graphistry.register(api=3, username="X", password="Y", bolt=MEMGRAPH)

# Run a simple Cypher query on Memgraph
g = graphistry.cypher('''
    MATCH (node1)-[connection]-(node2)
    RETURN node1, connection, node2;
''')

# Visualize the results
g.plot()

Example (Parameterized Query with Node and Edge Inspection)

import graphistry
from neo4j import GraphDatabase

# Register with Neo4j connection details
uri = "bolt://localhost:7687"
driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))

graphistry.register(bolt=driver)

# Run a parameterized Cypher query
query = '''
    MATCH (node1)-[connection]-(node2)
    WHERE node1.name = $name
    RETURN node1, connection, node2;
'''
params = {"name": "Alice"}

g = graphistry.cypher(query, params)

# Inspect the resulting nodes and edges DataFrames
print(g._nodes)  # DataFrame with node information
print(g._edges)  # DataFrame with edge information

# Visualize the results
g.plot()

This demonstrates how to connect to Neo4j, Memgraph, or Amazon Neptune, run a simple or parameterized Cypher query, inspect query results (nodes and edges), and visualize the graph.

description(description)#

Upload description

Parameters:

description (str) – Upload description

drop_nodes(nodes)#
Parameters:

nodes (Any)

Return type:

Plottable

edges(edges, source=None, destination=None, edge=None, *args, **kwargs)#

Specify edge list data and associated edge attribute values. If a callable, will be called with current Plotter and whatever positional+named arguments

Parameters:
  • edges (Pandas dataframe, NetworkX graph, or IGraph graph) – Edges and their attributes, or transform from Plotter to edges

  • self (Plottable)

Returns:

Plotter

Return type:

Plotter

Example
import graphistry
df = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
graphistry
    .bind(source='src', destination='dst')
    .edges(df)
    .plot()
Example
import graphistry
df = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0], 'id': [0, 1, 2]})
graphistry
    .bind(source='src', destination='dst', edge='id')
    .edges(df)
    .plot()
Example
import graphistry
df = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
graphistry
    .edges(df, 'src', 'dst')
    .plot()
Example
import graphistry
df = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0], 'id': [0, 1, 2]})
graphistry
    .edges(df, 'src', 'dst', 'id')
    .plot()
Example
import graphistry

def sample_edges(g, n):
    return g._edges.sample(n)

df = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})

graphistry
    .edges(df, 'src', 'dst')
    .edges(sample_edges, n=2)
    .edges(sample_edges, None, None, None, 2)  # equivalent
    .plot()
encode_axis(rows=[])#

Render radial and linear axes with optional labels

Parameters:

rows (List[Dict]) – List of rows - { label: Optional[str],?r: float, ?x: float, ?y: float, ?internal: true, ?external: true, ?space: true }

Returns:

Plotter

Return type:

Plotter

Example: Several radial axes
g.encode_axis([
  {'r': 14, 'external': True, 'label': 'outermost'},
  {'r': 12, 'external': True},
  {'r': 10, 'space': True},
  {'r': 8, 'space': True},
  {'r': 6, 'internal': True},
  {'r': 4, 'space': True},
  {'r': 2, 'space': True, 'label': 'innermost'}
])
Example: Several horizontal axes
g.encode_axis([
  {"label": "a",  "y": 2, "internal": True },
  {"label": "b",  "y": 40, "external": True, "width": 20, "bounds": {"min": 40, "max": 400}},
])
encode_edge_badge(column, position='TopRight', categorical_mapping=None, continuous_binning=None, default_mapping=None, comparator=None, color=None, bg=None, fg=None, for_current=False, for_default=True, as_text=None, blend_mode=None, style=None, border=None, shape=None)#
encode_edge_color(column, palette=None, as_categorical=None, as_continuous=None, categorical_mapping=None, default_mapping=None, for_default=True, for_current=False)#

Set edge color with more control than bind()

Parameters:
  • column (str) – Data column name

  • palette (Optional[list]) – Optional list of color-like strings. Ex: [“black, “#FF0”, “rgb(255,255,255)” ]. Used as a gradient for continuous and round-robin for categorical.

  • as_categorical (Optional[bool]) – Interpret column values as categorical. Ex: Uses palette via round-robin when more values than palette entries.

  • as_continuous (Optional[bool]) – Interpret column values as continuous. Ex: Uses palette for an interpolation gradient when more values than palette entries.

  • categorical_mapping (Optional[dict]) – Mapping from column values to color-like strings. Ex: {“car”: “red”, “truck”: #000”}

  • default_mapping (Optional[str]) – Augment categorical_mapping with mapping for values not in categorical_mapping. Ex: default_mapping=”gray”.

  • for_default (Optional[bool]) – Use encoding for when no user override is set. Default on.

  • for_current (Optional[bool]) – Use encoding as currently active. Clearing the active encoding resets it to default, which may be different. Default on.

Returns:

Plotter

Return type:

Plotter

Example: See encode_point_color

encode_edge_icon(column, categorical_mapping=None, continuous_binning=None, default_mapping=None, comparator=None, for_default=True, for_current=False, as_text=False, blend_mode=None, style=None, border=None, shape=None)#

Set edge icon with more control than bind() Values from Font Awesome 4 such as “laptop”: https://fontawesome.com/v4.7.0/icons/ , image URLs (http://…), and data URIs (data:…). When as_text=True is enabled, values are instead interpreted as raw strings.

Parameters:
  • column (str) – Data column name

  • categorical_mapping (Optional[dict]) – Mapping from column values to icon name strings. Ex: {“toyota”: ‘car’, “ford”: ‘truck’}

  • default_mapping (Optional[Union[int,float]]) – Augment categorical_mapping with mapping for values not in categorical_mapping. Ex: default_mapping=50.

  • for_default (Optional[bool]) – Use encoding for when no user override is set. Default on.

  • for_current (Optional[bool]) – Use encoding as currently active. Clearing the active encoding resets it to default, which may be different. Default on.

  • as_text (Optional[bool]) – Values should instead be treated as raw strings, instead of icons and images. (Default False.)

Returns:

Plotter

Return type:

Plotter

Example: Set a string column of icons for the edge icons, same as bind(edge_icon=’my_column’)
g2a = g.encode_edge_icon('my_icons_column')
Example: Map specific values to specific icons, including with a default
g2a = g.encode_edge_icon('brands', categorical_mapping={'toyota': 'car', 'ford': 'truck'})
g2b = g.encode_edge_icon('brands', categorical_mapping={'toyota': 'car', 'ford': 'truck'}, default_mapping='question')
Example: Map countries to abbreviations
g2a = g.encode_edge_icon('country_abbrev', as_text=True)
g2b = g.encode_edge_icon('country', as_text=True, categorical_mapping={'England': 'UK', 'America': 'US'}, default_mapping='')
Example: Border
g2b = g.encode_edge_icon('country', border={'width': 3, color: 'black', 'stroke': 'dashed'}, 'categorical_mapping={'England': 'UK', 'America': 'US'})
encode_point_badge(column, position='TopRight', categorical_mapping=None, continuous_binning=None, default_mapping=None, comparator=None, color=None, bg=None, fg=None, for_current=False, for_default=True, as_text=None, blend_mode=None, style=None, border=None, shape=None)#
encode_point_color(column, palette=None, as_categorical=None, as_continuous=None, categorical_mapping=None, default_mapping=None, for_default=True, for_current=False)#

Set point color with more control than bind()

Parameters:
  • column (str) – Data column name

  • palette (Optional[list]) – Optional list of color-like strings. Ex: [“black, “#FF0”, “rgb(255,255,255)” ]. Used as a gradient for continuous and round-robin for categorical.

  • as_categorical (Optional[bool]) – Interpret column values as categorical. Ex: Uses palette via round-robin when more values than palette entries.

  • as_continuous (Optional[bool]) – Interpret column values as continuous. Ex: Uses palette for an interpolation gradient when more values than palette entries.

  • categorical_mapping (Optional[dict]) – Mapping from column values to color-like strings. Ex: {“car”: “red”, “truck”: #000”}

  • default_mapping (Optional[str]) – Augment categorical_mapping with mapping for values not in categorical_mapping. Ex: default_mapping=”gray”.

  • for_default (Optional[bool]) – Use encoding for when no user override is set. Default on.

  • for_current (Optional[bool]) – Use encoding as currently active. Clearing the active encoding resets it to default, which may be different. Default on.

Returns:

Plotter

Return type:

Plotter

Example: Set a palette-valued column for the color, same as bind(point_color=’my_column’)
g2a = g.encode_point_color('my_int32_palette_column')
g2b = g.encode_point_color('my_int64_rgb_column')
Example: Set a cold-to-hot gradient of along the spectrum blue, yellow, red
g2 = g.encode_point_color('my_numeric_col', palette=["blue", "yellow", "red"], as_continuous=True)
Example: Round-robin sample from 5 colors in hex format
g2 = g.encode_point_color('my_distinctly_valued_col', palette=["#000", "#00F", "#0F0", "#0FF", "#FFF"], as_categorical=True)
Example: Map specific values to specific colors, including with a default
g2a = g.encode_point_color('brands', categorical_mapping={'toyota': 'red', 'ford': 'blue'})
g2a = g.encode_point_color('brands', categorical_mapping={'toyota': 'red', 'ford': 'blue'}, default_mapping='gray')
encode_point_icon(column, categorical_mapping=None, continuous_binning=None, default_mapping=None, comparator=None, for_default=True, for_current=False, as_text=False, blend_mode=None, style=None, border=None, shape=None)#

Set node icon with more control than bind(). Values from Font Awesome 4 such as “laptop”: https://fontawesome.com/v4.7.0/icons/ , image URLs (http://…), and data URIs (data:…). When as_text=True is enabled, values are instead interpreted as raw strings.

Parameters:
  • column (str) – Data column name

  • categorical_mapping (Optional[dict]) – Mapping from column values to icon name strings. Ex: {“toyota”: ‘car’, “ford”: ‘truck’}

  • default_mapping (Optional[Union[int,float]]) – Augment categorical_mapping with mapping for values not in categorical_mapping. Ex: default_mapping=50.

  • for_default (Optional[bool]) – Use encoding for when no user override is set. Default on.

  • for_current (Optional[bool]) – Use encoding as currently active. Clearing the active encoding resets it to default, which may be different. Default on.

  • as_text (Optional[bool]) – Values should instead be treated as raw strings, instead of icons and images. (Default False.)

  • blend_mode (Optional[str]) – CSS blend mode

  • style (Optional[dict]) – CSS filter properties - opacity, saturation, luminosity, grayscale, and more

  • border (Optional[dict]) – Border properties - ‘width’, ‘color’, and ‘storke’

Returns:

Plotter

Return type:

Plotter

Example: Set a string column of icons for the point icons, same as bind(point_icon=’my_column’)
g2a = g.encode_point_icon('my_icons_column')
Example: Map specific values to specific icons, including with a default
g2a = g.encode_point_icon('brands', categorical_mapping={'toyota': 'car', 'ford': 'truck'})
g2b = g.encode_point_icon('brands', categorical_mapping={'toyota': 'car', 'ford': 'truck'}, default_mapping='question')
Example: Map countries to abbreviations
g2b = g.encode_point_icon('country_abbrev', as_text=True)
g2b = g.encode_point_icon('country', as_text=True, categorical_mapping={'England': 'UK', 'America': 'US'}, default_mapping='')
Example: Border
g2b = g.encode_point_icon('country', border={'width': 3, color: 'black', 'stroke': 'dashed'}, 'categorical_mapping={'England': 'UK', 'America': 'US'})
encode_point_size(column, categorical_mapping=None, default_mapping=None, for_default=True, for_current=False)#

Set point size with more control than bind()

Parameters:
  • column (str) – Data column name

  • categorical_mapping (Optional[dict]) – Mapping from column values to numbers. Ex: {“car”: 100, “truck”: 200}

  • default_mapping (Optional[Union[int,float]]) – Augment categorical_mapping with mapping for values not in categorical_mapping. Ex: default_mapping=50.

  • for_default (Optional[bool]) – Use encoding for when no user override is set. Default on.

  • for_current (Optional[bool]) – Use encoding as currently active. Clearing the active encoding resets it to default, which may be different. Default on.

Returns:

Plotter

Return type:

Plotter

Example: Set a numerically-valued column for the size, same as bind(point_size=’my_column’)
g2a = g.encode_point_size('my_numeric_column')
Example: Map specific values to specific colors, including with a default
g2a = g.encode_point_size('brands', categorical_mapping={'toyota': 100, 'ford': 200})
g2b = g.encode_point_size('brands', categorical_mapping={'toyota': 100, 'ford': 200}, default_mapping=50)
fa2_layout(fa2_params=None, circle_layout_params=None, singleton_layout=None, partition_key=None, engine=EngineAbstract.AUTO)#
Parameters:
  • fa2_params (Dict[str, Any] | None)

  • circle_layout_params (Dict[str, Any] | None)

  • singleton_layout (Callable[[Plottable, Tuple[float, float, float, float] | Any], Plottable] | None)

  • partition_key (str | None)

  • engine (EngineAbstract | str)

Return type:

Plottable

filter_edges_by_dict(filter_dict=None)#
Parameters:

filter_dict (dict | None)

Return type:

Plottable

filter_nodes_by_dict(filter_dict=None)#
Parameters:

filter_dict (dict | None)

Return type:

Plottable

from_cugraph(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)

from_igraph(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 – Whether to merge with existing node/edge dataframes (default True)

  • merge_if_existing – bool

Returns:

Plotter

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
from_networkx(G)#

Convert a NetworkX graph to a PyGraphistry graph.

This method takes a NetworkX graph and converts it into a format that PyGraphistry can use for visualization. It extracts the node and edge data from the NetworkX graph and binds them to the graph object for further manipulation or visualization using PyGraphistry’s API.

Parameters:

G (networkx.Graph or networkx.DiGraph) – The NetworkX graph to convert.

Returns:

A PyGraphistry Plottable object with the node and edge data from the NetworkX graph.

Return type:

Plottable

Example: Basic NetworkX Conversion
import graphistry
import networkx as nx

# Create a NetworkX graph
G = nx.Graph()
G.add_nodes_from([
    (1, {"v": "one"}), 
    (2, {"v": "two"}), 
    (3, {"v": "three"}), 
    (4, {"v": "four"}), 
    (7, {"v": "seven"}), 
    (8, {"v": "eight"})
])
G.add_edges_from([
    [2, 3], 
    [3, 4], 
    [7, 8]
])

# Convert the NetworkX graph to PyGraphistry format
g = from_networkx(G)

g.plot()

This example creates a simple NetworkX graph with nodes and edges, converts it using from_networkx(), and then plots it with the PyGraphistry API.

Example: Using Custom Node and Edge Bindings
import graphistry
import networkx as nx

# Create a NetworkX graph with attributes
G = nx.Graph()
G.add_nodes_from([
    (1, {"v": "one"}), 
    (2, {"v": "two"}), 
    (3, {"v": "three"}), 
    (4, {"v": "four"}), 
    (7, {"v": "seven"}), 
    (8, {"v": "eight"})
])
G.add_edges_from([
    [2, 3], 
    [3, 4], 
    [7, 8]
])

# Bind custom node and edge names when converting from NetworkX to PyGraphistry
g = graphistry.bind(source='src', destination='dst').from_networkx(G)

g.plot()
get_degrees(col='degree', degree_in='degree_in', degree_out='degree_out')#
Parameters:
  • col (str)

  • degree_in (str)

  • degree_out (str)

Return type:

Plottable

get_indegrees(col='degree_in')#
Parameters:

col (str)

Return type:

Plottable

get_outdegrees(col='degree_out')#
Parameters:

col (str)

Return type:

Plottable

get_topological_levels(level_col='level', allow_cycles=True, warn_cycles=True, remove_self_loops=True)#
Parameters:
  • level_col (str)

  • allow_cycles (bool)

  • warn_cycles (bool)

  • remove_self_loops (bool)

Return type:

Plottable

graph(ig)#

Specify the node and edge data.

Parameters:

ig (Any) – NetworkX graph or an IGraph graph with node and edge attributes.

Returns:

Plotter

Return type:

Plotter

gsql(query, bindings={}, dry_run=False)#

Run Tigergraph query in interpreted mode and return transformed Plottable

param query:

Code to run

type query:

str

param bindings:

Mapping defining names of returned ‘edges’ and/or ‘nodes’, defaults to @@nodeList and @@edgeList

type bindings:

Optional[dict]

param dry_run:

Return target URL without running

type dry_run:

bool

returns:

Plotter

rtype:

Plotter

Example: Minimal
import graphistry
tg = graphistry.tigergraph()
tg.gsql("""
INTERPRET QUERY () FOR GRAPH Storage { 

    OrAccum<BOOL> @@stop;
    ListAccum<EDGE> @@edgeList;
    SetAccum<vertex> @@set;

    @@set += to_vertex("61921", "Pool");

    Start = @@set;

    while Start.size() > 0 and @@stop == false do

    Start = select t from Start:s-(:e)-:t
    where e.goUpper == TRUE
    accum @@edgeList += e
    having t.type != "Service";
    end;

    print @@edgeList;
}
""").plot()
Example: Full
import graphistry
tg = graphistry.tigergraph()
tg.gsql("""
INTERPRET QUERY () FOR GRAPH Storage { 

    OrAccum<BOOL> @@stop;
    ListAccum<EDGE> @@edgeList;
    SetAccum<vertex> @@set;

    @@set += to_vertex("61921", "Pool");

    Start = @@set;

    while Start.size() > 0 and @@stop == false do

    Start = select t from Start:s-(:e)-:t
    where e.goUpper == TRUE
    accum @@edgeList += e
    having t.type != "Service";
    end;

    print @@my_edge_list;
}
""", {'edges': 'my_edge_list'}).plot()
gsql_endpoint(method_name, args={}, bindings={}, db=None, dry_run=False)#

Invoke Tigergraph stored procedure at a user-definend endpoint and return transformed Plottable

Parameters:
  • method_name (str) – Stored procedure name

  • args (Optional[dict]) – Named endpoint arguments

  • bindings (Optional[dict]) – Mapping defining names of returned ‘edges’ and/or ‘nodes’, defaults to @@nodeList and @@edgeList

  • db (Optional[str]) – Name of the database, defaults to value set in .tigergraph(…)

  • dry_run (bool) – Return target URL without running

Returns:

Plotter

Return type:

Plotter

Example: Minimal
import graphistry
tg = graphistry.tigergraph(db='my_db')
tg.gsql_endpoint('neighbors').plot()
Example: Full
import graphistry
tg = graphistry.tigergraph()
tg.gsql_endpoint('neighbors', {'k': 2}, {'edges': 'my_edge_list'}, 'my_db').plot()
Example: Read data
import graphistry
tg = graphistry.tigergraph()
out = tg.gsql_endpoint('neighbors')
(nodes_df, edges_df) = (out._nodes, out._edges)
hop(nodes, hops=1, to_fixed_point=False, direction='forward', edge_match=None, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, return_as_wave_front=False, target_wave_front=None)#
Parameters:
  • nodes (DataFrame | None)

  • hops (int | None)

  • to_fixed_point (bool)

  • direction (str)

  • edge_match (dict | None)

  • source_node_match (dict | None)

  • destination_node_match (dict | None)

  • source_node_query (str | None)

  • destination_node_query (str | None)

  • edge_query (str | None)

  • return_as_wave_front (bool)

  • target_wave_front (DataFrame | None)

Return type:

Plottable

hypergraph(raw_events, entity_types=None, opts={}, drop_na=True, drop_edge_attrs=False, verbose=True, direct=False, engine='pandas', npartitions=None, chunksize=None)#

Transform a dataframe into a hypergraph.

Parameters:
  • raw_events (pandas.DataFrame) – Dataframe to transform (pandas or cudf).

  • entity_types (Optional[list]) – Columns (strings) to turn into nodes, None signifies all

  • opts (dict) – See below

  • drop_edge_attrs (bool) – Whether to include each row’s attributes on its edges, defaults to False (include)

  • verbose (bool) – Whether to print size information

  • direct (bool) – Omit hypernode and instead strongly connect nodes in an event

  • engine (bool) – String (pandas, cudf, …) for engine to use

  • npartitions (Optional[int]) – For distributed engines, how many coarse-grained pieces to split events into

  • chunksize (Optional[int]) – For distributed engines, split events after chunksize rows

  • drop_na (bool)

Create a graph out of the dataframe, and return the graph components as dataframes, and the renderable result Plotter. Hypergraphs reveal relationships between rows and between column values. This transform is useful for lists of events, samples, relationships, and other structured high-dimensional data.

Specify local compute engine by passing engine=’pandas’, ‘cudf’, ‘dask’, ‘dask_cudf’ (default: ‘pandas’). If events are not in that engine’s format, they will be converted into it.

The transform creates a node for every unique value in the entity_types columns (default: all columns). If direct=False (default), every row is also turned into a node. Edges are added to connect every table cell to its originating row’s node, or if direct=True, to the other nodes from the same row. Nodes are given the attribute ‘type’ corresponding to the originating column name, or in the case of a row, ‘EventID’. Options further control the transform, such column category definitions for controlling whether values reocurring in different columns should be treated as one node, or whether to only draw edges between certain column type pairs.

Consider a list of events. Each row represents a distinct event, and each column some metadata about an event. If multiple events have common metadata, they will be transitively connected through those metadata values. The layout algorithm will try to cluster the events together. Conversely, if an event has unique metadata, the unique metadata will turn into nodes that only have connections to the event node, and the clustering algorithm will cause them to form a ring around the event node.

Best practice is to set EVENTID to a row’s unique ID, SKIP to all non-categorical columns (or entity_types to all categorical columns), and CATEGORY to group columns with the same kinds of values.

To prevent creating nodes for null values, set drop_na=True. Some dataframe engines may have undesirable null handling, and recommend replacing None values with np.nan .

The optional opts={...} configuration options are:

  • ‘EVENTID’: Column name to inspect for a row ID. By default, uses the row index.

  • ‘CATEGORIES’: Dictionary mapping a category name to inhabiting columns. E.g., {‘IP’: [‘srcAddress’, ‘dstAddress’]}. If the same IP appears in both columns, this makes the transform generate one node for it, instead of one for each column.

  • ‘DELIM’: When creating node IDs, defines the separator used between the column name and node value

  • ‘SKIP’: List of column names to not turn into nodes. For example, dates and numbers are often skipped.

  • ‘EDGES’: For direct=True, instead of making all edges, pick column pairs. E.g., {‘a’: [‘b’, ‘d’], ‘d’: [‘d’]} creates edges between columns a->b and a->d, and self-edges d->d.

Returns:

{‘entities’: DF, ‘events’: DF, ‘edges’: DF, ‘nodes’: DF, ‘graph’: Plotter}

Return type:

dict

Parameters:
  • entity_types (List[str] | None)

  • opts (dict)

  • drop_na (bool)

  • drop_edge_attrs (bool)

  • verbose (bool)

  • direct (bool)

  • engine (str)

  • npartitions (int | None)

  • chunksize (int | None)

Example: Connect user<-row->boss

import graphistry
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df)
g = h['graph'].plot()

Example: Connect user->boss

import graphistry
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True)
g = h['graph'].plot()

Example: Connect user<->boss

import graphistry
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True, opts={'EDGES': {'user': ['boss'], 'boss': ['user']}})
g = h['graph'].plot()

Example: Only consider some columns for nodes

import graphistry
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, entity_types=['boss'])
g = h['graph'].plot()

Example: Collapse matching user::<id> and boss::<id> nodes into one person::<id> node

import graphistry
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, opts={'CATEGORIES': {'person': ['user', 'boss']}})
g = h['graph'].plot()

Example: Use cudf engine instead of pandas

import cudf, graphistry
users_gdf = cudf.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_gdf, engine='cudf')
g = h['graph'].plot()
igraph2pandas(ig)#

Under current bindings, transform an IGraph into a pandas edges dataframe and a nodes dataframe.

Deprecated in favor of .from_igraph()

Example
import graphistry
g = graphistry.bind()

es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
g = g.bind(source='src', destination='dst').edges(es)

ig = g.pandas2igraph(es)
ig.vs['community'] = ig.community_infomap().membership

(es2, vs2) = g.igraph2pandas(ig)
g.nodes(vs2).bind(point_color='community').plot()
infer_labels()#
Returns:

Plotter w/neo4j

  • Prefers point_title/point_label if available

  • Fallback to node id

  • Raises exception if no nodes available, no likely candidates, and no matching node id fallback

Example

import graphistry
g = graphistry.nodes(pd.read_csv('nodes.csv'), 'id_col').infer_labels()
g.plot()
keep_nodes(nodes)#
Parameters:

nodes (List | Any)

Return type:

Plottable

layout_cugraph(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)

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()
layout_graphviz(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)#

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, Any]]) – Graphviz graph attributes, see https://graphviz.org/docs/graph/

  • node_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.NodeAttr, Any]]) – Graphviz node attributes, see https://graphviz.org/docs/nodes/

  • edge_attr (Optional[Dict[graphistry.plugins_types.graphviz_types.EdgeAttr, Any]]) – 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'
)
layout_igraph(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

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()
layout_settings(play=None, locked_x=None, locked_y=None, locked_r=None, left=None, top=None, right=None, bottom=None, lin_log=None, strong_gravity=None, dissuade_hubs=None, edge_influence=None, precision_vs_speed=None, gravity=None, scaling_ratio=None)#

Set layout options. Additive over previous settings.

Corresponds to options at https://hub.graphistry.com/docs/api/1/rest/url/#urloptions

Example: Animated radial layout

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'boss': ['c','c','e','e']})
nodes = pd.DataFrame({
    'n': ['a', 'b', 'c', 'd', 'e'],
    'y': [1,   1,   2,   3,   4],
    'x': [1,   1,   0,   0,   0],
})
g = (graphistry
    .edges(edges, 's', 'd')
    .nodes(nodes, 'n')
    .layout_settings(locked_r=True, play=2000)
g.plot()
Parameters:
  • play (int | None)

  • locked_x (bool | None)

  • locked_y (bool | None)

  • locked_r (bool | None)

  • left (float | None)

  • top (float | None)

  • right (float | None)

  • bottom (float | None)

  • lin_log (bool | None)

  • strong_gravity (bool | None)

  • dissuade_hubs (bool | None)

  • edge_influence (float | None)

  • precision_vs_speed (float | None)

  • gravity (float | None)

  • scaling_ratio (float | None)

materialize_nodes(reuse=True, engine=EngineAbstract.AUTO)#
Parameters:
  • reuse (bool)

  • engine (EngineAbstract | str)

Return type:

Plottable

name(name)#

Upload name

Parameters:

name (str) – Upload name

networkx2pandas(g)#
networkx_checkoverlap(g)#

Raise an error if the node attribute already exists in the graph

nodes(nodes, node=None, *args, **kwargs)#

Specify the set of nodes and associated data. If a callable, will be called with current Plotter and whatever positional+named arguments

Must include any nodes referenced in the edge list.

Parameters:

nodes (Pandas dataframe or Callable) – Nodes and their attributes.

Returns:

Plotter

Return type:

Plotter

Example
import graphistry

es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
g = graphistry
    .bind(source='src', destination='dst')
    .edges(es)

vs = pandas.DataFrame({'v': [0,1,2], 'lbl': ['a', 'b', 'c']})
g = g.bind(node='v').nodes(vs)

g.plot()
Example
import graphistry

es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
g = graphistry.edges(es, 'src', 'dst')

vs = pandas.DataFrame({'v': [0,1,2], 'lbl': ['a', 'b', 'c']})
g = g.nodes(vs, 'v)

g.plot()
Example
import graphistry

def sample_nodes(g, n):
    return g._nodes.sample(n)

df = pandas.DataFrame({'id': [0,1,2], 'v': [1,2,0]})

graphistry
    .nodes(df, 'id')
    ..nodes(sample_nodes, n=2)
    ..nodes(sample_nodes, None, 2)  # equivalent
    .plot()
nodexl(xls_or_url, source='default', engine=None, verbose=False)#
pandas2igraph(edges, directed=True)#

Convert a pandas edge dataframe to an IGraph graph.

Uses current bindings. Defaults to treating edges as directed.

Example
import graphistry
g = graphistry.bind()

es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
g = g.bind(source='src', destination='dst')

ig = g.pandas2igraph(es)
ig.vs['community'] = ig.community_infomap().membership
g.bind(point_color='community').plot(ig)
pipe(graph_transform, *args, **kwargs)#

Create new Plotter derived from current

Parameters:

graph_transform (Callable)

Return type:

Plottable

Example: Simple
import graphistry

def fill_missing_bindings(g, source='src', destination='dst):
    return g.bind(source=source, destination=destination)

graphistry
    .edges(pandas.DataFrame({'src': [0,1,2], 'd': [1,2,0]}))
    .pipe(fill_missing_bindings, destination='d')  # binds 'src'
    .plot()
plot(graph=None, nodes=None, name=None, description=None, render='auto', skip_upload=False, as_files=False, memoize=True, extra_html='', override_html_style=None, validate=True)#

Upload data to the Graphistry server and show as an iframe of it.

Uses the currently bound schema structure and visual encodings. Optional parameters override the current bindings.

When used in a notebook environment, will also show an iframe of the visualization.

Parameters:
  • graph (Any) – Edge table (pandas, arrow, cudf) or graph (NetworkX, IGraph).

  • nodes (Any) – Nodes table (pandas, arrow, cudf)

  • name (str) – Upload name.

  • description (str) – Upload description.

  • render (Optional[Union[bool, RenderModes]] = "auto") – Whether to render the visualization using the native environment (default “auto”, True), a URL (“url”, False, None), a PyGraphistry Plottable (“g”), thon object (“ipython”), interactive Databricks object (“databricks”), or open a local web browser (“browser”). If _render is set via .settings(), and set to None, use _render.

  • skip_upload (bool) – Return node/edge/bindings that would have been uploaded. By default, upload happens.

  • as_files (bool) – Upload distinct node/edge files under the managed Files PI. Default off, will switch to default-on when stable.

  • memoize (bool) – Tries to memoize pandas/cudf->arrow conversion, including skipping upload. Default on.

  • extra_html (Optional[str]) – Allow injecting arbitrary HTML into the visualization iframe.

  • override_html_style (Optional[str]) – Set fully custom style tag.

  • validate (Optional[bool]) – Controls validations, including those for encodings.

Example: Simple
import graphistry
es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
graphistry
    .bind(source='src', destination='dst')
    .edges(es)
    .plot()
Example: Shorthand
import graphistry
es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
graphistry
    .bind(source='src', destination='dst')
    .plot(es)
privacy(mode=None, notify=None, invited_users=None, message=None)#

Set local sharing mode

Parameters:
  • mode (Optional[Mode]) – Either “private”, “public”, or inherit from global privacy()

  • notify (Optional[bool]) – Whether to email the recipient(s) upon upload, defaults to global privacy()

  • invited_users (Optional[List]) – List of recipients, where each is {“email”: str, “action”: str} and action is “10” (view) or “20” (edit), defaults to global privacy()

  • message (str | None) – Email to send when notify=True

Requires an account with sharing capabilities.

Shared datasets will appear in recipients’ galleries.

If mode is set to “private”, only accounts in invited_users list can access. Mode “public” permits viewing by any user with the URL.

Action “10” (view) gives read access, while action “20” (edit) gives edit access, like changing the sharing mode.

When notify is true, uploads will trigger notification emails to invitees. Email will use visualization’s “.name()”

When settings are not specified, they are inherited from the global graphistry.privacy() defaults

Example: Limit visualizations to current user

import graphistry
graphistry.register(api=3, username='myuser', password='mypassword')

#Subsequent uploads default to using .privacy() settings
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True)
g = h['graph']
g = g.privacy()  # default uploads to mode="private"
g.plot()

Example: Default to publicly viewable visualizations

import graphistry
graphistry.register(api=3, username='myuser', password='mypassword')

#Subsequent uploads default to using .privacy() settings
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True)
g = h['graph']
#g = g.privacy(mode="public")  # can skip calling .privacy() for this default
g.plot()

Example: Default to sharing with select teammates, and keep notifications opt-in

import graphistry
graphistry.register(api=3, username='myuser', password='mypassword')

#Subsequent uploads default to using .privacy() settings
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True)
g = h['graph']
g = g.privacy(
    mode="private",
    invited_users=[
        {"email": "friend1@acme.org", "action": "10"}, # view
        {"email": "friend2@acme.org", "action": "20"}, # edit
    ],
    notify=False)
g.plot()

Example: Keep visualizations public and email notifications upon upload

import graphistry
graphistry.register(api=3, username='myuser', password='mypassword')

#Subsequent uploads default to using .privacy() settings
users_df = pd.DataFrame({'user': ['a','b','x'], 'boss': ['x', 'x', 'y']})
h = graphistry.hypergraph(users_df, direct=True)
g = h['graph']
g = g.name('my cool viz')  # For friendlier invitations
g = g.privacy(
    mode="public",
    invited_users=[
        {"email": "friend1@acme.org", "action": "10"}, # view
        {"email": "friend2@acme.org", "action": "20"}, # edit
    ],
    notify=True)
g.plot()
protocol(v=None)#

Get or set the server protocol, e.g., “https”

Note that sets are global as PyGraphistry._config entries, so be careful in multi-user environments.

Parameters:

v (str | None)

Return type:

str

prune_self_edges()#
Return type:

Plottable

python_remote_g(code, api_token=None, dataset_id=None, format='parquet', output_type='all', engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • output_type (Literal['all', 'nodes', 'edges', 'shape'] | ~typing.Literal['table', 'shape'] | ~typing.Literal['json'] | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

Plottable

python_remote_json(code, api_token=None, dataset_id=None, engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

Any

python_remote_table(code, api_token=None, dataset_id=None, format='parquet', output_type='table', engine='cudf', run_label=None, validate=True)#
Parameters:
  • self (Plottable)

  • code (str)

  • api_token (str | None)

  • dataset_id (str | None)

  • format (Literal['json', 'csv', 'parquet'] | None)

  • output_type (Literal['table', 'shape'] | None)

  • engine (Literal['pandas', 'cudf'])

  • run_label (str | None)

  • validate (bool)

Return type:

DataFrame

reset_caches()#

Reset memoization caches

scene_settings(menu=None, info=None, show_arrows=None, point_size=None, edge_curvature=None, edge_opacity=None, point_opacity=None)#

Set scene options. Additive over previous settings.

Corresponds to options at https://hub.graphistry.com/docs/api/1/rest/url/#urloptions

Example: Hide arrows and straighten edges

import graphistry, pandas as pd
edges = pd.DataFrame({'s': ['a','b','c','d'], 'boss': ['c','c','e','e']})
nodes = pd.DataFrame({
    'n': ['a', 'b', 'c', 'd', 'e'],
    'y': [1,   1,   2,   3,   4],
    'x': [1,   1,   0,   0,   0],
})
g = (graphistry
    .edges(edges, 's', 'd')
    .nodes(nodes, 'n')
    .scene_settings(show_arrows=False, edge_curvature=0.0)
g.plot()
Parameters:
  • menu (bool | None)

  • info (bool | None)

  • show_arrows (bool | None)

  • point_size (float | None)

  • edge_curvature (float | None)

  • edge_opacity (float | None)

  • point_opacity (float | None)

server(v=None)#

Get or set the server basename, e.g., “hub.graphistry.com”

Note that sets are global as PyGraphistry._config entries, so be careful in multi-user environments.

Parameters:

v (str | None)

Return type:

str

settings(height=None, url_params={}, render=None)#

Specify iframe height and add URL parameter dictionary.

The library takes care of URI component encoding for the dictionary.

Parameters:
  • height (int) – Height in pixels.

  • url_params (dict) – Dictionary of querystring parameters to append to the URL.

  • render (bool) – Whether to render the visualization using the native notebook environment (default True), or return the visualization URL

spanner_gql_to_g(query)#

Submit GQL query to google spanner graph database and return Plottable with nodes and edges populated

GQL must be a path query with a syntax similar to the following, it’s recommended to return the path with SAFE_TO_JSON(p), TO_JSON() can also be used, but not recommend. LIMIT is optional, but for large graphs with millions of edges or more, it’s best to filter either in the query or use LIMIT so as not to exhaust GPU memory.

query=f’’’GRAPH my_graph MATCH p = (a)-[b]->(c) LIMIT 100000 return SAFE_TO_JSON(p) as path’’’

Parameters:
  • query (Str) – GQL query string

  • self (Plottable)

Returns:

Plottable with the results of GQL query as a graph

Return type:

Plottable

**Example: calling spanner_gql_to_g
import graphistry

# credentials_file is optional, all others are required
SPANNER_CONF = { "project_id":  PROJECT_ID,                 
                 "instance_id": INSTANCE_ID, 
                 "database_id": DATABASE_ID, 
                 "credentials_file": CREDENTIALS_FILE }

graphistry.register(..., spanner_config=SPANNER_CONF)

query=f'''GRAPH my_graph
MATCH p = (a)-[b]->(c) LIMIT 100000 return SAFE_TO_JSON(p) as path'''

g = graphistry.spanner_gql_to_g(query)

g.plot()
spanner_init(spanner_config)#

Initializes a SpannerGraph object with the provided configuration and connects to the instance db

spanner_config dict must contain the include the following keys, credentials_file is optional:
  • “project_id”: The GCP project ID.

  • “instance_id”: The Spanner instance ID.

  • “database_id”: The Spanner database ID.

  • “credentials_file”: json file API key for service accounts

:param spanner_config A dictionary containing the Spanner configuration. :type (Dict[str, str]) :return: Plottable with a Spanner connection :rtype: Plottable :raises ValueError: If any of the required keys in spanner_config are missing or have invalid values.

Parameters:
  • self (Plottable)

  • spanner_config (Dict[str, str])

Return type:

Plottable

spanner_query_to_df(query)#

Submit query to google spanner database and return a df of the results

query can be SQL or GQL as long as table of results are returned

query=’SELECT * from Account limit 10000’

Parameters:
  • query (Str) – query string

  • self (Plottable)

Returns:

Pandas DataFrame with the results of query

Return type:

pd.DataFrame

**Example: calling spanner_query_to_df
import graphistry

# credentials_file is optional, all others are required
SPANNER_CONF = { "project_id":  PROJECT_ID,                 
                 "instance_id": INSTANCE_ID, 
                 "database_id": DATABASE_ID, 
                 "credentials_file": CREDENTIALS_FILE }

graphistry.register(..., spanner_config=SPANNER_CONF)

query='SELECT * from Account limit 10000'

df = graphistry.spanner_query_to_df(query)

g.plot()
style(fg=None, bg=None, page=None, logo=None)#

Set general visual styles

See .bind() and .settings(url_params={}) for additional styling options, and addStyle() for another way to set the same attributes.

To facilitate reuse and replayable notebooks, the style() call is chainable. Invocation does not effect the old style: it instead returns a new Plotter instance with the new styles added to the existing ones. Both the old and new styles can then be used for different graphs.

style() will fully replace any defined parameter in the existing style settings, while addStyle() will merge over previous values

Parameters:
  • fg (dict) – Dictionary {‘blendMode’: str} of any valid CSS blend mode

  • bg (dict) – Nested dictionary of page background properties. { ‘color’: str, ‘gradient’: {‘kind’: str, ‘position’: str, ‘stops’: list }, ‘image’: { ‘url’: str, ‘width’: int, ‘height’: int, ‘blendMode’: str }

  • logo (dict) – Nested dictionary of logo properties. { ‘url’: str, ‘autoInvert’: bool, ‘position’: str, ‘dimensions’: { ‘maxWidth’: int, ‘maxHeight’: int }, ‘crop’: { ‘top’: int, ‘left’: int, ‘bottom’: int, ‘right’: int }, ‘padding’: { ‘top’: int, ‘left’: int, ‘bottom’: int, ‘right’: int}, ‘style’: str}

  • page (dict) – Dictionary of page metadata settings. { ‘favicon’: str, ‘title’: str }

Returns:

Plotter

Return type:

Plotter

Example: Chained merge - results in url and blendMode being set, while color is dropped
g2 =  g.style(bg={'color': 'black'}, fg={'blendMode': 'screen'})
g3 = g2.style(bg={'image': {'url': 'http://site.com/watermark.png'}})
Example: Gradient background
g.style(bg={'gradient': {'kind': 'linear', 'position': 45, 'stops': [['rgb(0,0,0)', '0%'], ['rgb(255,255,255)', '100%']]}})
Example: Page settings
g.style(page={'title': 'Site - {{ name }}', 'favicon': 'http://site.com/logo.ico'})
tigergraph(protocol='http', server='localhost', web_port=14240, api_port=9000, db=None, user='tigergraph', pwd='tigergraph', verbose=False)#

Register Tigergraph connection setting defaults

Parameters:
  • protocol (Optional[str]) – Protocol used to contact the database.

  • server (Optional[str]) – Domain of the database

  • web_port (Optional[int])

  • api_port (Optional[int])

  • db (Optional[str]) – Name of the database

  • user (Optional[str])

  • pwd (Optional[str])

  • verbose (Optional[bool]) – Whether to print operations

Returns:

Plotter

Return type:

Plotter

Example: Standard
import graphistry
tg = graphistry.tigergraph(protocol='https', server='acme.com', db='my_db', user='alice', pwd='tigergraph2')                    
to_cudf()#
Return type:

Plottable

to_cugraph(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:
  • directed (bool)

  • include_nodes (bool)

  • node_attributes (List[str] | None)

  • edge_attributes (List[str] | None)

  • kind (Literal['Graph', 'MultiGraph', 'BiPartiteGraph'])

to_igraph(directed=True, use_vids=False, include_nodes=True, node_attributes=None, edge_attributes=None)#

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)

to_pandas()#
Return type:

Plottable

upload(memoize=True, validate=True)#

Upload data to the Graphistry server and return as a Plottable. Headless-centric variant of plot().

Uses the currently bound schema structure and visual encodings. Optional parameters override the current bindings.

Upon successful upload, returned Plottable will have set the fields dataset_id, url, edges_file_id, and if applicable, nodes_file_id.

Parameters:
  • memoize (bool) – Tries to memoize pandas/cudf->arrow conversion, including skipping upload. Default true.

  • validate (bool) – Controls validations, including those for encodings. Default true.

Return type:

Plottable

Example: Simple
import graphistry
es = pandas.DataFrame({'src': [0,1,2], 'dst': [1,2,0]})
g1 = graphistry
    .bind(source='src', destination='dst')
    .edges(es)
g2 = g1.upload()
print(f'dataset id: {g2._dataset_id}, url: {g2._url}')
graphistry.PlotterBase.maybe_cudf()#
graphistry.PlotterBase.maybe_dask_cudf()#
graphistry.PlotterBase.maybe_dask_dataframe()#
graphistry.PlotterBase.maybe_spark()#