objective_base
==========================================

.. py:module:: evalml.objectives.objective_base

.. autoapi-nested-parse::

   Base class for all objectives.



Module Contents
---------------

Classes Summary
~~~~~~~~~~~~~~~

.. autoapisummary::

   evalml.objectives.objective_base.ObjectiveBase





Contents
~~~~~~~~~~~~~~~~~~~
.. py:class:: ObjectiveBase



   Base class for all objectives.


   **Attributes**

   .. list-table::
      :widths: 15 85
      :header-rows: 0

      * - **problem_types**
        - None


   **Methods**

   .. autoapisummary::
      :nosignatures:

      evalml.objectives.objective_base.ObjectiveBase.calculate_percent_difference
      evalml.objectives.objective_base.ObjectiveBase.expected_range
      evalml.objectives.objective_base.ObjectiveBase.greater_is_better
      evalml.objectives.objective_base.ObjectiveBase.is_bounded_like_percentage
      evalml.objectives.objective_base.ObjectiveBase.is_defined_for_problem_type
      evalml.objectives.objective_base.ObjectiveBase.name
      evalml.objectives.objective_base.ObjectiveBase.objective_function
      evalml.objectives.objective_base.ObjectiveBase.perfect_score
      evalml.objectives.objective_base.ObjectiveBase.positive_only
      evalml.objectives.objective_base.ObjectiveBase.score
      evalml.objectives.objective_base.ObjectiveBase.score_needs_proba
      evalml.objectives.objective_base.ObjectiveBase.validate_inputs

   .. py:method:: calculate_percent_difference(cls, score, baseline_score)
      :classmethod:

      Calculate the percent difference between scores.

      :param score: A score. Output of the score method of this objective.
      :type score: float
      :param baseline_score: A score. Output of the score method of this objective. In practice,
                             this is the score achieved on this objective with a baseline estimator.
      :type baseline_score: float

      :returns:

                The percent difference between the scores. Note that for objectives that can be interpreted
                    as percentages, this will be the difference between the reference score and score. For all other
                    objectives, the difference will be normalized by the reference score.
      :rtype: float


   .. py:method:: expected_range(cls)
      :property:

      Returns the expected range of the objective, which is not necessarily the possible ranges.

      For example, our expected R2 range is from [-1, 1], although the
      actual range is (-inf, 1].


   .. py:method:: greater_is_better(cls)
      :property:

      Returns a boolean determining if a greater score indicates better model performance.


   .. py:method:: is_bounded_like_percentage(cls)
      :property:

      Returns whether this objective is bounded between 0 and 1, inclusive.


   .. py:method:: is_defined_for_problem_type(cls, problem_type)
      :classmethod:

      Returns whether or not an objective is defined for a problem type.


   .. py:method:: name(cls)
      :property:

      Returns a name describing the objective.


   .. py:method:: objective_function(cls, y_true, y_predicted, y_train=None, X=None, sample_weight=None)
      :classmethod:
      :abstractmethod:

      Computes the relative value of the provided predictions compared to the actual labels, according a specified metric.

      :param y_predicted: Predicted values of length [n_samples]
      :type y_predicted: pd.Series
      :param y_true: Actual class labels of length [n_samples]
      :type y_true: pd.Series
      :param y_train: Observed training values of length [n_samples]
      :type y_train: pd.Series
      :param X: Extra data of shape [n_samples, n_features] necessary to calculate score
      :type X: pd.DataFrame or np.ndarray
      :param sample_weight: Sample weights used in computing objective value result
      :type sample_weight: pd.DataFrame or np.ndarray

      :returns: Numerical value used to calculate score


   .. py:method:: perfect_score(cls)
      :property:

      Returns the score obtained by evaluating this objective on a perfect model.


   .. py:method:: positive_only(cls)

      If True, this objective is only valid for positive data. Defaults to False.


   .. py:method:: score(self, y_true, y_predicted, y_train=None, X=None, sample_weight=None)

      Returns a numerical score indicating performance based on the differences between the predicted and actual values.

      :param y_predicted: Predicted values of length [n_samples]
      :type y_predicted: pd.Series
      :param y_true: Actual class labels of length [n_samples]
      :type y_true: pd.Series
      :param y_train: Observed training values of length [n_samples]
      :type y_train: pd.Series
      :param X: Extra data of shape [n_samples, n_features] necessary to calculate score
      :type X: pd.DataFrame or np.ndarray
      :param sample_weight: Sample weights used in computing objective value result
      :type sample_weight: pd.DataFrame or np.ndarray

      :returns: score


   .. py:method:: score_needs_proba(cls)
      :property:

      Returns a boolean determining if the score() method needs probability estimates.

      This should be true for objectives which work with predicted
      probabilities, like log loss or AUC, and false for objectives
      which compare predicted class labels to the actual labels, like
      F1 or correlation.


   .. py:method:: validate_inputs(self, y_true, y_predicted)

      Validates the input based on a few simple checks.

      :param y_predicted: Predicted values of length [n_samples].
      :type y_predicted: pd.Series, or pd.DataFrame
      :param y_true: Actual class labels of length [n_samples].
      :type y_true: pd.Series

      :raises ValueError: If the inputs are malformed.