LumaxForge
ZH EN

Scatter Chart (Scatter)

This chapter explains the data field conventions for Scatter charts in EasyChart, especially the compatibility behavior of SeriesData.y/value, and how the z dimension drives sizeMapping.

1. Use cases

  • Correlation analysis (two numeric dimensions X/Y)
  • Distribution visualization (point cloud)
  • Outlier detection

2. Minimum viable setup (checklist)

  1. ChartProfile.coordinateSystem = Cartesian2D
  2. Axes

    3. - Common: X=Value, Y=Value

  3. Series

    4. - Add 1 Serie - Serie.type = Scatter - Serie.seriesData has at least 2 points

3. Inspector fields

  • series[i].type = Scatter
  • series[i].settings: actual type is ScatterSettings

    • - point: point style (visible/size/texture) - hover: hover highlight (enabled/pickRadius/scale, etc. depending on version) - sizeMapping: point size mapping

4. SeriesData field interpretation (runtime behavior)

Scatter chart uses:

  • X coordinate: SeriesData.x
  • Y coordinate: prefers SeriesData.y

    • - Compatibility: if y == 0 and value != 0, runtime uses value as y

  • Size mapping dimension: SeriesData.z (when sizeMapping.enabled=true)

So there are two common patterns:

4.1 Recommended (explicit X/Y)

  • x = X value
  • y = Y value

4.2 Compatibility (legacy data: use value as y)

  • x = X value
  • value = Y value
  • y = 0
Recommendation: for new data, write y directly to avoid mixing meanings with value.

5. Standard template: Value X + Value Y

  • X axis: AxisType = Value
  • Y axis: AxisType = Value
  • Data: use pattern 4.1 (x/y)

6. sizeMapping: actual behavior

When ScatterSettings.sizeMapping.enabled = true:

  • point radius is mapped from SeriesData.z
  • mapping range: minValue/maxValue -> minSize/maxSize
  • if clamp = true, t is clamped to 0..1
  • curve applies a curve transform to t (non-linear mapping)

If sizeMapping "doesn't work", check first:

  • did you actually set z values (default 0)
  • is minValue/maxValue equal (degenerates mapping)

7. Common pitfalls and troubleshooting

  • All points are on a horizontal line

    • - you may have filled only value, but also set y to a non-zero value (compatibility won't trigger) - recommend using y consistently as the Y coordinate

  • Hover does not respond

    • - ScatterSettings.hover.enabled must be enabled - too small pickRadius makes picking difficult

  • Points are too small / too large

    • - adjust ScatterSettings.point.size - or check minSize/maxSize in sizeMapping

8. Further reading

  • Axes/range, Series and data: 00_02-WorkflowAndLibrary.md
  • Common recipes: 04_08-CommonRecipes.md
  • FAQ: 04_09-FAQ.md