DIG (Dive into Graphs)

Use this repo skill when a task names DIG, Dive into Graphs, dive-into-graphs, the dig Python package, or one of DIG's high-level graph-learning modules such as dig.ggraph, dig.sslgraph, dig.xgraph, dig.threedgraph, dig.ggraph3D, dig.oodgraph, dig.auggraph, dig.fairgraph, or dig.lsgraph.

DIG is a research-oriented graph deep learning library layered on PyTorch Geometric. It supplies turnkey datasets, method wrappers, evaluators, and example-style runners for graph generation, SSL, explainability, molecular/protein 3D learning, OOD graph benchmarks, augmentation, fairness, and large-scale graph experiments.

First Checks

• Read references/repo-provenance.md when deciding whether this skill matches a checkout or whether the skill should be refreshed.
• Read references/verification-record.md for the generated graph, smoke-check outcomes, and verification boundaries.
• Read references/installation-and-backends.md before installing DIG, selecting PyTorch/PyG wheels, deciding CPU vs CUDA coverage, or diagnosing optional dependencies.
• Read references/capability-map.md to map DIG package namespaces, datasets, models, evaluators, and examples to the right sub-skill.
• Read references/troubleshooting.md for cross-cutting install/import, dataset download, CUDA, RDKit/PySCF, PyG extension, config, and stale-cache problems.
• Run scripts/check_dig_environment.py --json for a safe package/import diagnostic that does not download datasets or run training.

Minimal Install Pattern

DIG uses the PyPI distribution name dive-into-graphs and the import package dig:

python -m pip install torch torch-geometric
python -m pip install dive-into-graphs
python - <<'PY'
from dig.version import __version__
import dig.ggraph, dig.sslgraph, dig.xgraph
print(__version__)
PY

For most workflows also install RDKit and the PyG extension wheels (torch-scatter, torch-sparse, torch-cluster, torch-spline-conv) that match the installed torch build. Several DIG modules are importable on CPU; Graphair, S-Mixup, and parts of large-scale graph learning contain CUDA-oriented code paths and need explicit backend planning.

Route by Task

• Molecular graph generation: use sub-skills/molecular-graph-generation/SKILL.md for dig.ggraph, 2D molecular generation datasets, GraphAF, GraphDF, GraphEBM, JTVAE, one-shot molecule tensors, RDKit validity, random generation, property optimization, and constrained optimization.
• 3D graph learning and 3D molecule generation: use sub-skills/three-d-graphs/SKILL.md for dig.threedgraph, QM93D, MD17, EC/FOLD protein datasets, SchNet, DimeNet++, SphereNet, ComENet, ProNet, the 3D runner, and dig.ggraph3D / G-SphereNet geometry generation.
• Self-supervised graph learning: use sub-skills/self-supervised-learning/SKILL.md for dig.sslgraph, Contrastive, GraphCL, GRACE, InfoGraph, MVGRL, pGRACE, view functions, TUDataset/Planetoid loaders, and SSL evaluators.
• GNN explainability: use sub-skills/graph-explainability/SKILL.md for dig.xgraph, GNNExplainer, PGExplainer, SubgraphX, GNN-LRP, DeepLIFT, GradCAM, FlowX, synthetic/molecule/sentiment explainability datasets, checkpoint compatibility, and fidelity/sparsity metrics.
• GOOD OOD graph datasets: use sub-skills/good-ood-datasets/SKILL.md for dig.oodgraph dataset loaders, domain/shift/subset choices, returned split dictionaries, metadata, and OOD benchmark dataset troubleshooting.
• Graph augmentation: use sub-skills/graph-augmentation/SKILL.md for dig.auggraph, GraphAug reward/generator/classifier runners, S-Mixup, augmentation configs, degree transforms, subset/triplet datasets, and TUDataset augmentation workflows.
• Fair graph learning: use sub-skills/fair-graph-learning/SKILL.md for dig.fairgraph, NBA/POKEC sensitive-attribute datasets, Graphair training/evaluation, fairness metrics, and CUDA-specific limitations.
• Large-scale graph workflows: use sub-skills/large-scale-graphs/SKILL.md for dig.lsgraph, GraphFMOB / GraphFMIB patterns, large node-classification datasets, METIS partitioning, subgraph loaders, feature momentum, and the dig_ext extension gap.

Shared Decision Rules

• Prefer tiny synthetic PyG Data fixtures, evaluator unit checks, and import diagnostics before invoking dataset downloads, long training loops, pretrained checkpoints, or benchmark notebooks.
• Treat examples/ and notebooks from DIG as evidence for recipes, not as runtime dependencies. Use the bundled scripts in this skill or recreate a small public-API snippet.
• DIG dataset constructors commonly download data during initialization. Ask before running anything that will fetch Google Drive, GitHub storage, TU Dortmund, OGB, QM9, MD17, GOOD, NBA/POKEC, or protein datasets.
• For molecular tasks, distinguish 2D molecule generation (dig.ggraph, RDKit molecules, SMILES, validity/novelty/property metrics) from 3D coordinate generation (dig.ggraph3D, atom numbers/positions, bond-length MMD, PySCF property evaluation).
• For CUDA-specific modules, do not claim CPU verification proves the selected GPU behavior. If a task uses Graphair, S-Mixup, or async large-scale loaders, require a real CUDA-compatible environment or route to documented limitations.
• When a task spans sub-skills, start with the data owner, then use the method/evaluation owner. Examples: GOOD dataset -> PyG model code; SSL pretraining -> graph generation augmentations; xgraph explanations -> base model/data shape checks.

Safe Shared Command

python scripts/check_dig_environment.py --json

Use --require-cuda, --check-optional, or --fail-on-large-scale-extension-missing only when the user needs a hard pass/fail diagnostic for those surfaces.

Avoid

• Do not assume pretrained checkpoints, Google Drive files, OGB data, QM9/MD17 archives, GOOD datasets, NBA/POKEC data, or protein hdf5 files are already available.
• Do not run long training examples or notebooks unless the user explicitly accepts runtime, downloads, result writes, and hardware usage.
• Do not use this skill for generic PyTorch Geometric API design when the task does not involve DIG-specific modules; a PyG-focused skill is usually a better route.
• Do not hide CUDA-only or missing-extension limitations. Surface them before recommending Graphair, S-Mixup, or dig.lsgraph execution.