{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Hat graph\nThis example shows how to create a [hat graph](https://doi.org/10.1186/s41235-019-0182-3) and how to annotate it with\nlabels.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\nimport numpy as np\n\n\ndef hat_graph(ax, xlabels, values, group_labels):\n    \"\"\"\n    Create a hat graph.\n\n    Parameters\n    ----------\n    ax : matplotlib.axes.Axes\n        The Axes to plot into.\n    xlabels : list of str\n        The category names to be displayed on the x-axis.\n    values : (M, N) array-like\n        The data values.\n        Rows are the groups (len(group_labels) == M).\n        Columns are the categories (len(xlabels) == N).\n    group_labels : list of str\n        The group labels displayed in the legend.\n    \"\"\"\n\n    values = np.asarray(values)\n    color_cycle_colors = plt.rcParams['axes.prop_cycle'].by_key()['color']\n\n    # Draw the hats\n    bars = ax.grouped_bar(\n        (values - values[0]).T, bottom=values[0], tick_labels=xlabels,\n        labels=group_labels, edgecolor='black', group_spacing=0.8,\n        colors=['none'] + color_cycle_colors)\n\n    # Attach a text label on top of each bar\n    for bc, heights in zip(bars.bar_containers, values):\n        ax.bar_label(bc, heights, padding=4)\n\n\n# Initialise labels and a numpy array make sure you have\n# N labels of N number of values in the array\nxlabels = ['I', 'II', 'III', 'IV', 'V']\nplayerA = np.array([5, 15, 22, 20, 25])\nplayerB = np.array([25, 32, 34, 30, 27])\n\nfig, ax = plt.subplots(layout='constrained')\n\nhat_graph(ax, xlabels, [playerA, playerB], ['Player A', 'Player B'])\n\n# Add some text for labels, title and custom x-axis tick labels, etc.\nax.set_xlabel('Games')\nax.set_ylabel('Score')\nax.set_ylim(0, 60)\nax.set_title('Scores by number of game and players')\nax.legend()\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.grouped_bar` / `matplotlib.pyplot.grouped_bar`\n   - `matplotlib.axes.Axes.bar_label` / `matplotlib.pyplot.bar_label`\n\n.. tags::\n\n   component: annotation\n   plot-type: bar\n   level: beginner\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.12.15"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}