---

name: loaders-and-sampling description: "Mini-batch PyTorch Geometric Data objects, configure DataLoader/NeighborLoader/LinkNeighborLoader, choose sampler parameters, and troubleshoot loader or optional sampling-backend failures." disable-model-invocation: true metadata: disco-role: operating license: MIT

PyTorch Geometric Loaders and Sampling

Use this sub-skill when the task involves mini-batching graphs, sampling neighborhoods from large graphs, building link-prediction loaders, adding temporal or weighted sampling, or debugging loader output shapes and optional sampler backends.

Quick routing

• Read references/loader-api.md when batching a list or dataset of Data/HeteroData objects, using follow_batch/exclude_keys, validating batch, ptr, num_graphs, or overriding Data.__inc__/Data.__cat_dim__ for custom attributes.
• Read references/sampling-workflows.md when configuring NeighborLoader, LinkNeighborLoader, num_neighbors, input_nodes, edge_label_index, temporal options, negative sampling, subgraph_type, or heterogeneous sampling dictionaries.
• Read references/troubleshooting.md when batches have wrong assignment vectors, sampling fails because pyg-lib or torch-sparse is missing, input_nodes/edge_label_index are malformed, temporal sampling arguments conflict, or directed subgraphs do not match model depth.
• Run scripts/loader_smoke_test.py --help to inspect safe checks, then run scripts/loader_smoke_test.py to validate basic installed APIs on tiny synthetic graphs without downloads, GPUs, network access, or writes.

Minimal decision pattern

1. Use torch_geometric.loader.DataLoader for many independent graph examples; it merges graphs into one disconnected Batch and increments index-like tensors between examples.
2. Use NeighborLoader for node mini-batches on one large graph; set input_nodes, num_neighbors, and batch_size, then compute loss only on batch[:batch.batch_size] seed-node outputs.
3. Use LinkNeighborLoader for edge/link supervision; pass edge_label_index and optional edge_label, and keep supervision edges disjoint from message-passing edges when leakage matters.
4. For heterogeneous graphs, pass node or edge types explicitly and use num_neighbors as either a shared list or a dictionary with equal hop counts per edge type.
5. Validate loader output before training: inspect batch.batch, batch.ptr, batch.n_id, batch.e_id, batch.input_id, batch.edge_label_index, and per-type stores for hetero data.

Safe command

python scripts/loader_smoke_test.py --check-neighbor

The smoke test always verifies DataLoader batching and reports an actionable optional-backend message if neighbor sampling cannot iterate in the current installation.