Feb 16, 2022 · Sep 26, 2021 · Sep 26, 2021 · Sep 26, 2021 · Sep 26, 2021 · Sep 26, 2021
diff --git a/doc/api/colors_api.rst b/doc/api/colors_api.rst
   :toctree: _as_gen/
   :template: autosummary.rst

   AsinhNorm
   BoundaryNorm
   Colormap
   CenteredNorm
diff --git a/doc/users/next_whats_new/asinh_scale.rst b/doc/users/next_whats_new/asinh_scale.rst
 New axis scale ``asinh``
 ------------------------

 The new ``asinh`` axis scale offers an alternative to ``symlog`` that
 smoothly transitions between the quasi-linear and asymptotically logarithmic
 regions of the scale. This is based on an arcsinh transformation that
 allows plotting both positive and negative values that span many orders
 of magnitude. A scale parameter is provided to allow the user
 to tune the width of the linear region of the scale.

 .. plot::

    import matplotlib.pyplot as plt
    import numpy

    fig, (ax0, ax1) = plt.subplots(1, 2, sharex=True)
    x = numpy.linspace(-3, 6, 100)

    ax0.plot(x, x)
    ax0.set_yscale('symlog')
    ax0.grid()
    ax0.set_title('symlog')

    ax1.plot(x, x)
    ax1.set_yscale('asinh')
    ax1.grid()
    ax1.set_title(r'$sinh^{-1}$')

    for p in (-2, 2):
      for ax in (ax0, ax1):
        c = plt.Circle((p, p), radius=0.5, fill=False,
                       color='red', alpha=0.8, lw=3)
        ax.add_patch(c)
diff --git a/examples/images_contours_and_fields/colormap_normalizations_symlognorm.py b/examples/images_contours_and_fields/colormap_normalizations_symlognorm.py
 """
 ==================================
 Colormap NormalizationsSymlognorm
 Colormap NormalizationsSymLogNorm
 ==================================

 Demonstration of using norm to map colormaps onto data in non-linear ways.

 .. redirect-from:: /gallery/userdemo/colormap_normalization_symlognorm
 """

 ########################################
 # Synthetic dataset consisting of two humps, one negative and one positive,
 # the positive with 8-times the amplitude.
 # Linearly, the negative hump is almost invisible,
 # and it is very difficult to see any detail of its profile.
 # With the logarithmic scaling applied to both positive and negative values,
 # it is much easier to see the shape of each hump.
 #
 # See `~.colors.SymLogNorm`.

 import numpy as np
 import matplotlib.pyplot as plt
 import matplotlib.colors as colors

 """
 SymLogNorm: two humps, one negative and one positive, The positive
 with 5-times the amplitude. Linearly, you cannot see detail in the
 negative hump.  Here we logarithmically scale the positive and
 negative data separately.

 Note that colorbar labels do not come out looking very good.
 """
 def rbf(x, y):
    return 1.0 / (1 + 5 * ((x ** 2) + (y ** 2)))

 N = 100
 N = 200
 gain = 8
 X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
 Z1 = np.exp(-X**2 - Y**2)
 Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
 Z = (Z1 - Z2) * 2
 Z1 = rbf(X + 0.5, Y + 0.5)
 Z2 = rbf(X - 0.5, Y - 0.5)
 Z = gain * Z1 - Z2

 shadeopts = {'cmap': 'PRGn', 'shading': 'gouraud'}
 colormap = 'PRGn'
 lnrwidth = 0.2

 fig, ax = plt.subplots(2, 1)
 fig, ax = plt.subplots(2, 1, sharex=True, sharey=True)

 pcm = ax[0].pcolormesh(X, Y, Z,
                       norm=colors.SymLogNorm(linthresh=0.03, linscale=0.03,
                                              vmin=-1.0, vmax=1.0, base=10),
 cmap='RdBu_r', shading='nearest')
                       norm=colors.SymLogNorm(linthresh=lnrwidth, linscale=1,
                                              vmin=-gain, vmax=gain, base=10),
 **shadeopts)
 fig.colorbar(pcm, ax=ax[0], extend='both')
 ax[0].text(-2.5, 1.5, 'symlog')

 pcm = ax[1].pcolormesh(X, Y, Z,cmap='RdBu_r', vmin=-np.max(Z),
 shading='nearest')
 pcm = ax[1].pcolormesh(X, Y, Z,vmin=-gain, vmax=gain,
 **shadeopts)
 fig.colorbar(pcm, ax=ax[1], extend='both')
 ax[1].text(-2.5, 1.5, 'linear')


 ########################################
 # Clearly, tt may be necessary to experiment with multiple different
 # colorscales in order to find the best visualization for
 # any particular dataset.
 # As well as the `~.colors.SymLogNorm` scaling, there is also
 # the option of using the `~.colors.AsinhNorm`, which has a smoother
 # transition between the linear and logarithmic regions of the transformation
 # applied to the "z" axis.
 # In the plots below, it may be possible to see ring-like artifacts
 # in the lower-amplitude, negative, hump shown in purple despite
 # there being no sharp features in the dataset itself.
 # The ``asinh`` scaling shows a smoother shading of each hump.

 fig, ax = plt.subplots(2, 1, sharex=True, sharey=True)

 pcm = ax[0].pcolormesh(X, Y, Z,
                       norm=colors.SymLogNorm(linthresh=lnrwidth, linscale=1,
                                              vmin=-2, vmax=gain, base=10),
                       **shadeopts)
 fig.colorbar(pcm, ax=ax[0], extend='both')
 ax[0].text(-2.5, 1.5, 'symlog')

 pcm = ax[1].pcolormesh(X, Y, Z,
                       norm=colors.AsinhNorm(linear_width=lnrwidth,
                                             vmin=-2, vmax=gain),
                       **shadeopts)
 fig.colorbar(pcm, ax=ax[1], extend='both')
 ax[1].text(-2.5, 1.5, 'asinh')


 plt.show()
