Scatter Series
The scatter method adds a scatter series, which is a plot of individual, disconnected data points. Scatter plots are ideal for examining distributions, correlations, and clusters in data.
Method Overloads
Below are the different available overloads for adding scatter data to a Figure object.
| Signature | Description |
|---|---|
scatter(x, y [, options]) | Pass a list of x and y data and optionally options. |
scatter(points [, options]) | Pass a list of points [[x[0],y[0]],[x[1],y[1]], ...] |
scatter(options) | Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes. |
Quick examples
Figure()
.scatter([1, 2, 3, 4, 5], [2, 4, 6, 8, 10])
.scatter([7,8,9,10,11], [2, 4, 6, 8, 10], ["color_by": "data"])
.scatter([[13,8],[14,8]])
.scatter([[16,8],[17,8]], ["color_by": "data"])
.scatter(["data": [[19,8],[20,8]]])
.save("./figures/ex_scatter_basic")
General Methods
Below are the different available methods for formatting general properties of the current data series.
| Option | Type | Description |
|---|---|---|
name | string | Series name shown in legend and tooltip. |
color_by | string | Color mapping: 'series' (different color for each) or 'data' (different color for each data element). |
clip | boolean | Clip series that overflows the coordinate area. |
Quick examples
Figure()
.scatter([1, 2, 3, 4, 5], [5, 3, 8, 2, 7], [
"name": "Color by data",
"color_by": "data",
"clip": true
])
.scatter([7, 8, 9, 10, 11], [4, 6, 2, 9, 5], [
"name": "Color by series",
"color_by": "series"
])
.legend()
.save("./figures/ex_scatter_general")
Symbol Options
| Option | Type | Description |
|---|---|---|
symbol | string | Symbol shape: "circle", "rect", "roundRect", "triangle", "diamond", "pin", "arrow", "none", or a "path://..." SVG path. |
symbol_size | number or List | Symbol diameter (or [width, height]). |
symbol_rotate | number | Symbol rotation in degrees. |
symbol_offset | List | [x, y] offset from the data point. |
show_symbol | boolean | Whether to display symbols on the line. |
show_all_symbol | boolean or string | Force showing all symbols even on dense category axes. |
Quick examples
Figure()
.scatter([1, 2, 3, 4, 5], [5, 3, 8, 2, 7], [
"name": "Circle",
"symbol": "circle",
"symbol_size": 12
])
.scatter([7, 8, 9, 10, 11], [4, 6, 2, 9, 5], [
"name": "Diamond Rotated",
"symbol": "diamond",
"symbol_size": 12,
"symbol_rotate": 45,
"symbol_offset": [0, -3]
])
.scatter([13, 14, 15, 16, 17], [6, 4, 7, 3, 8], [
"name": "Rect Sized",
"symbol": "rect",
"symbol_size": [10, 15]
])
.scatter([19, 20, 21, 22, 23], [5, 7, 3, 8, 4], [
"name": "Triangle",
"symbol": "triangle",
"symbol_size": 12
])
.scatter([25, 26, 27, 28, 29], [6, 2, 8, 4, 7], [
"name": "Pin",
"symbol": "pin",
"symbol_size": 12
])
.legend()
.save("./figures/ex_scatter_symbol_options")
item_style(options)
Controls the visual style of the symbol markers.
| Option | Type | Description |
|---|---|---|
color | Color | Sets the fill color of the symbol. |
border_color | Color | Sets the stroke color of the symbol’s border. |
border_width | number | Defines the width of the symbol’s border in pixels. |
border_type | string or List | Defines the border style. Can be 'solid', 'dashed', 'dotted', or a custom dash pattern array such as [5, 10]. |
opacity | number | Sets the transparency of the symbol, where 0 is fully transparent and 1 is fully opaque. |
shadow_blur | number | Controls the blur radius of the symbol’s shadow. Higher values create a softer shadow. |
shadow_color | Color | Sets the color of the symbol’s shadow. |
Quick examples
Figure()
.scatter([1, 2, 3, 4, 5], [1, 4, 9, 16, 25], [
"name": "Solid Border",
"show_symbol": true,
"symbol": "circle",
"symbol_size": 8,
"color": "#91CC75",
"item_style": [
"color": "#91CC75",
"border_color": "#2E5C3E",
"border_width": 2,
"opacity": 1.0
]
])
.scatter([7, 8, 9, 10, 11], [2, 5, 10, 17, 26], [
"name": "With Shadow",
"show_symbol": true,
"symbol": "rect",
"symbol_size": 8,
"color": "#5470C6",
"item_style": [
"color": "#5470C6",
"border_color": "#1E3A8A",
"border_width": 1,
"opacity": 0.9,
"shadow_blur": 4,
"shadow_color": "rgba(238, 7, 7, 0.97)"
]
])
.scatter([13, 14, 15, 16, 17], [3, 6, 11, 18, 27], [
"name": "Dashed Border",
"show_symbol": true,
"symbol": "diamond",
"symbol_size": 30,
"color": "#FF6B6B",
"item_style": [
"color": "#FF6B6B",
"border_color": "#DC2626",
"border_width": 2,
"border_type": "dashed",
"opacity": 0.8
]
])
.legend()
.save("./figures/ex_scatter_item_style")
label(options)
Labels rendered at each data point.
| Option | Type | Description |
|---|---|---|
show | boolean | Controls whether labels are displayed for the series. |
position | string or List | Sets the label position. Can be a preset such as 'top', 'bottom', 'left', 'right', 'inside', etc., or an explicit coordinate offset like [x, y]. |
distance | number | Defines the distance in pixels between the label and its associated symbol or data point. |
rotate | number | Sets the rotation angle of the label text in degrees. Positive values rotate clockwise. |
color | Color | Sets the text color of the label. Accepts any valid ECharts color value. |
font_size | number | Defines the font size of the label text in pixels. |
font_weight | string or number | Sets the font weight of the label text (e.g. 'normal', 'bold', or numeric values such as 400, 700). |
font_family | string | Sets the font family used for the label text. |
Quick examples
Figure()
.scatter([1, 2, 3, 4, 5], [1, 4, 9, 16, 25], [
"name": "Top Position",
"show_symbol": true,
"color": "#3f3dc2",
"label": [
"show": true,
"position": "top",
"distance": 5,
"rotate": 0,
"color": "#120ef1",
"font_size": 12,
"font_weight": "bold"
]
])
.scatter([7, 8, 9, 10, 11], [2, 5, 10, 17, 26], [
"name": "Rotate",
"show_symbol": true,
"color": "#a90d0d",
"label": [
"show": true,
"distance": 8,
"rotate": 45,
"color": "#FF6B6B",
"font_size": 10,
"font_weight": "normal",
"font_family": "monospace"
]
])
.scatter([13, 14, 15, 16, 17], [3, 6, 11, 18, 27], [
"name": "Right Position",
"show_symbol": true,
"color": "#07540b",
"label": [
"show": true,
"position": "right",
"distance": 8,
"color": "#0eee19",
"font_size": 11,
"font_weight": "bold"
]
])
.legend()
.save("./figures/ex_scatter_label")
label_line(options)
Guide line connecting a label to its point.
| Option | Type | Description |
|---|---|---|
show | boolean | Show the label guide line. |
show_above | boolean | Draw the line above the element. |
smooth | boolean or number | Smooth the guide line. |
line_style | Map | Sub-style for the guide line (same keys as line_style). |
Figure()
.scatter([1, 2, 3, 4, 5], [5, 3, 8, 2, 7], [
"name": "Straight Line",
"symbol_size": 10,
"label": [
"show": true,
"position": "top",
"distance": 15
],
"label_line": [
"show": true,
"smooth": false
]
])
.scatter([7, 8, 9, 10, 11], [4, 6, 2, 9, 5], [
"name": "Smooth Line",
"symbol_size": 10,
"label": [
"show": true,
"position": "top",
"distance": 15
],
"label_line": [
"show": true,
"smooth": true
]
])
.legend()
.save("./figures/ex_scatter_label_line")