recpack.algorithms.TorchMLAlgorithm
- class recpack.algorithms.TorchMLAlgorithm(batch_size: int, max_epochs: int, learning_rate: float, stopping_criterion: str, stop_early: bool = False, max_iter_no_change: int = 5, min_improvement: float = 0.0, seed: Optional[int] = None, save_best_to_file: bool = False, keep_last: bool = False, predict_topK: Optional[int] = None, validation_sample_size: Optional[int] = None)
Base class for PyTorch algorithms optimized by means of gradient descent/ascent
Uses gradient descent/ascent with respect to a loss function to optimize a model over several epochs of training.
During evaluation the stopping criterion is used to determine which model is best and if it would pay to stop training early if the model converges before max_epochs have concluded.
After training the best or last model will be loaded, and used for subsequent prediction.
The batch size is also used for prediction, to reduce load on GPU memory.
Usually a child class will have to implement the
_batch_predict()
,_init_model()
and_train_epoch()
methods.- Parameters
batch_size (int) – How many samples to use in each update step. Higher batch sizes make each epoch more efficient, but increases the amount of epochs needed to converge to the optimum, by reducing the amount of updates per epoch.
max_epochs (int) – The max number of epochs to train. If the stopping criterion uses early stopping, less epochs could be used.
learning_rate (float) – How much to update the weights at each update.
stopping_criterion (str) – Name of the stopping criterion to use for training. For available values, check
recpack.algorithms.stopping_criterion.StoppingCriterion.FUNCTIONS()
stop_early (bool, optional) – If True, early stopping is enabled, and after
max_iter_no_change
iterations where improvement of loss function is belowmin_improvement
the optimisation is stopped, even if max_epochs is not reached. Defaults to Falsemax_iter_no_change (int, optional) – If early stopping is enabled, stop after this amount of iterations without change. Defaults to 5
min_improvement (float, optional) – If early stopping is enabled, no change is detected, if the improvement is below this value. Defaults to 0.01
seed (int, optional) – Seed to the randomizers, useful for reproducible results, defaults to None
save_best_to_file (bool, optional) – If true, the best model will be saved after training, defaults to False
keep_last (bool, optional) – Retain last model, rather than best (according to stopping criterion value on validation data), defaults to False
predict_topK (int, optional) – The topK recommendations to keep per row in the matrix. Use when the user x item output matrix would become too large for RAM. Defaults to None, which results in no filtering.
validation_sample_size (int, optional) – Amount of users that will be sampled to calculate validation loss and stopping criterion value. This reduces computation time during validation, such that training times are strongly reduced. If None, all nonzero users are used. A reasonable sample includes at least 1000 users. Defaults to None.
Methods
_batch_predict
(X, users)Predict scores for matrix X, given the selected users in this batch
_check_prediction
(X_pred, X)Checks that the prediction matches expectations.
_evaluate
(val_in, val_out)Perform evaluation step
_get_top_k_recommendations
(X_pred)Keep only the top K recommendations as configured by the predict_topK hyperparameter
_init_model
(X)Initialise the torch model that will learn the weights
Load the best model from temp file
_predict
(X)Compute predictions per batch of users, to avoid going out of RAM on the GPU
Save the best model in a temp file
_train_epoch
(X)Perform a single training epoch
_transform_fit_input
(X, validation_data)Transform the input matrices of the training function to the expected types
Transform the input of predict to expected type
fit
(X, validation_data)Fit the parameters of the model.
load
(filename)Load torch model from file.
save
()Save the current model to disk.
Attributes
Name of the file at which save(self) will write the current best model.
identifier
Name of the object.
name
Name of the object's class.
- _batch_predict(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], users: List[int]) scipy.sparse._csr.csr_matrix
Predict scores for matrix X, given the selected users in this batch
- Parameters
X (csr_matrix) – Matrix of user item interactions, expected to only contain interactions for those users that are in users
users (List[int]) – users selected for recommendation
- Returns
Sparse matrix of scores per user item pair.
- Return type
csr_matrix
- _check_prediction(X_pred: scipy.sparse._csr.csr_matrix, X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) None
Checks that the prediction matches expectations.
Checks implemented - Check that all users with history got at least 1 recommendation
- Parameters
X_pred (csr_matrix) – The matrix with predictions
X (csr_matrix) – The input matrix for prediction, used as ‘history’
- _evaluate(val_in: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], val_out: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) None
Perform evaluation step
Evaluation computes predictions by passing the
val_in
matrix to the model, the expected output and predictions are passed to therecpack.algorithms.stopping_criterion.StoppingCriterion.update()
function. If the new model is better it is stored using_save_best()
- Parameters
val_in (csr_matrix) – Validation Data input
val_out (csr_matrix) – Expected output from validation data
- _get_top_k_recommendations(X_pred)
Keep only the top K recommendations as configured by the predict_topK hyperparameter
- Parameters
X_pred (csr_matrix) – Recommendation scores as a sparse matrix.
- Returns
The selected recommendation scores as a sparse matrix
- Return type
csr_matrix
- _init_model(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) None
Initialise the torch model that will learn the weights
- Parameters
X (Matrix) – a user item interaction Matrix.
- _load_best()
Load the best model from temp file
- _predict(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) scipy.sparse._csr.csr_matrix
Compute predictions per batch of users, to avoid going out of RAM on the GPU
Will batch the nonzero users into batches of self.batch_size.
- Parameters
X (csr_matrix) – The input user interaction matrix
- Returns
The predicted affinity of users for items.
- Return type
csr_matrix
- _save_best()
Save the best model in a temp file
- _train_epoch(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) None
Perform a single training epoch
A training epoch updates the internal model using the provided interactions. :param X: user item interaction matrix. :type X: csr_matrix
- _transform_fit_input(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], validation_data: Tuple[Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]]) Tuple[scipy.sparse._csr.csr_matrix, Tuple[scipy.sparse._csr.csr_matrix, scipy.sparse._csr.csr_matrix]]
Transform the input matrices of the training function to the expected types
All matrices get converted to binary csr matrices
- Parameters
X (Matrix) – The interactions matrix
validation_data (Tuple[Matrix, Matrix]) – The tuple with validation_in and validation_out data
- Returns
The transformed matrices
- Return type
Tuple[csr_matrix, Tuple[csr_matrix, csr_matrix]]
- _transform_predict_input(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]) scipy.sparse._csr.csr_matrix
Transform the input of predict to expected type
Data will be turned into a binary csr matrix.
- Parameters
X (Matrix) – User-item interaction matrix used as input to predict
- Returns
Transformed user-item interaction matrix used as input to predict
- Return type
csr_matrix
- property filename
Name of the file at which save(self) will write the current best model.
- fit(X: Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], validation_data: Tuple[Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix], Union[recpack.matrix.interaction_matrix.InteractionMatrix, scipy.sparse._csr.csr_matrix]]) recpack.algorithms.base.TorchMLAlgorithm
Fit the parameters of the model.
Interaction Matrix X will be used for training, the validation data tuple will be used to compute the evaluate scores.
This function provides the generic framework for training a PyTorch algorithm, such that each child class only needs to implement the
_transform_fit_input()
,_init_model()
,_train_epoch()
and_evaluate()
functions.The function will:
Transform input data to the expected types
Initialize the model using
_init_model()
Iterate for each epoch until max epochs, or when early stopping conditions are met.
Training step using
_train_epoch()
Evaluation step using
_evaluate()
Once the model has been fit, the best model is stored to disk, if specified during init.
- Returns
self, fitted algorithm
- Return type
- load(filename)
Load torch model from file.
- Parameters
filename (str) – File to load the model from
- save()
Save the current model to disk.
filename of the file to save model in is defined by the
filename
property.