Skip to content

Support negative values for log Scale. #20872

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

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+359 −57
Open

Support negative values for log Scale. #20872

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f1829b8
Support negative values for log Scale.
Antti-Palola Mar 26, 2025
c4e4c52
Fix log scale prototype strangeness
Antti-Palola Mar 28, 2025
b6aeb01
Fix log scale tick generation
Antti-Palola Apr 25, 2025
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
210 changes: 159 additions & 51 deletions src/scale/Log.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,48 +27,66 @@ import IntervalScale from './Interval';
import SeriesData from '../data/SeriesData';
import { DimensionName, ScaleTick } from '../util/types';

const scaleProto = Scale.prototype;
// FIXME:TS refactor: not good to call it directly with `this`?
const intervalScaleProto = IntervalScale.prototype;

const roundingErrorFix = numberUtil.round;
Copy link
Member

Choose a reason for hiding this comment

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

class Log has been refactored in echarts v6.

Therefore, this PR has some conflicts with the current codebase.


Copy link
Member

@100pah 100pah Jul 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

From my understanding:

A new log scale method should enabled explicitly by a new option

e.g., yAxis.method: 'asinh' | 'symlog' | 'negative' (or some other option names like 'scaleMapping', 'mappingMethod', 'mapping', ...)

Log scale methods comparison

  • asinh / symlog / signed log1p
    • I think asinh / symlog / signed log1p might be a more thorough or meaningful solution for negative values. This is because an axis is commonly shared by multiple series, and a series might have both positive and negative values. symlog has been available in matplotlib for a long time, while asinh offers better mathemetical properties. (feat(chart): support negative values in logarithmic axes #16547 tried to introduce symlog). signed log1p (sign(x) * log(1 + |x|)) is a similar approach but not infinite differentiable in 0.
  • Math.log1p
    • Can also be an optional method, since it's frequently used in scenario like cumulative return factors. It was also mentioned in this comment.
  • negative log (proposed in this PR)
    • I think it can only serve for case that all data values of all series are negative (a axis scale serves multiple series). I'm not sure whether this kind of scenario occurs frequently or not.

Additionally, consider value 0

  • asinh / symlog / signed log1p / Math.log1p inherently handles it.
  • normal log / negative log requires zero values filtered (in "scale union from series"), if intending to address it. And in log1p case, value smaller than -1 is supposed to be filtered.

Some related test cases:

option = {
    yAxis: {type: 'log'},
    xAxis: {data: ['d1', 'd2', 'd3']},
    series: [{
        id: 'a',
        type: 'line',
        data: [123, 456, 789], // all positive, sharing one yAxis
    }, {
        id: 'b',
        type: 'line',
        data: [-0.111, -0.333, -20], // all negative, sharing one yAxis
    }, {
        id: 'c',
        type: 'line',
        data: [611, -12, 23], // contain positive and negative, sharing one yAxis
    }, {   
        id: 'd',
        type: 'line',
        data: [98, 0, -12], // contain zero, sharing one yAxis.
    }, {   
        id: 'e',
        type: 'bar',
        data: [67, 91, 23], // bar start value is 0 by default.
    }]
}

After this comparison, I'm afraid the "negative log" method proposed in this PR doesn't seem sufficiently necessary to be a built-in method in echarts. Correct me if I missed any cases that require this method and can not be covered by other methods above.

const mathFloor = Math.floor;
const mathCeil = Math.ceil;
const mathPow = Math.pow;

const mathLog = Math.log;

class LogScale extends Scale {
const mathMax = Math.max;
const mathRound = Math.round;

// LogScale does not have any specific settings
type LogScaleSetting = {};

/**
* LogScale is a scale that maps values to a logarithmic range.
*
* Support for negative values is implemented by inverting the extents and first handling values as absolute values.
* Then in tick generation, the tick values are multiplied by -1 back to the original values and the normalize function
* uses a reverse extent to get the correct negative values in plot with smaller values at the top of Y axis.
*/
class LogScale extends IntervalScale<LogScaleSetting> {
static type = 'log';
readonly type = 'log';

base = 10;

private _originalScale: IntervalScale = new IntervalScale();

/**
* Whether the original input values are negative.
*
* @type {boolean}
* @private
*/
private _isNegative: boolean = false;

private _fixMin: boolean;
private _fixMax: boolean;

// FIXME:TS actually used by `IntervalScale`
private _interval: number = 0;
// FIXME:TS actually used by `IntervalScale`
private _niceExtent: [number, number];


/**
* @param Whether expand the ticks to niced extent.
*/
getTicks(expandToNicedExtent?: boolean): ScaleTick[] {
const originalScale = this._originalScale;
const extent = this._extent;
const originalExtent = originalScale.getExtent();
const negativeMultiplier = this._isNegative ? -1 : 1;

const ticks = super.getTicks(expandToNicedExtent);


const ticks = intervalScaleProto.getTicks.call(this, expandToNicedExtent);
// Ticks are created using the nice extent, but that can cause the first and last tick to be well outside the extent
Copy link
Member

Choose a reason for hiding this comment

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

The span of nice extent is supposed to be greater than (or equals to) the extent calculated from series.data.
In many cases, and by convention, the max/min data value are not expected to be displayed on the edge of the Cartesian. (otherwise, if need that, use option like yAxis.min/max to change the behavior.
We should have both of the behavior provided.

if (ticks[0].value < this._extent[0]) {
ticks[0].value = this._extent[0];
}
if (ticks[ticks.length - 1].value > this._extent[1]) {
ticks[ticks.length - 1].value = this._extent[1];
}

return zrUtil.map(ticks, function (tick) {
const val = tick.value;
let powVal = numberUtil.round(mathPow(this.base, val));
let powVal = mathPow(this.base, val);

// Fix #4158
powVal = (val === extent[0] && this._fixMin)
Expand All @@ -79,27 +97,84 @@ class LogScale extends Scale {
: powVal;

return {
value: powVal
value: powVal * negativeMultiplier
};
}, this);
}

/**
* Get minor ticks for log scale. Ticks are generated based on a decade so that 5 splits
* between 1 and 10 would be 2, 4, 6, 8 and
* between 5 and 10 would be 6, 8.
* @param splitNumber Get minor ticks number.
* @returns Minor ticks.
*/
getMinorTicks(splitNumber: number): number[][] {
Copy link
Member

Choose a reason for hiding this comment

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

This new implementation introduces a breaking change to minor ticks in logarithmic axis.
Previously minor ticks is in log axis is based on the raw value (before log performed), like:
image

The effect in this PR is based on the value that log is performed:
image

I thinks both of approaches make some sense (though personally I think the previous one might be more meaningful to hint users the fact of logarithm).

Anyway,

  • If we introduce a new effect, the previous should be still preserved. An new option can be introduced to controlled this.
  • Consider the maintenance and code size, I think the new effect could reuse the minor tick logic in scale/Interval.ts, rather than implement in another way.

const ticks = this.getTicks(true);
const minorTicks = [];
const negativeMultiplier = this._isNegative ? -1 : 1;

for (let i = 1; i < ticks.length; i++) {
const nextTick = ticks[i];
const prevTick = ticks[i - 1];
const logNextTick = Math.ceil(scaleHelper.absMathLog(nextTick.value, this.base));
const logPrevTick = Math.round(scaleHelper.absMathLog(prevTick.value, this.base));

const minorTicksGroup: number[] = [];
const tickDiff = logNextTick - logPrevTick;
const overDecade = tickDiff > 1;

if (overDecade) {
// For spans over a decade, generate evenly spaced ticks in log space
// For example, between 1 and 100, generate a tick at 10
const step = Math.ceil(tickDiff / splitNumber);

let minorTickValue = Math.pow(this.base, logPrevTick + step);
let j = 1;
while (minorTickValue < nextTick.value) {
minorTicksGroup.push(minorTickValue);

j++;
minorTickValue = Math.pow(this.base, logPrevTick + j * step) * negativeMultiplier;
}
}
else {
// For spans within a decade, generate linear subdivisions
// For example, between 1 and 10 with splitNumber=5, generate ticks at 2, 4, 6, 8
const maxValue = Math.pow(this.base, logNextTick);

// Divide the space linearly between min and max
const step = maxValue / splitNumber;
let minorTickValue = step;
while (minorTickValue < nextTick.value) {
minorTicksGroup.push(minorTickValue * negativeMultiplier);
minorTickValue += step;
}
}

minorTicks.push(minorTicksGroup);
}

return minorTicks;
}

setExtent(start: number, end: number): void {
const base = mathLog(this.base);
// Assume the start and end can be infinity
// log(-Infinity) is NaN, so safe guard here
start = mathLog(Math.max(0, start)) / base;
end = mathLog(Math.max(0, end)) / base;
intervalScaleProto.setExtent.call(this, start, end);
if (start < Infinity) {
start = scaleHelper.absMathLog(start, this.base);
}
if (end > -Infinity) {
end = scaleHelper.absMathLog(end, this.base);
}

super.setExtent(start, end);
}

/**
* @return {number} end
*/
getExtent() {
const base = this.base;
const extent = scaleProto.getExtent.call(this);
extent[0] = mathPow(base, extent[0]);
extent[1] = mathPow(base, extent[1]);
getExtent(): [number, number] {
const extent = super.getExtent();
extent[0] = mathPow(this.base, extent[0]);
extent[1] = mathPow(this.base, extent[1]);

// Fix #4158
const originalScale = this._originalScale;
Expand All @@ -113,10 +188,19 @@ class LogScale extends Scale {
unionExtent(extent: [number, number]): void {
this._originalScale.unionExtent(extent);

const base = this.base;
extent[0] = mathLog(extent[0]) / mathLog(base);
extent[1] = mathLog(extent[1]) / mathLog(base);
scaleProto.unionExtent.call(this, extent);
if (extent[0] < 0 && extent[1] < 0) {
// If both extent are negative, switch to plotting negative values.
// If there are only some negative values, they will be plotted incorrectly as positive values.
this._isNegative = true;
}
Copy link
Member

Choose a reason for hiding this comment

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

A axis scale is commonly shared by multiple series.
unionExtent is called multiple times if there are multiple series using this axis (scale).
Even if there is only one "series", sometimes users might call chart.setOption multiple times with no data.
I'm worried that auto-detect _isNegative here is error-prone and might confuse users if any unexpected behavior occurs.

I think a "all negative log scale" is inherently not self-adaptable - it can be only used in the specific case where all data in series are negative. If we provide that feature, it should be explicitly declared in option - making users know that they're using that feature for that specific case.

See also the comment at the header of this code review.


const [logStart, logEnd] = this.getLogExtent(extent[0], extent[1]);

extent[0] = logStart;
extent[1] = logEnd;

extent[0] < this._extent[0] && (this._extent[0] = extent[0]);
extent[1] > this._extent[1] && (this._extent[1] = extent[1]);
}

unionExtentFromData(data: SeriesData, dim: DimensionName): void {
Expand All @@ -131,13 +215,18 @@ class LogScale extends Scale {
*/
calcNiceTicks(approxTickNum: number): void {
approxTickNum = approxTickNum || 10;
const extent = this._extent;
const span = extent[1] - extent[0];

const span = this._extent[1] - this._extent[0];

if (span === Infinity || span <= 0) {
return;
}

let interval = numberUtil.quantity(span);
let interval = mathMax(
1,
mathRound(span / approxTickNum)
);
Copy link
Member

Choose a reason for hiding this comment

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

The original implementation uses the 10-based value as interval, while this PR do not use that strategy.
The current effect in this PR:
image

I think if introducing other base (e.g., 2-based ticks), it is a separate topic, and should be applied uniformly rather than only in log scale, and controlled by some new options.

Moreover, this change seems to be inconsistent with the following process like err <= 0.5.


const err = approxTickNum / span * interval;

// Filter ticks to get closer to the desired count.
Expand All @@ -150,10 +239,10 @@ class LogScale extends Scale {
interval *= 10;
}

const niceExtent = [
numberUtil.round(mathCeil(extent[0] / interval) * interval),
numberUtil.round(mathFloor(extent[1] / interval) * interval)
] as [number, number];
const niceExtent: [number, number] = [
mathFloor(this._extent[0] / interval) * interval,
mathCeil(this._extent[1] / interval) * interval
];

this._interval = interval;
this._niceExtent = niceExtent;
Expand All @@ -166,7 +255,7 @@ class LogScale extends Scale {
minInterval?: number,
maxInterval?: number
}): void {
intervalScaleProto.calcNiceExtent.call(this, opt);
super.calcNiceExtent(opt);

this._fixMin = opt.fixMin;
this._fixMax = opt.fixMax;
Expand All @@ -177,28 +266,47 @@ class LogScale extends Scale {
}

contain(val: number): boolean {
val = mathLog(val) / mathLog(this.base);
val = scaleHelper.absMathLog(val, this.base);
return scaleHelper.contain(val, this._extent);
}

normalize(val: number): number {
val = mathLog(val) / mathLog(this.base);
return scaleHelper.normalize(val, this._extent);
normalize(inputVal: number): number {
const val = scaleHelper.absMathLog(inputVal, this.base);
let ex: [number, number] = [this._extent[0], this._extent[1]];

if (this._isNegative) {
// Invert the extent for normalize calculations as the extent is inverted for negative values.
ex = [this._extent[1], this._extent[0]];
}
return scaleHelper.normalize(val, ex);
}

scale(val: number): number {
val = scaleHelper.scale(val, this._extent);
return mathPow(this.base, val);
}

getMinorTicks: IntervalScale['getMinorTicks'];
getLabel: IntervalScale['getLabel'];
/**
* Get the extent of the log scale.
* @param start - The start value of the extent.
* @param end - The end value of the extent.
* @returns The extent of the log scale. The extent is reversed for negative values.
*/
getLogExtent(start: number, end: number): [number, number] {
// Invert the extent but use absolute values
if (this._isNegative) {
const logStart = scaleHelper.absMathLog(Math.abs(end), this.base);
const logEnd = scaleHelper.absMathLog(Math.abs(start), this.base);
return [logStart, logEnd];
}
else {
const logStart = scaleHelper.absMathLog(start, this.base);
const logEnd = scaleHelper.absMathLog(end, this.base);
return [logStart, logEnd];
}
}
}

const proto = LogScale.prototype;
proto.getMinorTicks = intervalScaleProto.getMinorTicks;
proto.getLabel = intervalScaleProto.getLabel;

function fixRoundingError(val: number, originalVal: number): number {
return roundingErrorFix(val, numberUtil.getPrecision(originalVal));
}
Expand Down
19 changes: 19 additions & 0 deletions src/scale/helper.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ type intervalScaleNiceTicksResult = {
niceTickExtent: [number, number]
};

const mathLog = Math.log;

export function isValueNice(val: number) {
const exp10 = Math.pow(10, quantityExponent(Math.abs(val)));
const f = Math.abs(val / exp10);
Expand Down Expand Up @@ -136,3 +138,20 @@ export function normalize(val: number, extent: [number, number]): number {
export function scale(val: number, extent: [number, number]): number {
return val * (extent[1] - extent[0]) + extent[0];
}

/**
* Calculates the absolute logarithm of a number with a specified base.
* Handles edge cases by:
* - Returning 0 for values very close to 0 (within Number.EPSILON)
* - Taking the absolute value of the input to handle negative numbers
*
* @param x - The number to calculate the logarithm of
* @param base - The base of the logarithm (defaults to 10)
* @returns The absolute logarithm value, or 0 if x is very close to 0
*/
export function absMathLog(x: number, base = 10): number {
if (Math.abs(x) < Number.EPSILON) {
Copy link
Member

Choose a reason for hiding this comment

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

I do not fully understand the choice of Number.EPSILON here yet.

  • Consider an input 1e-20, smaller than Number.EPSILON but can be represented in a 64-bit float number, and log10(1e-20) is -20 - a normal number. I think it's not reasonable enough to exclude them.
  • log(1) is 0; log(near_zero) is supposed to be a big negative number, but return 0 here. It may cause unexpected results in the subsequent calculation?

return 0;
}
return mathLog(Math.abs(x)) / mathLog(base);
}
Loading