TGraphX for Scientific Data: Graph Learning in Biology and Materials Science

Graph-structured data appears naturally in biology and materials science. Protein interaction networks, molecular graphs, brain connectomes, crystal lattices, and phylogenetic trees are all graphs. The question for a researcher in these domains is not whether to use graphs, but which graph learning tools fit the specific structure of their data.

TGraphX's tensor-native design addresses one particular gap: when graph elements carry multi-dimensional structured features — volumetric density maps, spectral tensors, image-derived node representations — and you need message-passing that preserves that structure. This article explains where TGraphX is applicable in biology and materials science, and where you should use other tools instead.

Graph Structures in Biology

Protein-protein interaction networks (PPINs). Each node is a protein; edges represent physical interactions or co-expression correlations. Node features can be amino acid composition vectors, structural descriptors, or learned embeddings from protein language models. TGraphX's vector message-passing layers handle the [N, D] case directly. If node features are 3D structural density maps, [N, C, D, H, W] with spatial_rank=3 is supported at the storage level.

Metabolic and signaling networks. Biochemical pathway graphs with enzyme nodes. Node features are kinetic parameters, expression levels, or functional annotations.

Brain connectomes. Structural connectivity between brain regions, derived from diffusion MRI. Edge features can be DTI tensors (3×3 matrices describing anisotropic diffusion), and node features can be regional morphometry or fMRI activation patterns.

Single-cell RNA sequencing (scRNA-seq) graphs. Cell-cell similarity graphs where each node is a cell and features are gene expression profiles [N, num_genes]. Graph construction often uses kNN on a low-dimensional embedding.

Phylogenetic trees. Hierarchical graphs where node features encode evolutionary traits. These are trees (special graphs), supported by TGraphX's general graph representation.

Graph Structures in Materials Science

Crystal graphs. Each atom is a node, each bond is an edge. Node features include atomic number, valence, radius. Edge features can include bond angle, bond length, or coordination tensors. This is the domain of models like CGCNN and MEGNet.

Periodic lattice graphs. Unit cell graphs where periodic boundary conditions require special handling. TGraphX does not natively handle periodic boundaries — edge construction for periodic systems must be done externally.

Molecular property prediction. SMILES-derived molecular graphs, with atom-level node features and bond-level edge features. This is the domain of GNNs like MPNN, DimeNet, and SchNet.

Amorphous materials. Graph construction from atomic positions using radial cutoffs, where each atom is a node and edges connect atoms within some distance threshold.

When TGraphX's Tensor Features Apply

TGraphX is most useful in scientific contexts where node or edge features have spatial or volumetric structure that would be damaged by flattening.

Example: brain region fMRI patterns as node features.

Each brain region can be characterized by a time-series of activation volumes. If you represent each time step as a slice [H, W] and stack T time steps to form [T, H, W], a single node feature has shape [T, H, W]. TGraphX's ConvMessagePassing with spatial_rank=2 can process these with temporal channels C=T.

import torch
        from tgraphx import Graph, ConvMessagePassing
        from tgraphx.reproducibility import set_seed
        
        set_seed(42)
        
        # 90 brain regions, each represented as [T=20, H=16, W=16] fMRI activation
        N_regions = 90
        T, H, W = 20, 16, 16
        
        x = torch.randn(N_regions, T, H, W)  # [N, C, H, W] where C=T
        
        # Structural connectivity from DTI (binary for this example)
        edge_index = torch.randint(0, N_regions, (2, 300), dtype=torch.long)
        
        g = Graph(node_features=x, edge_index=edge_index)
        
        layer = ConvMessagePassing(
            in_shape=(T, H, W),
            out_shape=(32, H, W),
        )
        out = layer(g.node_features, g.edge_index)
        print(out.shape)  # [90, 32, 16, 16]
        

Example: molecular graph with bond tensor features.

from tgraphx import Graph
        from tgraphx.layers.gin import TensorGINLayer
        
        # 23 atoms, each with atomic property vector [D=64]
        N_atoms = 23
        D = 64
        E_bonds = 45
        
        x = torch.randn(N_atoms, D)
        # For vector features, use GCNConv directly
        edge_index = torch.randint(0, N_atoms, (2, E_bonds), dtype=torch.long)
        
        # Bond features: type, length, angle → [E, bond_dim]
        bond_features = torch.randn(E_bonds, 16)
        
        # Use TensorGINLayer with vector edge features
        # (node features are vectors here, so use spatial_rank=1 or GCNConv)
        from tgraphx.layers.vector_gcn import GCNConv
        
        gcn = GCNConv(in_dim=D, out_dim=128)
        out = gcn(x, edge_index)
        print(out.shape)  # [23, 128]
        

