A couple of quick comments.

• Can a0 be scaled to mean something in terms of the asymptotes? Folks are used to controlling the width of the linear region with threshold kwarg
• I think the locator and formatter should basically be the same as for symlog.
• I think by choosing a higher odd power of sinh you can make the transition more abrupt?

Thanks, Jody, for taking a look at this. In answer to your questions:

• The asymptotes behave like (a0*log(x) + O(1)), so a0 can be thought of as controlling the "base" of the logarithm, as well as the width of the quasi-linear region. However, this base obviously gets scaled away by the final affine translation before rendering on the screen. Also the word "threshold" very much implies an abrupt change between linear and logarithmic regimes, and that's something I deliberately don't want to imply.
• I'm not convinced that the locator and formatter should be the same as for symlog, because the latter seems very strongly tied to there being distinct regions of the transformation. Also, the default settings for symlog's locator seem only to put major ticks on the powers of ten, which is not very helpful for many plots. The example plots above hopefully show that the new formatter & locator put many more guides that should help the viewer get an intuition for how the data points are distributed. It's not obvious to me whether there's a simple way of getting both regularly spaced major ticks and neatly regular numerical values (as can be done for the plain log-scale), so my current solution is the best I've found so far that fits in a small number of lines of code.
• Interesting idea about higher powers of asinh, although that's obviously not implemented in this patch. The risk in offering this facility would be that one has even more subtlety for the viewer to interpret - we might have a region near zero where the graph was approximately cubic and the asymptotes would then be O((log(x)^3), for example.

This will need a bit of organization.

I'm not sure the new scale will see much use if it is not a clear drop-in replacement for symlog. In particular, I would have to do some math to calculate what a0 is and what an appropriate value for my dataset should be, whereas I readily understand what threshold means.

I just wanted to drop in and say that I think this is a worthwhile addition - for displaying signed data over a large range it has advantages and disadvantages to the symlog scaling. re. interpreting a0, for x <~ a0 the scale is approximately linear, for x >~ a0 the scaling is approximately logarithmic, so I think that there's a similar interpretation as a0 in both the existing norm and the new one in this PR.

interpreting a0, for x <~ a0 the scale is approximately linear, for x >~ a0

Great! The docs should explicitly say that.

Thanks for picking this up @rwpenney!

I agree that the name a0 could be more descriptive, I think linthresh would be a better choice to keep the similarity to symlog. Also, I believe there is a factor of 2 missing for the linear region approximation? The other linked PR had the base change, but I am not sure that is strictly necessary here, the other PR had it because that was trying to replace symlog. However, it wasn't a difficult change either, just adding another scaling parameter in, so that can be left up to you.

Thanks, all, for very helpful comments so far.

For @greglucas 's point, I'm not sure where there may be a missing factor of two. Agreed, the documentation needs to make explicit what arcsinh transformation I'm using, but I believe I've arranged that in the region |x|<<a0, the transformation is x -> 1*x+O(x^3), which seems like the simplest natural choice.

Also, I'm still reluctant to rename a0 to anything linked to the word "threshold" - the whole purpose of this new axis scaling is that there isn't a threshold that separates the nearly linear from asympotitically logarithmic regions.
Is there a clearer shorthand for this, perhaps transition_scale or tx_scale?

I'll aim to get the most of the code updates done later this week (after a few more urgent distractions elsewhere).

I don't mind not calling it threshold and agree with your argument, but a0 is too mysterious. transition_scale is OK, maybe linear_scale? Though I hesitate on either of those because this is defining the scale of part of a "scale", which is a bit confusing. Is transition_width possible? Maybe thats where the factor of two came from before...

Agreed, the documentation needs to make explicit what arcsinh transformation I'm using, but I believe I've arranged that in the region |x|<<a0, the transformation is x -> 1*x+O(x^3), which seems like the simplest natural choice.

If you're using asinh(ax), that's ax + O(x^3) for |x| < 1/a right? How about calling it linear_gradient or linear_slope in that case?

Its a0 sinh (x / a0), so I think its x + a0 O((x/a0)^3) for |x| < a0.

I think I've now addressed all the suggestions raised so far:

