Models

Recommender (Generic Class)

class cornac.models.recommender.Recommender(name, trainable=True, verbose=False)[source]

Generic class for a recommender model. All recommendation models should inherit from this class

Parameters:
  • name (str, required) – The name of the recommender model
  • trainable (boolean, optional, default: True) – When False, the model is not trainable
default_score()[source]

Overwrite this function if your algorithm has special treatment for cold-start problem

early_stop(min_delta=0.0, patience=0)[source]

Check if training should be stopped when validation loss has stopped improving.

Parameters:
  • min_delta (float, optional, default: 0.) – The minimum increase in monitored value on validation set to be considered as improvement, i.e. an increment of less than min_delta will count as no improvement.
  • patience (int, optional, default: 0) – Number of epochs with no improvement after which training should be stopped.
Returns:

res – Return True if model training should be stopped (no improvement on validation set), otherwise return False.

Return type:

bool

fit(train_set, val_set=None)[source]

Fit the model to observations. Need to

Parameters:
  • train_set (object of type TrainSet, required) – An object containing the user-item preference in csr scipy sparse format, as well as some useful attributes such as mappings to the original user/item ids. Please refer to the class TrainSet in the “data” module for details.
  • val_set (object of type TestSet, optional, default: None) – An object containing the user-item preference for model selection purposes (e.g., early stopping). Please refer to the class TestSet in the “data” module for details.
Returns:

self

Return type:

object

monitor_value()[source]

Calculating monitored value used for early stopping on validation set (val_set). This function will be called by early_stop() function. Note: val_set could be None thus it needs to be checked before usage.

Returns:
Return type:raise NotImplementedError
rank(user_idx, item_indices=None)[source]

Rank all test items for a given user.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform item raking.
  • item_indices (1d array, optional, default: None) – A list of candidate item indices to be ranked by the user. If None, list of ranked known item indices and their scores will be returned
Returns:

  • Tuple of item_rank, and item_scores. The order of values
  • in item_scores are corresponding to the order of their ids in item_ids

rate(user_idx, item_idx, clipping=True)[source]

Give a rating score between pair of user and item

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform item raking.
  • item_idx (int, required) – The index of the item to be rated by the user.
  • clipping (bool, default: True) – Whether to clip the predicted rating value.
Returns:

A rating score of the user for the item

Return type:

A scalar

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Context Poisson Factorization (C2PF)

class cornac.models.c2pf.recom_c2pf.C2PF(k=100, max_iter=100, variant='c2pf', name=None, trainable=True, verbose=False, init_params={'G_r': None, 'G_s': None, 'L2_r': None, 'L2_s': None, 'L3_r': None, 'L3_s': None, 'L_r': None, 'L_s': None})[source]

Collaborative Context Poisson Factorization.

Parameters:
  • k (int, optional, default: 100) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations for variational C2PF.
  • variant (string, optional, default: 'c2pf') – C2pf’s variant: c2pf: ‘c2pf’, ‘tc2pf’ (tied-c2pf) or ‘rc2pf’ (reduced-c2pf). Please refer to the original paper for details.
  • name (string, optional, default: None) – The name of the recommender model. If None, then “variant” is used as the default name of the model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (Theta, Beta and Xi are not None).
  • Item_context (See "cornac/examples/c2pf_example.py" in the GitHub repo for an example of how to use cornac's graph modality to load and provide "item context" for C2PF.) –
  • init_params (dictionary, optional, default: {'G_s':None, 'G_r':None, 'L_s':None, 'L_r':None, 'L2_s':None, 'L2_r':None, 'L3_s':None, 'L3_r':None}) – List of initial parameters, e.g., init_params = {‘G_s’:G_s, ‘G_r’:G_r, ‘L_s’:L_s, ‘L_r’:L_r, ‘L2_s’:L2_s, ‘L2_r’:L2_r, ‘L3_s’:L3_s, ‘L3_r’:L3_r}, where G_s and G_r are of type csc_matrix or np.array with the same shape as Theta, see below). They represent respectively the “shape” and “rate” parameters of Gamma distribution over Theta. It is the same for L_s, L_r and Beta, L2_s, L2_r and Xi, L3_s, L3_r and Kappa.
  • Theta (csc_matrix, shape (n_users,k)) – The expected user latent factors.
  • Beta (csc_matrix, shape (n_items,k)) – The expected item latent factors.
  • Xi (csc_matrix, shape (n_items,k)) – The expected context item latent factors multiplied by context effects Kappa, please refer to the paper below for details.

References

  • Salah, Aghiles, and Hady W. Lauw. A Bayesian Latent Variable Model of User Preferences with Item Context. In IJCAI, pp. 2667-2674. 2018.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Multi-Task Explainable Recommendation (MTER)

class cornac.models.mter.recom_mter.MTER(name='MTER', rating_scale=5.0, n_user_factors=15, n_item_factors=15, n_aspect_factors=12, n_opinion_factors=12, n_bpr_samples=1000, n_element_samples=50, lambda_reg=0.1, lambda_bpr=10, n_epochs=200000, lr=0.1, n_threads=0, trainable=True, verbose=False, init_params={}, seed=None)[source]

Multi-Task Explainable Recommendation

Parameters:
  • name (string, optional, default: 'MTER') – The name of the recommender model.
  • rating_scale (float, optional, default: 5.0) – The maximum rating score of the dataset.
  • n_user_factors (int, optional, default: 15) – The dimension of the user latent factors.
  • n_item_factors (int, optional, default: 15) – The dimension of the item latent factors.
  • n_aspect_factors (int, optional, default: 12) – The dimension of the aspect latent factors.
  • n_opinion_factors (int, optional, default: 12) – The dimension of the opinion latent factors.
  • n_bpr_samples (int, optional, default: 1000) – The number of samples from all BPR pairs.
  • n_element_samples (int, optional, default: 50) – The number of samples from all ratings in each iteration.
  • lambda_reg (float, optional, default: 0.1) – The regularization parameter.
  • lambda_bpr (float, optional, default: 10.0) – The regularization parameter for BPR.
  • n_epochs (int, optional, default: 200000) – Maximum number of epochs for training.
  • lr (float, optional, default: 0.1) – The learning rate for optimization
  • n_threads (int, optional, default: 0) – Number of parallel threads for training. If n_threads=0, all CPU cores will be utilized. If seed is not None, n_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U, I, A, O, G1, G2, and G3 are not None).
  • verbose (boolean, optional, default: False) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: {}) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘I’:I, ‘A’:A, ‘O’:O, ‘G1’:G1, ‘G2’:G2, ‘G3’:G3}

    U: ndarray, shape (n_users, n_user_factors)
    The user latent factors, optional initialization via init_params
    I: ndarray, shape (n_items, n_item_factors)
    The item latent factors, optional initialization via init_params
    A: ndarray, shape (num_aspects+1, n_aspect_factors)
    The aspect latent factors, optional initialization via init_params
    O: ndarray, shape (num_opinions, n_opinion_factors)
    The opinion latent factors, optional initialization via init_params
    G1: ndarray, shape (n_user_factors, n_item_factors, n_aspect_factors)
    The core tensor for user, item, and aspect factors, optional initialization via init_params
    G2: ndarray, shape (n_user_factors, n_aspect_factors, n_opinion_factors)
    The core tensor for user, aspect, and opinion factors, optional initialization via init_params
    G3: ndarray, shape (n_item_factors, n_aspect_factors, n_opinion_factors)
    The core tensor for item, aspect, and opinion factors, optional initialization via init_params
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

