Dec 21, 2024 · Dec 19, 2024 · Dec 20, 2024 · Dec 21, 2024 · Dec 20, 2024 · Dec 20, 2024
diff --git a/galleries/examples/scales/symlog_demo.py b/galleries/examples/scales/symlog_demo.py
 """
 ===========
 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.
 """
 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
 #
Original file line number	Diff line number	Diff line change
		@@ -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.
		"""
Expand DownExpand Up		@@ -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\|`.
Comment on lines +77 to +78 Copy link Contributor greglucasDec 20, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Where does this rule of thumb come from? I feel like this might be very data dependent and perhaps we shouldn't suggest anything 🤷 Copy link MemberAuthor timhoffmDec 20, 2024• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This comes from the two arguments linthresh should not be much larger than your min value, as that would push too many points into the linear region. But the linear region should not hold much data: 1. The symlog scale was chosen because of it's log scaling. If most interesting stuff is in the linear range, one could have remained on a linear scale. 2. Due to the different scaling, data relations in the lin. vs. Log regimes are not comparable. For clarity there shouldn't be much going on in the linear regime. linthresh should not be much smaller than your min value, as that would mean you have empty decades between linthresh and your data - effectively pushing your data to the borders of the plot and leaving a lot of unused space in the center. Unfortunately, one has to adapt linthresh depending on the data to get a decent looking plot. When I looked into this first I had no idea what value to choose. While you can create datasets that needs special different tuning, I feel the approximate rule of thumb will generally be a good starting point.. greglucas reacted with thumbs up emoji
		#
		#
		# 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
		#
Expand Down