• the AsinhLocator class has been relocated to ticker.py
• the a0 parameter has been renamed to linear_width
• the documentation now makes explicit what formula is used for the arcsinh transformation
• various unit-tests have been added for the transformations and tick-locator
• handling of tick-marks near zero has been improved to avoid very closely spaced ticks

As an illustration of the latest version of the demonstration plots, attached is the comparison of symlog with asinh on y=x.

The improved logic for handling ticks near zero has tidied up the nearly overlapping '0.1' and '0' markers shown in the original P/R message. I've also added some circles that show the points where the symlog transformation has discontinuous gradients. Given that these circles are themselves mapped through the same coordinate transformation, these egg-shaped annotations further emphasise the differences between the two axis scales.

@rwpenney I've added the "needs discussion" label, which means we may discuss at our (open to anyone!) developer call on Thursday. Questions to me are 1) do we want another scale like this? 2) is there general support for the non-decade locator/formatter?

Thanks @jklymak - it would be very welcome to hear others' views on whether a new axis-scale would be useful to the matplotlib community.

A few further thoughts on the non-decade formatter:

• In any non-linear axis transformation, the crucial requirement is to give the viewer enough clues about the coordinate system throughout all regions of the coordinate transformation. Having tick-marks that coincide neatly with powers of ten, or other "regular" benchmarks is of secondary importance, and not always achievable.
• Transformations such as (ordinary) log-scaling, have a regularity that makes it easy to achieve uniform tick marks across each decade - neither symlog nor asinh have this mathematical structure.
• The various plots I've shared in this pull-request, hopefully, make it clear that the default settings in symlog, even for very simple datasets, do not produce anything like enough tick-marks to help the viewer understand the various different regions of the coordinate transformation.

Just a few comments here:

• I think the reason I was thinking there was a factor of 2 off, was because in the other PR I was trying to replace the symlog scale, which has a default of 2 on linthresh. So, for this PR I think it makes sense to keep a default of 1 like you are and ignore my previous comment.
• For the tickers, I think it depends on each user's problem as to which one they would prefer. I personally only used symlog to try and get log-like scaling on positive/negative quantities on a colormapped image, so the different regions didn't really matter to me as much as it was nice to have +/- decades. However, I understand if you want to view the data in the linear region, then having a different ticker there makes sense.

For the example, I find it hard to see the differences other than the abrupt change. What about making one axis symlog and the other axis asinh? The left image has data closer to the linear region and asinh has nicer ticks, but the right image has more dynamic range and I find the symlog ticker does better for that case.

import numpy as np
import matplotlib.pyplot as plt

# Prepare sample values for variations on y=x graph:
x = np.linspace(-5, 5, 100)

# Compare "symlog" and "asinh" behaviour on sample y=x graph:
fig1 = plt.figure(constrained_layout=True)
ax0, ax1 = fig1.subplots(1, 2)

ax0.plot(x, x)
ax0.axline((0, 0), (5, 5), color="black", linestyle=(0, (5, 5)),
           transform=ax0.transAxes)
ax0.set_xscale('asinh')
ax0.set_yscale('symlog')
ax0.grid()

ax0.set_xlabel('asinh')
ax0.set_ylabel('symlog')
lims = np.min(x), np.max(x)
ax0.set_xlim(lims)
ax0.set_ylim(lims)

# Now use logspace to go out multiple decades logarithmically
x = np.logspace(-3, 3, 100)

ax1.plot(x, x)
ax1.axline((0, 0), (5, 5), color="black", linestyle=(0, (5, 5)),
           transform=ax1.transAxes)
ax1.set_xscale('asinh')
ax1.set_yscale('symlog')
ax1.grid()

ax1.set_xlabel('asinh')
ax1.set_ylabel('symlog')
lims = np.min(x), np.max(x)
ax1.set_xlim(lims)
ax1.set_ylim(lims)

plt.show()

I think re the ticker, I was only discussing the exponential ranges, and arguing that they should tick on powers of 10 (or powers of an optional base). I won't argue that symlogs current behaviour in the inner range is at all good!

Thanks for the various updates. I certainly agree that the choice of axis-scaling, and almost every other aesthetic choice about a plot, is very strongly dependent on one's data. There are definitely some cases where symlog offers very useful functionality, but I think there are other circumstances where I'd definitely prefer to have alternative tools available.

