feat(axis): support dataMin and dataMax option for calculating a nice axis extent

[Justin-ZS]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

Add dataMin and dataMax properties for value axes to extend the axis range while preserving nice scale algorithm.

Fixed issues

• [Feature] able to customize the dataMax/dataMin of axis rather than fixed max/min #20770

Details

Before: What was the problem?

Currently, ECharts provides two ways to set axis range:

1. Let ECharts auto-calculate nice values by default
2. Use min/max to set fixed values, but this disables the nice scale algorithm

There was no way to ensure a specific data point would be included in the axis range while still benefiting from the nice scale algorithm.

After: How does it behave after the fixing?

With the new dataMin/dataMax properties, users can:

• Specify values that should be included in the axis range
• Only affect the range if the specified value extends beyond the actual data range
• Still benefit from ECharts' nice scale algorithm for rounding values

These properties are only effective for value axes (value, log, time) and have no effect on category axes.

Document Info

One of the following should be checked.

• This PR doesn't relate to document changes
• The document should be updated later
• The document changes have been made in doc(axis): add doc for dataMin/dataMax echarts-doc#483

Misc

ZRender Changes

• This PR depends on ZRender changes (ecomfe/zrender#xxx).

Related test cases or examples to use the new APIs

Test cases have been included in test/axis-data-min-max.html to verify different scenarios including:

• Basic usage with standard value axes
• Scenarios with negative values
• Usage with log axes
• Verification that they don't affect category axes

Others

Merging options

• Please squash the commits into a single one when merging.

Other information

[echarts-bot]

Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

Document changes are required in this PR. Please also make a PR to apache/echarts-doc for document changes and update the issue id in the PR description. When the doc PR is merged, the maintainers will remove the PR: awaiting doc label.

[Justin-ZS]

@Ovilia @100pah Could you help to review the PR? Thanks!

[sjcobb]

I’ve experienced this problem as a user so interested to see how this PR progresses, I will say the naming here is a bit confusing, especially since ECharts already supports a different concept as: min: 'dataMin' and max: ‘dataMax’

[Justin-ZS]

I’ve experienced this problem as a user so interested to see how this PR progresses, I will say the naming here is a bit confusing, especially since ECharts already supports a different concept as: min: 'dataMin' and max: ‘dataMax’

I intentionally use the terms dataMin/dataMax:

1. From a usage perspective, dataMin/dataMax should not be used simultaneously with min/max.
2. If a user does combine them, dataMin/dataMax will affect the result of min: 'dataMin' and max: ‘dataMax’.
   For example: if the original data range is [100, 300], setting { dataMax: 500, max: 'dataMax' } will fix the axis maximum to 500.
   Using the same terms here makes the it more intuitive.
3. I'm open to change the name if the maintainers have any recommendations

[Ovilia]

This seems a little unexpected to me. Have you tried with the callback of axis.min?

yAxis: {
  max: value => Math.max(value, 1000)
}

or simply

yAxis: {
  max: 'dataMax'
}

[Justin-ZS]

This seems a little unexpected to me. Have you tried with the callback of axis.min?

yAxis: {
  max: value => Math.max(value, 1000)
}

or simply

yAxis: {
  max: 'dataMax'
}

Neither approach works in this case.
As described in #20770, we need a simple way to set the axis max to a nice round value.
This feature is particularly valuable when comparing multiple similar charts that should share the same axis range.
With this feature, I can just set the dataMax to the max value of all charts, then all charts will have the same axis range.

[Ovilia]

@Justin-ZS Can you further explain in which case should I set max value to be some rounded value larger than my given value, instead of not setting max at all?

[Justin-ZS]

@Justin-ZS Can you further explain in which case should I set max value to be some rounded value larger than my given value, instead of not setting max at all?

When comparing multiple similar charts. (like sales data from different stores, one chart for one store)
When not setting the max, the axis max of chart 1 is 4000, and the axis max of chart 2 is 3000.
Setting "max" to all charts directly will make them ugly, as the max value could be 3744.55
With this new feature, all axis max will be 4000.

[Ovilia]

It should be helpful to provide a feature to nice the min/max value of the axis. Thanks for the help! However, I don't think this should be the default behavior, and this also has a compatibility problem.

For the current implementation, when dataMax is larger than the actual data max, a niced value that is no smaller than the dataMax is used; while when dataMax is smaller than the actual data max, it's not used at all. This behavior seems really confusing to me.

I would suggest using max: 'niceDataMax' instead of providing a new option, and the data max is calculated to be a nice number automatically without providing a value. Does this satisfy your requirement?

[Justin-ZS]

It should be helpful to provide a feature to nice the min/max value of the axis. Thanks for the help! However, I don't think this should be the default behavior, and this also has a compatibility problem.

For the current implementation, when dataMax is larger than the actual data max, a niced value that is no smaller than the dataMax is used; while when dataMax is smaller than the actual data max, it's not used at all. This behavior seems really confusing to me.

I would suggest using max: 'niceDataMax' instead of providing a new option, and the data max is calculated to be a nice number automatically without providing a value. Does this satisfy your requirement?

Regarding compatibility, there should be no issues.
The behavior remains unchanged when dataMin/dataMax are not set.

To solve the use case, we need both:

1. User-defined max value
2. Enable nice rounding or not

With max: 'niceDataMax' alone, we can't achieve both because:

• It only enable the nice rounding
• But can't let users specify a reference max value

[100pah]

@Ovilia @Justin-ZS

At first glance, I originally thought the newly introduced dataMin/dataMax were not intuitive and didn't align well with the existing props min/max. But after thinking though this logic, I now find the design and naming appropriate.

[Justin-ZS]

@Ovilia @100pah
PR has been updated accordingly.
Could you help to review again? Thanks!

[100pah]

LGTM

[Ovilia]

Thanks for your contribution!

Please make sure that we explained the logic clearly in the document and give some examples for the users to understand because this concept may not be intuitive to all users at the first glance.

[echarts-bot]

Congratulations! Your PR has been merged. Thanks for your contribution! 👍