diff --git a/examples/scales/asinh_demo.py b/examples/scales/asinh_demo.py
 """
 ============
 Asinh Demo
 ============

 Illustration of the `asinh <.scale.AsinhScale>` axis scaling,
 which uses the transformation

 .. math::

    a \\rightarrow a_0 \\sinh^{-1} (a / a_0)

 For coordinate values close to zero (i.e. much smaller than
 the "linear width" :math:`a_0`), this leaves values essentially unchanged:

 .. math::

    a \\rightarrow a + {\\cal O}(a^3)

 but for larger values (i.e. :math:`|a| \\gg a_0`, this is asymptotically

 .. math::

    a \\rightarrow a_0 \\, {\\rm sgn}(a) \\ln |a| + {\\cal O}(1)

 As with the `symlog <.scale.SymmetricalLogScale>` scaling,
 this allows one to plot quantities
 that cover a very wide dynamic range that includes both positive
 and negative values. However, ``symlog`` involves a transformation
 that has discontinuities in its gradient because it is built
 from *separate* linear and logarithmic transformations.
 The ``asinh`` scaling uses a transformation that is smooth
 for all (finite) values, which is both mathematically cleaner
 and reduces visual artifacts associated with an abrupt
 transition between linear and logarithmic regions of the plot.

 See `~.scale.AsinhScale`, `~.scale.SymmetricalLogScale`.
 """

 import numpy as np
 import matplotlib.pyplot as plt

 # Prepare sample values for variations on y=x graph:
 x = np.linspace(-3, 6, 500)

 ########################################
 # Compare "symlog" and "asinh" behaviour on sample y=x graph,
 # where there is a discontinuous gradient in "symlog" near y=2:
 fig1 = plt.figure()
 ax0, ax1 = fig1.subplots(1, 2, sharex=True)

 ax0.plot(x, x)
 ax0.set_yscale('symlog')
 ax0.grid()
 ax0.set_title('symlog')

 ax1.plot(x, x)
 ax1.set_yscale('asinh')
 ax1.grid()
 ax1.set_title('asinh')


 ########################################
 # Compare "asinh" graphs with different scale parameter "linear_width":
 fig2 = plt.figure(constrained_layout=True)
 axs = fig2.subplots(1, 3, sharex=True)
 for ax, (a0, base) in zip(axs, ((0.2, 2), (1.0, 0), (5.0, 3))):
    ax.set_title('linear_width={:.3g}'.format(a0))
    ax.plot(x, x, label='y=x')
    ax.plot(x, 10*x, label='y=10x')
    ax.plot(x, 100*x, label='y=100x')
    ax.set_yscale('asinh', linear_width=a0, base=base)
    ax.grid()
    ax.legend(loc='best', fontsize='small')


 ########################################
 # Compare "symlog" and "asinh" scalings
 # on 2D Cauchy-distributed random numbers,
 # where one may be able to see more subtle artifacts near y=2
 # due to the gradient-discontinuity in "symlog":
 fig3 = plt.figure()
 ax = fig3.subplots(1, 1)
 r = 3 * np.tan(np.random.uniform(-np.pi / 2.02, np.pi / 2.02,
                                 size=(5000,)))
 th = np.random.uniform(0, 2*np.pi, size=r.shape)

 ax.scatter(r * np.cos(th), r * np.sin(th), s=4, alpha=0.5)
 ax.set_xscale('asinh')
 ax.set_yscale('symlog')
 ax.set_xlabel('asinh')
 ax.set_ylabel('symlog')
 ax.set_title('2D Cauchy random deviates')
 ax.set_xlim(-50, 50)
 ax.set_ylim(-50, 50)
 ax.grid()

 plt.show()

 ########################################
 #
 # .. admonition:: References
 #
 #    - `matplotlib.scale.AsinhScale`
 #    - `matplotlib.ticker.AsinhLocator`
 #    - `matplotlib.scale.SymmetricalLogScale`
