|
1 | 1 | """ |
2 | | -=========== |
3 | | -Symlog Demo |
4 | | -=========== |
| 2 | +============ |
| 3 | +Symlog scale |
| 4 | +============ |
| 5 | +
|
| 6 | +The symmetric logarithmic scale is an extension of the logarithmic scale that |
| 7 | +also covers negative values. As with the logarithmic scale, it is particularly |
| 8 | +useful for numerical data that spans a broad range of values, especially when there |
| 9 | +are significant differences between the magnitudes of the numbers involved. |
5 | 10 |
|
6 | 11 | Example use of symlog (symmetric log) axis scaling. |
7 | 12 | """ |
|
34 | 39 | plt.show() |
35 | 40 |
|
36 | 41 | # %% |
37 | | -# It should be noted that the coordinate transform used by ``symlog`` |
38 | | -# has a discontinuous gradient at the transition between its linear |
39 | | -# and logarithmic regions. The ``asinh`` axis scale is an alternative |
40 | | -# technique that may avoid visual artifacts caused by these discontinuities. |
| 42 | +# Linear threshold |
| 43 | +# ---------------- |
| 44 | +# Since each decade on a logarithmic scale covers the same amount of visual space |
| 45 | +# and there are infinitely many decades between a given number and zero, the symlog |
| 46 | +# scale must deviate from logarithmic mapping in a small range (-x0, x0), so that |
| 47 | +# that range is mapped to a finite visual space. |
| 48 | +# |
| 49 | +# The symlog scale achieves this by defining a parameter *linthresh* and switching |
| 50 | +# to a linear mapping in the region *(-linthresh, linthresh)*. |
| 51 | + |
| 52 | +def format_axes(ax, title=None): |
| 53 | + """A helper function to better visualize properties of the symlog scale.""" |
| 54 | + ax.xaxis.get_minor_locator().set_params(subs=[2, 3, 4, 5, 6, 7, 8, 9]) |
| 55 | + ax.grid() |
| 56 | + ax.xaxis.grid(which='minor') # minor grid on too |
| 57 | + linthresh = ax.xaxis.get_transform().linthresh |
| 58 | + linscale = ax.xaxis.get_transform().linscale |
| 59 | + ax.axvspan(-linthresh, linthresh, color='0.9') |
| 60 | + if title: |
| 61 | + ax.set_title(title.format(linthresh=linthresh, linscale=linscale)) |
| 62 | + |
| 63 | + |
| 64 | +x = np.linspace(-60, 60, 201) |
| 65 | +y = np.linspace(0, 100.0, 201) |
| 66 | + |
| 67 | +fig, (ax1, ax2) = plt.subplots(nrows=2, layout="constrained") |
| 68 | + |
| 69 | +ax1.plot(x, y) |
| 70 | +ax1.set_xscale('symlog', linthresh=1) |
| 71 | +format_axes(ax1, title='Linear region: linthresh={linthresh}') |
| 72 | + |
| 73 | +ax2.plot(x, y) |
| 74 | +ax2.set_xscale('symlog', linthresh=5) |
| 75 | +format_axes(ax2, title='Linear region: linthresh={linthresh}') |
| 76 | + |
| 77 | +# %% |
| 78 | +# Generally, *linthresh* should be chosen so that no or only a few |
| 79 | +# data points are in the linear region. As a rule of thumb, |
| 80 | +# :math:`linthresh \approx \mathrm{min} |x|`. |
| 81 | +# |
| 82 | +# |
| 83 | +# Linear scale |
| 84 | +# ------------ |
| 85 | +# Additionally, the *linscale* parameter determines how much visual space should be |
| 86 | +# used for the linear range. More precisely, it defines the ratio of visual space |
| 87 | +# of the region (0, linthresh) relative to one decade. |
| 88 | + |
| 89 | +fig, (ax1, ax2) = plt.subplots(nrows=2, layout="constrained") |
| 90 | + |
| 91 | +ax1.plot(x, y) |
| 92 | +ax1.set_xscale('symlog', linthresh=1) |
| 93 | +format_axes(ax1, title='Linear region: linthresh={linthresh}, linscale={linscale}') |
| 94 | + |
| 95 | +ax2.plot(x, y) |
| 96 | +ax2.set_xscale('symlog', linthresh=1, linscale=0.1) |
| 97 | +format_axes(ax2, title='Linear region: linthresh={linthresh}, linscale={linscale}') |
41 | 98 |
|
42 | 99 | # %% |
| 100 | +# The suitable value for linscale depends on the dynamic range of data. As most data |
| 101 | +# will be outside the linear region, you typically the linear region only to cover |
| 102 | +# a small fraction of the visual area. |
| 103 | +# |
| 104 | +# Limitations and alternatives |
| 105 | +# ---------------------------- |
| 106 | +# The coordinate transform used by ``symlog`` has a discontinuous gradient at the |
| 107 | +# transition between its linear and logarithmic regions. Depending on data and |
| 108 | +# scaling, this will be more or less obvious in the plot. |
| 109 | + |
| 110 | +fig, ax = plt.subplots() |
| 111 | +ax.plot(x, y) |
| 112 | +ax.set_xscale('symlog', linscale=0.05) |
| 113 | +format_axes(ax, title="Discontinuous gradient at linear/log transition") |
| 114 | + |
| 115 | +# %% |
| 116 | +# The ``asinh`` axis scale is an alternative transformation that supports a wide |
| 117 | +# dynamic range with a smooth gradient and thus may avoid such visual artifacts. |
| 118 | +# See :doc:`/gallery/scales/assinh_demo`. |
| 119 | +# |
43 | 120 | # |
44 | 121 | # .. admonition:: References |
45 | 122 | # |
|
0 commit comments