Skip to content

Visualization examples

Advanced: use this optional integration guide after Your first graph. It assumes you can run Python scripts or Node programs and work from a source checkout. To begin with a table, result.to_pylist() is enough; a graph picture is not required to analyze data.

GraphForge returns Arrow tables from queries and analyst verbs. The examples below render the same selected nodes and relationships with external libraries. GraphForge Core does not supply a point-and-click research or coding interface. For a first research report, explain what nodes and links represent and connect any visual pattern back to the underlying observations. Layout and color do not establish a finding.

Runnable sources live under examples/visualization/.

Runtime Library Artifact Layout seed Notes
Python Plotly plotly_karate.html + JSON Deterministic circular layout using seed 42 Requires network access to load CDN Plotly.js
Python Jaal jaal_karate_payload.json (+ Dash app) Not supported by Jaal create()/plot() Interactive view needs a Dash server (--serve)
Python PyVis pyvis_karate.html layout.randomSeed = 42 Writes standalone HTML
Node.js Plotly.js plotly_js_karate.html + JSON Same circular layout / seed 42 as Python Plotly CDN Plotly.js; figure JSON built without a Node Plotly package
Node.js Cytoscape.js elements JSON + HTML cose has no portable seed matching the contract Closest honest path: cose, animate: false
Node.js Sigma.js graphology JSON + HTML Seeded circular coordinates (42) Browser page loads graphology + sigma via import map

Awkward or limited options stay in the comparison with documented compromises.

Field Value
Dataset Zachary’s Karate Club
Source Mark Newman network data
Version identity SHA-256 of karate.zip recorded in examples/visualization/dataset/MANIFEST.json
Nodes / edges 34 / 78
Directed No (undirected friendships)
Citation W. W. Zachary, Journal of Anthropological Research 33, 452–473 (1977)

Raw archives and extracts are not committed. Fetch and verify:

Terminal window
python examples/visualization/dataset/fetch.py

All examples:

  1. Download and checksum-verify Newman’s karate.zip.
  2. Parse karate.gml edges.
  3. Load nodes/edges through GraphForge’s public API (add_node / add_edge or Node addNode / addEdge).
  4. Obtain the projection with public Cypher execute() queries defined in examples/visualization/shared/contract.json.
  5. Transform that projection into the library’s documented input shape.

Projection identity: karate-member-friend-v1

  • Node label: Member with club_id (1–34) and display label (M{id})
  • Relationship: undirected FRIEND (stored once per unordered pair)
  • Style defaults: node color #2E86AB, edge color #A0AEC0, layout seed 42

Adapters must not open GraphForge storage internals or extend Core for rendering.

These commands use files from the GraphForge source repository, not files installed by the Python wheel. Download or clone the source revision matching your package, open a terminal at its root, and activate the environment from Installation. The dataset download needs network access.

Install GraphForge as described in Installation, then install the example libraries:

Terminal window
python -m pip install -r examples/visualization/requirements.txt
python examples/visualization/dataset/fetch.py

The requirements file declares minimum versions of Plotly, Jaal, PyVis, pandas, and PyArrow; it is not an exact version lock. Record the installed versions if you need to reproduce a rendered artifact.

From the repository root, explicitly install the published package instead of the example manifest’s historical engine and Arrow pins:

Terminal window
npm install --prefix examples/visualization --no-save --package-lock=false @curatelabs/graphforge apache-arrow@21
export GRAPHFORGE_NODE_PATH="$PWD/examples/visualization/node_modules/@curatelabs/graphforge/index.js"

The export line is for a POSIX shell; in another shell, set the same environment variable to that installed index.js’s absolute path. This explicitly selects the registry engine rather than a possibly unbuilt in-repository binding. For development, select the absolute path of your rebuilt binding instead. Keep the working directory at the repository root for all commands below.

Node examples depend on apache-arrow for IPC decoding and load Plotly.js, Cytoscape.js, and Sigma.js in the generated HTML from public CDNs (no visualization dependency is added to GraphForge packages).

Terminal window
# Shared projection
python examples/visualization/shared/projection.py
# -> examples/visualization/output/projection.json
python examples/visualization/python/plotly_example.py
# -> output/plotly_karate.html, output/plotly_karate.json
python examples/visualization/python/pyvis_example.py
# -> output/pyvis_karate.html
python examples/visualization/python/jaal_example.py
# -> output/jaal_karate_payload.json
# Local interactive Dash UI: add --serve
node examples/visualization/node/plotly_example.mjs
# -> output/plotly_js_karate.html, output/plotly_js_karate.json
node examples/visualization/node/cytoscape_example.mjs
# -> output/cytoscape_karate_elements.json, output/cytoscape_karate.html
node examples/visualization/node/sigma_example.mjs
# -> output/sigma_karate_graph.json, output/sigma_karate.html

Open the HTML files in a browser locally. Pages that load scripts from a CDN still require network access. Example tests validate artifact construction without launching a browser:

Terminal window
python -m pytest examples/visualization/tests/test_python_examples.py -q
node --test examples/visualization/tests/test_node_examples.mjs

These checks are part of the example suite and need the visualization libraries, so they are not required CI, scheduled CI, or release gates. The part they share with GraphForge is: the Python binding job runs the example’s graph construction and projection against the built wheel on every binding change (crates/graphforge-bindings-py/tests/visualization_example_projection.py), offline and without a visualization library.

  • Jaal only becomes interactive through Dash; headless CI constructs the app via Jaal.create() and writes a JSON payload. Layout seed is unsupported.
  • Cytoscape.js cose does not provide a stable, documented seed equivalent to the shared contract; the HTML records the requested seed and uses non-animated cose.
  • Plotly / Plotly.js have no built-in force-directed seed for graphs; both examples use the same deterministic circular layout derived from seed 42.
  • These examples demonstrate integration paths. They are not library recommendations or scalability proofs.