class_docstr: Logistic regression models a discrete target variable as a function of
  several feature variables.
  
  The :class:`~turicreate.logistic_classifier.logisticClassifier` uses
  a discrete target variable :math:`y` instead of a scalar. For each
  observation, the probability that :math:`y=1` (instead of 0) is modeled as
  the logistic function of a linear combination of the feature values.
  
  Given a set of features :math:`x_i`, and a label :math:`y_i \in \{0,1\}`,
  logistic regression interprets the probability that the label is in one class
  as a logistic function of a linear combination of the features.
  
      .. math::
        f_i(\theta) =  p(y_i = 1 | x) = \frac{1}{1 + \exp(-\theta^T x)}
  
  An intercept term is added by appending a column of 1's to the features.
  Regularization is often required to prevent over fitting by penalizing
  models with extreme parameter values. The logistic regression module
  supports l1 and l2 regularization, which are added to the loss function.
  
  The composite objective being optimized for is the following;
  
      .. math::
         \min_{\theta} \sum_{i = 1}^{n} f_i(\theta) + \lambda_1 ||\theta||_1 + \lambda_2 ||\theta||^{2}_{2}
  
  where :math:`\lambda_1` is the ``l1_penalty`` and :math:`\lambda_2` is the
  ``l2_penalty``.
  
  For multi-class models, we perform multinomial logistic regression, which
  is an extension of the binary logistic regression model discussed above.
  
  This model cannot be constructed directly.  Instead, use
  :func:`turicreate.logistic_classifier.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.
  
  Examples
  --------
  .. sourcecode:: python
  
      # Load the data (From an S3 bucket)
      >>> data =  turicreate.SFrame('https://static.turi.com/datasets/regression/houses.csv')
  
      # Make sure the target is discrete
      >>> data['is_expensive'] = data['price'] > 30000
  
      # Make a logistic regression model
      >>> model = turicreate.logistic_classifier.create(data, target='is_expensive', features=['bath', 'bedroom', 'size'])
  
      # Extract the coefficients
      >>> coefficients = model.coefficients
  
      # Make predictions (as margins, probability, or class)
      >>> predictions = model.predict(data)
      >>> predictions = model.predict(data, output_type='probability')
      >>> predictions = model.predict(data, output_type='margin')
  
      # Evaluate the model
      >>> results = model.evaluate(data)
  
  See Also
  --------
  create
class_docstr_tok: ["Logistic","regression","models","a","discrete","target","variable","as","a","function","of","several","feature","variables",".","The",":","class",":","`","~turicreate.logistic_classifier.logisticClassifier","`","uses","a","discrete","target","variable",":","math",":","`","y","`","instead","of","a","scalar",".","For","each","observation",",","the","probability","that",":","math",":","`","y=1","`","(","instead","of","0",")","is","modeled","as","the","logistic","function","of","a","linear","combination","of","the","feature","values",".","Given","a","set","of","features",":","math",":","`","x_i","`",",","and","a","label",":","math",":","`","y_i","\\in","\\","{","0,1\\","}","`",",","logistic","regression","interprets","the","probability","that","the","label","is","in","one","class","as","a","logistic","function","of","a","linear","combination","of","the","features",".","..","math",":",":","f_i","(","\\theta",")","=","p","(","y_i","=","1","|","x",")","=","\\frac","{","1","}","{","1","+","\\exp","(","-\\theta^T","x",")","}","An","intercept","term","is","added","by","appending","a","column","of","1","'s","to","the","features",".","Regularization","is","often","required","to","prevent","over","fitting","by","penalizing","models","with","extreme","parameter","values",".","The","logistic","regression","module","supports","l1","and","l2","regularization",",","which","are","added","to","the","loss","function",".","The","composite","objective","being","optimized","for","is","the","following",";","..","math",":",":","\\min_","{","\\theta","}","\\sum_","{","i","=","1","}","^","{","n","}","f_i","(","\\theta",")","+","\\lambda_1","||\\theta||_1","+","\\lambda_2","||\\theta||^","{","2","}","_","{","2","}","where",":","math",":","`","\\lambda_1","`","is","the","``","l1_penalty","``","and",":","math",":","`","\\lambda_2","`","is","the","``","l2_penalty","``",".","For","multi-class","models",",","we","perform","multinomial","logistic","regression",",","which","is","an","extension","of","the","binary","logistic","regression","model","discussed","above",".","This","model","can","not","be","constructed","directly",".","Instead",",","use",":","func",":","`","turicreate.logistic_classifier.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",".","Examples","--","--","--","--","..","sourcecode",":",":","python","#","Load","the","data","(","From","an","S3","bucket",")",">",">",">","data","=","turicreate.SFrame","(","'https",":","\/\/static.turi.com\/datasets\/regression\/houses.csv","'",")","#","Make","sure","the","target","is","discrete",">",">",">","data","[","'is_expensive","'","]","=","data","[","'price","'","]",">","30000","#","Make","a","logistic","regression","model",">",">",">","model","=","turicreate.logistic_classifier.create","(","data",",","target='is_expensive","'",",","features=","[","'bath","'",",","'bedroom","'",",","'size","'","]",")","#","Extract","the","coefficients",">",">",">","coefficients","=","model.coefficients","#","Make","predictions","(","as","margins",",","probability",",","or","class",")",">",">",">","predictions","=","model.predict","(","data",")",">",">",">","predictions","=","model.predict","(","data",",","output_type='probability","'",")",">",">",">","predictions","=","model.predict","(","data",",","output_type='margin","'",")","#","Evaluate","the","model",">",">",">","results","=","model.evaluate","(","data",")","See","Also","--","--","--","--","create"]
docstr: Return top-k predictions for the ``dataset``, using the trained model.
  Predictions are returned as an SFrame with three columns: `id`,
  `class`, and `probability`, `margin`,  or `rank`, depending on the ``output_type``
  parameter. Input dataset size must be the same as for training of the model.
  
  Parameters
  ----------
  dataset : SFrame
      A dataset that has the same columns that were used during training.
      If the target column exists in ``dataset`` it will be ignored
      while making predictions.
  
  output_type : {'probability', 'rank', 'margin'}, optional
      Choose the return type of the prediction:
  
      - `probability`: Probability associated with each label in the prediction.
      - `rank`       : Rank associated with each label in the prediction.
      - `margin`     : Margin associated with each label in the prediction.
  
  k : int, optional
      Number of classes to return for each input example.
  
  missing_value_action : str, optional
      Action to perform when missing values are encountered. Can be
      one of:
  
      - 'auto': Default to 'impute'
      - 'impute': Proceed with evaluation by filling in the missing
        values with the mean of the training data. Missing
        values are also imputed if an entire column of data is
        missing during evaluation.
      - 'error': Do not proceed with evaluation and terminate with
        an error message.
  
  Returns
  -------
  out : SFrame
      An SFrame with model predictions.
  
  See Also
  --------
  predict, classify, evaluate
  
  Examples
  --------
  >>> pred = m.predict_topk(validation_data, k=3)
  >>> pred
  +--------+-------+-------------------+
  | id     | class |   probability     |
  +--------+-------+-------------------+
  |   0    |   4   |   0.995623886585  |
  |   0    |   9   |  0.0038311756216  |
  |   0    |   7   | 0.000301006948575 |
  |   1    |   1   |   0.928708016872  |
  |   1    |   3   |  0.0440889261663  |
  |   1    |   2   |  0.0176190119237  |
  |   2    |   3   |   0.996967732906  |
  |   2    |   2   |  0.00151345680933 |
  |   2    |   7   | 0.000637513934635 |
  |   3    |   1   |   0.998070061207  |
  |  ...   |  ...  |        ...        |
  +--------+-------+-------------------+
  [35688 rows x 3 columns]
