.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_auto_examples_ensemble_plot_monotonic_constraints.py>`     to download the full example code or to run this example in your browser via Binder
    .. rst-class:: sphx-glr-example-title

    .. _sphx_glr_auto_examples_ensemble_plot_monotonic_constraints.py:


=====================
Monotonic Constraints
=====================

This example illustrates the effect of monotonic constraints on a gradient
boosting estimator.

We build an artificial dataset where the target value is in general
positively correlated with the first feature (with some random and
non-random variations), and in general negatively correlated with the second
feature.

By imposing a positive (increasing) or negative (decreasing) constraint on
the features during the learning process, the estimator is able to properly
follow the general trend instead of being subject to the variations.

This example was inspired by the `XGBoost documentation
<https://xgboost.readthedocs.io/en/latest/tutorials/monotonic.html>`_.



.. image:: /auto_examples/ensemble/images/sphx_glr_plot_monotonic_constraints_001.png
    :alt: Monotonic constraints illustration
    :class: sphx-glr-single-img






.. code-block:: default

    from sklearn.experimental import enable_hist_gradient_boosting  # noqa
    from sklearn.ensemble import HistGradientBoostingRegressor
    from sklearn.inspection import plot_partial_dependence
    import numpy as np
    import matplotlib.pyplot as plt


    print(__doc__)

    rng = np.random.RandomState(0)

    n_samples = 5000
    f_0 = rng.rand(n_samples)  # positive correlation with y
    f_1 = rng.rand(n_samples)  # negative correlation with y
    X = np.c_[f_0, f_1]
    noise = rng.normal(loc=0.0, scale=0.01, size=n_samples)
    y = (5 * f_0 + np.sin(10 * np.pi * f_0) -
         5 * f_1 - np.cos(10 * np.pi * f_1) +
         noise)

    fig, ax = plt.subplots()


    # Without any constraint
    gbdt = HistGradientBoostingRegressor()
    gbdt.fit(X, y)
    disp = plot_partial_dependence(
        gbdt, X, features=[0, 1],
        line_kw={'linewidth': 4, 'label': 'unconstrained'},
        ax=ax)

    # With positive and negative constraints
    gbdt = HistGradientBoostingRegressor(monotonic_cst=[1, -1])
    gbdt.fit(X, y)

    plot_partial_dependence(
        gbdt, X, features=[0, 1],
        feature_names=('First feature\nPositive constraint',
                       'Second feature\nNegtive constraint'),
        line_kw={'linewidth': 4, 'label': 'constrained'},
        ax=disp.axes_)

    for f_idx in (0, 1):
        disp.axes_[0, f_idx].plot(X[:, f_idx], y, 'o', alpha=.3, zorder=-1)
        disp.axes_[0, f_idx].set_ylim(-6, 6)

    plt.legend()
    fig.suptitle("Monotonic constraints illustration")

    plt.show()


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.757 seconds)


.. _sphx_glr_download_auto_examples_ensemble_plot_monotonic_constraints.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example


  .. container:: binder-badge

    .. image:: https://mybinder.org/badge_logo.svg
      :target: https://mybinder.org/v2/gh/scikit-learn/scikit-learn/0.23.X?urlpath=lab/tree/notebooks/auto_examples/ensemble/plot_monotonic_constraints.ipynb
      :width: 150 px


  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: plot_monotonic_constraints.py <plot_monotonic_constraints.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: plot_monotonic_constraints.ipynb <plot_monotonic_constraints.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_