Nan Wang, Hongning Wang, Yiling Jia, and Yue Yin. 2018. Explainable Recommendation via Multi-Task Learning in Opinionated Text Data. In The 41st International ACM SIGIR Conference on Research & Development in Information Retrieval (SIGIR ‘18). ACM, New York, NY, USA, 165-174. DOI: https://doi.org/10.1145/3209978.3210010

fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Probabilistic Collaborative Representation Learning (PCRL)

class cornac.models.pcrl.recom_pcrl.PCRL(k=100, z_dims=[300], max_iter=300, batch_size=300, learning_rate=0.001, name='pcrl', trainable=True, verbose=False, w_determinist=True, init_params={'G_r': None, 'G_s': None, 'L_r': None, 'L_s': None})[source]

Probabilistic Collaborative Representation Learning.

Parameters:
  • k (int, optional, default: 100) – The dimension of the latent factors.
  • z_dims (Numpy 1d array, optional, default: [300]) – The dimensions of the hidden intermdiate layers ‘z’ in the order [dim(z_L), …,dim(z_1)], please refer to Figure 1 in the orginal paper for more details.
  • max_iter (int, optional, default: 300) – Maximum number of iterations (number of epochs) for variational PCRL.
  • batch_size (int, optional, default: 300) – The batch size for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD.
  • aux_info (see "cornac/examples/pcrl_example.py" in the GitHub repo for an example of how to use cornac's graph modality provide item auxiliary data (e.g., context, text, etc.) for PCRL.) –
  • name (string, optional, default: 'PCRL') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (Theta, Beta and Xi are not None).
  • w_determinist (boolean, optional, default: True) – When True, determinist wheights “W” are used for the generator network, otherwise “W” is stochastic as in the original paper.
  • init_params (dictionary, optional, default: {'G_s':None, 'G_r':None, 'L_s':None, 'L_r':None}) – List of initial parameters, e.g., init_params = {‘G_s’:G_s, ‘G_r’:G_r, ‘L_s’:L_s, ‘L_r’:L_r}, where G_s and G_r are of type csc_matrix or np.array with the same shape as Theta, see below). They represent respectively the “shape” and “rate” parameters of Gamma distribution over Theta. It is the same for L_s, L_r and Beta.
  • Theta (csc_matrix, shape (n_users,k)) – The expected user latent factors.
  • Beta (csc_matrix, shape (n_items,k)) – The expected item latent factors.

References

  • Salah, Aghiles, and Hady W. Lauw. Probabilistic Collaborative Representation Learning for Personalized Item Recommendation. In UAI 2018.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for a list of items.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

VAE for Collaborative Filtering (VAECF)

class cornac.models.vaecf.recom_vaecf.VAECF(name='VAECF', k=10, h=20, n_epochs=100, batch_size=100, learning_rate=0.001, beta=1.0, trainable=True, verbose=False, seed=None, use_gpu=False)[source]

Variational Autoencoder for Collaborative Filtering.

Parameters:
  • k (int, optional, default: 10) – The dimension of the stochastic user factors ``z’‘.
  • h (int, optional, default: 20) – The dimension of the deterministic hidden layer.
  • n_epochs (int, optional, default: 100) – The number of epochs for SGD.
  • batch_size (int, optional, default: 100) – The batch size.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD_RMSProp.
  • beta (float, optional, default: 1.) – The weight of the KL term as in beta-VAE.
  • name (string, optional, default: 'VAECF') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained.
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • seed (int, optional, default: None) – Random seed for parameters initialization.
  • use_gpu (boolean, optional, default: False) – If True and your system supports CUDA then training is performed on GPUs.

References

  • Liang, Dawen, Rahul G. Krishnan, Matthew D. Hoffman, and Tony Jebara. “Variational autoencoders for collaborative filtering.” In Proceedings of the 2018 World Wide Web Conference on World Wide Web, pp. 689-698.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Variational Autoencoder (CVAE)

class cornac.models.cvae.recom_cvae.CVAE(name='CVAE', z_dim=50, n_epochs=100, lambda_u=0.0001, lambda_v=0.001, lambda_r=10, lambda_w=0.0001, lr=0.001, a=1, b=0.01, input_dim=8000, vae_layers=[200, 100], act_fn='sigmoid', loss_type='cross-entropy', batch_size=128, init_params=None, trainable=True, seed=None, verbose=True)[source]

Collaborative Variational Autoencoder

Parameters:
  • z_dim (int, optional, default: 50) – The dimension of the user and item latent factors.
  • n_epochs (int, optional, default: 100) – Maximum number of epochs for training.
  • lambda_u (float, optional, default: 1e-4) – The regularization hyper-parameter for user latent factor.
  • lambda_v (float, optional, default: 0.001) – The regularization hyper-parameter for item latent factor.
  • lambda_r (float, optional, default: 10.0) – Parameter that balance the focus on content or ratings
  • lambda_w (float, optional, default: 1e-4) – The regularization for VAE weights
  • lr (float, optional, default: 0.001) – Learning rate in the auto-encoder training
  • a (float, optional, default: 1) – The confidence of observed ratings.
  • b (float, optional, default: 0.01) – The confidence of unseen ratings.
  • input_dim (int, optional, default: 8000) – The size of input vector
  • vae_layers (list, optional, default: [200, 100]) – The list containing size of each layers in neural network structure
  • act_fn (str, default: 'sigmoid') – Name of the activation function used for the variational auto-encoder. Supported functions: [‘sigmoid’, ‘tanh’, ‘elu’, ‘relu’, ‘relu6’, ‘leaky_relu’, ‘identity’]
  • loss_type (String, optional, default: "cross-entropy") – Either “cross-entropy” or “rmse” The type of loss function in the last layer
  • batch_size (int, optional, default: 128) – The batch size for SGD.
  • init_params (dict, optional, default: {'U':None, 'V':None}) – Initial U and V latent matrix
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).

References

Collaborative Variational Autoencoder for Recommender Systems X. Li and J. She ACM SIGKDD International Conference on Knowledge Discovery and Data Mining 2017

http://eelxpeng.github.io/assets/paper/Collaborative_Variational_Autoencoder.pdf

fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Generalized Matrix Factorization (GMF)

