From Notebook to Reproducible Experiment: Using the TGraphX Colab Gallery
A demo notebook is a great way to see a framework work, but a two-minute toy run is not an experiment. The gap between "I ran the notebook" and "I have a reproducible result on my data" is small but real, and crossing it deliberately is what turns a tutorial into research. TGraphX ships a curated notebook gallery for the first half and the tooling for the second. This guide shows how to use both — and is honest about what the notebooks are and are not.
If you have not installed TGraphX yet, Getting Started with Tensor-Valued Nodes is the prerequisite.
What the gallery actually is
The public colab_gallery.md indexes a curated set of CPU-runnable notebooks, each focused on a single concept, each documented to run in under two minutes on a modest CPU using synthetic or toy data. They cover Easy Mode, tensor-native message passing, sampling, knowledge graphs, classical generation, evolutionary optimization, graph RL, graph IO, mining, benchmarking, and reproducibility. The notebooks are hosted on Google Drive; you open one and choose Open with → Google Colaboratory, or download and run it locally in Jupyter. The same scenarios also live as scripts under the repo's notebooks/ and tutorials/ directories.
A few starting points worth knowing by number, since they exist in the gallery:
- Install and
tgraphx doctor— verify a fresh Colab install in about 30 seconds. - Reproducibility and seed control — strict CPU determinism,
set_seed, CUDA caveats. - End-to-end research workflow — data → model → train → metrics → artifacts.
- Limitations and roadmap — an honest capability map of what is and is not implemented.
That last one is unusual and worth opening early: a framework that ships a "here is what we do not do yet" notebook is telling you where the edges are.
Step 1: confirm the environment
Before anything else, check the install. The gallery's install notebook uses the tgraphx-doctor CLI, which reports environment and dependency status:
pip install tgraphx
tgraphx-doctor # environment + install verification
Running doctor first means that if something is wrong, you find out in seconds with a clear report rather than mid-experiment with a confusing stack trace.
Step 2: pick a concept notebook and swap in your data
Choose the gallery notebook closest to your task — Easy Mode node classification for a first tensor-GNN, the KG notebook for link prediction, and so on. The conversion from demo to experiment is almost always the same move: replace the synthetic data with yours, keeping the shapes consistent. Because the notebooks use small [C, H, W] tensors, the main thing to get right is that your nodes have a compatible feature_shape.
Step 3: add the three reproducibility ingredients
A demo becomes an experiment when it is reproducible. Wrap the run as described in Reproducibility by Construction:
import tgraphx as tgx
with tgx.reproducible(seed=42) as state:
tgx.save_tgraphx(g, "run/input_graph.tgx") # exact input
# ... train ...
# write_run_metadata(...) alongside results
The three ingredients are: a seeded context (reproducible), the exact input saved (save_tgraphx, see Serializing Tensor Graphs), and run metadata recorded with the result. With those, your notebook output is something a reviewer — or future you — can re-run.
Honest framing
Three honest points. First, the gallery notebooks use synthetic or toy data and run in two minutes — they are concept demonstrations, not benchmarks, and you should not read a notebook's numbers as performance claims. Second, the notebooks are Drive-hosted .ipynb files; treat the gallery index in the repo as the canonical entry point and verify a link before sharing it. Third, "runs in Colab" is about accessibility, not scale — a real experiment on large data needs the sampling and feature-store tooling covered elsewhere in this series, not a single notebook cell, and you should profile a real workload against the source before drawing any performance conclusion.
Three notebooks worth running first
If you have time for only a few, three notebooks give the quickest orientation. The install-and-tgraphx doctor notebook confirms the environment in about thirty seconds and is the right first run on any new machine. The Easy Mode node-classification notebook shows the shortest path to a trained tensor-GNN, so you see the data → model → metrics arc end to end. And the limitations-and-roadmap notebook is the one most people skip and shouldn't: it lays out, honestly, what the framework does and does not yet do, which saves you from designing around a capability that is still Experimental.
After those three, pick the notebook nearest your task — knowledge graphs, sampling, generation — and use it as the skeleton you adapt. Because each notebook is single-concept and CPU-runnable, you can read one, understand exactly which capability it exercises, and copy just that part into your own code without dragging along unrelated scaffolding.
And keep the honest framing in mind: a notebook that runs in two minutes is a demonstration, so the moment your result matters, move it out of the notebook and into a versioned script with a fixed seed and saved inputs. The gallery is a launchpad, not a place to keep an experiment you intend to publish.
Related guides
Conclusion
The TGraphX Colab gallery is a fast way to see each capability in isolation; turning one into an experiment means checking the environment with tgraphx-doctor, swapping in your data at a compatible shape, and adding the three reproducibility ingredients — seeded context, saved input, recorded metadata. The notebooks are honest toy demos by design; the path from there to a reproducible result is short and entirely supported.