Rebuild 3.10.0 docs

Author: ksunden

Diff for: 3.10.0/_downloads/00c5504fb7c2dac95f97dfc7fb5df3a0/angles_on_bracket_arrows.zip

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Symlog Demo\n\nExample use of symlog (symmetric log) axis scaling.\n"
+        "\n# Symlog scale\n\nThe symmetric logarithmic scale is an extension of the logarithmic scale that\nalso covers negative values. As with the logarithmic scale, it is particularly\nuseful for numerical data that spans a broad range of values, especially when there\nare significant differences between the magnitudes of the numbers involved.\n\nExample use of symlog (symmetric log) axis scaling.\n"
       ]
     },
     {
@@ -22,14 +22,61 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "It should be noted that the coordinate transform used by ``symlog``\nhas a discontinuous gradient at the transition between its linear\nand logarithmic regions. The ``asinh`` axis scale is an alternative\ntechnique that may avoid visual artifacts caused by these discontinuities.\n\n"
+        "## Linear threshold\nSince each decade on a logarithmic scale covers the same amount of visual space\nand there are infinitely many decades between a given number and zero, the symlog\nscale must deviate from logarithmic mapping in a small range\n*(-linthresh, linthresh)*, so that the range is mapped to a finite visual space.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "def format_axes(ax, title=None):\n    \"\"\"A helper function to better visualize properties of the symlog scale.\"\"\"\n    ax.xaxis.get_minor_locator().set_params(subs=[2, 3, 4, 5, 6, 7, 8, 9])\n    ax.grid()\n    ax.xaxis.grid(which='minor')  # minor grid on too\n    linthresh = ax.xaxis.get_transform().linthresh\n    linscale = ax.xaxis.get_transform().linscale\n    ax.axvspan(-linthresh, linthresh, color='0.9')\n    if title:\n        ax.set_title(title.format(linthresh=linthresh, linscale=linscale))\n\n\nx = np.linspace(-60, 60, 201)\ny = np.linspace(0, 100.0, 201)\n\nfig, (ax1, ax2) = plt.subplots(nrows=2, layout=\"constrained\")\n\nax1.plot(x, y)\nax1.set_xscale('symlog', linthresh=1)\nformat_axes(ax1, title='Linear region: linthresh={linthresh}')\n\nax2.plot(x, y)\nax2.set_xscale('symlog', linthresh=5)\nformat_axes(ax2, title='Linear region: linthresh={linthresh}')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Generally, *linthresh* should be chosen so that no or only a few\ndata points are in the linear region. As a rule of thumb,\n$linthresh \\approx \\mathrm{min} |x|$.\n\n\n## Linear scale\nAdditionally, the *linscale* parameter determines how much visual space should be\nused for the linear range. More precisely, it defines the ratio of visual space\nof the region (0, linthresh) relative to one decade.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "fig, (ax1, ax2) = plt.subplots(nrows=2, layout=\"constrained\")\n\nax1.plot(x, y)\nax1.set_xscale('symlog', linthresh=1)\nformat_axes(ax1, title='Linear region: linthresh={linthresh}, linscale={linscale}')\n\nax2.plot(x, y)\nax2.set_xscale('symlog', linthresh=1, linscale=0.1)\nformat_axes(ax2, title='Linear region: linthresh={linthresh}, linscale={linscale}')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The suitable value for linscale depends on the dynamic range of data. As most data\nwill be outside the linear region, you typically the linear region only to cover\na small fraction of the visual area.\n\n## Limitations and alternatives\nThe coordinate transform used by ``symlog`` has a discontinuous gradient at the\ntransition between its linear and logarithmic regions. Depending on data and\nscaling, this will be more or less obvious in the plot.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots()\nax.plot(x, y)\nax.set_xscale('symlog', linscale=0.05)\nformat_axes(ax, title=\"Discontinuous gradient at linear/log transition\")"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        ".. admonition:: References\n\n   - `matplotlib.scale.SymmetricalLogScale`\n   - `matplotlib.ticker.SymmetricalLogLocator`\n   - `matplotlib.scale.AsinhScale`\n\n"
+        "The ``asinh`` axis scale is an alternative transformation that supports a wide\ndynamic range with a smooth gradient and thus may avoid such visual artifacts.\nSee :doc:`/gallery/scales/asinh_demo`.\n\n\n.. admonition:: References\n\n   - `matplotlib.scale.SymmetricalLogScale`\n   - `matplotlib.ticker.SymmetricalLogLocator`\n   - `matplotlib.scale.AsinhScale`\n\n"
       ]
     }
   ],

