Skip to content

feat: add symlog scale - #12386

Open
wmunoz1018 wants to merge 2 commits into
chartjs:masterfrom
wmunoz1018:feat/symlog-scale
Open

wmunoz1018 wants to merge 2 commits into
chartjs:masterfrom
wmunoz1018:feat/symlog-scale

Conversation

@wmunoz1018

Copy link
Copy Markdown

Title: feat: add symlog scale

Refs #11919

What this adds

A symlog (symmetric logarithmic) cartesian scale, type: 'symlog', for data that mixes zeros, negative and positive values across several orders of magnitude (counts with many zeros, or differences from a baseline). A value x is placed at sign(x) * ln(1 + |x| / linearThreshold): the axis is close to linear near zero and close to logarithmic further out, with no cutoff, and x and -x are mirrored around zero. linearThreshold (default 1) sets how wide the near-linear band is.

It behaves like the other cartesian scales: min, max, suggestedMin, suggestedMax, reverse, grace and bounds work the same way (percent grace is applied in the scale's log space, so it does not add orders of magnitude of empty axis below zero), it works as an x or y axis, ticks.callback and tooltips receive the real values, and it is exported (SymLogScale) and registered like the built-in scales.

Ticks are powers of ten on both sides of zero plus zero, with 2x/5x values when every decade on the axis has room, evenly spaced values inside the linear band and on narrow ranges, and short labels (-5K, 100M) that switch to plain numbers only when three significant digits cannot tell neighbouring ticks apart. Zero and the axis ends take priority over the powers of ten next to them; a power of ten next to an end is kept when its label fits.

Files

  • src/scales/scale.symlog.js (new), exported from src/scales/index.js
  • src/core/core.ticks.js: a symlog formatter; the existing formatters are unchanged
  • src/types/index.d.ts, src/types.ts, test/types/scales/symlog.ts
  • docs/axes/cartesian/symlog.md with its sidebar entry, plus one line each in docs/axes/cartesian/index.md and docs/getting-started/integration.md
  • test/specs/scale.symlog.tests.js and image fixtures in test/fixtures/scale.symlog/

No existing spec or fixture is changed; scale.linear.js, scale.linearbase.js and scale.logarithmic.js are untouched.

Checks

On Linux, Node 22, pnpm 8.13.0:

  • pnpm lint: lint-js 0 errors (the 49 existing warnings), lint-md 0 errors (the 3 existing warnings), lint-types passes
  • pnpm build passes
  • xvfb-run --auto-servernum pnpm test-ci-karma: Chrome 1838 of 1838; Firefox 135 of 135 for scale.symlog and 1837 of 1838 overall, the one failure being core.scale/label-offset-vertical-axes.json, which fails the same way on untouched master with Firefox 153 ESR
  • pnpm test-ci-integration passes
  • pnpm docs builds, with the new page at axes/cartesian/symlog.html

Known limits

  • Values with |x| around 1e16 and above on a mixed-sign axis: the distance helper loses precision and zero can land on a non-finite pixel. Not addressed here; happy to follow up if the scale is wanted.
  • ticks.includeBounds: true with an explicit bound very close to zero (for example min: -0.01): zero wins and the bound tick is dropped, unlike linear.
  • A very small linearThreshold (1e-300) produces long decimal labels; a value above about 1e-12 is fine.
  • Ranges narrower than 15 significant digits (around 1e15) get duplicate labels; positions are still right.

Notes for reviewers

  • The implementation was written with the help of an AI coding model and reviewed, tested and adjusted by me turn by turn.
  • Design choices I expect questions on: zero and the ends outrank the powers of ten next to them; 2x/5x fill-ins only when every decade has room; one label style per axis; the issue's log10 sketch became log1p with a configurable threshold so the band around zero is adjustable and the transform is exact near zero.

Adds a symmetric logarithmic (symlog) cartesian scale: values are placed at sign(x) * ln(1 + |x| / linearThreshold), so zero, negative and positive values all land on one axis, with a linearThreshold option (default 1) for the width of the near-linear band around zero. Includes the symlog tick formatter, types with a type test, a docs page with its sidebar entry, specs and image fixtures.

Refs chartjs#11919

@TARUNTEjjjj TARUNTEjjjj left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted review with independent browser validation on the current head. Details and scope are in the inline comment.

Comment thread src/scales/scale.symlog.js Outdated
return Math.log1p((a - b) / (c + b));
}
if (a <= 0 && b <= 0) {
return -Math.log1p((b - a) / (c - b));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same-sign delta formula can still lose precision when the values are far apart: for a = 0, b = -1e16, c = 1, (b - a) / (c - b) rounds to -1, so this returns Infinity instead of the finite transformed distance. A scatter chart with data [-1e16, -1, 0, 1, 1e16] and y: {type: 'symlog', min: -1e16, max: 1e16} places both 0 and -1 at pixel -32768; zero should be at the midpoint (201.8 in my 600×400 chart). The existing large-value checks only require finite pixels, which passes because the core clamps the infinite result. Please retain the close-value calculation but use a stable alternative when this ratio approaches -1, and assert zero's midpoint/monotonicity in the extreme-range tests. I reproduced this in Chrome Headless 157: the existing 135 symlog tests pass and an added midpoint regression fails. AI-assisted review and local validation with OpenAI Codex.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants