class_docstr: A hybrid latent representation recommender model.
  
  The model learns embeddings (latent representations in a high-dimensional
  space) for users and items in a way that encodes user preferences over items.
  When multiplied together, these representations produce scores for every item
  for a given user; items scored highly are more likely to be interesting to
  the user.
  
  The user and item representations are expressed in terms of representations
  of their features: an embedding is estimated for every feature, and these
  features are then summed together to arrive at representations for users and
  items. For example, if the movie 'Wizard of Oz' is described by the following
  features: 'musical fantasy', 'Judy Garland', and 'Wizard of Oz', then its
  embedding will be given by taking the features' embeddings and adding them
  together. The same applies to user features.
  
  The embeddings are learned through `stochastic gradient
  descent <http://cs231n.github.io/optimization-1/>`_ methods.
  
  Four loss functions are available:
  
  - logistic: useful when both positive (1) and negative (-1) interactions
    are present.
  - BPR: Bayesian Personalised Ranking [1]_ pairwise loss. Maximises the
    prediction difference between a positive example and a randomly
    chosen negative example. Useful when only positive interactions
    are present and optimising ROC AUC is desired.
  - WARP: Weighted Approximate-Rank Pairwise [2]_ loss. Maximises
    the rank of positive examples by repeatedly sampling negative
    examples until rank violating one is found. Useful when only
    positive interactions are present and optimising the top of
    the recommendation list (precision@k) is desired.
  - k-OS WARP: k-th order statistic loss [3]_. A modification of WARP that
    uses the k-th positive example for any given user as a basis for pairwise
    updates.
  
  Two learning rate schedules are available:
  
  - adagrad: [4]_
  - adadelta: [5]_
  
  Parameters
  ----------
  
  no_components: int, optional
      the dimensionality of the feature latent embeddings.
  k: int, optional
      for k-OS training, the k-th positive example will be selected from the
      n positive examples sampled for every user.
  n: int, optional
      for k-OS training, maximum number of positives sampled for each update.
  learning_schedule: string, optional
      one of ('adagrad', 'adadelta').
  loss: string, optional
      one of  ('logistic', 'bpr', 'warp', 'warp-kos'): the loss function.
  learning_rate: float, optional
      initial learning rate for the adagrad learning schedule.
  rho: float, optional
      moving average coefficient for the adadelta learning schedule.
  epsilon: float, optional
      conditioning parameter for the adadelta learning schedule.
  item_alpha: float, optional
      L2 penalty on item features. Tip: setting this number too high can slow
      down training. One good way to check is if the final weights in the
      embeddings turned out to be mostly zero. The same idea applies to
      the user_alpha parameter.
  user_alpha: float, optional
      L2 penalty on user features.
  max_sampled: int, optional
      maximum number of negative samples used during WARP fitting.
      It requires a lot of sampling to find negative triplets for users that
      are already well represented by the model; this can lead to very long
      training times and overfitting. Setting this to a higher number will
      generally lead to longer training times, but may in some cases improve
      accuracy.
  random_state: int seed, RandomState instance, or None
      The seed of the pseudo random number generator to use when shuffling
      the data and initializing the parameters.
  
  Attributes
  ----------
  
  item_embeddings: np.float32 array of shape [n_item_features, n_components]
       Contains the estimated latent vectors for item features. The [i, j]-th
       entry gives the value of the j-th component for the i-th item feature.
       In the simplest case where the item feature matrix is an identity
       matrix, the i-th row will represent the i-th item latent vector.
  user_embeddings: np.float32 array of shape [n_user_features, n_components]
       Contains the estimated latent vectors for user features. The [i, j]-th
       entry gives the value of the j-th component for the i-th user feature.
       In the simplest case where the user feature matrix is an identity
       matrix, the i-th row will represent the i-th user latent vector.
  item_biases: np.float32 array of shape [n_item_features,]
       Contains the biases for item_features.
  user_biases: np.float32 array of shape [n_user_features,]
       Contains the biases for user_features.
  
  Notes
  -----
  
  Users' and items' latent representations are expressed in terms of their
  features' representations. If no feature matrices are provided to the
  :func:`lightfm.LightFM.fit` or :func:`lightfm.LightFM.predict` methods, they are
  implicitly assumed to be identity matrices: that is, each user and item
  are characterised by one feature that is unique to that user (or item).
  In this case, LightFM reduces to a traditional collaborative filtering
  matrix factorization method.
  
  For including features, there are two strategies:
  
  1. Characterizing each user/item *only* by its features.
  
  2. Characterizing each user/item by its features *and* an identity matrix
     that captures interactions between users and items directly.
  
  1. When using only features, the feature matrix should be of shape
  ``(num_<users/items> x num_features)``. To build these feature matrices,
  it is recommended to use the build methods from the class
  :class:`lightfm.data.Dataset` and setting the ``<user/item>_identity_features``
  to ``False``.
  An embedding will then be estimated for every feature: that is, there will be
  ``num_features`` embeddings.
  To obtain the representation for user i, the model will look up the i-th
  row of the feature matrix to find the features with non-zero weights in
  that row; the embeddings for these features will then be added together
  to arrive at the user representation. For example, if user 10 has weight 1
  in the 5th column of the user feature matrix, and weight 3 in the 20th
  column, that user's representation will be found by adding together
  the embedding for the 5th and the 20th features (multiplying the latter
  by 3). The same goes for items.
  
  Note: This strategy may result in a less expressive model because no per-user
  features are estimated, the model may underfit. To combat this, follow
  strategy 2. and include per-user (per-item) features (that is, an identity matrix)
  as part of the feature matrix.
  
  2. To use features alongside user-item interactions, the feature matrix should
  include an identity matrix. The resulting feature matrix should be of shape
  ``(num_<users/items> x (num_<users/items> + num_features))``. This strategy is
  the default when using the :class:`lightfm.data.Dataset` class. The
  behavior is controlled by the ``<user/item>_identity_features=True`` default arguments.
  
  
  References
  ----------
  
  .. [1] Rendle, Steffen, et al. "BPR: Bayesian personalized ranking from
         implicit feedback."
         Proceedings of the Twenty-Fifth Conference on Uncertainty in
         Artificial Intelligence. AUAI Press, 2009.
  .. [2] Weston, Jason, Samy Bengio, and Nicolas Usunier. "Wsabie: Scaling up
         to large vocabulary image annotation." IJCAI. Vol. 11. 2011.
  .. [3] Weston, Jason, Hector Yee, and Ron J. Weiss. "Learning to rank
         recommendations with the k-order statistic loss."
         Proceedings of the 7th ACM conference on Recommender systems. ACM,
         2013.
  .. [4] Duchi, John, Elad Hazan, and Yoram Singer. "Adaptive subgradient
         methods for online learning and stochastic optimization."
         The Journal of Machine Learning Research 12 (2011): 2121-2159.
  .. [5] Zeiler, Matthew D. "ADADELTA: An adaptive learning rate method."
         arXiv preprint arXiv:1212.5701 (2012).
