{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Stairs Demo\n\nThis example demonstrates the use of `~.matplotlib.pyplot.stairs` for stepwise\nconstant functions. A common use case is histogram and histogram-like data\nvisualization.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\nimport numpy as np\n\nfrom matplotlib.patches import StepPatch\n\nnp.random.seed(0)\nh, edges = np.histogram(np.random.normal(5, 3, 5000),\n                        bins=np.linspace(0, 10, 20))\n\nfig, axs = plt.subplots(3, 1, figsize=(7, 15))\naxs[0].stairs(h, edges, label='Simple histogram')\naxs[0].stairs(h, edges + 5, baseline=50, label='Modified baseline')\naxs[0].stairs(h, edges + 10, baseline=None, label='No edges')\naxs[0].set_title(\"Step Histograms\")\n\naxs[1].stairs(np.arange(1, 6, 1), fill=True,\n              label='Filled histogram\\nw/ automatic edges')\naxs[1].stairs(np.arange(1, 6, 1)*0.3, np.arange(2, 8, 1),\n              orientation='horizontal', hatch='//',\n              label='Hatched histogram\\nw/ horizontal orientation')\naxs[1].set_title(\"Filled histogram\")\n\npatch = StepPatch(values=[1, 2, 3, 2, 1],\n                  edges=range(1, 7),\n                  label=('Patch derived underlying object\\n'\n                         'with default edge/facecolor behaviour'))\naxs[2].add_patch(patch)\naxs[2].set_xlim(0, 7)\naxs[2].set_ylim(-1, 5)\naxs[2].set_title(\"StepPatch artist\")\n\nfor ax in axs:\n    ax.legend()\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "*baseline* can take an array to allow for stacked histogram plots\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "A = [[0, 0, 0],\n     [1, 2, 3],\n     [2, 4, 6],\n     [3, 6, 9]]\n\nfor i in range(len(A) - 1):\n    plt.stairs(A[i+1], baseline=A[i], fill=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Comparison of `.pyplot.step` and `.pyplot.stairs`\n\n`.pyplot.step` defines the positions of the steps as single values. The steps\nextend left/right/both ways from these reference values depending on the\nparameter *where*. The number of *x* and *y* values is the same.\n\nIn contrast, `.pyplot.stairs` defines the positions of the steps via their\nbounds *edges*, which is one element longer than the step values.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "bins = np.arange(14)\ncenters = bins[:-1] + np.diff(bins) / 2\ny = np.sin(centers / 2)\n\nplt.step(bins[:-1], y, where='post', label='step(where=\"post\")')\nplt.plot(bins[:-1], y, 'o--', color='grey', alpha=0.3)\n\nplt.stairs(y - 1, bins, baseline=None, label='stairs()')\nplt.plot(centers, y - 1, 'o--', color='grey', alpha=0.3)\nplt.plot(np.repeat(bins, 2), np.hstack([y[0], np.repeat(y, 2), y[-1]]) - 1,\n         'o', color='red', alpha=0.2)\n\nplt.legend()\nplt.title('step() vs. stairs()')\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.stairs` / `matplotlib.pyplot.stairs`\n   - `matplotlib.patches.StepPatch`\n\n.. tags::\n\n   plot-type: stairs\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
}