class cornac.models.ncf.recom_gmf.GMF(name='GMF', num_factors=8, regs=(0.0, 0.0), num_epochs=20, batch_size=256, num_neg=4, lr=0.001, learner='adam', early_stopping=None, trainable=True, verbose=True, seed=None)[source]

Generalized Matrix Factorization.

Parameters:
  • num_factors (int, optional, default: 8) – Embedding size of MF model.
  • regs (float, optional, default: 0.) – Regularization for user and item embeddings.
  • num_epochs (int, optional, default: 20) – Number of epochs.
  • batch_size (int, optional, default: 256) – Batch size.
  • num_neg (int, optional, default: 4) – Number of negative instances to pair with a positive instance.
  • lr (float, optional, default: 0.001) – Learning rate.
  • learner (str, optional, default: 'adam') – Specify an optimizer: adagrad, adam, rmsprop, sgd
  • early_stopping ({min_delta: float, patience: int}, optional, default: None) –

    If None, no early stopping. Meaning of the arguments:

    • min_delta: the minimum increase in monitored value on validation set to be considered as improvement, i.e. an increment of less than min_delta will count as no improvement.
    • patience: number of epochs with no improvement after which training should be stopped.
  • name (string, optional, default: 'GMF') – Name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained.
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • He, X., Liao, L., Zhang, H., Nie, L., Hu, X., & Chua, T. S. (2017, April). Neural collaborative filtering. In Proceedings of the 26th international conference on world wide web (pp. 173-182).
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

monitor_value()[source]

Calculating monitored value used for early stopping on validation set (val_set). This function will be called by early_stop() function.

Returns:res – Monitored value on validation set. Return None if val_set is None.
Return type:float
score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Indexable Bayesian Personalized Ranking (IBPR)

class cornac.models.ibpr.recom_ibpr.IBPR(k=20, max_iter=100, learning_rate=0.05, lamda=0.001, batch_size=100, name='IBPR', trainable=True, verbose=False, init_params=None)[source]

Indexable Bayesian Personalized Ranking.

Parameters:
  • k (int, optional, default: 20) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.05) – The learning rate for SGD.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • batch_size (int, optional, default: 100) – The batch size for SGD.
  • name (string, optional, default: 'IBRP') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: None) – List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V} please see below the definition of U and V.
  • U (csc_matrix, shape (n_users,k)) – The user latent factors, optional initialization via init_params.
  • V (csc_matrix, shape (n_items,k)) – The item latent factors, optional initialization via init_params.

References

  • Le, D. D., & Lauw, H. W. (2017, November). Indexable Bayesian personalized ranking for efficient top-k recommendation. In Proceedings of the 2017 ACM on Conference on Information and Knowledge Management (pp. 1389-1398). ACM.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Matrix Co-Factorization (MCF)

class cornac.models.mcf.recom_mcf.MCF(k=5, max_iter=100, learning_rate=0.001, gamma=0.9, lamda=0.001, name='MCF', trainable=True, verbose=False, init_params={}, seed=None)[source]

Matrix Co-Factorization.

Parameters:
  • k (int, optional, default: 5) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD_RMSProp.
  • gamma (float, optional, default: 0.9) – The weight for previous/current gradient in RMSProp.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • name (string, optional, default: 'MCF') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained (U and V are not None).
  • network (item-affinity) –
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: {}) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}.

    U: a csc_matrix of shape (n_users,k), containing the user latent factors. V: a csc_matrix of shape (n_items,k), containing the item latent factors. Z: a csc_matrix of shape (n_items,k), containing the “Also-Viewed” item latent factors.

  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • Park, Chanyoung, Donghyun Kim, Jinoh Oh, and Hwanjo Yu. “Do Also-Viewed Products Help User Rating Prediction?.” In Proceedings of WWW, pp. 1113-1122. 2017.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Multi-Layer Perceptron (MLP)

class cornac.models.ncf.recom_mlp.MLP(name='MLP', layers=(64, 32, 16, 8), act_fn='relu', reg_layers=(0.0, 0.0, 0.0, 0.0), num_epochs=20, batch_size=256, num_neg=4, lr=0.001, learner='adam', early_stopping=None, trainable=True, verbose=True, seed=None)[source]

Multi-Layer Perceptron.

Parameters:
  • layers (list, optional, default: [64, 32, 16, 8]) – MLP layers. Note that the first layer is the concatenation of user and item embeddings. So layers[0]/2 is the embedding size.
  • act_fn (str, default: 'relu') – Name of the activation function used for the MLP layers. Supported functions: [‘sigmoid’, ‘tanh’, ‘elu’, ‘relu’, ‘selu, ‘relu6’, ‘leaky_relu’]
  • reg_layers (list, optional, default: [0., 0., 0., 0.]) – Regularization for each MLP layer, reg_layers[0] is the regularization for embeddings.
  • num_epochs (int, optional, default: 20) – Number of epochs.
  • batch_size (int, optional, default: 256) – Batch size.
  • num_neg (int, optional, default: 4) – Number of negative instances to pair with a positive instance.
  • lr (float, optional, default: 0.001) – Learning rate.
  • learner (str, optional, default: 'adam') – Specify an optimizer: adagrad, adam, rmsprop, sgd
  • early_stopping ({min_delta: float, patience: int}, optional, default: None) –

    If None, no early stopping. Meaning of the arguments:

    • min_delta: the minimum increase in monitored value on validation set to be considered as improvement, i.e. an increment of less than min_delta will count as no improvement.
    • patience: number of epochs with no improvement after which training should be stopped.
  • name (string, optional, default: 'MLP') – Name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained.
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • He, X., Liao, L., Zhang, H., Nie, L., Hu, X., & Chua, T. S. (2017, April). Neural collaborative filtering. In Proceedings of the 26th international conference on world wide web (pp. 173-182).
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

monitor_value()[source]

Calculating monitored value used for early stopping on validation set (val_set). This function will be called by early_stop() function.

Returns:res – Monitored value on validation set. Return None if val_set is None.
Return type:float
score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Neural Matrix Factorization (NeuMF/NCF)

class cornac.models.ncf.recom_neumf.NeuMF(name='NeuMF', num_factors=8, layers=(64, 32, 16, 8), act_fn='relu', reg_mf=0.0, reg_layers=(0.0, 0.0, 0.0, 0.0), num_epochs=20, batch_size=256, num_neg=4, lr=0.001, learner='adam', early_stopping=None, trainable=True, verbose=True, seed=None)[source]

Neural Matrix Factorization.