class_docstr_tok: ["A","hybrid","latent","representation","recommender","model",".","The","model","learns","embeddings","(","latent","representations","in","a","high-dimensional","space",")","for","users","and","items","in","a","way","that","encodes","user","preferences","over","items",".","When","multiplied","together",",","these","representations","produce","scores","for","every","item","for","a","given","user",";","items","scored","highly","are","more","likely","to","be","interesting","to","the","user",".","The","user","and","item","representations","are","expressed","in","terms","of","representations","of","their","features",":","an","embedding","is","estimated","for","every","feature",",","and","these","features","are","then","summed","together","to","arrive","at","representations","for","users","and","items",".","For","example",",","if","the","movie","'Wizard","of","Oz","'","is","described","by","the","following","features",":","'musical","fantasy","'",",","'Judy","Garland","'",",","and","'Wizard","of","Oz","'",",","then","its","embedding","will","be","given","by","taking","the","features","'","embeddings","and","adding","them","together",".","The","same","applies","to","user","features",".","The","embeddings","are","learned","through","`","stochastic","gradient","descent","<","http",":","\/\/cs231n.github.io\/optimization-1\/",">","`","_","methods",".","Four","loss","functions","are","available",":","-","logistic",":","useful","when","both","positive","(","1",")","and","negative","(","-1",")","interactions","are","present",".","-","BPR",":","Bayesian","Personalised","Ranking","[","1","]","_","pairwise","loss",".","Maximises","the","prediction","difference","between","a","positive","example","and","a","randomly","chosen","negative","example",".","Useful","when","only","positive","interactions","are","present","and","optimising","ROC","AUC","is","desired",".","-","WARP",":","Weighted","Approximate-Rank","Pairwise","[","2","]","_","loss",".","Maximises","the","rank","of","positive","examples","by","repeatedly","sampling","negative","examples","until","rank","violating","one","is","found",".","Useful","when","only","positive","interactions","are","present","and","optimising","the","top","of","the","recommendation","list","(","precision","@","k",")","is","desired",".","-","k-OS","WARP",":","k-th","order","statistic","loss","[","3","]","_",".","A","modification","of","WARP","that","uses","the","k-th","positive","example","for","any","given","user","as","a","basis","for","pairwise","updates",".","Two","learning","rate","schedules","are","available",":","-","adagrad",":","[","4","]","_","-","adadelta",":","[","5","]","_","Parameters","--","--","--","--","--","no_components",":","int",",","optional","the","dimensionality","of","the","feature","latent","embeddings",".","k",":","int",",","optional","for","k-OS","training",",","the","k-th","positive","example","will","be","selected","from","the","n","positive","examples","sampled","for","every","user",".","n",":","int",",","optional","for","k-OS","training",",","maximum","number","of","positives","sampled","for","each","update",".","learning_schedule",":","string",",","optional","one","of","(","'adagrad","'",",","'adadelta","'",")",".","loss",":","string",",","optional","one","of","(","'logistic","'",",","'bpr","'",",","'warp","'",",","'warp-kos","'",")",":","the","loss","function",".","learning_rate",":","float",",","optional","initial","learning","rate","for","the","adagrad","learning","schedule",".","rho",":","float",",","optional","moving","average","coefficient","for","the","adadelta","learning","schedule",".","epsilon",":","float",",","optional","conditioning","parameter","for","the","adadelta","learning","schedule",".","item_alpha",":","float",",","optional","L2","penalty","on","item","features",".","Tip",":","setting","this","number","too","high","can","slow","down","training",".","One","good","way","to","check","is","if","the","final","weights","in","the","embeddings","turned","out","to","be","mostly","zero",".","The","same","idea","applies","to","the","user_alpha","parameter",".","user_alpha",":","float",",","optional","L2","penalty","on","user","features",".","max_sampled",":","int",",","optional","maximum","number","of","negative","samples","used","during","WARP","fitting",".","It","requires","a","lot","of","sampling","to","find","negative","triplets","for","users","that","are","already","well","represented","by","the","model",";","this","can","lead","to","very","long","training","times","and","overfitting",".","Setting","this","to","a","higher","number","will","generally","lead","to","longer","training","times",",","but","may","in","some","cases","improve","accuracy",".","random_state",":","int","seed",",","RandomState","instance",",","or","None","The","seed","of","the","pseudo","random","number","generator","to","use","when","shuffling","the","data","and","initializing","the","parameters",".","Attributes","--","--","--","--","--","item_embeddings",":","np.float32","array","of","shape","[","n_item_features",",","n_components","]","Contains","the","estimated","latent","vectors","for","item","features",".","The","[","i",",","j","]","-th","entry","gives","the","value","of","the","j-th","component","for","the","i-th","item","feature",".","In","the","simplest","case","where","the","item","feature","matrix","is","an","identity","matrix",",","the","i-th","row","will","represent","the","i-th","item","latent","vector",".","user_embeddings",":","np.float32","array","of","shape","[","n_user_features",",","n_components","]","Contains","the","estimated","latent","vectors","for","user","features",".","The","[","i",",","j","]","-th","entry","gives","the","value","of","the","j-th","component","for","the","i-th","user","feature",".","In","the","simplest","case","where","the","user","feature","matrix","is","an","identity","matrix",",","the","i-th","row","will","represent","the","i-th","user","latent","vector",".","item_biases",":","np.float32","array","of","shape","[","n_item_features",",","]","Contains","the","biases","for","item_features",".","user_biases",":","np.float32","array","of","shape","[","n_user_features",",","]","Contains","the","biases","for","user_features",".","Notes","--","--","-","Users","'","and","items","'","latent","representations","are","expressed","in","terms","of","their","features","'","representations",".","If","no","feature","matrices","are","provided","to","the",":","func",":","`","lightfm.LightFM.fit","`","or",":","func",":","`","lightfm.LightFM.predict","`","methods",",","they","are","implicitly","assumed","to","be","identity","matrices",":","that","is",",","each","user","and","item","are","characterised","by","one","feature","that","is","unique","to","that","user","(","or","item",")",".","In","this","case",",","LightFM","reduces","to","a","traditional","collaborative","filtering","matrix","factorization","method",".","For","including","features",",","there","are","two","strategies",":","1",".","Characterizing","each","user\/item","*","only","*","by","its","features",".","2",".","Characterizing","each","user\/item","by","its","features","*","and","*","an","identity","matrix","that","captures","interactions","between","users","and","items","directly",".","1",".","When","using","only","features",",","the","feature","matrix","should","be","of","shape","``","(","num_","<","users\/items",">","x","num_features",")","``",".","To","build","these","feature","matrices",",","it","is","recommended","to","use","the","build","methods","from","the","class",":","class",":","`","lightfm.data.Dataset","`","and","setting","the","``","<","user\/item",">","_identity_features","``","to","``","False","``",".","An","embedding","will","then","be","estimated","for","every","feature",":","that","is",",","there","will","be","``","num_features","``","embeddings",".","To","obtain","the","representation","for","user","i",",","the","model","will","look","up","the","i-th","row","of","the","feature","matrix","to","find","the","features","with","non-zero","weights","in","that","row",";","the","embeddings","for","these","features","will","then","be","added","together","to","arrive","at","the","user","representation",".","For","example",",","if","user","10","has","weight","1","in","the","5th","column","of","the","user","feature","matrix",",","and","weight","3","in","the","20th","column",",","that","user","'s","representation","will","be","found","by","adding","together","the","embedding","for","the","5th","and","the","20th","features","(","multiplying","the","latter","by","3",")",".","The","same","goes","for","items",".","Note",":","This","strategy","may","result","in","a","less","expressive","model","because","no","per-user","features","are","estimated",",","the","model","may","underfit",".","To","combat","this",",","follow","strategy","2.","and","include","per-user","(","per-item",")","features","(","that","is",",","an","identity","matrix",")","as","part","of","the","feature","matrix",".","2",".","To","use","features","alongside","user-item","interactions",",","the","feature","matrix","should","include","an","identity","matrix",".","The","resulting","feature","matrix","should","be","of","shape","``","(","num_","<","users\/items",">","x","(","num_","<","users\/items",">","+","num_features",")",")","``",".","This","strategy","is","the","default","when","using","the",":","class",":","`","lightfm.data.Dataset","`","class",".","The","behavior","is","controlled","by","the","``","<","user\/item",">","_identity_features=True","``","default","arguments",".","References","--","--","--","--","--","..","[","1","]","Rendle",",","Steffen",",","et","al",".","``","BPR",":","Bayesian","personalized","ranking","from","implicit","feedback",".","''","Proceedings","of","the","Twenty-Fifth","Conference","on","Uncertainty","in","Artificial","Intelligence",".","AUAI","Press",",","2009",".","..","[","2","]","Weston",",","Jason",",","Samy","Bengio",",","and","Nicolas","Usunier",".","``","Wsabie",":","Scaling","up","to","large","vocabulary","image","annotation",".","''","IJCAI",".","Vol",".","11",".","2011",".","..","[","3","]","Weston",",","Jason",",","Hector","Yee",",","and","Ron","J.","Weiss",".","``","Learning","to","rank","recommendations","with","the","k-order","statistic","loss",".","''","Proceedings","of","the","7th","ACM","conference","on","Recommender","systems",".","ACM",",","2013",".","..","[","4","]","Duchi",",","John",",","Elad","Hazan",",","and","Yoram","Singer",".","``","Adaptive","subgradient","methods","for","online","learning","and","stochastic","optimization",".","''","The","Journal","of","Machine","Learning","Research","12","(","2011",")",":","2121-2159",".","..","[","5","]","Zeiler",",","Matthew","D.","``","ADADELTA",":","An","adaptive","learning","rate","method",".","''","arXiv","preprint","arXiv:1212.5701","(","2012",")","."]
docstr: Fit the model.
  
  Fit the model. Unlike fit, repeated calls to this method will
  cause training to resume from the current model state.
  
  For details on how to use feature matrices, see the documentation
  on the :class:`lightfm.LightFM` class.
  
  Arguments
  ---------
  
  interactions: np.float32 coo_matrix of shape [n_users, n_items]
       the matrix containing
       user-item interactions. Will be converted to
       numpy.float32 dtype if it is not of that type.
  user_features: np.float32 csr_matrix of shape [n_users, n_user_features], optional
       Each row contains that user's weights over features.
  item_features: np.float32 csr_matrix of shape [n_items, n_item_features], optional
       Each row contains that item's weights over features.
  sample_weight: np.float32 coo_matrix of shape [n_users, n_items], optional
       matrix with entries expressing weights of individual
       interactions from the interactions matrix.
       Its row and col arrays must be the same as
       those of the interactions matrix. For memory
       efficiency its possible to use the same arrays
       for both weights and interaction matrices.
       Defaults to weight 1.0 for all interactions.
       Not implemented for the k-OS loss.
  epochs: int, optional
       number of epochs to run
  num_threads: int, optional
       Number of parallel computation threads to use. Should
       not be higher than the number of physical cores.
  verbose: bool, optional
       whether to print progress messages.
       If `tqdm` is installed, a progress bar will be displayed instead.
  
  Returns
  -------
  
  LightFM instance
      the fitted model
