torch_geometric.data.TemporalData

class TemporalData(src: Optional[Tensor] = None, dst: Optional[Tensor] = None, t: Optional[Tensor] = None, msg: Optional[Tensor] = None, **kwargs)[source]

Bases: BaseData

A data object composed by a stream of events describing a temporal graph. The TemporalData object can hold a list of events (that can be understood as temporal edges in a graph) with structured messages. An event is composed by a source node, a destination node, a timestamp and a message. Any Continuous-Time Dynamic Graph (CTDG) can be represented with these four values.

In general, TemporalData tries to mimic the behavior of a regular Python dictionary. In addition, it provides useful functionality for analyzing graph structures, and provides basic PyTorch tensor functionalities.

from torch import Tensor
from torch_geometric.data import TemporalData

events = TemporalData(
    src=Tensor([1,2,3,4]),
    dst=Tensor([2,3,4,5]),
    t=Tensor([1000,1010,1100,2000]),
    msg=Tensor([1,1,0,0])
)

# Add additional arguments to `events`:
events.y = Tensor([1,1,0,0])

# It is also possible to set additional arguments in the constructor
events = TemporalData(
    ...,
    y=Tensor([1,1,0,0])
)

# Get the number of events:
events.num_events
>>> 4

# Analyzing the graph structure:
events.num_nodes
>>> 5

# PyTorch tensor functionality:
events = events.pin_memory()
events = events.to('cuda:0', non_blocking=True)

Parameters

src (torch.Tensor, optional) – A list of source nodes for the events with shape [num_events]. (default: None)
dst (torch.Tensor, optional) – A list of destination nodes for the events with shape [num_events]. (default: None)
t (torch.Tensor, optional) – The timestamps for each event with shape [num_events]. (default: None)
msg (torch.Tensor, optional) – Messages feature matrix with shape [num_events, num_msg_features]. (default: None)
**kwargs (optional) – Additional attributes.

Note

The shape of src, dst, t and the first dimension of :obj`msg` should be the same (num_events).

to_dict() → Dict[str, Any][source]: Returns a dictionary of stored key/value pairs.

to_namedtuple() → NamedTuple[source]: Returns a NamedTuple of stored key/value pairs.

property num_nodes: int: Returns the number of nodes in the graph.

property num_events: int: Returns the number of events loaded.

Note

In a TemporalData, each row denotes an event. Thus, they can be also understood as edges.

property num_edges: int: Alias for num_events().

size(dim: Optional[int] = None) → Optional[Union[Tuple[Optional[int], Optional[int]], int]][source]: Returns the size of the adjacency matrix induced by the graph.

__cat_dim__(key: str, value: Any, *args, **kwargs) → Any[source]: Returns the dimension for which the value value of the attribute key will get concatenated when creating mini-batches using torch_geometric.loader.DataLoader.

Note

This method is for internal use only, and should only be overridden in case the mini-batch creation process is corrupted for a specific attribute.

__inc__(key: str, value: Any, *args, **kwargs) → Any[source]: Returns the incremental count to cumulatively increase the value value of the attribute key when creating mini-batches using torch_geometric.loader.DataLoader.

Note

This method is for internal use only, and should only be overridden in case the mini-batch creation process is corrupted for a specific attribute.

train_val_test_split(val_ratio: float = 0.15, test_ratio: float = 0.15)[source]

Splits the data in training, validation and test sets according to time.

Parameters

val_ratio (float, optional) – The proportion (in percents) of the dataset to include in the validation split. (default: 0.15)
test_ratio (float, optional) – The proportion (in percents) of the dataset to include in the test split. (default: 0.15)

coalesce()[source]: Sorts and removes duplicated entries from edge indices edge_index.

has_isolated_nodes() → bool[source]: Returns True if the graph contains isolated nodes.

has_self_loops() → bool[source]: Returns True if the graph contains self-loops.

is_undirected() → bool[source]: Returns True if graph edges are undirected.

is_directed() → bool[source]: Returns True if graph edges are directed.

apply(func: Callable, *args: List[str]): Applies the function func, either to all attributes or only the ones given in *args.

apply_(func: Callable, *args: List[str]): Applies the in-place function func, either to all attributes or only the ones given in *args.

clone(*args: List[str]): Performs cloning of tensors, either for all attributes or only the ones given in *args.

contiguous(*args: List[str]): Ensures a contiguous memory layout, either for all attributes or only the ones given in *args.

cpu(*args: List[str]): Copies attributes to CPU memory, either for all attributes or only the ones given in *args.

cuda(device: Optional[Union[int, str]] = None, *args: List[str], non_blocking: bool = False): Copies attributes to CUDA memory, either for all attributes or only the ones given in *args.

detach(*args: List[str]): Detaches attributes from the computation graph by creating a new tensor, either for all attributes or only the ones given in *args.

detach_(*args: List[str]): Detaches attributes from the computation graph, either for all attributes or only the ones given in *args.

edge_attrs() → List[str]: Returns all edge-level tensor attribute names.

generate_ids(): Generates and sets n_id and e_id attributes to assign each node and edge to a continuously ascending and unique ID.

is_coalesced() → bool: Returns True if edge indices edge_index are sorted and do not contain duplicate entries.

property is_cuda: bool: Returns True if any torch.Tensor attribute is stored on the GPU, False otherwise.

property keys: List[str]: Returns a list of all graph attribute names.

node_attrs() → List[str]: Returns all node-level tensor attribute names.

pin_memory(*args: List[str]): Copies attributes to pinned memory, either for all attributes or only the ones given in *args.

record_stream(stream: Stream, *args: List[str]): Ensures that the tensor memory is not reused for another tensor until all current work queued on stream has been completed, either for all attributes or only the ones given in *args.

requires_grad_(*args: List[str], requires_grad: bool = True): Tracks gradient computation, either for all attributes or only the ones given in *args.

share_memory_(*args: List[str]): Moves attributes to shared memory, either for all attributes or only the ones given in *args.

to(device: Union[int, str], *args: List[str], non_blocking: bool = False): Performs tensor device conversion, either for all attributes or only the ones given in *args.

update(data: BaseData) → BaseData: Updates the data object with the elements from another data object.