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 below min_improvement the optimisation is stopped, even if max_epochs is not reached. Defaults to False
max_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_best`()	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_best`()	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_predict_input`(X)	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.
`set_fit_request`(*[, validation_data])	Request metadata passed to the `fit` method.

Attributes

`filename`	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 the recpack.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: TorchMLAlgorithm

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.

set_fit_request(*, validation_data: Union[bool, None, str] = '$UNCHANGED$') → recpack.algorithms.base.TorchMLAlgorithm

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters: validation_data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for validation_data parameter in fit.
Returns: self – The updated object.
Return type: object