@greglucas 's plots further highlight the trade-offs between these two axis scales. There was a demonstration plot in examples/scales/asinh_demo.py that shows a scatterplot of some fat-tailed circularly-symmetric random deviates. That plot (as attached) seems to show quite noticeable horizontal artifacts due to the symlog discontinuity. I'm wondering whether similar artifacts might lurk within the colorscales that you're basing on symlog?

I'd assume that there's no reason why a user couldn't use the SymmetricalLogLocator with the AsinhScale, if that works best for their particular scenario?

Hi @rwpenney, this was brought up on the weekly dev call today for discussion. People were generally in agreement that the transform and scale are nice mathematical alternatives to symlog and would be OK additions. There was some confusion about the locator though, due to the ticking not being symmetric about 0 and not being on decades at the large ranges. So, there was a general preference to use the current SymmetricalLogLocator with this transform and scale.

There is also the option to add this as a separate package if you'd like, which is currently done with mpl-probscale https://github.com/matplotlib/mpl-probscale.

For the documentation, I really like your examples and descriptions in the asinh area. I'm wondering if we could also add some text and alternatives in the SymLog examples pointing to this new option and explaining why someone might want to use it instead. Going in the reverse direction as well because SymmetricLog is easier to search/find than asinh if you don't know what you're looking for.

Finally, addressing your last comment about colormapping:

I'm wondering whether similar artifacts might lurk within the colorscales that you're basing on symlog

I would guess you're right, but likely less noticeable than on a lineplot. It might be worth adding this new norm to the SymLogNorm colormapping example too, demoing the alternative there as well.
https://64066-1385122-gh.circle-artifacts.com/0/doc/build/html/gallery/images_contours_and_fields/colormap_normalizations_symlognorm.html

Thanks, @greglucas for discussing this at the weekly dev call, and for your suggestions on a way forward.

I was mistaken in assuming that we could simply use the SymmetricalLogLocator directly, having forgotten that it is quite strongly coupled to the assumed axis-scale transformation (as indeed is AsinhLocator). So, I'm in the process of revising AsinhLocator to support rounding to an arbitrary number base, so that the default behaviour of AsinhScale will be to put major ticks on powers of ten, and minor ticks at the adjacent multiples of 2, 5.

Thanks for the comments about the documentation - I'll be adding some links to the SymmetricalLogScale pages to give some signposts to the tradeoffs between these two facilities.

I'll need to add a few more tests for the new tick-locator, and hope to have something ready for more formal review within the next few days.

Illustration of new tick-locator, which now supports arbitrary number bases as well as the "base-0" variant that tries to fit neatly rounded ticks at roughly uniform spacing.

The plots show base-2 on the left, "base-0" in the middle, and base-3 on the right.

I believe I've now addressed all the points raised in @greglucas 's most recent message:

• The default axis marker now shows powers of ten, and supports arbitrary number bases;
• The AsinhLocator will automatically select minor tick spacings for common number bases (e.g. 10->(2,5), 16->(2, 4, 8), etc.), as well as allowing user customization;
• Test coverage has been further improved;
• There are documentation cross-references between the examples/scales/asinh_demo.py and examples/scales/symlog_demo.py to make it easier for users to assess the tradeoffs between these two transformations;
• There is a new AsinhNorm colorscale, analogous to SymLogNorm;
• The SymLogNorm contour-plot demonstration has been reworked so that its synthetic dataset is more consistent with its description and now shows a comparison with the AsinhNorm colorscale.

An example of the colorscale plot in the revised examples/images_contours_and_fields/colormap_normalizations_symlognorm.py is show below:

As ever, I'd welcome others' thoughts on how we proceed from here.

This PR is affected by a re-writing of our history to remove a large number of accidentally committed files see discourse for details.

