.. only:: html

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

        Click :ref:`here <sphx_glr_download_gallery_text_labels_and_annotations_custom_legends.py>`     to download the full example code
    .. rst-class:: sphx-glr-example-title

    .. _sphx_glr_gallery_text_labels_and_annotations_custom_legends.py:


========================
Composing Custom Legends
========================

Composing custom legends piece-by-piece.

.. note::

   For more information on creating and customizing legends, see the following
   pages:

   * :doc:`/tutorials/intermediate/legend_guide`
   * :doc:`/gallery/text_labels_and_annotations/legend_demo`

Sometimes you don't want a legend that is explicitly tied to data that
you have plotted. For example, say you have plotted 10 lines, but don't
want a legend item to show up for each one. If you simply plot the lines
and call ``ax.legend()``, you will get the following:


.. code-block:: default

    from matplotlib import rcParams, cycler
    import matplotlib.pyplot as plt
    import numpy as np

    # Fixing random state for reproducibility
    np.random.seed(19680801)

    N = 10
    data = (np.geomspace(1, 10, 100) + np.random.randn(N, 100)).T
    cmap = plt.cm.coolwarm
    rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))

    fig, ax = plt.subplots()
    lines = ax.plot(data)
    ax.legend()




.. image:: /gallery/text_labels_and_annotations/images/sphx_glr_custom_legends_001.png
    :alt: custom legends
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    No handles with labels found to put in legend.

    <matplotlib.legend.Legend object at 0x7f79ca9bff40>



Note that no legend entries were created.
In this case, we can compose a legend using Matplotlib objects that aren't
explicitly tied to the data that was plotted. For example:


.. code-block:: default


    from matplotlib.lines import Line2D
    custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),
                    Line2D([0], [0], color=cmap(.5), lw=4),
                    Line2D([0], [0], color=cmap(1.), lw=4)]

    fig, ax = plt.subplots()
    lines = ax.plot(data)
    ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'])





.. image:: /gallery/text_labels_and_annotations/images/sphx_glr_custom_legends_002.png
    :alt: custom legends
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <matplotlib.legend.Legend object at 0x7f79ca3ef7f0>



There are many other Matplotlib objects that can be used in this way. In the
code below we've listed a few common ones.


.. code-block:: default


    from matplotlib.patches import Patch
    from matplotlib.lines import Line2D

    legend_elements = [Line2D([0], [0], color='b', lw=4, label='Line'),
                       Line2D([0], [0], marker='o', color='w', label='Scatter',
                              markerfacecolor='g', markersize=15),
                       Patch(facecolor='orange', edgecolor='r',
                             label='Color Patch')]

    # Create the figure
    fig, ax = plt.subplots()
    ax.legend(handles=legend_elements, loc='center')

    plt.show()



.. image:: /gallery/text_labels_and_annotations/images/sphx_glr_custom_legends_003.png
    :alt: custom legends
    :class: sphx-glr-single-img






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

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


.. _sphx_glr_download_gallery_text_labels_and_annotations_custom_legends.py:


.. only :: html

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



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

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



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

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


.. only:: html

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

    Keywords: matplotlib code example, codex, python plot, pyplot
    `Gallery generated by Sphinx-Gallery
    <https://sphinx-gallery.readthedocs.io>`_