Parameters:
  • num_factors (int, optional, default: 8) – Embedding size of MF model.
  • layers (list, optional, default: [64, 32, 16, 8]) – MLP layers. Note that the first layer is the concatenation of user and item embeddings. So layers[0]/2 is the embedding size.
  • act_fn (str, default: 'relu') – Name of the activation function used for the MLP layers. Supported functions: [‘sigmoid’, ‘tanh’, ‘elu’, ‘relu’, ‘selu, ‘relu6’, ‘leaky_relu’]
  • reg_mf (float, optional, default: 0.) – Regularization for MF embeddings.
  • reg_layers (list, optional, default: [0., 0., 0., 0.]) – Regularization for each MLP layer, reg_layers[0] is the regularization for embeddings.
  • num_epochs (int, optional, default: 20) – Number of epochs.
  • batch_size (int, optional, default: 256) – Batch size.
  • num_neg (int, optional, default: 4) – Number of negative instances to pair with a positive instance.
  • lr (float, optional, default: 0.001) – Learning rate.
  • learner (str, optional, default: 'adam') – Specify an optimizer: adagrad, adam, rmsprop, sgd
  • early_stopping ({min_delta: float, patience: int}, optional, default: None) –

    If None, no early stopping. Meaning of the arguments:

    • min_delta: the minimum increase in monitored value on validation set to be considered as improvement, i.e. an increment of less than min_delta will count as no improvement.
    • patience: number of epochs with no improvement after which training should be stopped.
  • name (string, optional, default: 'NeuMF') – Name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained.
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • He, X., Liao, L., Zhang, H., Nie, L., Hu, X., & Chua, T. S. (2017, April). Neural collaborative filtering. In Proceedings of the 26th international conference on world wide web (pp. 173-182).
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

monitor_value()[source]

Calculating monitored value used for early stopping on validation set (val_set). This function will be called by early_stop() function.

Returns:res – Monitored value on validation set. Return None if val_set is None.
Return type:float
pretrain(gmf_model, mlp_model, alpha=0.5)[source]

Provide pre-trained GMF and MLP models. Section 3.4.1 of the paper.

Parameters:
  • gmf_model (object of type GMF, required) – Reference to trained/fitted GMF model.
  • gmf_model – Reference to trained/fitted GMF model.
  • alpha (float, optional, default: 0.5) – Hyper-parameter determining the trade-off between the two pre-trained models. Details are described in the section 3.4.1 of the paper.
score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Online Indexable Bayesian Personalized Ranking (OIBPR)

class cornac.models.online_ibpr.recom_online_ibpr.OnlineIBPR(k=20, max_iter=100, learning_rate=0.05, lamda=0.001, batch_size=100, name='online_ibpr', trainable=True, verbose=False, init_params=None)[source]

Online Indexable Bayesian Personalized Ranking.

Parameters:
  • k (int, optional, default: 20) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.05) – The learning rate for SGD.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • batch_size (int, optional, default: 100) – The batch size for SGD.
  • name (string, optional, default: 'IBRP') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: None) – List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V} please see below the definition of U and V.
  • U (csc_matrix, shape (n_users,k)) – The user latent factors, optional initialization via init_params.
  • V (csc_matrix, shape (n_items,k)) – The item latent factors, optional initialization via init_params.

References

  • Le, D. D., & Lauw, H. W. (2017, November). Indexable Bayesian personalized ranking for efficient top-k recommendation. In Proceedings of the 2017 ACM on Conference on Information and Knowledge Management (pp. 1389-1398). ACM.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Visual Matrix Factorization (VMF)

class cornac.models.vmf.recom_vmf.VMF(name='VMF', k=10, d=10, n_epochs=100, batch_size=100, learning_rate=0.001, gamma=0.9, lambda_u=0.001, lambda_v=0.001, lambda_p=1.0, lambda_e=10.0, trainable=True, verbose=False, use_gpu=False, init_params={}, seed=None)[source]

Visual Matrix Factorization.

Parameters:
  • k (int, optional, default: 10) – The dimension of the user and item factors.
  • d (int, optional, default: 10) – The dimension of the user visual factors.
  • n_epochs (int, optional, default: 100) – The number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD_RMSProp.
  • gamma (float, optional, default: 0.9) – The weight for previous/current gradient in RMSProp.
  • lambda_u (float, optional, default: 0.001) – The regularization parameter for user factors.
  • lambda_v (float, optional, default: 0.001) – The regularization parameter for item factors.
  • lambda_p (float, optional, default: 1.0) – The regularization parameter for user visual factors.
  • lambda_e (float, optional, default: 10.) – The regularization parameter for the kernel embedding matrix
  • lambda_u – The regularization parameter for user factors.
  • name (string, optional, default: 'VMF') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained (The parameters of the model U, V, P, E are not None).
  • visual_features (See "cornac/examples/vmf_example.py" for an example of how to use cornac's visual modality to load and provide the "item visual features" for VMF.) –
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: {}) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V, ‘P’: P, ‘E’: E}.

    U: numpy array of shape (n_users,k), user latent factors. V: numpy array of shape (n_items,k), item latent factors. P: numpy array of shape (n_users,d), user visual latent factors. E: numpy array of shape (d,c), embedding kernel matrix.

  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • Park, Chanyoung, Donghyun Kim, Jinoh Oh, and Hwanjo Yu. “Do Also-Viewed Products Help User Rating Prediction?.” In Proceedings of WWW, pp. 1113-1122. 2017.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Deep Ranking (CDR)

class cornac.models.cdr.recom_cdr.CDR(name='CDR', k=50, autoencoder_structure=None, act_fn='relu', lambda_u=0.1, lambda_v=100, lambda_w=0.1, lambda_n=1000, corruption_rate=0.3, learning_rate=0.001, dropout_rate=0.1, batch_size=128, max_iter=100, trainable=True, verbose=True, vocab_size=8000, init_params=None, seed=None)[source]

Collaborative Deep Ranking.

Parameters:
  • k (int, optional, default: 50) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • autoencoder_structure (list, default: None) – The number of neurons of encoder/decoder layer for SDAE. For example, autoencoder_structure = [200], the SDAE structure will be [vocab_size, 200, k, 200, vocab_size]
  • act_fn (str, default: 'relu') – Name of the activation function used for the auto-encoder. Supported functions: [‘sigmoid’, ‘tanh’, ‘elu’, ‘relu’, ‘relu6’, ‘leaky_relu’, ‘identity’]
  • learning_rate (float, optional, default: 0.001) – The learning rate for AdamOptimizer.
  • lambda_u (float, optional, default: 0.1) – The regularization parameter for users.
  • lambda_v (float, optional, default: 10) – The regularization parameter for items.
  • lambda_w (float, optional, default: 0.1) – The regularization parameter for SDAE weights.
  • lambda_n (float, optional, default: 1000) – The regularization parameter for SDAE output.
  • corruption_rate (float, optional, default: 0.3) – The corruption ratio for SDAE.
  • dropout_rate (float, optional, default: 0.1) – The probability that each element is removed in dropout of SDAE.
  • batch_size (int, optional, default: 128) – The batch size for SGD.
  • name (string, optional, default: 'CDR') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • init_params (dictionary, optional, default: None) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}

    U: ndarray, shape (n_users,k)
    The user latent factors, optional initialization via init_params.
    V: ndarray, shape (n_items,k)
    The item latent factors, optional initialization via init_params.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

