Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

DOC: Explain parameters linthresh and linscale of symlog scale #29347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 21, 2024
Merged

DOC: Explain parameters linthresh and linscale of symlog scale #29347

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c818093
DOC: Explain parameters linthresh and linscale of symlog scale
timhoffm Dec 19, 2024
70382ad
Update galleries/examples/scales/symlog_demo.py
timhoffm Dec 20, 2024
6694a9c
Apply suggestions from code review
timhoffm Dec 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 82 additions & 7 deletions 89 galleries/examples/scales/symlog_demo.py
View file
Open in desktop
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 Down Expand 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

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
Member Author

@timhoffm timhoffm Dec 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..

#
#
# 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
Loading
Morty Proxy This is a proxified and sanitized view of the page, visit original site.