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.

Return type:

TemporalData

to_dict() → Dict[str, Any][source]

Returns a dictionary of stored key/value pairs.

Return type:

Dict[str, Any]

to_namedtuple() → NamedTuple[source]

Returns a NamedTuple of stored key/value pairs.

Return type:

NamedTuple

property num_nodes: int

Returns the number of nodes in the graph.

Return type:

int

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.

Return type:

int

property num_edges: int

Alias for num_events().

Return type:

int

property edge_index: Tensor

Returns the edge indices of the graph.

Return type:

Tensor

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.

Return type:

Union[Tuple[Optional[int], Optional[int]], int, None]

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

Return type:

Any

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

Return type:

Any

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.

Return type:

bool

has_self_loops() → bool[source]

Returns True if the graph contains self-loops.

Return type:

bool

is_undirected() → bool[source]

Returns True if graph edges are undirected.

Return type:

bool

is_directed() → bool[source]

Returns True if graph edges are directed.

Return type:

bool

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.

Return type:

Self

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.

Return type:

List[str]

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.

Return type:

bool

property is_cuda: bool

Returns True if any torch.Tensor attribute is stored on the GPU, False otherwise.

Return type:

bool

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)

Return type:

bool

is_sorted_by_time() → bool

Returns True if time is sorted.

Return type:

bool

keys() → List[str]

Returns a list of all graph attribute names.

Return type:

List[str]

node_attrs() → List[str]

Returns all node-level tensor attribute names.

Return type:

List[str]

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

Return type:

Self

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)

Return type:

Self

sort_by_time() → Self

Sorts data associated with time according to time.

Return type:

Self

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

Return type:

Self

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

Return type:

Self