To recover this PR it will need be rebased onto the new default branch (main). There are several ways to accomplish this, but we recommend (assuming that you call the matplotlib/matplotlib remote "upstream"

git remote update
git checkout main
git merge --ff-only upstream/main
git checkout YOUR_BRANCH
git rebase --onto=main upstream/old_master
# git rebase -i main # if you prefer
git push --force-with-lease   # assuming you are tracking your branch

If you do not feel comfortable doing this or need any help please reach out to any of the Matplotlib developers. We can either help you with the process or do it for you.

Thank you for your contributions to Matplotlib and sorry for the inconvenience.

Thanks @greglucas for going through the code, and for your many helpful comments.

There are a few points that perhaps warrant a bit more discussion:

• I'll take a closer look at the tick-generation in interactive mode - I think I missed a get_view_interval() in my Locator.__call__(), which I'll patch-up.
• I've deliberately chosen the axis ranges in some of the demos to have asymmetric ranges simply to confirm that the tick-locators behave sensibly in these cases. Naturally, for asymmetric data extent, the ticks may not themselves be symmetrical around the origin, especially when the coordinate transformation is non-linear.
• For the 3**4 tick-formatting, again that was a deliberate choice in one of the demos - the default is to use powers of ten. Perhaps that demo could use powers of 2 and powers of 10 just to give a hint of the common use-cases?
• I absolutely share the reluctance to create a new tick-locator for each new axis scale, but I'm afraid I don't see any clean solution here. The SymmetricalLogLocator makes assumptions about the coordinate transform that simply aren't appropriate for the AsinhScale, and I'm struggling to see how even the SymmetricalLogLocator achieves much reuse of existing tick-locators. The way I've implemented the AsinhLocator could, possibly, provide an outline through which an arbitrary monotonic coordinate transformation could be used to produce roughly uniformly spaced ticks, but that doesn't seem easy to generalize within the current API provided by Locator and would certainly require much wider changes to other Locator subclasses. Creating three separate data regions that are handed differently by the Locator again seems to be taking us back to the artifacts associated with discontinuities between the different regions in symlog, and may well require a lot of fine-tuning to cope with different settings of linear_width.

@rwpenney, I apologize for letting this drop off my radar! I just came across issue #17402 that describes some ticking related issues with symlog and short ranges. I just tried out this PR and it looks like it suffers some of the same issues. I'm wondering what your thoughts would be about including some of the ideas from this comment into your locator?

Thanks, @greglucas for the link to issue #17402 - interesting to see that we haven't yet converged on an ideal solution to this problem. Also notable is that many of the example plots in that issue-report seem to very nicely emphasise the discontinuous gradients that were a big incentive to revisit the assumptions behind symlog.

I'll give the ideas in #17402 some more thought, and see what we might be able to merge into the arcsinh mechanisms.

The question of whether there is a much better, or even "correct", design for the tick-locator in these symlog-like scenarios seems rather intractable. We have a number of options at the moment, including SymmetricalLogLocator, the proposed AsinhLocator and the mechanisms of #17402, and I think all of these are trying to balance some mutually incompatible goals when we have a non-linear axis scale which inevitably has varying lengthscales across its extent:

• The location of powers of ten (or any other base) is obviously entirely fixed by the coordinate transformation - the only freedom we have is whether or not to mark that location in some way.
• The tick-marks are most necessary where the lengthscale of the coordinate transformation is changing rapidly (e.g. near the "linear" region of the arcsinh or the linear/logarithmic discontinuity of symlog)
• If a tick-mark is needed to help the viewer interpret the changing lengthscales, then there is no guarantee that the text label attached to that tick mark won't overlap nearby tick labels.

Although the way the current API separates the coordinate transformation from the tick-location from the tick marking is elegant, this seems to be at the expense of allowing us to have major tick locations marked on the axis without also having the accompanying textual label. What symlog and asinh transformation seem to be highlighting is that there are situations where that API is itself imposing constraints that affect the aesthetics of the axis labelling. Certainly, it's unlikely to be worth making drastic changes to the API to accommodate these non-homogeneous coordinate transformations, but I fear it does mean that we're unlikely to avoid some compromises with what we can achieve with our axis labelling.

So, overall, I think the AsinhLocator is about the best I can see how to achieve for the AsinhScale - its tick-marks are well-aligned to powers of the base; reasonably well-spaced across the visible range of the plot; sensibly placed if the axis range happens to be asymmetric around zero; and avoids abrupt discontinuities that aren't explicitly labelled within the SymmetricalLogLocator. I'm not sure I can see a way forward unless there's some fundamentally different, and mathematically self-consistent solution that's possible within the existing Transform/Locator APIs.

Thanks @rwpenney! Congratulations on your first PR to Matplotlib 🎉 We hope to hear from you again.