Collaborative Deep Ranking: A Hybrid Pair-Wise Recommendation Algorithm with Implicit Feedback Ying H., Chen L., Xiong Y., Wu J. (2016)

fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Ordinal Embedding (COE)

class cornac.models.coe.recom_coe.COE(k=20, max_iter=100, learning_rate=0.05, lamda=0.001, batch_size=1000, name='coe', trainable=True, verbose=False, init_params=None)[source]

Collaborative Ordinal Embedding.

Parameters:
  • k (int, optional, default: 20) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.05) – The learning rate for SGD.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • batch_size (int, optional, default: 100) – The batch size for SGD.
  • name (string, optional, default: 'IBRP') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: None) – List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V} please see below the definition of U and V.
  • U (csc_matrix, shape (n_users,k)) – The user latent factors, optional initialization via init_params.
  • V (csc_matrix, shape (n_items,k)) – The item latent factors, optional initialization via init_params.

References

  • Le, D. D., & Lauw, H. W. (2016, June). Euclidean co-embedding of ordinal data for multi-type visualization. In Proceedings of the 2016 SIAM International Conference on Data Mining (pp. 396-404). Society for Industrial and Applied Mathematics.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Convolutional Matrix Factorization (ConvMF)

class cornac.models.conv_mf.recom_convmf.ConvMF(give_item_weight=True, cnn_epochs=5, n_epochs=50, lambda_u=1, lambda_v=100, k=50, name='convmf', trainable=True, verbose=False, dropout_rate=0.2, emb_dim=200, max_len=300, num_kernel_per_ws=100, init_params=None, seed=None)[source]
Parameters:
  • k (int, optional, default: 50) – The dimension of the user and item latent factors.
  • n_epochs (int, optional, default: 50) – Maximum number of epochs for training.
  • lambda_u (float, optional, default: 1.0) – The regularization hyper-parameter for user latent factor.
  • lambda_v (float, optional, default: 100.0) – The regularization hyper-parameter for item latent factor.
  • emb_dim (int, optional, default: 200) – The embedding size of each word. One word corresponds with [1 x emb_dim] vector in the embedding space
  • max_len (int, optional, default 300) – The maximum length of item’s document
  • num_kernel_per_ws (int, optional, default: 100) – The number of kernel filter in convolutional layer
  • dropout_rate (float, optional, default: 0.2) – Dropout rate while training CNN
  • give_item_weight (boolean, optional, default: True) – When True, each item will be weighted base on the number of user who have rated this item
  • init_params (dict, optional, default: {'U':None, 'V':None, 'W': None}) – Initial U and V matrix and initial weight for embedding layer W
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).

References

  • Donghyun Kim1, Chanyoung Park1. ConvMF: Convolutional Matrix Factorization for Document Context-Aware Recommendation. In :10th ACM Conference on Recommender Systems Pages 233-240
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Spherical k-means (Skmeans)

class cornac.models.skm.recom_skmeans.SKMeans(k=5, max_iter=100, name='Skmeans', trainable=True, tol=1e-06, verbose=True, init_par=None)[source]

Spherical k-means based recommender.

Parameters:
  • k (int, optional, default: 5) – The number of clusters.
  • max_iter (int, optional, default: 100) – Maximum number of iterations.
  • name (string, optional, default: 'Skmeans') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already trained.
  • tol (float, optional, default: 1e-6) – Relative tolerance with regards to skmeans’ criterion to declare convergence.
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_par (numpy 1d array, optional, default: None) – The initial object parition, 1d array contaning the cluster label (int type starting from 0) of each object (user). If par = None, then skmeans is initialized randomly.
  • centroids (csc_matrix, shape (k,n_users)) – The maxtrix of cluster centroids.

References

  • Salah, Aghiles, Nicoleta Rogovschi, and Mohamed Nadif. “A dynamic collaborative filtering system via a weighted clustering approach.” Neurocomputing 175 (2016): 206-215.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Visual Bayesian Personalized Ranking (VBPR)

class cornac.models.vbpr.recom_vbpr.VBPR(name='VBPR', k=10, k2=10, n_epochs=50, batch_size=100, learning_rate=0.005, lambda_w=0.01, lambda_b=0.01, lambda_e=0.0, use_gpu=False, trainable=True, verbose=True, init_params=None, seed=None)[source]

Visual Bayesian Personalized Ranking.

Parameters:
  • k (int, optional, default: 10) – The dimension of the gamma latent factors.
  • k2 (int, optional, default: 10) – The dimension of the theta latent factors.
  • n_epochs (int, optional, default: 20) – Maximum number of epochs for SGD.
  • batch_size (int, optional, default: 100) – The batch size for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD.
  • lambda_w (float, optional, default: 0.01) – The regularization hyper-parameter for latent factor weights.
  • lambda_b (float, optional, default: 0.01) – The regularization hyper-parameter for biases.
  • lambda_e (float, optional, default: 0.0) – The regularization hyper-parameter for embedding matrix E and beta prime vector.
  • use_gpu (boolean, optional, default: True) – Whether or not to use GPU to speed up training.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • verbose (boolean, optional, default: True) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘Bi’: beta_item, ‘Gu’: gamma_user, ‘Gi’: gamma_item, ‘Tu’: theta_user, ‘E’: emb_matrix, ‘Bp’: beta_prime}
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

  • He, R., & McAuley, J. (2016). VBPR: Visual Bayesian Personalized Ranking from Implicit Feedback.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Deep Learning (CDL)

class cornac.models.cdl.recom_cdl.CDL(name='CDL', k=50, autoencoder_structure=None, act_fn='relu', lambda_u=0.1, lambda_v=100, lambda_w=0.1, lambda_n=1000, a=1, b=0.01, corruption_rate=0.3, learning_rate=0.001, vocab_size=8000, dropout_rate=0.1, batch_size=128, max_iter=100, trainable=True, verbose=True, init_params=None, seed=None)[source]

Collaborative Deep Learning.

Parameters:
  • name (string, default: 'CDL') – The name of the recommender model.
  • k (int, optional, default: 50) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • autoencoder_structure (list, default: None) – The number of neurons of encoder/decoder layer for SDAE. For example, autoencoder_structure = [200], the SDAE structure will be [vocab_size, 200, k, 200, vocab_size]
  • act_fn (str, default: 'relu') – Name of the activation function used for the auto-encoder. Supported functions: [‘sigmoid’, ‘tanh’, ‘elu’, ‘relu’, ‘relu6’, ‘leaky_relu’, ‘identity’]
  • learning_rate (float, optional, default: 0.001) – The learning rate for AdamOptimizer.
  • vocab_size (int, default: 8000) – The size of text input for the SDAE.
  • lambda_u (float, optional, default: 0.1) – The regularization parameter for users.
  • lambda_v (float, optional, default: 10) – The regularization parameter for items.
  • lambda_w (float, optional, default: 0.1) – The regularization parameter for SDAE weights.
  • lambda_n (float, optional, default: 1000) – The regularization parameter for SDAE output.
  • a (float, optional, default: 1) – The confidence of observed ratings.
  • b (float, optional, default: 0.01) – The confidence of unseen ratings.
  • corruption_rate (float, optional, default: 0.3) – The corruption ratio for input text of the SDAE.
  • dropout_rate (float, optional, default: 0.1) – The probability that each element is removed in dropout of SDAE.
  • batch_size (int, optional, default: 100) – The batch size for SGD.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • init_params (dictionary, optional, default: None) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}

    U: ndarray, shape (n_users,k)
    The user latent factors, optional initialization via init_params.
    V: ndarray, shape (n_items,k)
    The item latent factors, optional initialization via init_params.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

  • Hao Wang, Naiyan Wang, Dit-Yan Yeung. CDL: Collaborative Deep Learning for Recommender Systems. In : SIGKDD. 2015. p. 1235-1244.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Hierarchical Poisson Factorization (HPF)