Knowledge Graphs in Biology

Biological knowledge graphs connect entities of multiple types: genes, proteins, diseases, drugs, pathways, phenotypes. TGraphX's KG module supports this through heterogeneous entity features:

import torch
        from tgraphx.kg import KnowledgeGraph, TransEModel, KGTrainer, KGTrainingConfig
        
        # Simplified biological KG: gene-protein-disease triples
        # Entities: 0-99=genes, 100-149=proteins, 150-199=diseases
        triples = torch.tensor([
            [0, 0, 100],   # gene_0 --encodes--> protein_100
            [100, 1, 150], # protein_100 --associated_with--> disease_150
            [0, 2, 150],   # gene_0 --linked_to--> disease_150
        ], dtype=torch.long)
        
        kg = KnowledgeGraph(triples, num_entities=200, num_relations=3)
        model = TransEModel(
            num_entities=kg.num_entities,
            num_relations=kg.num_relations,
            embedding_dim=64,
        )
        config = KGTrainingConfig(num_epochs=50, lr=1e-3, seed=42)
        trainer = KGTrainer(model, config, kg.triples)
        trainer.train()
        

For multimodal biological KGs where genes have sequence embeddings and proteins have structural features, see the knowledge graph with tensor features tutorial.

Graph Mining for Biological Network Analysis

Before training a GNN on a biological network, mining the structural properties is informative:

from tgraphx.mining import graph_summary, degree_statistics, clustering_coefficient
        import torch
        
        # PPI network edge index
        edge_index = torch.randint(0, 200, (2, 1000), dtype=torch.long)
        
        summary = graph_summary(edge_index, num_nodes=200)
        print("Density:", summary["density"])
        
        deg = degree_statistics(edge_index, num_nodes=200)
        print("Mean degree:", deg["mean_degree"], "Max:", deg["max_degree"])
        
        cc = clustering_coefficient(edge_index, num_nodes=200)
        print("Mean clustering coeff:", cc.mean().item())
        

High clustering with low average path length is characteristic of biological small-world networks. These properties can inform graph construction choices and expected GNN performance.

What TGraphX Does Not Cover for Scientific Applications

Being explicit about limitations is important:

Periodic boundary conditions. Crystal graph learning with PBC requires special edge construction that accounts for atom images across unit cell boundaries. TGraphX's Graph object does not implement this — you must construct the edge index externally.

Domain-specific molecular featurization. TGraphX does not include SMILES parsers, RDKit integration, or atom featurizers. These are available in PyG's molecular dataset loaders or in packages like DeepChem.

Specialized GNN architectures for molecules. DimeNet, SchNet, PaiNN, and other geometry-aware molecular GNNs use distance-based continuous filters. TGraphX does not implement these. PyG and TorchDrug are better choices for geometry-aware molecular learning.

Protein structure modeling. Protein structure GNNs (GVP-GNN, ProteinMPNN-like architectures) with geometric vector features are not in TGraphX.

Large-scale bioinformatics datasets. TGraphX does not include loaders for STRING, BioGRID, or KEGG. You must load these externally and convert to TGraphX format.

Benchmarks against domain baselines. TGraphX does not make performance claims against biological or materials science benchmarks. See TGraphX benchmark disclaimers.

When to Use Domain-Specific Libraries Instead

TGraphX is most useful in biological and materials science contexts where you have custom tensor-valued node or edge features that you want to process with message passing, and where the research workflow benefits from TGraphX's integrated mining, reproducibility, and reporting tools.

Further Reading

• What is a TGX graph — the core data model
• Tensor-valued nodes in GNNs — why multi-dimensional features matter
• Knowledge graph embedding with tensor features — for biological KGs
• Graph mining vs GNN message passing — when to use each approach
• GNN research reproducibility — making scientific GNN experiments reproducible
• AnnotateX structured annotation — annotation tooling for biological vision datasets