Plotter API Reference#
The below Python API reference documentation is for three views of the core graph abstraction, Plottable:
The
graphistry.plotter.Plotter
class that mixes in all layers such as pluginsThe
graphistry.Plottable
abstract interface for the core Graphistry graph objectThe
graphistry.PlotterBase
class implementing it
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:
graphistry.PlotterBase.PlotterBase
: Base class for plotting graphs.graphistry.compute.ComputeMixin
: Enables computation-related functions like degree calculations.graphistry.layouts.LayoutsMixin
: Provides methods for controlling graph layouts.graphistry.compute.conditional.ConditionalMixin
: Adds support for conditional graph operations.graphistry.feature_utils.FeatureMixin
: Adds feature engineering capabilities.graphistry.umap_utils.UMAPMixin
: Integrates UMAP for dimensionality reduction.graphistry.compute.cluster.ClusterMixin
: Enables clustering-related functionalities.graphistry.dgl_utils.DGLGraphMixin
: Integrates deep graph learning with DGL.graphistry.text_utils.SearchToGraphMixin
: Supports converting search results into graphs.graphistry.embed_utils.HeterographEmbedModuleMixin
: Adds heterograph embedding capabilities.graphistry.gremlin.GremlinMixin
: Provides Gremlin query support for graph databases.graphistry.gremlin.CosmosMixin
: Integrates with Azure Cosmos DB.graphistry.gremlin.NeptuneMixin
: Integrates with AWS Neptune DB.
- 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:
- 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:
- 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:
- 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:
- copy()#
- 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:
- fa2_layout(fa2_params=None, circle_layout_params=None, singleton_layout=None, partition_key=None, engine=EngineAbstract.AUTO)#
- filter_edges_by_dict(filter_dict=None)#
- Parameters:
filter_dict (dict | None)
- Return type:
- filter_nodes_by_dict(filter_dict=None)#
- Parameters:
filter_dict (dict | None)
- Return type:
- 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)
- get_degrees(col='degree', degree_in='degree_in', degree_out='degree_out')#
- Parameters:
col (str)
degree_in (str)
degree_out (str)
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- pipe(graph_transform, *args, **kwargs)#
- Parameters:
graph_transform (Callable)
- Return type:
- 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:
- protocol(v=None)#
- Parameters:
v (str | None)
- Return type:
str
- 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:
- 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:
- 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:
- 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
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:
- 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:
- 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:
- 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:
- 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
- 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:
- 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
- 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)#
- filter_edges_by_dict(filter_dict=None)#
- Parameters:
filter_dict (dict | None)
- Return type:
- filter_nodes_by_dict(filter_dict=None)#
- Parameters:
filter_dict (dict | None)
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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()
- 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=Truedrop_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:
- 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:
- 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:
- 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
- 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:
- 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:
- **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.
- 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_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)
- 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:
- 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()#