class cornac.models.hpf.recom_hpf.HPF(k=5, max_iter=100, name='HPF', trainable=True, verbose=False, hierarchical=True, init_params={'G_r': None, 'G_s': None, 'L_r': None, 'L_s': None})[source]

Hierarchical Poisson Factorization.

Parameters:
  • k (int, optional, default: 5) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations.
  • name (string, optional, default: 'HPF') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model is already pre-trained (Theta and Beta are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • hierarchical (boolean, optional, default: True) – When False, PF is used instead of HPF.
  • init_params (dictionary, optional, default: {'G_s':None, 'G_r':None, 'L_s':None, 'L_r':None}) – List of initial parameters, e.g., init_params = {‘G_s’:G_s, ‘G_r’:G_r, ‘L_s’:L_s, ‘L_r’:L_r}, where G_s and G_r are of type csc_matrix or np.array with the same shape as Theta, see below). They represent respectively the “shape” and “rate” parameters of Gamma distribution over Theta. Similarly, L_s, L_r are the shape and rate parameters of the Gamma over Beta.
  • Theta (csc_matrix, shape (n_users,k)) – The expected user latent factors.
  • Beta (csc_matrix, shape (n_items,k)) – The expected item latent factors.

References

  • Gopalan, Prem, Jake M. Hofman, and David M. Blei. Scalable Recommendation with Hierarchical Poisson Factorization. In UAI, pp. 326-335. 2015.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Explicit Factor Model (EFM)

class cornac.models.efm.recom_efm.EFM

Explict Factor Models

Parameters:
  • num_explicit_factors (int, optional, default: 40) – The dimension of the explicit factors.
  • num_latent_factors (int, optional, default: 60) – The dimension of the latent factors.
  • num_most_cared_aspects (int, optional, default: 15) – The number of most cared aspects for each user.
  • rating_scale (float, optional, default: 5.0) – The maximum rating score of the dataset.
  • alpha (float, optional, default: 0.85) – Trace off factor for constructing ranking score.
  • lambda_x (float, optional, default: 1) – The regularization parameter for user aspect attentions.
  • lambda_y (float, optional, default: 1) – The regularization parameter for item aspect qualities.
  • lambda_u (float, optional, default: 0.01) – The regularization parameter for user and item explicit factors.
  • lambda_h (float, optional, default: 0.01) – The regularization parameter for user and item latent factors.
  • lambda_v (float, optional, default: 0.01) – The regularization parameter for V.
  • use_item_aspect_popularity (boolean, optional, default: True) – When False, item aspect frequency is omitted from item aspect quality computation formular. Specifically, \(Y_{ij} = 1 + \frac{N - 1}{1 + e^{-s_{ij}}}\) if \(p_i\) is reviewed on feature \(F_j\)
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs.
  • name (string, optional, default: 'EFM') – The name of the recommender model.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If 0, all CPU cores will be utilized.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U1, U2, V, H1, and H2 are not None).
  • verbose (boolean, optional, default: False) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: {}) –

    List of initial parameters, e.g., init_params = {‘U1’:U1, ‘U2’:U2, ‘V’:V, ‘H1’:H1, ‘H2’:H2}

    U1: ndarray, shape (n_users, n_explicit_factors)
    The user explicit factors, optional initialization via init_params.
    U2: ndarray, shape (n_ratings, n_explicit_factors)
    The item explicit factors, optional initialization via init_params.
    V: ndarray, shape (n_aspects, n_explict_factors)
    The aspect factors, optional initialization via init_params.
    H1: ndarray, shape (n_users, n_latent_factors)
    The user latent factors, optional initialization via init_params.
    H2: ndarray, shape (n_ratings, n_latent_factors)
    The item latent factors, optional initialization via init_params.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

Yongfeng Zhang, Guokun Lai, Min Zhang, Yi Zhang, Yiqun Liu, and Shaoping Ma. 2014. Explicit factor models for explainable recommendation based on phrase-level sentiment analysis. In Proceedings of the 37th international ACM SIGIR conference on Research & development in information retrieval (SIGIR ‘14). ACM, New York, NY, USA, 83-92. DOI: https://doi.org/10.1145/2600428.2609579

fit

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

rank

Rank all test items for a given user.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform item raking.
  • item_indices (1d array, optional, default: None) – A list of candidate item indices to be ranked by the user. If None, list of ranked known item indices and their scores will be returned
Returns:

  • Tuple of item_rank, and item_scores. The order of values
  • in item_scores are corresponding to the order of their ids in item_ids

score

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Social Bayesian Personalized Ranking (SBPR)

class cornac.models.sbpr.recom_sbpr.SBPR

Social Bayesian Personalized Ranking.

Parameters:
  • k (int, optional, default: 10) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD.
  • lambda_reg (float, optional, default: 0.001) – The regularization hyper-parameter.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If num_threads=0, all CPU cores will be utilized. If seed is not None, num_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘U’: user_factors, ‘V’: item_factors, ‘Bi’: item_biases}
  • seed (int, optional, default: None) – Random seed for weight initialization. If specified, training will take longer because of single-thread (no parallelization).

References

  • Zhao, T., McAuley, J., & King, I. (2014, November). Leveraging social connections to improve personalized ranking for collaborative filtering. CIKM 2014 (pp. 261-270).
fit

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Hidden Factors and Hidden Topics (HFT)

class cornac.models.hft.recom_hft.HFT(name='HFT', k=10, max_iter=50, grad_iter=50, lambda_text=0.1, l2_reg=0.001, vocab_size=8000, init_params=None, trainable=True, verbose=True, seed=None)[source]

Hidden Factors and Hidden Topics