docstr_tok: ["Return","top-k","predictions","for","the","``","dataset","``",",","using","the","trained","model",".","Predictions","are","returned","as","an","SFrame","with","three","columns",":","`","id","`",",","`","class","`",",","and","`","probability","`",",","`","margin","`",",","or","`","rank","`",",","depending","on","the","``","output_type","``","parameter",".","Input","dataset","size","must","be","the","same","as","for","training","of","the","model",".","Parameters","--","--","--","--","--","dataset",":","SFrame","A","dataset","that","has","the","same","columns","that","were","used","during","training",".","If","the","target","column","exists","in","``","dataset","``","it","will","be","ignored","while","making","predictions",".","output_type",":","{","'probability","'",",","'rank","'",",","'margin","'","}",",","optional","Choose","the","return","type","of","the","prediction",":","-","`","probability","`",":","Probability","associated","with","each","label","in","the","prediction",".","-","`","rank","`",":","Rank","associated","with","each","label","in","the","prediction",".","-","`","margin","`",":","Margin","associated","with","each","label","in","the","prediction",".","k",":","int",",","optional","Number","of","classes","to","return","for","each","input","example",".","missing_value_action",":","str",",","optional","Action","to","perform","when","missing","values","are","encountered",".","Can","be","one","of",":","-","'auto","'",":","Default","to","'impute'","-","'impute","'",":","Proceed","with","evaluation","by","filling","in","the","missing","values","with","the","mean","of","the","training","data",".","Missing","values","are","also","imputed","if","an","entire","column","of","data","is","missing","during","evaluation",".","-","'error","'",":","Do","not","proceed","with","evaluation","and","terminate","with","an","error","message",".","Returns","--","--","--","-","out",":","SFrame","An","SFrame","with","model","predictions",".","See","Also","--","--","--","--","predict",",","classify",",","evaluate","Examples","--","--","--","--",">",">",">","pred","=","m.predict_topk","(","validation_data",",","k=3",")",">",">",">","pred","+","--","--","--","--","+","--","--","--","-+","--","--","--","--","--","--","--","--","--","-+","|","id","|","class","|","probability","|","+","--","--","--","--","+","--","--","--","-+","--","--","--","--","--","--","--","--","--","-+","|","0","|","4","|","0.995623886585","|","|","0","|","9","|","0.0038311756216","|","|","0","|","7","|","0.000301006948575","|","|","1","|","1","|","0.928708016872","|","|","1","|","3","|","0.0440889261663","|","|","1","|","2","|","0.0176190119237","|","|","2","|","3","|","0.996967732906","|","|","2","|","2","|","0.00151345680933","|","|","2","|","7","|","0.000637513934635","|","|","3","|","1","|","0.998070061207","|","|","...","|","...","|","...","|","+","--","--","--","--","+","--","--","--","-+","--","--","--","--","--","--","--","--","--","-+","[","35688","rows","x","3","columns","]"]
code: def predict_topk(
      self,
      dataset,
      output_type="probability",
      k=3,
      missing_value_action="auto",
  ):
      """
      Return top-k predictions for the ``dataset``, using the trained model.
      Predictions are returned as an SFrame with three columns: `id`,
      `class`, and `probability`, `margin`,  or `rank`, depending on the ``output_type``
      parameter. Input dataset size must be the same as for training of the model.
  
      Parameters
      ----------
      dataset : SFrame
          A dataset that has the same columns that were used during training.
          If the target column exists in ``dataset`` it will be ignored
          while making predictions.
  
      output_type : {'probability', 'rank', 'margin'}, optional
          Choose the return type of the prediction:
  
          - `probability`: Probability associated with each label in the prediction.
          - `rank`       : Rank associated with each label in the prediction.
          - `margin`     : Margin associated with each label in the prediction.
  
      k : int, optional
          Number of classes to return for each input example.
  
      missing_value_action : str, optional
          Action to perform when missing values are encountered. Can be
          one of:
  
          - 'auto': Default to 'impute'
          - 'impute': Proceed with evaluation by filling in the missing
            values with the mean of the training data. Missing
            values are also imputed if an entire column of data is
            missing during evaluation.
          - 'error': Do not proceed with evaluation and terminate with
            an error message.
  
      Returns
      -------
      out : SFrame
          An SFrame with model predictions.
  
      See Also
      --------
      predict, classify, evaluate
  
      Examples
      --------
      >>> pred = m.predict_topk(validation_data, k=3)
      >>> pred
      +--------+-------+-------------------+
      | id     | class |   probability     |
      +--------+-------+-------------------+
      |   0    |   4   |   0.995623886585  |
      |   0    |   9   |  0.0038311756216  |
      |   0    |   7   | 0.000301006948575 |
      |   1    |   1   |   0.928708016872  |
      |   1    |   3   |  0.0440889261663  |
      |   1    |   2   |  0.0176190119237  |
      |   2    |   3   |   0.996967732906  |
      |   2    |   2   |  0.00151345680933 |
      |   2    |   7   | 0.000637513934635 |
      |   3    |   1   |   0.998070061207  |
      |  ...   |  ...  |        ...        |
      +--------+-------+-------------------+
      [35688 rows x 3 columns]
      """
      _check_categorical_option_type(
          "output_type", output_type, ["rank", "margin", "probability"]
      )
      _check_categorical_option_type(
          "missing_value_action",
          missing_value_action,
          ["auto", "impute", "error"],
      )
      if missing_value_action == "auto":
          missing_value_action = "impute"
  
      # Low latency path
      if isinstance(dataset, list):
          return self.__proxy__.fast_predict_topk(
              dataset, missing_value_action, output_type, k
          )
      if isinstance(dataset, dict):
          return self.__proxy__.fast_predict_topk(
              [dataset], missing_value_action, output_type, k
          )
      # Fast path
      _raise_error_if_not_sframe(dataset, "dataset")
      if missing_value_action == "auto":
          missing_value_action = (
              _sl.select_default_missing_value_policy(self, "predict")
          )
      return self.__proxy__.predict_topk(
          dataset, missing_value_action, output_type, k
      )
  
file_path: turicreate/src/python/turicreate/toolkits/classifier/logistic_classifier.py
imports: from __future__ import print_function
  from __future__ import division
  from __future__ import absolute_import
  import turicreate.toolkits._supervised_learning
  from turicreate.toolkits._supervised_learning import Classifier
  from turicreate.toolkits._internal_utils import _toolkit_repr_print, _toolkit_get_topk_bottomk, _raise_error_if_not_sframe, _check_categorical_option_type, _raise_error_evaluation_metric_is_valid, _summarize_coefficients
label_desc: Use image node_id 10 for calling the LogisticClassifier obj's underlying member method code with example usage: obj.predict_topk(dataset, output_type, k, missing_value_action) and returns: self, self, self