Diff for: 3.10.0/_downloads/014a880826469dce2e3ad8104270a00a/demo_parasite_axes2.zip

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Logit Demo\n\nExamples of plots with logit axes.\n"
+        "\n# Logit scale\n\nExamples of plots with logit axes.\n"
       ]
     },
     {

Diff for: 3.10.0/_downloads/02364fe9e55f3dfcd38ea93f7be43beb/image_masked.zip

@@ -1,27 +1,34 @@
 """
-===========
-Broken Barh
-===========
+======================
+Broken horizontal bars
+======================
 
-Make a "broken" horizontal bar plot, i.e., one with gaps
+`~.Axes.broken_barh` creates sequences of horizontal bars. This example shows
+a timing diagram.
 """
 import matplotlib.pyplot as plt
+import numpy as np
+
+# data is a sequence of (start, duration) tuples
+cpu_1 = [(0, 3), (3.5, 1), (5, 5)]
+cpu_2 = np.column_stack([np.linspace(0, 9, 10), np.full(10, 0.5)])
+cpu_3 = np.column_stack([10*np.random.random(61), np.full(61, 0.05)])
+cpu_4 = [(2, 1.7), (7, 1.2)]
+disk = [(1, 1.5)]
+network = np.column_stack([10*np.random.random(10), np.full(10, 0.05)])
 
-# Horizontal bar plot with gaps
 fig, ax = plt.subplots()
-ax.broken_barh([(110, 30), (150, 10)], (10, 9), facecolors='tab:blue')
-ax.broken_barh([(10, 50), (100, 20), (130, 10)], (20, 9),
-               facecolors=('tab:orange', 'tab:green', 'tab:red'))
-ax.set_ylim(5, 35)
-ax.set_xlim(0, 200)
-ax.set_xlabel('seconds since start')
-ax.set_yticks([15, 25], labels=['Bill', 'Jim'])     # Modify y-axis tick labels
-ax.grid(True)                                       # Make grid lines visible
-ax.annotate('race interrupted', (61, 25),
-            xytext=(0.8, 0.9), textcoords='axes fraction',
-            arrowprops=dict(facecolor='black', shrink=0.05),
-            fontsize=16,
-            horizontalalignment='right', verticalalignment='top')
+# broken_barh(xranges, (ymin, height))
+ax.broken_barh(cpu_1, (5.8, 0.4))
+ax.broken_barh(cpu_2, (4.8, 0.4))
+ax.broken_barh(cpu_3, (3.8, 0.4))
+ax.broken_barh(cpu_4, (2.8, 0.4))
+ax.broken_barh(disk, (1.8, 0.4), color="tab:orange")
+ax.broken_barh(network, (0.8, 0.4), color="tab:green")
+ax.set_xlim(0, 10)
+ax.set_yticks([6, 5, 4, 3, 2, 1],
+              labels=["CPU 1", "CPU 2", "CPU 3", "CPU 4", "disk", "network"])
+ax.set_title("Resource usage")
 
 plt.show()
 

Diff for: 3.10.0/_downloads/02383bbfb2fce48594c5851fb5283fa4/double_pendulum.zip

@@ -1,7 +1,12 @@
 """
-===========
-Symlog Demo
-===========
+============
+Symlog scale
+============
+
+The symmetric logarithmic scale is an extension of the logarithmic scale that
+also covers negative values. As with the logarithmic scale, it is particularly
+useful for numerical data that spans a broad range of values, especially when there
+are significant differences between the magnitudes of the numbers involved.
 
 Example use of symlog (symmetric log) axis scaling.
 """
@@ -34,12 +39,82 @@
 plt.show()
 
 # %%
-# It should be noted that the coordinate transform used by ``symlog``
-# has a discontinuous gradient at the transition between its linear
-# and logarithmic regions. The ``asinh`` axis scale is an alternative
-# technique that may avoid visual artifacts caused by these discontinuities.
+# Linear threshold
+# ----------------
+# Since each decade on a logarithmic scale covers the same amount of visual space
+# and there are infinitely many decades between a given number and zero, the symlog
+# scale must deviate from logarithmic mapping in a small range
+# *(-linthresh, linthresh)*, so that the range is mapped to a finite visual space.
+
+
+def format_axes(ax, title=None):
+    """A helper function to better visualize properties of the symlog scale."""
+    ax.xaxis.get_minor_locator().set_params(subs=[2, 3, 4, 5, 6, 7, 8, 9])
+    ax.grid()
+    ax.xaxis.grid(which='minor')  # minor grid on too
+    linthresh = ax.xaxis.get_transform().linthresh
+    linscale = ax.xaxis.get_transform().linscale
+    ax.axvspan(-linthresh, linthresh, color='0.9')
+    if title:
+        ax.set_title(title.format(linthresh=linthresh, linscale=linscale))
+
+
+x = np.linspace(-60, 60, 201)
+y = np.linspace(0, 100.0, 201)
+
+fig, (ax1, ax2) = plt.subplots(nrows=2, layout="constrained")
+
+ax1.plot(x, y)
+ax1.set_xscale('symlog', linthresh=1)
+format_axes(ax1, title='Linear region: linthresh={linthresh}')
+
+ax2.plot(x, y)
+ax2.set_xscale('symlog', linthresh=5)
+format_axes(ax2, title='Linear region: linthresh={linthresh}')
+
+# %%
+# Generally, *linthresh* should be chosen so that no or only a few
+# data points are in the linear region. As a rule of thumb,
+# :math:`linthresh \approx \mathrm{min} |x|`.
+#
+#
+# Linear scale
+# ------------
+# Additionally, the *linscale* parameter determines how much visual space should be
+# used for the linear range. More precisely, it defines the ratio of visual space
+# of the region (0, linthresh) relative to one decade.
+
+fig, (ax1, ax2) = plt.subplots(nrows=2, layout="constrained")
+
+ax1.plot(x, y)
+ax1.set_xscale('symlog', linthresh=1)
+format_axes(ax1, title='Linear region: linthresh={linthresh}, linscale={linscale}')
+
+ax2.plot(x, y)
+ax2.set_xscale('symlog', linthresh=1, linscale=0.1)
+format_axes(ax2, title='Linear region: linthresh={linthresh}, linscale={linscale}')
 
 # %%
+# The suitable value for linscale depends on the dynamic range of data. As most data
+# will be outside the linear region, you typically the linear region only to cover
+# a small fraction of the visual area.
+#
+# Limitations and alternatives
+# ----------------------------
+# The coordinate transform used by ``symlog`` has a discontinuous gradient at the
+# transition between its linear and logarithmic regions. Depending on data and
+# scaling, this will be more or less obvious in the plot.
+
+fig, ax = plt.subplots()
+ax.plot(x, y)
+ax.set_xscale('symlog', linscale=0.05)
+format_axes(ax, title="Discontinuous gradient at linear/log transition")
+
+# %%
+# The ``asinh`` axis scale is an alternative transformation that supports a wide
+# dynamic range with a smooth gradient and thus may avoid such visual artifacts.
+# See :doc:`/gallery/scales/asinh_demo`.
+#
 #
 # .. admonition:: References
 #

Diff for: 3.10.0/_downloads/025a5da5932878208d30e0b01fad0dfe/fillunder3d.zip

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Broken Barh\n\nMake a \"broken\" horizontal bar plot, i.e., one with gaps\n"
+        "\n# Broken horizontal bars\n\n`~.Axes.broken_barh` creates sequences of horizontal bars. This example shows\na timing diagram.\n"
       ]
     },
     {
@@ -15,7 +15,7 @@
       },
       "outputs": [],
       "source": [
-        "import matplotlib.pyplot as plt\n\n# Horizontal bar plot with gaps\nfig, ax = plt.subplots()\nax.broken_barh([(110, 30), (150, 10)], (10, 9), facecolors='tab:blue')\nax.broken_barh([(10, 50), (100, 20), (130, 10)], (20, 9),\n               facecolors=('tab:orange', 'tab:green', 'tab:red'))\nax.set_ylim(5, 35)\nax.set_xlim(0, 200)\nax.set_xlabel('seconds since start')\nax.set_yticks([15, 25], labels=['Bill', 'Jim'])     # Modify y-axis tick labels\nax.grid(True)                                       # Make grid lines visible\nax.annotate('race interrupted', (61, 25),\n            xytext=(0.8, 0.9), textcoords='axes fraction',\n            arrowprops=dict(facecolor='black', shrink=0.05),\n            fontsize=16,\n            horizontalalignment='right', verticalalignment='top')\n\nplt.show()"
+        "import matplotlib.pyplot as plt\nimport numpy as np\n\n# data is a sequence of (start, duration) tuples\ncpu_1 = [(0, 3), (3.5, 1), (5, 5)]\ncpu_2 = np.column_stack([np.linspace(0, 9, 10), np.full(10, 0.5)])\ncpu_3 = np.column_stack([10*np.random.random(61), np.full(61, 0.05)])\ncpu_4 = [(2, 1.7), (7, 1.2)]\ndisk = [(1, 1.5)]\nnetwork = np.column_stack([10*np.random.random(10), np.full(10, 0.05)])\n\nfig, ax = plt.subplots()\n# broken_barh(xranges, (ymin, height))\nax.broken_barh(cpu_1, (5.8, 0.4))\nax.broken_barh(cpu_2, (4.8, 0.4))\nax.broken_barh(cpu_3, (3.8, 0.4))\nax.broken_barh(cpu_4, (2.8, 0.4))\nax.broken_barh(disk, (1.8, 0.4), color=\"tab:orange\")\nax.broken_barh(network, (0.8, 0.4), color=\"tab:green\")\nax.set_xlim(0, 10)\nax.set_yticks([6, 5, 4, 3, 2, 1],\n              labels=[\"CPU 1\", \"CPU 2\", \"CPU 3\", \"CPU 4\", \"disk\", \"network\"])\nax.set_title(\"Resource usage\")\n\nplt.show()"
       ]
     },
     {