class_docstr: A FactorizationRecommender learns latent factors for each
  user and item and uses them to make rating predictions.
  
  FactorizationRecommender [Koren_et_al]_ contains a number of options that
  tailor to a variety of datasets and evaluation metrics, making this one of
  the most powerful model in the Turi Create recommender toolkit.
  
  **Side information**
  
  Side features may be provided via the `user_data` and `item_data` options
  when the model is created.
  
  Additionally, observation-specific information, such as the time of day when
  the user rated the item, can also be included. Any column in the
  `observation_data` SFrame that is not the user id, item id, or target is
  treated as a observation side features. The same side feature columns must
  be present when calling :meth:`predict`.
  
  Side features may be numeric or categorical. User ids and item ids are
  treated as categorical variables. For the additional side features, the type
  of the :class:`~turicreate.SFrame` column determines how it's handled: strings
  are treated as categorical variables and integers and floats are treated as
  numeric variables. Dictionaries and numeric arrays are also supported.
  
  **Creating a FactorizationRecommender**
  
  This model cannot be constructed directly.  Instead, use
  :func:`turicreate.recommender.factorization_recommender.create`
  to create an instance
  of this model. A detailed list of parameter options and code samples
  are available in the documentation for the create function.
  
  **Model parameters**
  
  Trained model parameters may be accessed using
  `m.get('coefficients')` or equivalently `m['coefficients']`.
  
  See Also
  --------
  create, :func:`turicreate.recommender.ranking_factorization_recommender.create`
  
  Notes
  -----
  **Model Definition**
  
  `FactorizationRecommender` trains a model capable of predicting a score for
  each possible combination of users and items.  The internal coefficients of
  the model are learned from known scores of users and items.
  Recommendations are then based on these scores.
  
  In the two factorization models, users and items are represented by weights
  and factors.  These model coefficients are learned during training.
  Roughly speaking, the weights, or bias terms, account for a user or item's
  bias towards higher or lower ratings.  For example, an item that is
  consistently rated highly would have a higher weight coefficient associated
  with them.  Similarly, an item that consistently receives below average
  ratings would have a lower weight coefficient to account for this bias.
  
  The factor terms model interactions between users and items.  For example,
  if a user tends to love romance movies and hate action movies, the factor
  terms attempt to capture that, causing the model to predict lower scores
  for action movies and higher scores for romance movies.  Learning good
  weights and factors is controlled by several options outlined below.
  
  More formally, when side data is not present, the predicted score for user
  :math:`i` on item :math:`j` is given by
  
  .. math::
     \operatorname{score}(i, j) =
        \mu + w_i + w_j
        + \mathbf{a}^T \mathbf{x}_i + \mathbf{b}^T \mathbf{y}_j
        + {\mathbf u}_i^T {\mathbf v}_j,
  
  where :math:`\mu` is a global bias term, :math:`w_i` is the weight term for
  user :math:`i`, :math:`w_j` is the weight term for item :math:`j`,
  :math:`\mathbf{x}_i` and :math:`\mathbf{y}_j` are respectively the user and
  item side feature vectors, and :math:`\mathbf{a}` and :math:`\mathbf{b}`
  are respectively the weight vectors for those side features.
  The latent factors, which are vectors of length ``num_factors``, are given
  by :math:`{\mathbf u}_i` and :math:`{\mathbf v}_j`.
  
  When `binary_target=True`, the above score is passed through a logistic
  function:
  
  .. math::
  
     \operatorname{score}(i, j) = 1 / (1 + exp (- z)),
  
  where :math:`z` is the original linear score.
  
  **Training the model**
  
  Formally, the objective function we are optimizing for is:
  
  .. math::
    \min_{\mathbf{w}, \mathbf{a}, \mathbf{b}, \mathbf{V}, \mathbf{U}}
    \frac{1}{|\mathcal{D}|} \sum_{(i,j,r_{ij}) \in \mathcal{D}}
    \mathcal{L}(\operatorname{score}(i, j), r_{ij})
    + \lambda_1 (\lVert {\mathbf w} \rVert^2_2 + || {\mathbf a} ||^2_2 + || {\mathbf b} ||^2_2 )
    + \lambda_2 \left(\lVert {\mathbf U} \rVert^2_2
                         + \lVert {\mathbf V} \rVert^2_2 \right)
  
  where :math:`\mathcal{D}` is the observation dataset, :math:`r_{ij}` is the
  rating that user :math:`i` gave to item :math:`j`,
  :math:`{\mathbf U} = ({\mathbf u}_1, {\mathbf u}_2, ...)` denotes the user's
  latent factors and :math:`{\mathbf V} = ({\mathbf v}_1, {\mathbf v}_2, ...)`
  denotes the item latent factors.  The loss function
  :math:`\mathcal{L}(\hat{y}, y)` is :math:`(\hat{y} - y)^2` by default.
  :math:`\lambda_1` denotes the `linear_regularization` parameter and
  :math:`\lambda_2` the `regularization` parameter.
  
  The model is trained using one of the following solvers:
  
  (a) Stochastic Gradient Descent [sgd]_ with additional tricks [Bottou]_
  to improve convergence. The optimization is done in parallel
  over multiple threads. This procedure is inherently random, so different
  calls to `create()` may return slightly different models, even with the
  same `random_seed`.
  
  (b) Alternating least squares (ALS), where the user latent factors are
  computed by fixing the item latent factors and vice versa.
  
  The Factorization Machine recommender model approximates target rating
  values as a weighted combination of user and item latent factors, biases,
  side features, and their pairwise combinations.
  
  The Factorization Machine [Rendle]_ is a generalization of Matrix Factorization.
  In particular, while Matrix Factorization learns latent factors for only the
  user and item interactions, the Factorization Machine learns latent factors
  for all variables, including side features, and also allows for interactions
  between all pairs of variables. Thus the Factorization Machine is capable of
  modeling complex relationships in the data. Typically,
  using `linear_side_features=True` performs better in terms of RMSE,
  but may require a longer training time.
  
  
  References
  ----------
  .. [Koren_et_al] Koren, Yehuda, Robert Bell and Chris Volinsky. `"Matrix
      Factorization Techniques for Recommender Systems." <http://www2.research
      .att.com/~volinsky/papers/ieeecomputer.pdf?utm_source=twitterfeed&utm_me
      dium=twitter>`_ Computer Volume: 42, Issue: 8 (2009): 30-37.
  
  .. [sgd] `Wikipedia - Stochastic gradient descent
      <http://en.wikipedia.org/wiki/Stochastic_gradient_descent>`_
  
  .. [Bottou] Leon Bottou, `"Stochastic Gradient Tricks,"
      <http://research.microsoft.com/apps/pubs/default.aspx?id=192769>`_
      Neural Networks, Tricks of the Trade, Reloaded, 430--445, Lecture Notes
      in Computer Science (LNCS 7700), Springer, 2012.
  
  .. [Rendle] Steffen Rendle, `"Factorization Machines,"
      <http://www.csie.ntu.edu.tw/~b97053/paper/Rendle2010FM.pdf>`_ in
      Proceedings of the 10th IEEE International Conference on Data Mining
      (ICDM), 2010.