Parameters:
  • name (string, default: 'HFT') – The name of the recommender model.
  • k (int, optional, default: 10) – The dimension of the latent factors.
  • max_iter (int, optional, default: 50) – Maximum number of iterations for EM.
  • grad_iter (int, optional, default: 50) – Maximum number of iterations for L-BFGS.
  • lambda_text (float, default: 0.1) – Weight of corpus likelihood in objective function.
  • l2_reg (float, default: 0.001) – Regularization for user item latent factors.
  • vocab_size (int, optional, default: 8000) – Size of vocabulary for review text.
  • init_params (dictionary, optional, default: None) –

    List of initial parameters, e.g., init_params = {‘alpha’: alpha, ‘beta_u’: beta_u, ‘beta_i’: beta_i, ‘gamma_u’: gamma_u, ‘gamma_v’: gamma_v}

    alpha: float
    Model offset, optional initialization via init_params.
    beta_u: ndarray. shape (n_user, 1)
    User biases, optional initialization via init_params.
    beta_u: ndarray. shape (n_item, 1)
    Item biases, optional initialization via init_params.
    gamma_u: ndarray, shape (n_users,k)
    The user latent factors, optional initialization via init_params.
    gamma_v: ndarray, shape (n_items,k)
    The item latent factors, optional initialization via init_params.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, some running logs are displayed.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

Julian McAuley, Jure Leskovec. “Hidden Factors and Hidden Topics: Understanding Rating Dimensions with Review Text” RecSys ‘13 Proceedings of the 7th ACM conference on Recommender systems Pages 165-172

fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Collaborative Topic Modeling (CTR)

class cornac.models.ctr.recom_ctr.CTR(name='CTR', k=200, lambda_u=0.01, lambda_v=0.01, eta=0.01, a=1, b=0.01, max_iter=100, trainable=True, verbose=True, init_params=None, seed=None)[source]

Collaborative Topic Regression.

Parameters:
  • name (string, default: 'CTR') – The name of the recommender model.
  • k (int, optional, default: 200) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • lambda_u (float, optional, default: 0.01) – The regularization parameter for users.
  • lambda_v (float, optional, default: 0.01) – The regularization parameter for items.
  • a (float, optional, default: 1) – The confidence of observed ratings.
  • b (float, optional, default: 0.01) – The confidence of unseen ratings.
  • eta (float, optional, default: 0.01) – Added value for smoothing phi.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • init_params (dictionary, optional, default: None) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}

    U: ndarray, shape (n_users,k)
    The user latent factors, optional initialization via init_params.
    V: ndarray, shape (n_items,k)
    The item latent factors, optional initialization via init_params.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

Wang, Chong, and David M. Blei. “Collaborative topic modeling for recommending scientific articles.” Proceedings of the 17th ACM SIGKDD international conference on Knowledge discovery and data mining. ACM, 2011.

fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Baseline Only

cornac.models.baseline_only.recom_bo

alias of cornac.models.baseline_only.recom_bo

Bayesian Personalized Ranking (BPR)

class cornac.models.bpr.recom_bpr.BPR

Bayesian Personalized Ranking.

Parameters:
  • k (int, optional, default: 10) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD.
  • lambda_reg (float, optional, default: 0.001) – The regularization hyper-parameter.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If num_threads=0, all CPU cores will be utilized. If seed is not None, num_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘U’: user_factors, ‘V’: item_factors, ‘Bi’: item_biases}
  • seed (int, optional, default: None) – Random seed for weight initialization. If specified, training will take longer because of single-thread (no parallelization).

References

  • Rendle, Steffen, Christoph Freudenthaler, Zeno Gantner, and Lars Schmidt-Thieme. BPR: Bayesian personalized ranking from implicit feedback. In UAI, pp. 452-461. 2009.
fit

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Global Average (GlobalAvg)

class cornac.models.global_avg.recom_global_avg.GlobalAvg(name='GlobalAvg')[source]

Global Average baseline for rating prediction. Rating predictions equal to average rating of training data (not personalized).

Parameters:name (string, default: 'GlobalAvg') – The name of the recommender model.
score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Matrix Factorization (MF)

class cornac.models.mf.recom_mf.MF

Matrix Factorization.

Parameters:
  • k (int, optional, default: 10) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.01) – The learning rate.
  • lambda_reg (float, optional, default: 0.001) – The lambda value used for regularization.
  • use_bias (boolean, optional, default: True) – When True, user, item, and global biases are used.
  • early_stop (boolean, optional, default: False) – When True, delta loss will be checked after each iteration to stop learning earlier.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If num_threads=0, all CPU cores will be utilized. If seed is not None, num_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘U’: user_factors, ‘V’: item_factors, ‘Bu’: user_biases, ‘Bi’: item_biases}
  • seed (int, optional, default: None) – Random seed for weight initialization. If specified, training will take longer because of single-thread (no parallelization).

References

  • Koren, Y., Bell, R., & Volinsky, C. Matrix factorization techniques for recommender systems. In Computer, (8), 30-37. 2009.
fit

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Most Popular (MostPop)

class cornac.models.most_pop.recom_most_pop.MostPop(name='MostPop')[source]

Most Popular. Item are recommended based on their popularity (not personalized).

Parameters:name (string, default: 'MostPop') – The name of the recommender model.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Non-negative Matrix Factorization (NMF)

class cornac.models.nmf.recom_nmf.NMF

Non-negative Matrix Factorization

Parameters:
  • k (int, optional, default: 15) – The dimension of the latent factors.
  • max_iter (int, optional, default: 50) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.005) – The learning rate.
  • lambda_u (float, optional, default: 0.06) – The regularization parameter for user factors U.
  • lambda_v (float, optional, default: 0.06) – The regularization parameter for item factors V.
  • lambda_bu (float, optional, default: 0.02) – The regularization parameter for user biases Bu.
  • lambda_bi (float, optional, default: 0.02) – The regularization parameter for item biases Bi.
  • use_bias (boolean, optional, default: False) – When True, user, item, and global biases are used.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If num_threads=0, all CPU cores will be utilized. If seed is not None, num_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘U’: user_factors, ‘V’: item_factors, ‘Bu’: user_biases, ‘Bi’: item_biases, ‘mu’: global_mean}
  • seed (int, optional, default: None) – Random seed for weight initialization. If specified, training will take longer because of single-thread (no parallelization).

References

  • Lee, D. D., & Seung, H. S. (2001). Algorithms for non-negative matrix factorization. In Advances in neural information processing systems (pp. 556-562).
  • Takahashi, N., Katayama, J., & Takeuchi, J. I. (2014). A generalized sufficient condition for global convergence of modified multiplicative updates for NMF. In Proceedings of 2014 International Symposium on Nonlinear Theory and its Applications (pp. 44-47).
fit

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Probabilitic Matrix Factorization (PMF)

class cornac.models.pmf.recom_pmf.PMF(k=5, max_iter=100, learning_rate=0.001, gamma=0.9, lamda=0.001, name='PMF', variant='non_linear', trainable=True, verbose=False, init_params={}, seed=None)[source]

Probabilistic Matrix Factorization.