docstr_tok: ["Fit","the","model",".","Fit","the","model",".","Unlike","fit",",","repeated","calls","to","this","method","will","cause","training","to","resume","from","the","current","model","state",".","For","details","on","how","to","use","feature","matrices",",","see","the","documentation","on","the",":","class",":","`","lightfm.LightFM","`","class",".","Arguments","--","--","--","--","-","interactions",":","np.float32","coo_matrix","of","shape","[","n_users",",","n_items","]","the","matrix","containing","user-item","interactions",".","Will","be","converted","to","numpy.float32","dtype","if","it","is","not","of","that","type",".","user_features",":","np.float32","csr_matrix","of","shape","[","n_users",",","n_user_features","]",",","optional","Each","row","contains","that","user","'s","weights","over","features",".","item_features",":","np.float32","csr_matrix","of","shape","[","n_items",",","n_item_features","]",",","optional","Each","row","contains","that","item","'s","weights","over","features",".","sample_weight",":","np.float32","coo_matrix","of","shape","[","n_users",",","n_items","]",",","optional","matrix","with","entries","expressing","weights","of","individual","interactions","from","the","interactions","matrix",".","Its","row","and","col","arrays","must","be","the","same","as","those","of","the","interactions","matrix",".","For","memory","efficiency","its","possible","to","use","the","same","arrays","for","both","weights","and","interaction","matrices",".","Defaults","to","weight","1.0","for","all","interactions",".","Not","implemented","for","the","k-OS","loss",".","epochs",":","int",",","optional","number","of","epochs","to","run","num_threads",":","int",",","optional","Number","of","parallel","computation","threads","to","use",".","Should","not","be","higher","than","the","number","of","physical","cores",".","verbose",":","bool",",","optional","whether","to","print","progress","messages",".","If","`","tqdm","`","is","installed",",","a","progress","bar","will","be","displayed","instead",".","Returns","--","--","--","-","LightFM","instance","the","fitted","model"]
code: def fit_partial(
      self,
      interactions,
      user_features=None,
      item_features=None,
      sample_weight=None,
      epochs=1,
      num_threads=1,
      verbose=False,
  ):
      """
      Fit the model.
  
      Fit the model. Unlike fit, repeated calls to this method will
      cause training to resume from the current model state.
  
      For details on how to use feature matrices, see the documentation
      on the :class:`lightfm.LightFM` class.
  
      Arguments
      ---------
  
      interactions: np.float32 coo_matrix of shape [n_users, n_items]
           the matrix containing
           user-item interactions. Will be converted to
           numpy.float32 dtype if it is not of that type.
      user_features: np.float32 csr_matrix of shape [n_users, n_user_features], optional
           Each row contains that user's weights over features.
      item_features: np.float32 csr_matrix of shape [n_items, n_item_features], optional
           Each row contains that item's weights over features.
      sample_weight: np.float32 coo_matrix of shape [n_users, n_items], optional
           matrix with entries expressing weights of individual
           interactions from the interactions matrix.
           Its row and col arrays must be the same as
           those of the interactions matrix. For memory
           efficiency its possible to use the same arrays
           for both weights and interaction matrices.
           Defaults to weight 1.0 for all interactions.
           Not implemented for the k-OS loss.
      epochs: int, optional
           number of epochs to run
      num_threads: int, optional
           Number of parallel computation threads to use. Should
           not be higher than the number of physical cores.
      verbose: bool, optional
           whether to print progress messages.
           If `tqdm` is installed, a progress bar will be displayed instead.
  
      Returns
      -------
  
      LightFM instance
          the fitted model
      """
  
      # We need this in the COO format.
      # If that's already true, this is a no-op.
      interactions = interactions.tocoo()
  
      if interactions.dtype != CYTHON_DTYPE:
          interactions.data = interactions.data.astype(CYTHON_DTYPE)
  
      sample_weight_data = self._process_sample_weight(
          interactions, sample_weight
      )
  
      n_users, n_items = interactions.shape
      (user_features, item_features) = self._construct_feature_matrices(
          n_users, n_items, user_features, item_features
      )
  
      for input_data in (
          user_features.data,
          item_features.data,
          interactions.data,
          sample_weight_data,
      ):
          self._check_input_finite(input_data)
      if self.item_embeddings is None:
          # Initialise latent factors only if this is the first call
          # to fit_partial.
          self._initialize(
              self.no_components,
              item_features.shape[1],
              user_features.shape[1],
          )
  
      # Check that the dimensionality of the feature matrices has
      # not changed between runs.
      if not item_features.shape[1] == self.item_embeddings.shape[0]:
          raise ValueError(
              "Incorrect number of features in item_features"
          )
  
      if not user_features.shape[1] == self.user_embeddings.shape[0]:
          raise ValueError(
              "Incorrect number of features in user_features"
          )
  
      if num_threads < 1:
          raise ValueError("Number of threads must be 1 or larger.")
  
      for _ in self._progress(epochs, verbose=verbose):
          self._run_epoch(
              item_features,
              user_features,
              interactions,
              sample_weight_data,
              num_threads,
              self.loss,
          )
  
          self._check_finite()
  
      return self
  
imports: from __future__ import print_function
  import numpy
  import scipy.sparse
  from ._lightfm_fast import CSRMatrix, FastLightFM, fit_bpr, fit_logistic, fit_warp, fit_warp_kos, predict_lightfm, predict_ranks
label_desc: Use image node_id 14 for calling the LightFM obj's underlying member method code with example usage: obj.fit_partial(interactions, user_features, item_features, sample_weight, epochs, num_threads, verbose) and returns: self