diff --git a/examples/scales/symlog_demo.py b/examples/scales/symlog_demo.py

 fig.tight_layout()
 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 disconinuities.

 ########################################
 #
 # .. admonition:: References
 #
 #    - `matplotlib.scale.SymmetricalLogScale`
 #    - `matplotlib.ticker.SymmetricalLogLocator`
 #    - `matplotlib.scale.AsinhScale`
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
        self._scale.linthresh = value


 @make_norm_from_scale(
    scale.AsinhScale,
    init=lambda linear_width=1, vmin=None, vmax=None, clip=False: None)
 class AsinhNorm(Normalize):
    """
    The inverse hyperbolic sine scale is approximately linear near
    the origin, but becomes logarithmic for larger positive
    or negative values. Unlike the `SymLogNorm`, the transition between
    these linear and logarithmic regions is smooth, which may reduce
    the risk of visual artifacts.

    Parameters
    ----------
    linear_width : float, default: 1
        The effective width of the linear region, beyond which
        the transformation becomes asymptotically logarithmic
    """

    @property
    def linear_width(self):
        return self._scale.linear_width

    @linear_width.setter
    def linear_width(self, value):
        self._scale.linear_width = value


 class PowerNorm(Normalize):
    """
    Linearly map a given value to the 0-1 range and then apply
Original file line number	Diff line number	Diff line change
Expand Up		@@ -21,6 +21,7 @@ Classes
		:toctree: _as_gen/
		:template: autosummary.rst

		AsinhNorm
		BoundaryNorm
		Colormap
		CenteredNorm
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,33 @@
		New axis scale ``asinh``
		------------------------
rwpenney marked this conversation as resolved. Show resolvedHide resolved

		The new ``asinh`` axis scale offers an alternative to ``symlog`` that
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		smoothly transitions between the quasi-linear and asymptotically logarithmic
		regions of the scale. This is based on an arcsinh transformation that
		allows plotting both positive and negative values that span many orders
		of magnitude. A scale parameter is provided to allow the user
Copy link Contributor greglucasOct 25, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I don't know if we want to put in mention of the scale parameter in the release notes or not...? If so, we should probably use it in the example below? Copy link ContributorAuthor rwpenneyOct 26, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Perhaps you're right that the scale-parameter is too much detail for inclusion the release notes.
		to tune the width of the linear region of the scale.

		.. plot::

		import matplotlib.pyplot as plt
		import numpy

		fig, (ax0, ax1) = plt.subplots(1, 2, sharex=True)
		x = numpy.linspace(-3, 6, 100)
QuLogic marked this conversation as resolved. Show resolvedHide resolved

		ax0.plot(x, x)
		ax0.set_yscale('symlog')
		ax0.grid()
		ax0.set_title('symlog')

		ax1.plot(x, x)
		ax1.set_yscale('asinh')
		ax1.grid()
		ax1.set_title(r'$sinh^{-1}$')

		for p in (-2, 2):
		for ax in (ax0, ax1):
		c = plt.Circle((p, p), radius=0.5, fill=False,
		color='red', alpha=0.8, lw=3)
		ax.add_patch(c)
QuLogic marked this conversation as resolved. Show resolvedHide resolved
Original file line number	Diff line number	Diff line change
		@@ -1,42 +1,85 @@
		"""
		==================================
		Colormap NormalizationsSymlognorm
		Colormap NormalizationsSymLogNorm
		==================================

		Demonstration of using norm to map colormaps onto data in non-linear ways.

		.. redirect-from:: /gallery/userdemo/colormap_normalization_symlognorm
		"""

		########################################
QuLogic marked this conversation as resolved. Show resolvedHide resolved
		# Synthetic dataset consisting of two humps, one negative and one positive,
		# the positive with 8-times the amplitude.
		# Linearly, the negative hump is almost invisible,
		# and it is very difficult to see any detail of its profile.
		# With the logarithmic scaling applied to both positive and negative values,
		# it is much easier to see the shape of each hump.
		#
		# See `~.colors.SymLogNorm`.

		import numpy as np
		import matplotlib.pyplot as plt
		import matplotlib.colors as colors

		"""
		SymLogNorm: two humps, one negative and one positive, The positive
		with 5-times the amplitude. Linearly, you cannot see detail in the
		negative hump. Here we logarithmically scale the positive and
		negative data separately.

		Note that colorbar labels do not come out looking very good.
		"""
		def rbf(x, y):
		return 1.0 / (1 + 5 * ((x 2) + (y 2)))

		N = 100
		N = 200
		gain = 8
		X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
		Z1 = np.exp(-X2 - Y2)
		Z2 = np.exp(-(X - 1)2 - (Y - 1)2)
		Z = (Z1 - Z2) * 2
		Z1 = rbf(X + 0.5, Y + 0.5)
		Z2 = rbf(X - 0.5, Y - 0.5)
		Z = gain * Z1 - Z2

		shadeopts = {'cmap': 'PRGn', 'shading': 'gouraud'}
		colormap = 'PRGn'
		lnrwidth = 0.2

		fig, ax = plt.subplots(2, 1)
		fig, ax = plt.subplots(2, 1, sharex=True, sharey=True)

		pcm = ax[0].pcolormesh(X, Y, Z,
		norm=colors.SymLogNorm(linthresh=0.03, linscale=0.03,
		vmin=-1.0, vmax=1.0, base=10),
		cmap='RdBu_r', shading='nearest')
		norm=colors.SymLogNorm(linthresh=lnrwidth, linscale=1,
		vmin=-gain, vmax=gain, base=10),
		**shadeopts)
		fig.colorbar(pcm, ax=ax[0], extend='both')
		ax[0].text(-2.5, 1.5, 'symlog')

		pcm = ax[1].pcolormesh(X, Y, Z,cmap='RdBu_r', vmin=-np.max(Z),
		shading='nearest')
		pcm = ax[1].pcolormesh(X, Y, Z,vmin=-gain, vmax=gain,
		**shadeopts)
		fig.colorbar(pcm, ax=ax[1], extend='both')
		ax[1].text(-2.5, 1.5, 'linear')


		########################################
		# Clearly, tt may be necessary to experiment with multiple different
		# colorscales in order to find the best visualization for
		# any particular dataset.
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		# As well as the `~.colors.SymLogNorm` scaling, there is also
		# the option of using the `~.colors.AsinhNorm`, which has a smoother
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		# transition between the linear and logarithmic regions of the transformation
		# applied to the "z" axis.
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		# In the plots below, it may be possible to see ring-like artifacts
		# in the lower-amplitude, negative, hump shown in purple despite
		# there being no sharp features in the dataset itself.
		# The ``asinh`` scaling shows a smoother shading of each hump.

		fig, ax = plt.subplots(2, 1, sharex=True, sharey=True)

		pcm = ax[0].pcolormesh(X, Y, Z,
		norm=colors.SymLogNorm(linthresh=lnrwidth, linscale=1,
		vmin=-2, vmax=gain, base=10),
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		**shadeopts)
		fig.colorbar(pcm, ax=ax[0], extend='both')
		ax[0].text(-2.5, 1.5, 'symlog')

		pcm = ax[1].pcolormesh(X, Y, Z,
		norm=colors.AsinhNorm(linear_width=lnrwidth,
		vmin=-2, vmax=gain),
		**shadeopts)
		fig.colorbar(pcm, ax=ax[1], extend='both')
		ax[1].text(-2.5, 1.5, 'asinh')


		plt.show()
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,106 @@
		"""
		============
		Asinh Demo
		============
