10 Minutes to Graphistry Visualization#

This guide covers core visualization topics like the difference between uploading and viewing graphs, how the client/server architecture works, and how to use PyGraphistry’s fluent API to create powerful visualizations by combining ideas like encodings, layouts, and settings. Finally, we overview how to embed visualizations into different workflows.

Key Concepts#

Client/Server Architecture: Uploading vs. Serving vs. Viewing#

PyGraphistry uses a client-server model. By separating the uploader, server, and viewer, we can achieve better performance, new capabilities, and a variety of usage modes.

  • Upload Client: In your local environment, you can shape data and call the Graphistry API to upload it to a server (self-hosted or Graphistry Hub).

  • Visualization Server: The server processes the data using GPU acceleration to handle large graphs.

  • Visualization Client: The graph is then explored in your browser, where interactions like zooming and filtering are handled smoothly by using local and remote GPU resources as appropriate.

This split architecture allows scalable, high-performance visualization for even the largest datasets.

Fluent API Style#

PyGraphistry uses a fluent style API, which means that methods can be chained together. This allows for concise and readable code without an extensive setup:

g1 = graphistry.edges(df, 'src', 'dst')
g2 = g1.nodes(df2, 'n')
g3 = g2.encode_point_size('score')
g3.plot()

# As shorter fluent lines
g = graphistry.edges(df, 'src', 'dst').nodes(df2, 'n')
g.encode_point_size('score').plot()

This approach lets you layer operations as needed, keeping code light and intuitive.

Shaping Your Data#

PyGraphistry supports flexible shaping of your graph data:

  • `.edges()` & `.nodes()`: Define edges between entities and optional node attributes

    # df[['src', 'dst', ...]]
    graphistry.edges(df, 'src', 'dst').plot()
    
    # ... + df2[['n', ...]]
    graphistry.edges(df, 'src', 'dst').nodes(df2, 'n').plot()
    
  • Hypergraph: Use multiple columns for nodes for more complex visualizations

    # df[['actor', 'event', 'location', ...]]
    hg = graphistry.hypergraph(df, ['actor', 'event', 'location'])
    hg['graph'].plot()
    
  • UMAP: Dimensionality reduction & embedding visualization tool based on row similarity

    # df[['score', 'time', ...]]
    graphistry.nodes(df).umap(X=['score', 'time']).plot()
    

These methods ensure you can quickly load & shape data and move into visualizing.

Layouts#

PyGraphistry’s Layout catalog provides many options, covering:

  • Live Layout: Graphistry performs GPU-accelerated force-directed layouts at interaction time. You can adjust settings, such as gravity, edge weight, and initial clustering time:

    g.settings(url_params={'play': 7000, 'info': True}).plot()
    
  • PyGraphistry Layouts: PyGraphistry ships with special layouts unavailable elsewhere and that work with the rendering engine’s special features:

    g.time_ring_layout('time_col').plot()
    
  • Plugin Layouts: Integrated use of external libraries for specific layouts:

    • Graphviz for hierarchical and directed layouts such as the “dot” engine

    • cuGraph for GPU-accelerated FA2, a weaker version of Graphistry’s live layout

    • igraph for CPU-based layouts, similar to GraphViz and with layouts that focus more on medium-sized social networks

  • External Layouts: Pass in x, y columns, such as from your own edits, external data, or external ML/AI packages:

    # nodes_df[['x', 'y', 'n', ...]]
    g = graphistry.edges(e_df, 's', 'd').nodes(nodes_df, 'n')
    g2 = g.settings(url_params={'play': 0}) # skip initial loadtime layout
    g2.plot()
    

Node & Edge Encodings#

You can encode your graph attributes visually using colors, sizes, icons, and more:

Global URL settings#

Graphistry visualizations are highly configurable via URL parameters. You can control the look, interaction, and data filters:

g.settings(url_params={'play': 7000, 'info': True}).plot()

For a complete list of parameters, refer to the official REST URL params page.

Plotting: Inline and URL Rendering#

Once you’re ready to visualize, use .plot() to render:

  • Inline Plotting: Directly embed interactive visualizations in your notebook or Python environment:

    g.plot()
    
  • URL Rendering: Get a sharable and embeddable URL to view in the browser:

    url = g.plot(render=False)
    print(f"View your graph at: {url}")
    

    You can further control the embeded visualization using URL parameters and JavaScript

Next Steps#

External Resources#

To dive deeper into graph analytics and visualizations, check out the following resources:

Happy graphing!