Parameters:
  • k (int, optional, default: 5) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD_RMSProp.
  • gamma (float, optional, default: 0.9) – The weight for previous/current gradient in RMSProp.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • name (string, optional, default: 'PMF') – The name of the recommender model.
  • variant ({"linear","non_linear"}, optional, default: 'non_linear') – Pmf variant. If ‘non_linear’, the Gaussian mean is the output of a Sigmoid function. If ‘linear’ the Gaussian mean is the output of the identity function.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: {}) – List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}. U: a csc_matrix of shape (n_users,k), containing the user latent factors. V: a csc_matrix of shape (n_items,k), containing the item latent factors.
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

  • Mnih, Andriy, and Ruslan R. Salakhutdinov. Probabilistic matrix factorization. In NIPS, pp. 1257-1264. 2008.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array

Singular Value Decomposition (SVD)

class cornac.models.svd.recom_svd.SVD(name='SVD', k=10, max_iter=20, learning_rate=0.01, lambda_reg=0.02, early_stop=False, num_threads=0, trainable=True, verbose=False, init_params=None, seed=None)[source]

Singular Value Decomposition (SVD). The implementation is based on Matrix Factorization with biases.

Parameters:
  • k (int, optional, default: 10) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.01) – The learning rate.
  • lambda_reg (float, optional, default: 0.001) – The lambda value used for regularization.
  • early_stop (boolean, optional, default: False) – When True, delta loss will be checked after each iteration to stop learning earlier.
  • num_threads (int, optional, default: 0) – Number of parallel threads for training. If num_threads=0, all CPU cores will be utilized. If seed is not None, num_threads=1 to remove randomness from parallelization.
  • trainable (boolean, optional, default: True) – When False, the model will not be re-trained, and input of pre-trained parameters are required.
  • verbose (boolean, optional, default: True) – When True, running logs are displayed.
  • init_params (dictionary, optional, default: None) – Initial parameters, e.g., init_params = {‘U’: user_factors, ‘V’: item_factors, ‘Bu’: user_biases, ‘Bi’: item_biases}
  • seed (int, optional, default: None) – Random seed for weight initialization. If specified, training will take longer because of single-thread (no parallelization).

References

  • Koren, Y. Factorization meets the neighborhood: a multifaceted collaborative filtering model. In SIGKDD, pp. 426-434. 2008.
  • Koren, Y. Factor in the neighbors: Scalable and accurate collaborative filtering. In TKDD, 2010.

Social Recommendation using PMF (SoRec)

class cornac.models.sorec.recom_sorec.SoRec(name='SoRec', k=5, max_iter=100, learning_rate=0.001, lamda_c=10, lamda=0.001, gamma=0.9, weight_link=True, trainable=True, verbose=False, init_params={}, seed=None)[source]

Social recommendation using Probabilistic Matrix Factorization.

Parameters:
  • k (int, optional, default: 5) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for SGD_RMSProp.
  • gamma (float, optional, default: 0.9) – The weight for previous/current gradient in RMSProp.
  • lamda (float, optional, default: 0.001) – The regularization parameter.
  • lamda_c (float, optional, default: 10) – The parameter balancing the information from the user-item rating matrix and the user social network.
  • weight_link (boolean, optional, default: True) – When true the social network links are weighted according to eq. (4) in the original paper.
  • name (string, optional, default: 'SOREC') – The name of the recommender model.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U, V and Z are not None).
  • verbose (boolean, optional, default: False) – When True, some running logs are displayed.
  • init_params (dictionary, optional, default: {'U':None, 'V':None}) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V, ‘Z’:Z}.

    U: a ndarray of shape (n_users, k)
    Containing the user latent factors.
    V: a ndarray of shape (n_items, k)
    Containing the item latent factors.
    Z: a ndarray of shape (n_users, k)
    Containing the social network latent factors.
  • seed (int, optional, default: None) – Random seed for parameters initialization.

References

    1. Ma, H. Yang, M. R. Lyu, and I. King. SoRec:Social recommendation using probabilistic matrix factorization. CIKM ’08, pages 931–940, Napa Valley, USA, 2008.
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item. :param user_idx: The index of the user for whom to perform score prediction. :type user_idx: int, required :param item_idx: The index of the item for that to perform score prediction.

If None, scores for all known items will be returned.
Returns:res – Relative scores that the user gives to the item or to all known items
Return type:A scalar or a Numpy array

Weighted Matrix Factorization (WMF)

class cornac.models.wmf.recom_wmf.WMF(name='WMF', k=200, lambda_u=0.01, lambda_v=0.01, a=1, b=0.01, learning_rate=0.001, batch_size=128, max_iter=100, trainable=True, verbose=True, init_params=None, seed=None)[source]

Weighted Matrix Factorization.

Parameters:
  • name (string, default: 'WMF') – The name of the recommender model.
  • k (int, optional, default: 200) – The dimension of the latent factors.
  • max_iter (int, optional, default: 100) – Maximum number of iterations or the number of epochs for SGD.
  • learning_rate (float, optional, default: 0.001) – The learning rate for AdamOptimizer.
  • lambda_u (float, optional, default: 0.01) – The regularization parameter for users.
  • lambda_v (float, optional, default: 0.01) – The regularization parameter for items.
  • a (float, optional, default: 1) – The confidence of observed ratings.
  • b (float, optional, default: 0.01) – The confidence of unseen ratings.
  • batch_size (int, optional, default: 128) – The batch size for SGD.
  • trainable (boolean, optional, default: True) – When False, the model is not trained and Cornac assumes that the model already pre-trained (U and V are not None).
  • init_params (dictionary, optional, default: None) –

    List of initial parameters, e.g., init_params = {‘U’:U, ‘V’:V}

    U: ndarray, shape (n_users,k)
    The user latent factors, optional initialization via init_params.
    V: ndarray, shape (n_items,k)
    The item latent factors, optional initialization via init_params.
  • seed (int, optional, default: None) – Random seed for weight initialization.

References

  • Hu, Y., Koren, Y., & Volinsky, C. (2008, December). Collaborative filtering for implicit feedback datasets. In 2008 Eighth IEEE International Conference on Data Mining (pp. 263-272).
  • Pan, R., Zhou, Y., Cao, B., Liu, N. N., Lukose, R., Scholz, M., & Yang, Q. (2008, December). One-class collaborative filtering. In 2008 Eighth IEEE International Conference on Data Mining (pp. 502-511).
fit(train_set, val_set=None)[source]

Fit the model to observations.

Parameters:
  • train_set (cornac.data.Dataset, required) – User-Item preference data as well as additional modalities.
  • val_set (cornac.data.Dataset, optional, default: None) – User-Item preference data for model selection purposes (e.g., early stopping).
Returns:

self

Return type:

object

score(user_idx, item_idx=None)[source]

Predict the scores/ratings of a user for an item.

Parameters:
  • user_idx (int, required) – The index of the user for whom to perform score prediction.
  • item_idx (int, optional, default: None) – The index of the item for that to perform score prediction. If None, scores for all known items will be returned.
Returns:

res – Relative scores that the user gives to the item or to all known items

Return type:

A scalar or a Numpy array