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 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).

classmethod from_dict(mapping: Dict[str, Any]) → TemporalData[source]

Creates a TemporalData object from a Python dictionary.

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().

property edge_index: Tensor

Returns the edge indices of the graph.

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: str)

Applies the function func, either to all attributes or only the ones given in *args.

apply_(func: Callable, *args: str)

Applies the in-place function func, either to all attributes or only the ones given in *args.

clone(*args: str)

Performs cloning of tensors, either for all attributes or only the ones given in *args.

concat(data: Self) → Self

Concatenates self with another data object. All values needs to have matching shapes at non-concat dimensions.

contiguous(*args: str)

Ensures a contiguous memory layout, either for all attributes or only the ones given in *args.

cpu(*args: 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: str, non_blocking: bool = False)

Copies attributes to CUDA memory, either for all attributes or only the ones given in *args.

detach(*args: 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: 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.

is_sorted(sort_by_row: bool = True) → bool

Returns True if edge indices edge_index are sorted.

Parameters:

sort_by_row (bool, optional) – If set to False, will require column-wise order/by destination node order of edge_index. (default: True)

is_sorted_by_time() → bool

Returns True if time is sorted.

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: str)

Copies attributes to pinned memory, either for all attributes or only the ones given in *args.

record_stream(stream: Stream, *args: 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: str, requires_grad: bool = True)

Tracks gradient computation, either for all attributes or only the ones given in *args.

share_memory_(*args: str)

Moves attributes to shared memory, either for all attributes or only the ones given in *args.

snapshot(start_time: Union[float, int], end_time: Union[float, int], attr: str = 'time') → Self

Returns a snapshot of data to only hold events that occurred in period [start_time, end_time].

sort(sort_by_row: bool = True) → Self

Sorts edge indices edge_index and their corresponding edge features.

Parameters:

sort_by_row (bool, optional) – If set to False, will sort edge_index in column-wise order/by destination node. (default: True)

sort_by_time() → Self

Sorts data associated with time according to time.

to(device: Union[int, str], *args: str, non_blocking: bool = False)

Performs tensor device conversion, either for all attributes or only the ones given in *args.

up_to(end_time: Union[float, int]) → Self

Returns a snapshot of data to only hold events that occurred up to end_time (inclusive of edge_time).

update(data: Self) → Self

Updates the data object with the elements from another data object. Added elements will override existing ones (in case of duplicates).