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 predictions for ``dataset``, using the trained logistic
  regression model. Predictions can be generated as class labels,
  probabilities that the target value is True, or margins (i.e. the
  distance of the observations from the hyperplane separating the
  classes). `probability_vector` returns a vector of probabilities by
  each class.
  
  For each new example in ``dataset``, the margin---also known as the
  linear predictor---is the inner product of the example and the model
  coefficients. The probability is obtained by passing the margin through
  the logistic function. Predicted classes are obtained by thresholding
  the predicted probabilities at 0.5. If you would like to threshold
  predictions at a different probability level, you can use the
  Turi Create evaluation toolkit.
  
  Parameters
  ----------
  dataset : SFrame
      Dataset of new observations. Must include columns with the same
      names as the features used for model training, but does not require
      a target column. Additional columns are ignored.
  
  output_type : {'probability', 'margin', 'class', 'probability_vector'}, optional
      Form of the predictions which are one of:
  
      - 'probability': Prediction probability associated with the True
        class (not applicable for multi-class classification)
      - 'probability_vector': Prediction probability associated with each
        class as a vector. The probability of the first class (sorted
        alphanumerically by name of the class in the training set) is in
        position 0 of the vector, the second in position 1 and so on.
      - 'class': Class prediction. For multi-class classification, this
        returns the class with maximum probability.
  
  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 : SArray
      An SArray with model predictions.
  
  See Also
  ----------
  create, evaluate, classify
  
  Examples
  ----------
  >>> data =  turicreate.SFrame('https://static.turi.com/datasets/regression/houses.csv')
  
  >>> data['is_expensive'] = data['price'] > 30000
  >>> model = turicreate.logistic_classifier.create(data,
                                       target='is_expensive',
                                       features=['bath', 'bedroom', 'size'])
  
  >>> probability_predictions = model.predict(data, output_type='probability')
  >>> margin_predictions = model.predict(data, output_type='margin')
  >>> class_predictions = model.predict(data, output_type='class')
docstr_tok: ["Return","predictions","for","``","dataset","``",",","using","the","trained","logistic","regression","model",".","Predictions","can","be","generated","as","class","labels",",","probabilities","that","the","target","value","is","True",",","or","margins","(","i.e",".","the","distance","of","the","observations","from","the","hyperplane","separating","the","classes",")",".","`","probability_vector","`","returns","a","vector","of","probabilities","by","each","class",".","For","each","new","example","in","``","dataset","``",",","the","margin","--","-also","known","as","the","linear","predictor","--","-is","the","inner","product","of","the","example","and","the","model","coefficients",".","The","probability","is","obtained","by","passing","the","margin","through","the","logistic","function",".","Predicted","classes","are","obtained","by","thresholding","the","predicted","probabilities","at","0.5",".","If","you","would","like","to","threshold","predictions","at","a","different","probability","level",",","you","can","use","the","Turi","Create","evaluation","toolkit",".","Parameters","--","--","--","--","--","dataset",":","SFrame","Dataset","of","new","observations",".","Must","include","columns","with","the","same","names","as","the","features","used","for","model","training",",","but","does","not","require","a","target","column",".","Additional","columns","are","ignored",".","output_type",":","{","'probability","'",",","'margin","'",",","'class","'",",","'probability_vector","'","}",",","optional","Form","of","the","predictions","which","are","one","of",":","-","'probability","'",":","Prediction","probability","associated","with","the","True","class","(","not","applicable","for","multi-class","classification",")","-","'probability_vector","'",":","Prediction","probability","associated","with","each","class","as","a","vector",".","The","probability","of","the","first","class","(","sorted","alphanumerically","by","name","of","the","class","in","the","training","set",")","is","in","position","0","of","the","vector",",","the","second","in","position","1","and","so","on",".","-","'class","'",":","Class","prediction",".","For","multi-class","classification",",","this","returns","the","class","with","maximum","probability",".","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",":","SArray","An","SArray","with","model","predictions",".","See","Also","--","--","--","--","--","create",",","evaluate",",","classify","Examples","--","--","--","--","--",">",">",">","data","=","turicreate.SFrame","(","'https",":","\/\/static.turi.com\/datasets\/regression\/houses.csv","'",")",">",">",">","data","[","'is_expensive","'","]","=","data","[","'price","'","]",">","30000",">",">",">","model","=","turicreate.logistic_classifier.create","(","data",",","target='is_expensive","'",",","features=","[","'bath","'",",","'bedroom","'",",","'size","'","]",")",">",">",">","probability_predictions","=","model.predict","(","data",",","output_type='probability","'",")",">",">",">","margin_predictions","=","model.predict","(","data",",","output_type='margin","'",")",">",">",">","class_predictions","=","model.predict","(","data",",","output_type='class","'",")"]
code: def predict(
      self, dataset, output_type="class", missing_value_action="auto"
  ):
      """
      Return predictions for ``dataset``, using the trained logistic
      regression model. Predictions can be generated as class labels,
      probabilities that the target value is True, or margins (i.e. the
      distance of the observations from the hyperplane separating the
      classes). `probability_vector` returns a vector of probabilities by
      each class.
  
      For each new example in ``dataset``, the margin---also known as the
      linear predictor---is the inner product of the example and the model
      coefficients. The probability is obtained by passing the margin through
      the logistic function. Predicted classes are obtained by thresholding
      the predicted probabilities at 0.5. If you would like to threshold
      predictions at a different probability level, you can use the
      Turi Create evaluation toolkit.
  
      Parameters
      ----------
      dataset : SFrame
          Dataset of new observations. Must include columns with the same
          names as the features used for model training, but does not require
          a target column. Additional columns are ignored.
  
      output_type : {'probability', 'margin', 'class', 'probability_vector'}, optional
          Form of the predictions which are one of:
  
          - 'probability': Prediction probability associated with the True
            class (not applicable for multi-class classification)
          - 'probability_vector': Prediction probability associated with each
            class as a vector. The probability of the first class (sorted
            alphanumerically by name of the class in the training set) is in
            position 0 of the vector, the second in position 1 and so on.
          - 'class': Class prediction. For multi-class classification, this
            returns the class with maximum probability.
  
      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 : SArray
          An SArray with model predictions.
  
      See Also
      ----------
      create, evaluate, classify
  
      Examples
      ----------
      >>> data =  turicreate.SFrame('https://static.turi.com/datasets/regression/houses.csv')
  
      >>> data['is_expensive'] = data['price'] > 30000
      >>> model = turicreate.logistic_classifier.create(data,
                                           target='is_expensive',
                                           features=['bath', 'bedroom', 'size'])
  
      >>> probability_predictions = model.predict(data, output_type='probability')
      >>> margin_predictions = model.predict(data, output_type='margin')
      >>> class_predictions = model.predict(data, output_type='class')
  
      """
  
      return super(_Classifier, self).predict(
          dataset,
          output_type=output_type,
          missing_value_action=missing_value_action,
      )
  
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 8 for calling the LogisticClassifier obj's underlying member method code with example usage: obj.predict(dataset, output_type, missing_value_action) and returns: super