Inference engines#
The module tsl.engines
contains inference engines, i.e., modules meant
to wrap deep models in order to ease training and inference phases.
Every engine extends a LightningModule
from
Lightning.
Currently, there are two basic engines:
-
Use this module when you are addressing the prediction task, i.e., inference of future observations.
-
Use this module when you are addressing the imputation task, i.e., reconstruction of missing observations.
We suggest to extends this module and override some of the methods to meet your project-specific needs.
- class Predictor(model: Optional[Module] = None, loss_fn: Optional[Callable] = None, scale_target: bool = False, metrics: Optional[Mapping[str, Metric]] = None, *, model_class: Optional[Type] = None, model_kwargs: Optional[Mapping] = None, optim_class: Optional[Type] = None, optim_kwargs: Optional[Mapping] = None, scheduler_class: Optional = None, scheduler_kwargs: Optional[Mapping] = None)[source]#
LightningModule
to implement predictors.Input data should follow the format [batch, steps, nodes, features].
- Parameters:
model (torch.nn.Module, optional) – Model implementing the predictor. Ignored if argument model_class is not
None
. This argument should mainly be used for inference. (default:None
)model_class (type, optional) – Class of
Module
implementing the predictor. If notNone
, argumentmodel
will be ignored. (default:None
)model_kwargs (mapping, optional) – Dictionary of arguments to be forwarded to
model_class
at instantiation. (default:None
)optim_class (type, optional) – Class of
Optimizer
implementing the optimizer to be used for training the model. (default:None
)optim_kwargs (mapping, optional) – Dictionary of arguments to be forwarded to
optim_class
at instantiation. (default:None
)loss_fn (callable, optional) – Loss function to be used for training the model. (default:
None
)scale_target (bool) – Whether to scale target before evaluating the loss. The metrics instead will always be evaluated in the original range. (default:
False
)metrics (mapping, optional) – Set of metrics to be logged during train, val and test steps. The metric’s name will be automatically prefixed with the loop in which the metric is computed (e.g., metric
mae
will be logged astrain_mae
when evaluated during training). (default:None
)scheduler_class (type, optional) – Class of
_LRScheduler
implementing the learning rate scheduler to be used during training. (default:None
)scheduler_kwargs (mapping, optional) – Dictionary of arguments to be forwarded to
scheduler_class
at instantiation. (default:None
)
- load_model(filename: str)[source]#
Load model’s weights from checkpoint at
filename
.Differently from
load_from_checkpoint()
, this method allows to load the state_dict also for models instantiated outside the predictor, without checking that hyperparameters of the checkpoint’s model are the same of the predictor’s model.
- predict_batch(batch: Data, preprocess: bool = False, postprocess: bool = True, return_target: bool = False, **forward_kwargs)[source]#
This method takes as input a
Data
object and outputs the predictions.Note that this method works seamlessly for all
Data
subclasses likeStaticBatch
andDisjointBatch
.- Parameters:
batch (Data) – The batch to be forwarded to the model.
preprocess (bool, optional) – If
True
, then preprocess tensors inbatch.input
using transformation modules inbatch.transform
. Note that inputs are preprocessed before creating the batch by default. (default:False
)postprocess (bool, optional) – If
True
, then postprocess the model output using transformation modules forbatch.target
inbatch.transform
. (default:True
)return_target (bool, optional) – If
True
, then returns also the prediction targetbatch.target
and the prediction maskbatch.mask
, besides the model output. In this case, the order of the arguments in the return isbatch.target
,y_hat
,batch.mask
. (default:False
)**forward_kwargs – additional keyword arguments passed to the forward method.
- class Imputer(model: Optional[Module] = None, loss_fn: Optional[Callable] = None, scale_target: bool = False, metrics: Optional[Mapping[str, Metric]] = None, *, whiten_prob: Optional[Union[float, List[float]]] = 0.05, prediction_loss_weight: float = 1.0, impute_only_missing: bool = True, warm_up_steps: Union[int, Tuple[int, int]] = 0, model_class: Optional[Type] = None, model_kwargs: Optional[Mapping] = None, optim_class: Optional[Type] = None, optim_kwargs: Optional[Mapping] = None, scheduler_class: Optional = None, scheduler_kwargs: Optional[Mapping] = None)[source]#
LightningModule
to implement imputers.An imputer is an engines designed to fill out missing values in spatiotemporal data.
- Parameters:
model (torch.nn.Module, optional) – Model implementing the imputer. Ignored if argument model_class is not null. This argument should mainly be used for inference. (default:
None
)model_class (type, optional) – Class of
Module
implementing the imputer. If not None, argument model will be ignored. (default:None
)model_kwargs (mapping, optional) – Dictionary of arguments to be forwarded to
model_class
at instantiation. (default:None
)optim_class (type, optional) – Class of
Optimizer
implementing the optimizer to be used for training the model. (default:None
)optim_kwargs (mapping, optional) – Dictionary of arguments to be forwarded to
optim_class
at instantiation. (default:None
)loss_fn (callable, optional) – Loss function to be used for training the model. (default:
None
)scale_target (bool) – Whether to scale target before evaluating the loss. The metrics instead will always be evaluated in the original range. (default:
False
)whiten_prob (float or list) – Randomly mask out a valid datapoint during a training step with probability
whiten_prob
. If a list is passed,whiten_prob
is sampled from the list for each batch. (default:0.05
)prediction_loss_weight (float) –
The weight to assign to predictions (if any) in the loss. The loss is computed as
\[L = \ell(\bar{y}, y, m) + \lambda \sum_i \ell(\hat{y}_i, y, m)\]where \(\ell(\bar{y}, y, m)\) is the imputation loss, \(\ell(\bar{y}_i, y, m)\) is the forecasting error of prediction \(\bar{y}_i\), and \(\lambda\) is
prediction_loss_weight
. (default:1.0
)impute_only_missing (bool) – Whether to impute only missing values in inference all the whole sequence. (default:
True
)warm_up_steps (int, tuple) – Number of steps to be considered as warm up stage at the beginning of the sequence. If a tuple is provided, the padding is applied both at the beginning and the end of the sequence. (default:
0
)metrics (mapping, optional) – Set of metrics to be logged during train, val and test steps. The metric’s name will be automatically prefixed with the loop in which the metric is computed (e.g., metric
mae
will be logged astrain_mae
when evaluated during training). (default:None
)scheduler_class (type) – Class of
_LRScheduler
implementing the learning rate scheduler to be used during training. (default:None
)scheduler_kwargs (mapping) – Dictionary of arguments to be forwarded to
scheduler_class
at instantiation. (default:None
)