pydgn.training
training.callback
training.event
training.engine
- class pydgn.training.engine.DataStreamTrainingEngine(engine_callback: Callable[[...], pydgn.training.callback.engine_callback.EngineCallback], model: pydgn.model.interface.ModelInterface, loss: pydgn.training.callback.metric.Metric, optimizer: pydgn.training.callback.optimizer.Optimizer, scorer: pydgn.training.callback.metric.Metric, scheduler: Optional[pydgn.training.callback.scheduler.Scheduler] = None, early_stopper: Optional[pydgn.training.callback.early_stopping.EarlyStopper] = None, gradient_clipper: Optional[pydgn.training.callback.gradient_clipping.GradientClipper] = None, device: str = 'cpu', plotter: Optional[pydgn.training.callback.plotter.Plotter] = None, exp_path: Optional[str] = None, evaluate_every: int = 1, store_last_checkpoint: bool = False, reset_eval_model_hidden_state: bool = True)
Bases:
pydgn.training.engine.TrainingEngine
Class that handles a stream of graphs that could end at any moment.
- _loop(loader: torch_geometric.loader.DataLoader)
Compared to superclass version, handles the issue of a stream of data that could end at any moment. This is done using an additional boolean state variable.
- class pydgn.training.engine.GraphSequenceTrainingEngine(engine_callback: Callable[[...], pydgn.training.callback.engine_callback.EngineCallback], model: pydgn.model.interface.ModelInterface, loss: pydgn.training.callback.metric.Metric, optimizer: pydgn.training.callback.optimizer.Optimizer, scorer: pydgn.training.callback.metric.Metric, scheduler: Optional[pydgn.training.callback.scheduler.Scheduler] = None, early_stopper: Optional[pydgn.training.callback.early_stopping.EarlyStopper] = None, gradient_clipper: Optional[pydgn.training.callback.gradient_clipping.GradientClipper] = None, device: str = 'cpu', plotter: Optional[pydgn.training.callback.plotter.Plotter] = None, exp_path: Optional[str] = None, evaluate_every: int = 1, store_last_checkpoint: bool = False, reset_eval_model_hidden_state: bool = True)
Bases:
pydgn.training.engine.TrainingEngine
Assumes that the model can return None predictions (i.e., output[0] below) whenever no values should be predicted according to the mask field in the Data object representing a snapshot
- _loop_helper()
Compared to superclass version, aas the batch is composed of a list of snapshots, where each snapshot is a graph object, we add an inner loop to pass one snapshot at a time.
- class pydgn.training.engine.LinkPredictionSingleGraphEngine(engine_callback: Callable[[...], pydgn.training.callback.engine_callback.EngineCallback], model: pydgn.model.interface.ModelInterface, loss: pydgn.training.callback.metric.Metric, optimizer: pydgn.training.callback.optimizer.Optimizer, scorer: pydgn.training.callback.metric.Metric, scheduler: Optional[pydgn.training.callback.scheduler.Scheduler] = None, early_stopper: Optional[pydgn.training.callback.early_stopping.EarlyStopper] = None, gradient_clipper: Optional[pydgn.training.callback.gradient_clipping.GradientClipper] = None, device: str = 'cpu', plotter: Optional[pydgn.training.callback.plotter.Plotter] = None, exp_path: Optional[str] = None, evaluate_every: int = 1, store_last_checkpoint: bool = False, reset_eval_model_hidden_state: bool = True)
Bases:
pydgn.training.engine.TrainingEngine
Specific engine for link prediction tasks. Here, we expect target values in the form of tuples:
(_, pos_edges, neg_edges)
, wherepos_edges
andneg_edges
have been generated by the splitter and provided by the data provider.- _num_targets(targets)
Computes the number of targets as the positive links + negative links
- _to_data_list(x, batch, y)
Converts model outputs back to a list of Data elements. Useful for incremental architectures.
- Parameters
x (
torch.Tensor
) – tensor holding information of different nodes/graphs embeddingsbatch (
torch.Tensor
) – the usual PyG batch tensor. Used to split node/graph embeddings graph-wise.y (
torch.Tensor
) – target labels, used to determine whether the task is graph prediction or node prediction. Can beNone
.
- Returns
a list of PyG Data objects (with only
x
andy
attributes)
- _to_list(data_list, embeddings, batch, edge_index, y)
Extends the
data_list
list of PyG Data objects with new samples.- Parameters
data_list – a list of PyG Data objects (with only
x
andy
attributes)embeddings (
torch.Tensor
) – tensor holding information of different nodes/graphs embeddingsbatch (
torch.Tensor
) – the usual PyG batch tensor. Used to split node/graph embeddings graph-wise.edge_index –
y (
torch.Tensor
) – target labels, used to determine whether the task is graph prediction or node prediction. Can beNone
.
- Returns
a list of PyG Data objects (with only
x
andy
attributes)
- class pydgn.training.engine.TrainingEngine(engine_callback: Callable[[...], pydgn.training.callback.engine_callback.EngineCallback], model: pydgn.model.interface.ModelInterface, loss: pydgn.training.callback.metric.Metric, optimizer: pydgn.training.callback.optimizer.Optimizer, scorer: pydgn.training.callback.metric.Metric, scheduler: Optional[pydgn.training.callback.scheduler.Scheduler] = None, early_stopper: Optional[pydgn.training.callback.early_stopping.EarlyStopper] = None, gradient_clipper: Optional[pydgn.training.callback.gradient_clipping.GradientClipper] = None, device: str = 'cpu', plotter: Optional[pydgn.training.callback.plotter.Plotter] = None, exp_path: Optional[str] = None, evaluate_every: int = 1, store_last_checkpoint: bool = False, reset_eval_model_hidden_state: bool = True)
Bases:
pydgn.training.event.dispatcher.EventDispatcher
This is the most important class when it comes to training a model. It implements the
EventDispatcher
interface, which means that after registering some callbacks in a given order, it will proceed to trigger specific events that will result in the sharedState
object being updated by the callbacks. Callbacks implement the EventHandler interface, and they receive the shared State object when any event is triggered. Knowing the order in which callbacks are called is important. The order is:loss function
score function
gradient clipper
optimizer
early stopper
scheduler
plotter
- Parameters
engine_callback – (Callable[…,
EngineCallback
]): the engine callback object to be used for data fetching and checkpoints (or even other purposes if necessary)model (
ModelInterface
) – the model to be trainedloss (
Metric
) – the loss to be usedoptimizer (
Optimizer
) – the optimizer to be usedscorer (
Metric
) – the score to be usedscheduler (
Scheduler
) – the scheduler to be used Default isNone
.early_stopper –
- (
EarlyStopper
): the early stopper to be used. Default is
None
.
- (
gradient_clipper – (
GradientClipper
): the gradient clipper to be used. Default isNone
.device (str) – the device on which to train. Default is
cpu
.plotter (
Plotter
) – the plotter to be used. Default isNone
.exp_path (str) – the path of the experiment folder. Default is
None
but it is always instantiated.evaluate_every (int) – the frequency of logging epoch results. Default is
1
.store_last_checkpoint (bool) – whether to store a checkpoint at the end of each epoch. Allows to resume training from last epoch. Default is
False
.reset_eval_model_hidden_state (bool) – [temporal graph learning] Used when we want to reset the state after performing previous inference. It should be
False
when we are dealing with a single temporal graph sequence, because we don’t want to reset the hidden state after processing the previous [training/validation] time steps.
- _loop(loader: torch_geometric.loader.DataLoader)
Main method that computes a pass over the dataset using the data loader provided.
- Parameters
loader (
torch_geometric.loader.DataLoader
) – the loader to be used
- _loop_helper()
Helper function that loops over the data.
- _num_targets(targets: torch.Tensor) int
Computes the number of targets (different from the dimension of each target).
:param targets (
torch.Tensor
: the ground truth tensor- Returns
an integer with the number of targets to predict
- _restore_checkpoint_and_best_results(ckpt_filename, best_ckpt_filename, zero_epoch)
Restores the (best or last) checkpoint from a given file, and loads the best results so far into the state if any.
- _to_data_list(x: torch.Tensor, batch: torch.Tensor, y: Optional[torch.Tensor]) List[torch_geometric.data.Data]
Converts model outputs back to a list of Data elements. Useful for incremental architectures.
- Parameters
x (
torch.Tensor
) – tensor holding information of different nodes/graphs embeddingsbatch (
torch.Tensor
) – the usual PyG batch tensor. Used to split node/graph embeddings graph-wise.y (
torch.Tensor
) – target labels, used to determine whether the task is graph prediction or node prediction. Can beNone
.
- Returns
a list of PyG Data objects (with only
x
andy
attributes)
- _to_list(data_list: List[torch_geometric.data.Data], embeddings: Union[Tuple[torch.Tensor], torch.Tensor], batch: torch.Tensor, edge_index: torch.Tensor, y: Optional[torch.Tensor]) List[torch_geometric.data.Data]
Extends the
data_list
list of PyG Data objects with new samples.- Parameters
data_list – a list of PyG Data objects (with only
x
andy
attributes)embeddings (
torch.Tensor
) – tensor holding information of different nodes/graphs embeddingsbatch (
torch.Tensor
) – the usual PyG batch tensor. Used to split node/graph embeddings graph-wise.edge_index –
y (
torch.Tensor
) – target labels, used to determine whether the task is graph prediction or node prediction. Can beNone
.
- Returns
a list of PyG Data objects (with only
x
andy
attributes)
- _train(loader)
Implements a loop over the data in training mode
- infer(loader: torch_geometric.loader.DataLoader, set: str) Tuple[dict, dict, List[torch_geometric.data.Data]]
Performs an evaluation step on the data.
- Parameters
loader (
torch_geometric.loader.DataLoader
) – the loader to be usedset (str) – the type of dataset being used, can be
TRAINING
,VALIDATION
orTEST
(as defined inpydgn.static
)
- Returns
a tuple (loss dict, score dict, list of
torch_geometric.data.Data
objects withx
andy
attributes only). The data list can be used, for instance, in semi-supervised experiments or in incremental architectures
- set_device()
Moves the model and the loss metric to the proper device.
- set_eval_mode()
Sets the model and the internal state in
EVALUATION
mode
- set_training_mode()
Sets the model and the internal state in
TRAINING
mode
- train(train_loader: torch_geometric.loader.DataLoader, validation_loader: Optional[torch_geometric.loader.DataLoader] = None, test_loader: Optional[torch_geometric.loader.DataLoader] = None, max_epochs: int = 100, zero_epoch: bool = False, logger: Optional[pydgn.log.logger.Logger] = None) Tuple[dict, dict, List[torch_geometric.data.Data], dict, dict, List[torch_geometric.data.Data], dict, dict, List[torch_geometric.data.Data]]
Trains the model and regularly evaluates on validation and test data (if given). May perform early stopping and checkpointing.
- Parameters
train_loader (
torch_geometric.loader.DataLoader
) – the DataLoader associated with training datavalidation_loader (
torch_geometric.loader.DataLoader
) – the DataLoader associated with validation data, if anytest_loader (
torch_geometric.loader.DataLoader
) – the DataLoader associated with test data, if anymax_epochs (int) – maximum number of training epochs. Default is
100
zero_epoch – if
True
, starts again from epoch 0 and resets optimizer and scheduler states. Default isFalse
logger – the logger
- Returns
a tuple (train_loss, train_score, train_embeddings, validation_loss, validation_score, validation_embeddings, test_loss, test_score, test_embeddings)
- pydgn.training.engine.log(msg, logger: pydgn.log.logger.Logger)
Logs a message using a logger
- pydgn.training.engine.reorder(obj: List[object], perm: List[int])
Reorders a list of objects in ascending order according to the indices defined in permutation argument.
- Parameters
obj (List[object]) – the list of objects
perm (List[int]) – the permutation
- Returns
The reordered list of objects
training.profiler
- class pydgn.training.profiler.Profiler(threshold: float)
Bases:
object
A decorator class that is applied to a
EventHandler
object implementing a set of callback functions. For each callback, the Profiler stores the average and total running time across epochs. When the experiment terminates (either correctly or abruptly) the Profiler can produce a report to be stored in the experiment’s log file.The Profiler is used as a singleton, and it produces wrappers that update its own state.
- Parameters
threshold (float) – used to filter out callback functions that consume a negligible amount of time from the report
- Usage:
Istantiate a profiler, and then register an event_handler with the syntax profiler(event_handler), which returns another object implementing the
EventHandler
interface
- report() str
Builds a report string containing the statistics of the experiment accumulated so far.
- Returns
a string containing the report
training.util
- pydgn.training.util.atomic_save(data: dict, filepath: str)
Atomically stores a dictionary that can be serialized by
torch.save()
, exploiting the atomicos.replace()
.- Parameters
data (dict) – the dictionary to be stored
filepath (str) – the absolute filepath where to store the dictionary