class_docstr_tok: ["A","FactorizationRecommender","learns","latent","factors","for","each","user","and","item","and","uses","them","to","make","rating","predictions",".","FactorizationRecommender","[","Koren_et_al","]","_","contains","a","number","of","options","that","tailor","to","a","variety","of","datasets","and","evaluation","metrics",",","making","this","one","of","the","most","powerful","model","in","the","Turi","Create","recommender","toolkit",".","*","*","Side","information","*","*","Side","features","may","be","provided","via","the","`","user_data","`","and","`","item_data","`","options","when","the","model","is","created",".","Additionally",",","observation-specific","information",",","such","as","the","time","of","day","when","the","user","rated","the","item",",","can","also","be","included",".","Any","column","in","the","`","observation_data","`","SFrame","that","is","not","the","user","id",",","item","id",",","or","target","is","treated","as","a","observation","side","features",".","The","same","side","feature","columns","must","be","present","when","calling",":","meth",":","`","predict","`",".","Side","features","may","be","numeric","or","categorical",".","User","ids","and","item","ids","are","treated","as","categorical","variables",".","For","the","additional","side","features",",","the","type","of","the",":","class",":","`","~turicreate.SFrame","`","column","determines","how","it","'s","handled",":","strings","are","treated","as","categorical","variables","and","integers","and","floats","are","treated","as","numeric","variables",".","Dictionaries","and","numeric","arrays","are","also","supported",".","*","*","Creating","a","FactorizationRecommender","*","*","This","model","can","not","be","constructed","directly",".","Instead",",","use",":","func",":","`","turicreate.recommender.factorization_recommender.create","`","to","create","an","instance","of","this","model",".","A","detailed","list","of","parameter","options","and","code","samples","are","available","in","the","documentation","for","the","create","function",".","*","*","Model","parameters","*","*","Trained","model","parameters","may","be","accessed","using","`","m.get","(","'coefficients","'",")","`","or","equivalently","`","m","[","'coefficients","'","]","`",".","See","Also","--","--","--","--","create",",",":","func",":","`","turicreate.recommender.ranking_factorization_recommender.create","`","Notes","--","--","-","*","*","Model","Definition","*","*","`","FactorizationRecommender","`","trains","a","model","capable","of","predicting","a","score","for","each","possible","combination","of","users","and","items",".","The","internal","coefficients","of","the","model","are","learned","from","known","scores","of","users","and","items",".","Recommendations","are","then","based","on","these","scores",".","In","the","two","factorization","models",",","users","and","items","are","represented","by","weights","and","factors",".","These","model","coefficients","are","learned","during","training",".","Roughly","speaking",",","the","weights",",","or","bias","terms",",","account","for","a","user","or","item's","bias","towards","higher","or","lower","ratings",".","For","example",",","an","item","that","is","consistently","rated","highly","would","have","a","higher","weight","coefficient","associated","with","them",".","Similarly",",","an","item","that","consistently","receives","below","average","ratings","would","have","a","lower","weight","coefficient","to","account","for","this","bias",".","The","factor","terms","model","interactions","between","users","and","items",".","For","example",",","if","a","user","tends","to","love","romance","movies","and","hate","action","movies",",","the","factor","terms","attempt","to","capture","that",",","causing","the","model","to","predict","lower","scores","for","action","movies","and","higher","scores","for","romance","movies",".","Learning","good","weights","and","factors","is","controlled","by","several","options","outlined","below",".","More","formally",",","when","side","data","is","not","present",",","the","predicted","score","for","user",":","math",":","`","i","`","on","item",":","math",":","`","j","`","is","given","by","..","math",":",":","\\operatorname","{","score","}","(","i",",","j",")","=","\\mu","+","w_i","+","w_j","+","\\mathbf","{","a","}","^T","\\mathbf","{","x","}","_i","+","\\mathbf","{","b","}","^T","\\mathbf","{","y","}","_j","+","{","\\mathbf","u","}","_i^T","{","\\mathbf","v","}","_j",",","where",":","math",":","`","\\mu","`","is","a","global","bias","term",",",":","math",":","`","w_i","`","is","the","weight","term","for","user",":","math",":","`","i","`",",",":","math",":","`","w_j","`","is","the","weight","term","for","item",":","math",":","`","j","`",",",":","math",":","`","\\mathbf","{","x","}","_i","`","and",":","math",":","`","\\mathbf","{","y","}","_j","`","are","respectively","the","user","and","item","side","feature","vectors",",","and",":","math",":","`","\\mathbf","{","a","}","`","and",":","math",":","`","\\mathbf","{","b","}","`","are","respectively","the","weight","vectors","for","those","side","features",".","The","latent","factors",",","which","are","vectors","of","length","``","num_factors","``",",","are","given","by",":","math",":","`","{","\\mathbf","u","}","_i","`","and",":","math",":","`","{","\\mathbf","v","}","_j","`",".","When","`","binary_target=True","`",",","the","above","score","is","passed","through","a","logistic","function",":","..","math",":",":","\\operatorname","{","score","}","(","i",",","j",")","=","1","\/","(","1","+","exp","(","-","z",")",")",",","where",":","math",":","`","z","`","is","the","original","linear","score",".","*","*","Training","the","model","*","*","Formally",",","the","objective","function","we","are","optimizing","for","is",":","..","math",":",":","\\min_","{","\\mathbf","{","w","}",",","\\mathbf","{","a","}",",","\\mathbf","{","b","}",",","\\mathbf","{","V","}",",","\\mathbf","{","U","}","}","\\frac","{","1","}","{","|\\mathcal","{","D","}","|","}","\\sum_","{","(","i",",","j",",","r_","{","ij","}",")","\\in","\\mathcal","{","D","}","}","\\mathcal","{","L","}","(","\\operatorname","{","score","}","(","i",",","j",")",",","r_","{","ij","}",")","+","\\lambda_1","(","\\lVert","{","\\mathbf","w","}","\\rVert^2_2","+","||","{","\\mathbf","a","}","||^2_2","+","||","{","\\mathbf","b","}","||^2_2",")","+","\\lambda_2","\\left","(","\\lVert","{","\\mathbf","U","}","\\rVert^2_2","+","\\lVert","{","\\mathbf","V","}","\\rVert^2_2","\\right",")","where",":","math",":","`","\\mathcal","{","D","}","`","is","the","observation","dataset",",",":","math",":","`","r_","{","ij","}","`","is","the","rating","that","user",":","math",":","`","i","`","gave","to","item",":","math",":","`","j","`",",",":","math",":","`","{","\\mathbf","U","}","=","(","{","\\mathbf","u","}","_1",",","{","\\mathbf","u","}","_2",",","...",")","`","denotes","the","user's","latent","factors","and",":","math",":","`","{","\\mathbf","V","}","=","(","{","\\mathbf","v","}","_1",",","{","\\mathbf","v","}","_2",",","...",")","`","denotes","the","item","latent","factors",".","The","loss","function",":","math",":","`","\\mathcal","{","L","}","(","\\hat","{","y","}",",","y",")","`","is",":","math",":","`","(","\\hat","{","y","}","-","y",")","^2","`","by","default",".",":","math",":","`","\\lambda_1","`","denotes","the","`","linear_regularization","`","parameter","and",":","math",":","`","\\lambda_2","`","the","`","regularization","`","parameter",".","The","model","is","trained","using","one","of","the","following","solvers",":","(","a",")","Stochastic","Gradient","Descent","[","sgd","]","_","with","additional","tricks","[","Bottou","]","_","to","improve","convergence",".","The","optimization","is","done","in","parallel","over","multiple","threads",".","This","procedure","is","inherently","random",",","so","different","calls","to","`","create","(",")","`","may","return","slightly","different","models",",","even","with","the","same","`","random_seed","`",".","(","b",")","Alternating","least","squares","(","ALS",")",",","where","the","user","latent","factors","are","computed","by","fixing","the","item","latent","factors","and","vice","versa",".","The","Factorization","Machine","recommender","model","approximates","target","rating","values","as","a","weighted","combination","of","user","and","item","latent","factors",",","biases",",","side","features",",","and","their","pairwise","combinations",".","The","Factorization","Machine","[","Rendle","]","_","is","a","generalization","of","Matrix","Factorization",".","In","particular",",","while","Matrix","Factorization","learns","latent","factors","for","only","the","user","and","item","interactions",",","the","Factorization","Machine","learns","latent","factors","for","all","variables",",","including","side","features",",","and","also","allows","for","interactions","between","all","pairs","of","variables",".","Thus","the","Factorization","Machine","is","capable","of","modeling","complex","relationships","in","the","data",".","Typically",",","using","`","linear_side_features=True","`","performs","better","in","terms","of","RMSE",",","but","may","require","a","longer","training","time",".","References","--","--","--","--","--","..","[","Koren_et_al","]","Koren",",","Yehuda",",","Robert","Bell","and","Chris","Volinsky",".","`","``","Matrix","Factorization","Techniques","for","Recommender","Systems",".","''","<","http",":","\/\/www2.research",".att.com\/~volinsky\/papers\/ieeecomputer.pdf","?","utm_source=twitterfeed","&","utm_me","dium=twitter",">","`","_","Computer","Volume",":","42",",","Issue",":","8","(","2009",")",":","30-37",".","..","[","sgd","]","`","Wikipedia","-","Stochastic","gradient","descent","<","http",":","\/\/en.wikipedia.org\/wiki\/Stochastic_gradient_descent",">","`","_","..","[","Bottou","]","Leon","Bottou",",","`","``","Stochastic","Gradient","Tricks",",","''","<","http",":","\/\/research.microsoft.com\/apps\/pubs\/default.aspx","?","id=192769",">","`","_","Neural","Networks",",","Tricks","of","the","Trade",",","Reloaded",",","430","--","445",",","Lecture","Notes","in","Computer","Science","(","LNCS","7700",")",",","Springer",",","2012",".","..","[","Rendle","]","Steffen","Rendle",",","`","``","Factorization","Machines",",","''","<","http",":","\/\/www.csie.ntu.edu.tw\/~b97053\/paper\/Rendle2010FM.pdf",">","`","_","in","Proceedings","of","the","10th","IEEE","International","Conference","on","Data","Mining","(","ICDM",")",",","2010","."]
code: def _native_name(cls):
      return "factorization_recommender"
  
file_path: turicreate/src/python/turicreate/toolkits/recommender/factorization_recommender.py
imports: from __future__ import print_function
  from __future__ import division
  from __future__ import absolute_import
  from turicreate.toolkits._model import _get_default_options_wrapper
  import turicreate
  from turicreate.toolkits.recommender.util import _Recommender
  from turicreate.data_structures.sframe import SFrame
label_desc: Use image node_id 2 for calling the FactorizationRecommender obj's underlying member method code with example usage: obj._native_name(cls) and returns: str