rwpenney marked this conversation as resolved. Show resolvedHide resolved

		Illustration of the `asinh <.scale.AsinhScale>` axis scaling,
		which uses the transformation

		.. math::

		a \\rightarrow a_0 \\sinh^{-1} (a / a_0)

		For coordinate values close to zero (i.e. much smaller than
		the "linear width" :math:`a_0`), this leaves values essentially unchanged:

		.. math::

		a \\rightarrow a + {\\cal O}(a^3)

		but for larger values (i.e. :math:`\|a\| \\gg a_0`, this is asymptotically

		.. math::

		a \\rightarrow a_0 \\, {\\rm sgn}(a) \\ln \|a\| + {\\cal O}(1)

		As with the `symlog <.scale.SymmetricalLogScale>` scaling,
		this allows one to plot quantities
		that cover a very wide dynamic range that includes both positive
		and negative values. However, ``symlog`` involves a transformation
		that has discontinuities in its gradient because it is built
		from separate linear and logarithmic transformations.
		The ``asinh`` scaling uses a transformation that is smooth
		for all (finite) values, which is both mathematically cleaner
		and reduces visual artifacts associated with an abrupt
		transition between linear and logarithmic regions of the plot.

rwpenney marked this conversation as resolved. Show resolvedHide resolved
		See `~.scale.AsinhScale`, `~.scale.SymmetricalLogScale`.
		"""

		import numpy as np
		import matplotlib.pyplot as plt

		# Prepare sample values for variations on y=x graph:
		x = np.linspace(-3, 6, 500)

		########################################
		# Compare "symlog" and "asinh" behaviour on sample y=x graph,
		# where there is a discontinuous gradient in "symlog" near y=2:
		fig1 = plt.figure()
		ax0, ax1 = fig1.subplots(1, 2, sharex=True)

		ax0.plot(x, x)
		ax0.set_yscale('symlog')
		ax0.grid()
		ax0.set_title('symlog')

		ax1.plot(x, x)
		ax1.set_yscale('asinh')
		ax1.grid()
		ax1.set_title('asinh')


		########################################
		# Compare "asinh" graphs with different scale parameter "linear_width":
		fig2 = plt.figure(constrained_layout=True)
		axs = fig2.subplots(1, 3, sharex=True)
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		for ax, (a0, base) in zip(axs, ((0.2, 2), (1.0, 0), (5.0, 3))):
		ax.set_title('linear_width={:.3g}'.format(a0))
		ax.plot(x, x, label='y=x')
		ax.plot(x, 10*x, label='y=10x')
		ax.plot(x, 100*x, label='y=100x')
		ax.set_yscale('asinh', linear_width=a0, base=base)
		ax.grid()
		ax.legend(loc='best', fontsize='small')


		########################################
		# Compare "symlog" and "asinh" scalings
rwpenney marked this conversation as resolved. Show resolvedHide resolved
		# on 2D Cauchy-distributed random numbers,
		# where one may be able to see more subtle artifacts near y=2
		# due to the gradient-discontinuity in "symlog":
		fig3 = plt.figure()
		ax = fig3.subplots(1, 1)
		r = 3 * np.tan(np.random.uniform(-np.pi / 2.02, np.pi / 2.02,
		size=(5000,)))
		th = np.random.uniform(0, 2*np.pi, size=r.shape)

		ax.scatter(r * np.cos(th), r * np.sin(th), s=4, alpha=0.5)
		ax.set_xscale('asinh')
		ax.set_yscale('symlog')
		ax.set_xlabel('asinh')
		ax.set_ylabel('symlog')
		ax.set_title('2D Cauchy random deviates')
		ax.set_xlim(-50, 50)
		ax.set_ylim(-50, 50)
		ax.grid()

		plt.show()

		########################################
		#
		# .. admonition:: References
		#
		# - `matplotlib.scale.AsinhScale`
		# - `matplotlib.ticker.AsinhLocator`
		# - `matplotlib.scale.SymmetricalLogScale`
Original file line number	Diff line number	Diff line change
Expand Up		@@ -33,3 +33,17 @@

		fig.tight_layout()
		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 disconinuities.
rwpenney marked this conversation as resolved. Show resolvedHide resolved

		########################################
		#
		# .. admonition:: References
		#
		# - `matplotlib.scale.SymmetricalLogScale`
		# - `matplotlib.ticker.SymmetricalLogLocator`
		# - `matplotlib.scale.AsinhScale`
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1652,6 +1652,33 @@ def linthresh(self, value):
		self._scale.linthresh = value


		@make_norm_from_scale(
		scale.AsinhScale,
		init=lambda linear_width=1, vmin=None, vmax=None, clip=False: None)
		class AsinhNorm(Normalize):
		"""
		The inverse hyperbolic sine scale is approximately linear near
		the origin, but becomes logarithmic for larger positive
		or negative values. Unlike the `SymLogNorm`, the transition between
		these linear and logarithmic regions is smooth, which may reduce
		the risk of visual artifacts.

		Parameters
		----------
		linear_width : float, default: 1
		The effective width of the linear region, beyond which
		the transformation becomes asymptotically logarithmic
		"""

		@property
		def linear_width(self):
		return self._scale.linear_width

		@linear_width.setter
		def linear_width(self, value):
		self._scale.linear_width = value


		class PowerNorm(Normalize):
		"""
		Linearly map a given value to the 0-1 range and then apply
Expand Down