{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Scatter plot with a legend\n\nTo create a scatter plot with a legend one may use a loop and create one\n`~.Axes.scatter` plot per item to appear in the legend and set the ``label``\naccordingly.\n\nThe following also demonstrates how transparency of the markers\ncan be adjusted by giving ``alpha`` a value between 0 and 1.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\nimport numpy as np\n\nnp.random.seed(19680801)\n\n\nfig, ax = plt.subplots()\nfor color in ['tab:blue', 'tab:orange', 'tab:green']:\n    n = 750\n    x, y = np.random.rand(2, n)\n    scale = 200.0 * np.random.rand(n)\n    ax.scatter(x, y, c=color, s=scale, label=color,\n               alpha=0.3, edgecolors='none')\n\nax.legend()\nax.grid(True)\n\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Automated legend creation\n\nAnother option for creating a legend for a scatter is to use the\n`.PathCollection.legend_elements` method.  It will automatically try to\ndetermine a useful number of legend entries to be shown and return a tuple of\nhandles and labels. Those can be passed to the call to `~.axes.Axes.legend`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "N = 45\nx, y = np.random.rand(2, N)\nc = np.random.randint(1, 5, size=N)\ns = np.random.randint(10, 220, size=N)\n\nfig, ax = plt.subplots()\n\nscatter = ax.scatter(x, y, c=c, s=s)\n\n# produce a legend with the unique colors from the scatter\nlegend1 = ax.legend(*scatter.legend_elements(),\n                    loc=\"lower left\", title=\"Classes\")\nax.add_artist(legend1)\n\n# produce a legend with a cross-section of sizes from the scatter\nhandles, labels = scatter.legend_elements(prop=\"sizes\", alpha=0.6)\nlegend2 = ax.legend(handles, labels, loc=\"upper right\", title=\"Sizes\")\n\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Further arguments to the `.PathCollection.legend_elements` method\ncan be used to steer how many legend entries are to be created and how they\nshould be labeled. The following shows how to use some of them.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "volume = np.random.rayleigh(27, size=40)\namount = np.random.poisson(10, size=40)\nranking = np.random.normal(size=40)\nprice = np.random.uniform(1, 10, size=40)\n\nfig, ax = plt.subplots()\n\n# Because the price is much too small when being provided as size for ``s``,\n# we normalize it to some useful point sizes, s=0.3*(price*3)**2\nscatter = ax.scatter(volume, amount, c=ranking, s=0.3*(price*3)**2,\n                     vmin=-3, vmax=3, cmap=\"Spectral\")\n\n# Produce a legend for the ranking (colors). Even though there are 40 different\n# rankings, we only want to show 5 of them in the legend.\nlegend1 = ax.legend(*scatter.legend_elements(num=5),\n                    loc=\"upper left\", title=\"Ranking\")\nax.add_artist(legend1)\n\n# Produce a legend for the price (sizes). Because we want to show the prices\n# in dollars, we use the *func* argument to supply the inverse of the function\n# used to calculate the sizes from above. The *fmt* ensures to show the price\n# in dollars. Note how we target at 5 elements here, but obtain only 4 in the\n# created legend due to the automatic round prices that are chosen for us.\nkw = dict(prop=\"sizes\", num=5, color=scatter.cmap(0.7), fmt=\"$ {x:.2f}\",\n          func=lambda s: np.sqrt(s/.3)/3)\nlegend2 = ax.legend(*scatter.legend_elements(**kw),\n                    loc=\"lower right\", title=\"Price\")\n\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. admonition:: References\n\n   The use of the following functions, methods, classes and modules is shown\n   in this example:\n\n   - `matplotlib.axes.Axes.scatter` / `matplotlib.pyplot.scatter`\n   - `matplotlib.axes.Axes.legend` / `matplotlib.pyplot.legend`\n   - `matplotlib.collections.PathCollection.legend_elements`\n\n.. tags::\n\n   component: legend\n   plot-type: scatter\n   level: intermediate\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}