Interoperating with PyTorch Geometric, OGB, and DGL Datasets in TGraphX

A new graph framework is only useful if it can read the data you already have. The mature ecosystem — PyTorch Geometric, OGB, DGL, torchvision — holds an enormous amount of curated graph and image data, and re-downloading or re-implementing it would be wasteful and error-prone. TGraphX treats interop as a first-class concern: tgraphx/datasets ships adapters that convert external datasets into tensor-aware Graph objects. This tutorial shows how they work and the design decisions that keep them safe.

This is the practical complement to the positioning pieces TGraphX vs PyTorch Geometric and TGraphX vs DGL.

The adapter modules

The tgraphx/datasets package contains a wrapper per ecosystem, plus shared conversion machinery:

The unifying idea is that every adapter ultimately produces a tgraphx.Graph (or a dataset of them), so once data is in, the rest of the framework — validation, sampling, layers, dashboard — works uniformly regardless of where the data came from.

Lazy imports and no hidden downloads

Two design decisions matter for reliability. First, the heavy dependencies are lazy: PyG, OGB, and DGL are declared as optional extras in pyproject.toml, and the wrappers import them only when called. So a base pip install tgraphx stays slim (just torch, torchvision, pyyaml), and you install tgraphx[pyg] or tgraphx[ogb] only if you need that bridge. Second, the capability map describes the OGB/TGB wrappers as having "no hidden downloads" and requiring explicit user setup — the adapters will not silently pull gigabytes of data behind your back. Both choices favour predictability over magic.

import tgraphx as tgx
        
        # Friendly name resolution through the registry
        g = tgx.load_dataset("cora")          # see tgx.list_dataset_aliases()
        
        # Or convert an in-hand PyG Data object (requires tgraphx[pyg])
        # from tgraphx.datasets.converters import from_pyg_data
        # g = from_pyg_data(pyg_data)
        

tgx.list_dataset_aliases() shows the names the registry understands. Runnable end-to-end examples live in examples/pyg_dataset_adapter_demo.py and examples/dgl_dataset_adapter_demo.py.

What conversion preserves — and the tensor angle

The converters map the standard fields you would expect: node features to node_features, edge_index to edge_index, labels and masks across. The interesting direction is upgrading flat data into tensor-aware form — for example, torchvision_wrappers and the patch helpers can turn images into graphs of [C, H, W] patch nodes, which is where TGraphX's tensor-native design adds something PyG/DGL data does not arrive with. Plain vector datasets convert faithfully too; they simply do not exercise the tensor features.

Honest framing

Three caveats. First, an adapter is only as available as its optional dependency — call a PyG wrapper without tgraphx[pyg] installed and you get a clear ImportError, not a silent failure. Second, interop is about reading external datasets into Graph objects, not about running TGraphX layers inside a PyG or DGL training loop; the integration point is the data layer. Third, this is complementary tooling: PyG and DGL remain excellent for their large-scale workflows, and the README positioning is explicit that TGraphX interoperates with, rather than replaces, them.

A conversion checklist

When you bring an external dataset in, a short checklist avoids surprises. Confirm the optional dependency is installed (tgraphx[pyg], tgraphx[ogb], or DGL) — the wrapper raises a clear ImportError otherwise. After conversion, validate the result with tgx.validate_graph(g) so any shape or index issue surfaces immediately rather than mid-training. Check that labels and masks made the trip: if the source dataset used a transductive split, confirm the masks landed in g.metadata['masks']. And inspect g.feature_shape — a plain vector dataset arrives as [N, D] and only becomes tensor-valued if you deliberately reshape or re-encode it, for example by turning images into patch grids.

When interop is the wrong tool

Interop reads external data into Graph objects; it does not run TGraphX layers inside a PyG or DGL training loop. If your goal is large-scale, distributed GNN training on flat-vector data, doing it natively in PyG or DGL is the better path — the adapter is for bringing data in, not for embedding one framework inside another. Reach for it when you want TGraphX's tensor-aware tooling on data that happens to live in the ecosystem, and reach for the native library when its scale is the thing you need.

Finally, treat conversion as a one-time ingestion step: once data is a Graph, cache the .tgx bundle so you do not re-run an expensive adapter — or re-download a dataset — on every experiment, and record which adapter and package version produced it so the ingestion itself is reproducible.

Related guides

• TGraphX vs PyTorch Geometric: Choosing the Right Framework
• TGraphX vs DGL for Tensor-Valued Workflows
• The TGraphX Graph and GraphBatch

Conclusion

TGraphX reads the ecosystem's data rather than asking you to abandon it: tgraphx/datasets provides lazy-imported PyG, OGB, DGL, and torchvision adapters plus a friendly load_dataset registry, all converging on the Graph object. With no hidden downloads and clear optional-dependency boundaries, you can bring your existing datasets in, optionally upgrade them to tensor-aware form, and use the rest of the framework unchanged.