User guide for the Grapho data science + storytelling toolkit
Welcome to the user guide for Grapho - a toolkit for data science + storytelling.
In 2024 data science is having a moment with the explosion in generative AI fuelled by deep learning techniques and vast data collections. But the reality is that for all the technical advances, it comes back to humans. How are we collecting data? Why are we collecting it? What are our motivations for using it? How do we communicate? Getting to grips with modern data still requires that ancient skillset we’ve evolved - storytelling - and how we tell stories is changing.
This toolkit is for anyone anyone working with graph data. It empowers users to create data stories on any platform including spatial computing. It lets you draw connections in real-time within immersive virtual worlds. Explore and query graphs using parameters relevant to you. Grapho productivity tools make taking a deep dive into complex data sets more accessible and engaging. It brings connections to life.
Contact us for more information.
See the Grapho Developers Guide for more information on preparing data and systems for Grapho.
Return to Table of Contents.
Data is about people. Your people must understand the story your data is telling. As data scientists lean further into the astonishing power of Machine Learning, a one-size-fits-all automated approach is inadequate. In the age of AI, coherant storytelling is more valuable than ever.
Grapho started life as a spatial knowledge graph interface for a VR documentary A Clever Label released on Steam in 2021 using a Neo4j backend. This was then spun out as a white label tool Grapho XR in 2022 for knowledge graphs. Our first customer was APNIC.
In 2024 ISO 76120 - Graph Query Language (GQL) was published - the first database query language standard in 37 years since SQL. This provides a future-proof way of defining data structures and basic operations on property graphs. GQL is largely based on Neo4j’s CYPHER language.
In 2024 the Grapho service offering was expanded to applied data science including deep learning model creation and training.
Return to Table of Contents.
Grapho is available through Mod’s SaaS and consulting service.
Return to Table of Contents.
Grapho XR is a spatial graph visualisation tool and a new way to manage and present graph data.
It’s an interactive experience that feels like Minority Report meets 60 Minutes. Grapho provides flexibility to switch between data sets and between visual themes, ensuring the look is right for your audience. Display and take control of your data. Share knowledge in a hands-on intuitive way. Use it on-set as an interactive in-camera VFX solution.
See also
Return to Table of Contents.
start ./Grapho.exe -vr
(default)start ./Grapho.exe -noxrstereo
(Desktop is for users without VR)Return to Table of Contents.
Grapho XR is configured by default with a “demo” graph database - a small set of actors & movies in cross-referenced pop culture
Return to Table of Contents.
Grapho XR builds are available for the following platforms.
Return to Table of Contents.
NOTE Grapho XR’s “desktop mode” (non-XR) support on Windows is provided for backwards compatibility, accessibility, and testing. We only recommend use of 3D visualisation on 3D displays for professional use given given research findings that 2D visualisation works better on a 2D displays. See Dashboard options for off-the-shelf and custom options.
Controllers are currently required. Hand tracking support on request.
We don’t currently recommend hand tracking for precise manipulation of graph data for professional use.
Return to Table of Contents.
Grapho XR plugins and a separate Grapho Development Guide are provided to licensees for third party development with the following frameworks
Return to Table of Contents.
The Grapho UI has the following key components
A Handle is a special type of node that is a convenient handle to a section of a graph that speeds up navigation and helps manage clutter.
Think of it as a pointer or a bookmark to a particular spot in a the graph.
The graph is made up of Nodes
Connections between nodes are relationships (or links)
Nodes properties (anything from multimedia to a simple list of text) appear on an attached surface - the data pad.
Context menus allow you to perform actions on a particular node.
Return to Table of Contents.
Meta Quest Touch Controller layout
**Passthrough camera support is available on Quest and Vive mobile headsets but not on Windows.
See Mixed Reality for PCVR camera support for combining greenscreen live action footage and Grapho visualisation**
Toggle FACE BUTTON #2 button to switch between virtual environment and passthrough (see the real world through the onboard cameras). Passthrough (sometimes called Mixed Reality) can be great for new users unfamiliar with VR.
TIP Use this if real world surroundings make it too hard virtual objects.
Push LEFT or RIGHT joystick forward to show reticule and direction arrow on the ground plane. Rotate joystick to change direction of the arrow. This determines what direction you teleport. Release joystick to teleport.
NOTE Users new to VR can get confused if they trigger teleport by mistake. You can change Settings > Teleport delay to adjust how responsive the joysticks are if this is a problem.
Use GRIP button to grab object (handle, node, relationship).
Force pull is a telekinesis-like feature that lets you quickly grab an object regardless of its distance from you.
VR mode:
Use natural hand movements to move objects out of the way
Grab Handle. Flip Handle upside down to open graph nodes (run a query).
Flip again to close graph nodes.
Press TRIGGER button to toggle opening and closing of a node to reveal its “Datapad” which shows the properties of a node.
Settings > Open Datapad on Grab checkbox controls whether this happens automatically on GRAB. It can get annoying sometimes to have this on but useful as a default for new starters.
Additional functionality is available while holding a node.
GRAB + <FACE BUTTON #1> opens a floating menu of buttons
While keeping buttons pressed, move hand over the buttons to highlight them
Release <FACE BUTTON #1> to select highlight action.
Move your hand off the menu and release <FACE BUTTON #1> to close menu without doing an action.
Context Menu > Expand
Any neighbouring node not already visible are spawned
Any neighbouring node that was previously expanded (but not part of original query) is hidden
The node is hidden.
To reveal node again you currently have to Close Graph and Open Graph again using the Handle
The node is pinned in place - moving neighbouring parts of the graph will have no effect on it
The node is unpinned - moving neighbouring parts of the graph will effect its position
Not yet implemented. Sorry about that!
Press SETTINGS button on Left Controller
NOTE - Changed settings are saved to your local device. There is currently no Reset Settings feature
Return to Table of Contents.
The PCVR build of Grapho XR supports having a separate virtual camera with desktop user controls (separate view to what VR user can see) for collaborations.
CONTROL + S - Toggle Spectator Camera
WASD keys to move camera
Spectator mode is not yet available for mobile VR.
However using Meta Quest Developer Hub > Casting > Start Forwarding Camera Input you can now remote operate the Quest virtual camera.
WARNING - do not attempt to use this while someone is wearing the HMD as this can make them very sick!
Grapho Machines (GMs) are re-distributable applications and online services. They are how we build, deploy, distribute and operate services in a standard way. There is no one-size fits-all approach that will work for all use cases so GMs provide an abstraction layer for delivering services across a variety of platforms as required.
GMs include
GMs support a variety of container and virtual machine formats for use on your local device, on-premises hosting or on cloud platforms.
We use packer and terragrunt to maintain Infrastructure as Code definitions of all Grapho components to automated creation of Grapho Machine instances and GM variants for multiple platforms as required.
e.g. a Grapho Machine might be created as
Supported:
Contact us to discuss how we can accomodate any new infrastructure requirements not on this list.
The default Grapho Machine is currently a Linux Debian instance that hosts LXC Containers based on the Academy Software Foundation’s VFX Reference Platform.
See the Grapho Developers Guide for more information on preparing data and systems for Grapho.
Return to Table of Contents.
Grapho provides useful screens for managing your data whether these are off-the-shelf integrations or custom built for specific use cases from popular frameworks.
e.g. Neo4j Neodash Dashboard Builder
See our list of Integrations available below and contact us for any new integration requirements you might have.
Return to Table of Contents.
grapho-server is a sample python REST API service available to Grapho customers
This provides a thin abstraction layer to help manage vendor lock-in and provide data to Grapho applications in a consistent manner as part of a manageable pipeline.
Features
Public release COMING SOON
Grapho XR default configuration includes this public instance of the Grapho API. It provides access to sample data sets.
See also
Return to Table of Contents.
Return to Table of Contents.
Formats
Platforms
Graphics Engines
Return to Table of Contents.
Grapho XR PCVR supports the LIV Mixed Reality for real-time live action video integration.
Grapho has been deployed for a variety of use cases across major projects in different sectors.
The APNIC Visualisation Tool was built with Grapho XR to provide internal staff with a resource for network graph exploration and analysis on desktop and in VR.
Grapho tools were used to model and illustrate the complex interplay between people, processes and technology for the Software Management Plan.
Grapho was used to design and prototype a digital human agent that communicated in Japanese sign language on broadcast TV.
Grapho tools are being used to update the service framework for Australia’s national multimedia collection, including a knowledge graph and a topological machine learning pipeline.
Neo4j field engineers and marketing managers use Grapho XR to help visitors to their trade show stand get a handle (literally!) on graph databases.
Grapho XR’s first iteration was as the core mechanic behind Mod’s VR investigative documentary, A Clever Label, available on Steam.
Property graphs form a core component of Mod’s studio management and production pipeline - tracking physical and digital IP as well as managing storyworlds and productions.
We’re here to help.
For general issues on Grapho or this documentation, use https://github.com/modprods/grapho-user-guide/issues or contact your Grapho account manager.
Return to Table of Contents.
Email - support (AT) grapho (DOT) app
Discord - post in channel #grapho on Mod’s Discord server