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/.
Comparison
Section titled “Comparison”| 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.
Dataset provenance
Section titled “Dataset provenance”| 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:
python examples/visualization/dataset/fetch.pyShared projection contract
Section titled “Shared projection contract”All examples:
- Download and checksum-verify Newman’s
karate.zip. - Parse
karate.gmledges. - Load nodes/edges through GraphForge’s public API (
add_node/add_edgeor NodeaddNode/addEdge). - Obtain the projection with public Cypher
execute()queries defined inexamples/visualization/shared/contract.json. - Transform that projection into the library’s documented input shape.
Projection identity: karate-member-friend-v1
- Node label:
Memberwithclub_id(1–34) and displaylabel(M{id}) - Relationship: undirected
FRIEND(stored once per unordered pair) - Style defaults: node color
#2E86AB, edge color#A0AEC0, layout seed42
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.
Python
Section titled “Python”Install GraphForge as described in Installation, then install the example libraries:
python -m pip install -r examples/visualization/requirements.txtpython examples/visualization/dataset/fetch.pyThe 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.
Node.js
Section titled “Node.js”From the repository root, explicitly install the published package instead of the example manifest’s historical engine and Arrow pins:
npm install --prefix examples/visualization --no-save --package-lock=false @curatelabs/graphforge apache-arrow@21export 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).
Commands and expected output
Section titled “Commands and expected output”# Shared projectionpython 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.htmlOpen 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:
python -m pytest examples/visualization/tests/test_python_examples.py -qnode --test examples/visualization/tests/test_node_examples.mjsThese 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.
Limitations (honest comparison)
Section titled “Limitations (honest comparison)”- 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
cosedoes 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.
Related
Section titled “Related”- Analytics Integration — Arrow → pandas / NetworkX
- Graph Construction — public construction API
- Network Analysis use case