netscout-mthorn commented on PR #21646: URL: https://github.com/apache/echarts/pull/21646#issuecomment-4670997912
## Naming feedback requested: `logMapping` and `logLinearWidth` I introduced a new option `logLinearWidth` that controls the width of the quasi-linear region around zero for both `asinh` and `symlog` transforms. The name is my best candidate, but I am open to alternatives and would welcome maintainer input. ### What it does For `logMapping: 'asinh'`, the transform is `f(x) = asinh(x / a0) * a0`. For `logMapping: 'symlog'`, the transform is `f(x) = sign(x) * ln(1 + |x| / C)`. In both cases, `logLinearWidth` supplies `a0` / `C`: the scale of the region near zero where the axis behaves approximately linearly. The default is `1`, matching d3 `scaleSymlog` and matplotlib `AsinhScale`. ### Precedent in reference implementations | Library | Transform | Parameter name | Default | |---------|-----------|---------------|--------| | matplotlib | `AsinhScale` | `linear_width` | `1.0` | | matplotlib | `SymmetricalLogScale` | `linthresh` | `2` | | d3-scale | `scaleSymlog` | `constant` | `1` (exposed via `.constant(c)` chainable method) | | ECharts (proposed) | both | `logLinearWidth` | `1` | matplotlib uses different parameter names for the two transforms ([`linear_width`](https://github.com/matplotlib/matplotlib/blob/v3.10.9/lib/matplotlib/scale.py#L479) vs [`linthresh`](https://github.com/matplotlib/matplotlib/blob/v3.10.9/lib/matplotlib/scale.py#L366)), reflecting the different mathematical character of each: - `linear_width` (asinh): a continuous scale parameter with no hard boundary - `linthresh` (symlog): a hard threshold at which the piecewise formula transitions I chose a single unified name `logLinearWidth` because: 1. ECharts exposes a single `logMapping` option for both transforms, so a single companion parameter is consistent. 2. `logLinearWidth` is descriptive for both: it is the width (scale) of the linear region in both cases. 3. It follows the `logBase` naming convention already in ECharts. ### Alternatives considered | Name | Notes | |------|-------| | `logLinearWidth` | **Chosen.** Descriptive, consistent with `logBase` naming. | | `logLinthresh` | Borrows from matplotlib symlog naming; less accurate for asinh (no hard threshold). | | `logThreshold` | Accurate for symlog; misleading for asinh (no threshold). | | `logLinearScale` | Could be confused with "linear scale" as a transform type. | | `logLinearRange` | Reasonable; slightly less precise than "width". | | `logC` | Matches d3's internal naming but opaque without context. | ### Naming convention research I surveyed existing ECharts mode-selection options before choosing `logMapping` and `logLinearWidth`: - `sampling: 'none' | 'average' | 'min' | 'max' | ...` enables an alternative data-reduction method; `'none'` is the explicit default. - `graph.layout: 'none' | 'force' | 'circular'` selects a graph layout algorithm. - `smooth: boolean | number`, `boundaryGap: boolean | [string, string]` are mixed union types with non-string sentinels. `logMapping` follows the `sampling`/`layout` pattern directly: a string union with `'none'` as the explicit default, each value naming an alternative mode. I considered `scaleMapping`, `mappingMethod`, and `mapping` (all suggested by reviewer `100pah` in #20872) but prefer `logMapping` for consistency with the existing `logBase` option name. ### Question for reviewers Is `logLinearWidth` acceptable? Is there a naming convention in ECharts that I should follow instead? I am also open to separate parameter names for `asinh` and `symlog` if the maintainers prefer consistency with matplotlib (e.g. `logLinthresh` for symlog and `logLinearWidth` for asinh), though a single unified parameter seems simpler. Also: is `logMapping` the preferred option name, or would one of the names suggested in #20872 (`scaleMapping`, `mappingMethod`, `mapping`) be preferred? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
