Jupyter Scatter

Appearance

API Reference ​

Scatter ​

Scatter(x, y, data=None, **kwargs) ​

Arguments:

  • x is either an array-like list of coordinates or a string referencing a column in data.
  • y is either an array-like list of coordinates or a string referencing a column in data.
  • data is a Pandas DataFrame. [optional]
  • kwargs is a dictionary of additional properties. [optional]

Returns: a new scatter instance.

Examples:

python
from jscatter import Scatter
scatter = Scatter(x='speed', y='weight', data=cars)
scatter.show()

Methods ​

scatter.x(x=Undefined, scale=Undefined, **kwargs) ​

Get or set the x coordinate.

Arguments:

  • x is either an array-like list of coordinates or a string referencing a column in data.
  • scale is either a string (linear, log, pow), a tuple defining the value range that's map to the extent of the scatter plot, or an instance of matplotlib.colors.LogNorm or matplotlib.colors.PowerNorm.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the x coordinate when x is Undefined or self.

Examples:

python
scatter.x('price') # Triggers and animated transition of the x coordinates

scatter.y(y=Undefined, scale=Undefined, **kwargs) ​

Get or set the y coordinate.

Arguments:

  • y is either an array-like list of coordinates or a string referencing a column in data.
  • scale is either a string (linear, log, pow), a tuple defining the value range that's map to the extent of the scatter plot, or an instance of matplotlib.colors.LogNorm or matplotlib.colors.PowerNorm.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the y coordinate when y is Undefined or self.

Examples:

python
scatter.y('price') # Triggers and animated transition of the y coordinates

scatter.xy(x=Undefined, y=Undefined, x_scale=Undefined, y_scale=Undefined, **kwargs) ​

Get or set the x and y coordinate. This is just a convenience function to animate a change in the x and y coordinate at the same time.

Arguments:

  • x is either an array-like list of coordinates or a string referencing a column in data.
  • y is either an array-like list of coordinates or a string referencing a column in data.
  • x_scale is either a string (linear, time, log, pow), a tuple defining the value range that's map to the extent of the scatter plot, or an instance of matplotlib.colors.LogNorm or matplotlib.colors.PowerNorm.
  • y_scale is either a string (linear, time, log, pow), a tuple defining the value range that's map to the extent of the scatter plot, or an instance of matplotlib.colors.LogNorm or matplotlib.colors.PowerNorm.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the x and y coordinate when x and y are Undefined or self.

Examples:

python
scatter.xy('size', 'speed') # Mirror plot along the diagonal

scatter.data(data=Undefined, use_index=Undefined, reset_scales=False, zoom_view=False, animate=False, **kwargs) ​

Get or set the referenced Pandas DataFrame.

Arguments:

  • data is a Pandas DataFrame.
  • use_index is a Boolean value indicating if the data frame's index should be used for referencing point by the selection() and filter() methods instead of the row index.
  • reset_scales is a Boolean value indicating whether all scales (and norms) will be reset to the extend of the the new data.
  • zoom_view is a Boolean value indicating if the view will zoom to the data extent.
  • animate is a Boolean value indicating if the points will transition smoothly. However, animated point transitions are only supported if the number of points remain the same, and if reset_scales is False. If zoom_view is True, the view will also transition smoothly.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the data and use_index if no argument was passed to the method or self.

Examples:

python
scatter.data(df)

scatter.selection(point_idxs=Undefined) ​

Get or set the selected points.

Arguments:

  • point_idxs is either an array-like list of point indices.

Returns: either the currently selected point indices when point_idxs is Undefined or self.

Examples:

python
# Select all points corresponding to cars with a speed of less than 50
scatter.selection(cars.query('speed < 50').index)

# To unset the selection
scatter.selection(None) # or scatter.selection([])

# Retrieve the point indices of the currently selected points
scatter.selection()
# => array([0, 42, 1337], dtype=uint32)

scatter.filter(point_idxs=Undefined) ​

Get or set the filtered points. When filtering down to a set of points, all other points will be hidden from the view.

Arguments:

  • point_idxs is a list or an array-like object of point indices or None.

Returns: either the currently filtered point indices when point_idxs is Undefined or self.

Examples:

python
scatter.filter(cars.query('speed < 50').index)
scatter.filter(None) # To unset filter

scatter.color(default=Undefined, selected=Undefined, hover=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point color.

Arguments:

  • default is a valid matplotlib color.
  • selected is a valid matplotlib color.
  • hover is a valid matplotlib color.
  • by is either an array-like list of values or a string referencing a column in data.
  • map is either a string referencing a matplotlib color map, a matplotlib color map object, a list of matplotlib-compatible colors, a dictionary of category-color pairs, or auto (to let jscatter choose a default color map).
  • norm is either a tuple defining a value range that's map to [0, 1] with matplotlib.colors.Normalize or a matplotlib normalizer.
  • order is either a list of values (for categorical coloring) or reverse to reverse a color map.
  • labeling is either a tuple of three strings specyfing a label for the minimum value, maximum value, and variable that the color encodes or a dictionary of the form {'minValue': 'label', 'maxValue': 'label', 'variable': 'label'}. The specified labels are only used for continuous color encoding and are displayed together with the legend.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the x and y coordinate when x and y are Undefined or self.

Examples:

python
# Assuming `country` is of type `category` with less than nine categories, then
# the default color map will be Okabe Ito. Otherwise is it Glasbey. When the
# data type is not `category` then `viridis` is the default color map.
scatter.color(by='country')

# You can of course override the color map as follows.
scatter.color(
  by='country',
  map=dict(
    usa='red',
    europe='green',
    asia='blue'
  ),
)

# Assuming `gpd` is a continue float/int, we can also reference Matplotlib colormaps by their name
scatter.color(by='gpd', map='viridis')

scatter.opacity(default=Undefined, unselected=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point opacity.

Arguments:

  • default is a valid matplotlib color.
  • unselected is the factor by which the opacity of unselected points is scaled. It must be in [0, 1] and is only applied if one or more points are selected.
  • by is either an array-like list of values, a string referencing a column in data, or density
  • map is either a triple specifying an np.linspace(*map), a list of opacities, a dictionary of category-opacity pairs, or auto (to let jscatter choose a default opacity map).
  • norm is either a tuple defining a value range that's map to [0, 1] with matplotlib.colors.Normalize or a matplotlib normalizer.
  • order is either a list of values (for categorical opacity encoding) or reverse to reverse the opacity map.
  • labeling is either a tuple of three strings specyfing a label for the minimum value, maximum value, and variable that the opacity encodes or a dictionary of the form {'minValue': 'label', 'maxValue': 'label', 'variable': 'label'}. The specified labels are only used for continuous opacity encoding and are displayed together with the legend.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the x and y coordinate when x and y are Undefined or self.

Examples:

python
# Data-driven opacity encoding
scatter.opacity(by='price', map=(1, 0.25, 10))

# View-driven opacity encoding: the opacity is determined dynamically depending
# on the number and size of points in the view.
scatter.opacity(by='density')

scatter.size(default=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point size.

Arguments:

  • default is a valid matplotlib color.
  • by is either an array-like list of values or a string referencing a column in data.
  • map is either a triple specifying an np.linspace(*map), a list of sizes, a dictionary of category-size pairs, or auto (to let jscatter choose a default size map).
  • norm is either a tuple defining a value range that's map to [0, 1] with matplotlib.colors.Normalize or a matplotlib normalizer.
  • order is either a list of values (for categorical size encoding) or reverse to reverse the size map.
  • labeling is either a tuple of three strings specyfing a label for the minimum value, maximum value, and variable that the size encodes or a dictionary of the form {'minValue': 'label', 'maxValue': 'label', 'variable': 'label'}. The specified labels are only used for continuous size encoding and are displayed together with the legend.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the x and y coordinate when x and y are Undefined or self.

Examples:

python
scatter.size(by='price', map=(1, 0.25, 10))

scatter.connect(by=Undefined, order=Undefined, **kwargs) ​

Get or set the point connection.

Description: The by argument defines which points are part of a line segment. Points with the same value are considered to be part of a line segment. By default, points are connected in the order in which they appear the dataframe. You can customize that ordering via order.

Arguments:

  • by is either an array-like list of integers or a string referencing a column in the dataframe.
  • order is either an array-like list of integers or a string referencing a column in the dataframe.
  • kwargs:
    • skip_widget_update allows to skip the dynamic widget update when True. This can be useful when you want to animate the transition of multiple properties at once instead of animating one after the other.

Returns: either the connect properties when by and order are Undefined or self.

Examples:

Dataframe:

xygrouporder
00.130.27A2
10.870.93A1
20.100.25B2
30.030.90A3
40.190.78B1
python
# The following call will result in two lines, connecting the points:
# - 0, 1, and 3
# - 2 and 4
scatter.connect(by='group')
# Note that the points will be connected by a line in the order in which they
# appear in the dataframe.

# To customize the order use the `order` column:
scatter.connect(by='group', order='order')
# This results in the following two lines:
# - [1]--[0]--[3]
# - [4]--[2]

scatter.connection_color(default=Undefined, selected=Undefined, hover=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point connection color. This function behaves identical to [scatter.color()][#scatter.color].

scatter.connection_opacity(default=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point connection opacity. This function behaves identical to [scatter.opacity()][#scatter.opacity].

scatter.connection_size(default=Undefined, by=Undefined, map=Undefined, norm=Undefined, order=Undefined, labeling=Undefined, **kwargs) ​

Get or set the point connection size. This function behaves identical to [scatter.size()]#[scatter.size].

scatter.axes(axes=Undefined, grid=Undefined, labels=Undefined) ​

Get or set the x and y axes.

Arguments:

  • axes is a Boolean value to specify if the x and y axes should be shown or not.
  • grid is a Boolean value to specify if an axes-based grid should be shown or not.
  • labels is a Boolean value, a list of strings, or a dictionary with two keys (x and y) that specify the axes labels. When set to True the labels are the x and y column name of data.

Returns: either the axes properties when all arguments are Undefined or self.

Example:

python
scatter = Scatter(data=df, x='speed', y='weight')
scatter.axes(axes=True, labels=['Speed (km/h)', 'Weight (tons)'])

scatter.legend(legend=Undefined, position=Undefined, size=Undefined) ​

Set or get the legend settings.

Arguments:

  • legend is a Boolean specifying if the legend should be shown or not.
  • position is a string specifying the legend position. It must be one of top, left, right, bottom, top-left, top-right, bottom-left, bottom-right, or center.
  • size is a string specifying the size of the legend. It must be one of small, medium, or large.

Returns: either the legend properties when all arguments are Undefined or self.

Example:

python
scatter.legend(True, 'top-right', 'small')

scatter.annotations(annotations=Undefined) ​

Set or get annotations.

Arguments:

  • annotations is a list of annotations (Line, HLine, VLine, Rect, or Contour)

Returns: either the annotation properties when all arguments are Undefined or self.

Example:

python
from jscatter import HLine, VLine
scatter.annotations([HLine(42), VLine(42)])

scatter.tooltip(enable=Undefined, properties=Undefined, histograms=Undefined, histograms_bins=Undefined, histograms_ranges=Undefined, histograms_size=Undefined, preview=Undefined, preview_type=Undefined, preview_text_lines=Undefined, preview_image_background_color=Undefined, preview_image_position=Undefined, preview_image_size=Undefined, preview_audio_length=Undefined, preview_audio_loop=Undefined, preview_audio_controls=Undefined, size=Undefined) ​

Set or get the tooltip settings.

Arguments:

  • enable is a Boolean specifying if the tooltip should be enabled or disabled.

  • properties is a list of string specifying for which visual or data properties to show in the tooltip. The visual properties can be some of x, y, color, opacity, and size. Note that visual properties are only shown if they are actually used to data properties. To reference other data properties, specify a column of the bound DataFrame by its name.

  • histograms is a Boolean specifying if the tooltip should show histograms of the properties

  • histograms_bins is either an Integer specifying the number of bins of all numerical histograms or a dictionary of property-specific number of bins. The default is 20.

  • histograms_ranges is either a tuple of the lower and upper range of all bins or a dictionary of property-specific lower upper bin ranges. The default is (min(), max()).

  • histograms_size is a string specifying the size of the histograms. It must be one of small, medium, or large. The default is "small".

  • preview is a string referencing a column name of the bound DataFrame that contains preview data. Currently three data types are supported: plain text, URLs referencing images, and URLs referencing audio.

  • preview_type is a string specifying the media type of the preview. This can be one of "text", "image", or "audio". The default is "text".

  • preview_text_lines is an integer specifying the maximum number of lines for text previews that should be displayed. Text that exceeds defined limit will be truncated with an ellipsis. By default, the line limit is set to None to be disabled.

  • preview_image_background_color is a string specifying the background color for image previews. By default, the value is None, which means that image preview has a transparent background. In this case and if preview_image_size is set to "contain" and your image does not perfectly cover the preview area, you will see the tooltip's background color.

  • preview_image_position is a string specifying the image position of image previews. This can be one of "top", "bottom", "left", "right", or "center". The default value is "center".

    See https://developer.mozilla.org/en-US/docs/Web/CSS/background-position for details on the behavior.

  • preview_image_size is a string specifying the size of the image in the context of the preview area. This can be one of "cover" or "contain" and is set to "contain" by default.

    See https://developer.mozilla.org/en-US/docs/Web/CSS/background-size for details on the behavior.

  • preview_audio_length is an integer specifying the number of seconds of an audio preview that should be played. By default (None), the audio file is played from the start to the end.

  • preview_audio_loop is a Boolean specifying if the audio preview is indefinitely looped for the duration the tooltip is shown.

    See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#loop for details on the behavior.

  • preview_audio_controls is a Boolean specifying if the audio preview will include controls. While you cannot interact with the controls (as the tooltip disappears upon leaving a point), the controls show the progression and length of the played audio.

    See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#controls for details on the behavior.

  • size is a string specifying the size of the tooltip. It must be one of small, medium, or large. The default is "small".

Returns: either the legend properties when all arguments are Undefined or self.

Example:

python
scatter.tooltip(
  enable=True,
  properties=["color", "opacity", "effect_size"],
  histograms=True,
  histograms_bins=12,
  histograms_ranges={"effect_size": (0.5, 1.5)},
  histograms_width="medium",
  preview="image_url",
  preview_type="image",
  preview_image_background_color="black",
  preview_image_position="center",
  preview_image_size="cover",
  size="small",
)

scatter.show_tooltip(point_idx) ​

Programmatically show a tooltip for a point.

INFO

The tooltip is not permanent and will go away as soon as you mouse over some other points in the plot.

WARNING

If the widget has not been instantiated yet or the tooltip has not been activated via scatter.tooltip(True), this method is a noop.

Arguments:

  • point_idx is a point index.

Example:

python
scatter.show_tooltip(42)

scatter.zoom(to=Undefined, animation=Undefined, padding=Undefined, on_selection=Undefined, on_filter=Undefined) ​

Zoom to a set of points.

Arguments:

  • to is a list of point indices or None. When set to None the camera zoom is reset.
  • animation defines whether to animate the transition to the new zoom state. This value can either be a Boolean or an Integer specifying the duration of the animation in milliseconds.
  • padding is the relative padding around the bounding box of the target points. E.g., 0 stands for no padding and 1 stands for a padding that is as wide and tall as the width and height of the points' bounding box.
  • on_selection if True jscatter will automatically zoom to selected points.
  • on_filter if True jscatter will automatically zoom to filtered points.

Returns: either the current zoom state (when all arguments are Undefined) or self.

Example:

python
scatter.zoom([0, 1, 2, 3])
scatter.zoom(None)
scatter.zoom(scatter.selection())
scatter.zoom(to=scatter.selection(), animation=2000, padding=0.1)

scatter.camera(target=Undefined, distance=Undefined, rotation=Undefined, view=Undefined) ​

Get or set the camera view.

Arguments:

  • target is a float tuple defining the view center.
  • distance is a float value defining the distance of the camera from the scatter plot (imagine as a 2D plane in a 3D world).
  • rotation is a float value defining the rotation in radians.
  • view is an array-like list of 16 floats defining a view matrix.

Returns: either the camera properties when all arguments are Undefined or self.

Example:

python
scatter.camera(target=[0.5, 0.5])

scatter.mouse(mode=Undefined) ​

Get or set the mouse mode.

Arguments:

  • mode is either 'panZoom', 'lasso', or 'rotate'

Returns: either the mouse mode when mode is Undefined or self.

Example:

python
scatter.mouse(mode='lasso')

scatter.lasso(color=Undefined, initiator=Undefined, min_delay=Undefined, min_dist=Undefined, on_long_press=Undefined) ​

Get or set the lasso for selecting multiple points.

Arguments:

  • color is a string referring to a Matplotlib-compatible color.
  • initiator is a Boolean value to specify if the click-based lasso initiator should be enabled or not.
  • min_delay is an integer specifying the minimal delay in milliseconds before a new lasso point is stored. Higher values will result in more coarse grain lasso polygons but might be more performant.
  • min_dist is an integer specifying the minimal distance in pixels that the mouse has to move before a new lasso point is stored. Higher values will result in more coarse grain lasso polygons but might be more performant.
  • on_long_press is a Boolean value specifying if the lasso should be activated upon a long press.

Returns: either the lasso properties when all arguments are Undefined or self.

Example:

python
scatter.lasso(initiator=True)

scatter.reticle(show=Undefined, color=Undefined) ​

Get or set the reticle for the point hover interaction.

Arguments:

  • show is a Boolean value to display the reticle when set to True.
  • color is either a string referring to a Matplotlib-compatible color or 'auto'.

Returns: either the reticle properties when all arguments are Undefined or self.

Example:

python
scatter.reticle(show=True, color="red")

scatter.background(color=Undefined, image=Undefined) ​

Get or set a background color or image.

Arguments:

  • color is a string representing a color compatible with Matplotlib
  • image is either a URL string pointing to an image or a PIL image understood by Matplotlib's imshow() method

Returns: either the background properties when all arguments are Undefined or self.

Example:

python
scatter.background(color='black')
scatter.background(color='#000000')
scatter.background(image='https://picsum.photos/640/640?random')

scatter.options(transition_points=Undefined, transition_points_duration=Undefined, regl_scatterplot_options=Undefined) ​

Get or set other Jupyter Scatter and regl-scatterplot options.

Arguments:

  • transition_points is a Boolean value to enable or disable the potential animated transitioning of points as their coordinates update. If False, points will never be animated.
  • transition_points_duration is an Integer value determining the time of the animated point transition in milliseconds. The default value is 3000.
  • regl_scatterplot_options is a dictionary of regl-scatterplot properties.

Returns: either the options when options are Undefined or self.

scatter.pixels() ​

Gets the pixels of the current scatter plot view. Make sure to first download the pixels first by clicking on the button with the camera icon.

Returns: a Numpy array with the pixels in RGBA format.

Properties ​

The following is a list of all settable properties of a Scatter instance. You can define those property when creating a Scatter instance. For example, Scatter(data=df, x='speed', x_scale='log', ...).

NameTypeDefault
datapandas.DataFrameNone
xstr | list[float] | ndarrayNone
x_scale'linear' | 'log' | 'pow' | tuple[float] | LogNorm | PowerNormlinear
ystr | list[float] | ndarrayNone
y_scale'linear' | 'log' | 'pow' | tuple[float] | LogNorm | PowerNormlinear
selectionlist[int][]
widthint | 'auto''auto'
heightint240
colorstr | tuple[float] | list[float](0, 0, 0, 0.66)
color_selectedstr | tuple[float] | list[float](0, 0.55, 1, 1)
color_hoverstr | tuple[float] | list[float](0, 0, 0, 1)
color_bystr | list[float | str]None
color_mapstr | list[str] | Colormap | dict | 'auto'None
color_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
color_orderlist[str | int] | 'reverse'None
opacityfloat0.66
opacity_unselectedfloat0.5
opacity_bystr | list[float]'density'
opacity_maptriple[float] | list[float] | dict | 'auto'None
opacity_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
opacity_orderlist[str | int] | 'reverse'None
sizeint3
size_bystr | list[int]None
size_maptriple[float] | list[int] | dict | 'auto'None
size_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
size_orderlist[str | int] | 'reverse'None
connect_bystr | list[int]None
connect_orderstr | list[int]None
connection_colorstr | tuple[float] | list[float](0, 0, 0, 0.1)
connection_color_selectedstr | tuple[float] | list[float](0, 0.55, 1, 1)
connection_color_hoverstr | tuple[float] | list[float](0, 0, 0, 0.66)
connection_color_bystr | list[float | str]None
connection_color_mapstr | list[str] | Colormap | dict | 'auto'None
connection_color_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
connection_color_orderlist[str | int] | 'reverse'None
connection_opacityfloat0.1
connection_opacity_bystr | list[float]None
connection_opacity_maptriple[float] | list[float] | dict | 'auto'None
connection_opacity_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
connection_opacity_orderlist[str | int] | 'reverse'None
connection_sizeint2
connection_size_bystr | list[int]None
connection_size_maptriple[float] | list[int] | dict | 'auto'None
connection_size_normtuple[float] | Normalizematplotlib.colors.Normalize(0, 1, clip=True)
connection_size_orderlist[str | int] | 'reverse'None
axesboolTrue
axes_gridboolFalse
lasso_colorstr | tuple[float] | list[float](0, 0.666666667, 1, 1)
lasso_initiatorboolFalse
lasso_min_delayint10
lasso_min_distint3
lasso_on_long_pressboolTrue
reticleboolTrue
reticle_colorstr | 'auto''auto'
background_colorstr'white'
background_imagestr | array-like or PIL imageNone
mouse_mode'panZoom' | 'lasso' | 'rotate''panZoom'
camera_targettuple[float][0, 0]
camera_distancefloat1
camera_rotationfloat0
camera_viewlist[float]None
zoom_tolist[int]None
zoom_animationint500
zoom_on_selectionlist[float]0.33
zoom_on_filterlist[float]False
zoom_paddinglist[float]False
optionsdict{}

Widget ​

The widget (scatter.widget) has the following properties, which you can think of as the view model of Jupyter Scatter.

WARNING

While you can adjust these properties directly, the Scatter methods are the idiomatic and recommended way to set widget properties.

NameType
Default
Allow NoneRead OnlyNote
dom_element_idstrTrueFor debugging
data2D numerical array
prevent_filter_resetboolFalse
selectionint[]TruePoint indices
filterint[]TruePoint indices
hoveringintTrue
x_titlestrTrue
y_titlestrTrue
color_titlestrTrue
opacity_titlestrTrue
size_titlestrTrue
x_scalestrTrue
y_scalestrTrue
color_scalestrTrue
opacity_scalestrTrue
size_scalestrTrue
x_domain[float, float]
y_domain[float, float]
x_scale_domain[float, float]
y_scale_domain[float, float]
color_domain[float, float] | {}True
opacity_domain[float, float] | {}True
size_domain[float, float] | {}True
x_histogramfloat[]True
y_histogramfloat[]True
color_histogramfloat[]True
opacity_histogramfloat[]True
size_histogramfloat[]True
x_histogram_range[float, float]True
y_histogram_range[float, float]True
color_histogram_range[float, float]True
opacity_histogram_range[float, float]True
size_histogram_range[float, float]True
camera_target[float, float]
camera_distancefloat
camera_rotationfloat
camera_viewfloat[]TrueView matrix
zoom_toint[]Point indices
zoom_animationint1000Animation time in milliseconds
zoom_paddingfloat0.333Zoom padding relative to the bounding box of the points to zoom to
zoom_on_selectionboolFalseIf True zoom to selected points automatically
zoom_on_filterboolFalseIf True zoom to filtered points automatically
mouse_mode"panZoom" | "lasso" | "rotate""panZoom"
lasso_initiatorboolFalse
lasso_on_long_pressboolTrue
axesboolTrue
axes_gridboolFalse
axes_color[float, float, float, float]RGBA
axes_labelsbool | str[]False
legendboolFalse
legend_position"top"
| "top-right"
| "top-left"
| "bottom"
| "bottom-right"
| "bottom-left"
| "left"
| "right"
| "center"		"top-left"
legend_size"small" | "medium" | "large""small"
legend_color[float, float, float, float]RGBA
legend_encoding{}
tooltip_enableboolFalseWhy is this property not just called tooltip you might wonder? Ipywidgets seem to internally use this property, which prevents other widgets from using it unfortunately.
tooltip_size"small" | "medium" | "large""small"
tooltip_color[float, float, float, float]RGBA
tooltip_propertiesstr[]['x', 'y', 'color', 'opacity', 'size']
tooltip_properties_non_visual_info{}
tooltip_histogramsboolTrue
tooltip_histograms_rangesdictTrue
tooltip_histograms_size"small" | "medium" | "large""small"
tooltip_previewstrTrue
tooltip_preview_type"text" | "image" | "audio""text"
tooltip_preview_text_linesint3True
tooltip_preview_image_background_color"auto" | str"auto"
tooltip_preview_image_position"top"
| "left"
| "right"
| "bottom"
| "center"		"center"True
tooltip_preview_image_size"contain" | "cover""contain"True
tooltip_preview_audio_lengthintNoneTrue
tooltip_preview_audio_loopboolFalse
tooltip_preview_audio_controlsboolTrue
colorstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0, 0, 0.66] or
[1, 1, 1, 0.66]		Default value depends on the luminance of the background color.
color_selectedstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0.55, 1, 1]
color_hoverstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0, 0, 1] or
[1, 1, 1, 1]		Default value depends on the luminance of the background color.
color_by"valueA" | "valueB"NoneTrue
opacityfloat | float[]0.66
opacity_unselectedfloat | float[]0.5
opacity_by"valueA" | "valueB" | "density""density"True
sizeint | int[] | float | float[]3
size_by"valueA" | "valueB"NoneTrue
connectboolFalse
connection_colorstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0, 0, 0.1] or
[1, 1, 1, 0.1]		Default value depends on the luminance of the background color.
connection_color_by"valueA" | "valueB" | "segment"NoneTrueDefault value depends on the luminance of the background color.
connection_color_selectedstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0.55, 1, 1]
connection_color_hoverstr
| str[]
| [float, float, float, float]
| [float, float, float, float][]		[0, 0, 0, 0.66] or
[1, 1, 1, 0.66]		Default value depends on the luminance of the background color.
connection_opacityfloat | float[]0.1
connection_opacity_by"valueA" | "valueB" | "segment"NoneTrue
connection_sizeint | int[] | float | float[]2
connection_size_by"valueA" | "valueB" | "segment"NoneTrue
widthint | "auto""auto"
heightint240
background_colorstr | [float, float, float, float]"white"
background_imagestrNoneTrue
lasso_colorstr | [float, float, float, float][0, 0.666666667, 1, 1]
lasso_min_delayint10
lasso_min_distfloat3
reticleboolTrue
reticle_colorstr
| [float, float, float, float]
| "auto"		"auto"
other_optionsdict{}For setting other regl-scatterplot properties. Note that whatever is defined in options will be overwritten by the short-hand options
view_resetboolFalse
view_downloadboolNoneTrue
view_dataint[]NoneTrueTrueUint8ClampedArray
view_shape[int, int]NoneTrueTrue
view_syncstrNoneTrueFor synchronyzing view changes across scatter plot instances

Plotting Shorthand ​

plot(x=Undefined, y=Undefined, data=Undefined, **kwargs) ​

A shorthand function that creates a new scatter instance and immediately returns its widget.

Arguments: are the same as of Scatter.

Returns: a new scatter widget.

Examples:

python
from jscatter import plot
plot(data=cars, x='speed', y='weight', color='black', opacity_by='density', size=4)

Composing & Linking ​

compose(scatters, sync_views=False, sync_selection=False, sync_hover=False, match_by="index", cols=None, rows=1, row_height=320) ​

A function to compose multiple scatter plot instances in a grid and allow synchronized view, selection, and hover interactions.

Arguments:

  • scatters a list of scatter plot instances
  • sync_views a Boolean enabling synchronized panning & zooming when set to True
  • sync_selection a Boolean enabling synchronized point selection when set to True
  • sync_hover a Boolean enabling synchronized point hovering when set to True
  • match_by a string or a list of strings referencing a column in the scatters' data frame for identifying corresponding data points. When set to index corresponding points are associated by their index. The referenced column must hold strings or categorical data.
  • cols a number specifying the number of columns or None. When set to None the number of columns is derived from the number of scatters and rows.
  • rows a number specifying the number of rows.
  • row_height a number specifying the row height in pixels.

Returns: a grid of scatter widgets.

Examples:

python
from jscatter import Scatter, compose
from numpy.random import rand

compose(
    [Scatter(x=rand(500), y=rand(500)) for i in range(4)],
    sync_selection=True,
    sync_hover=True,
    rows=2
)

A shorthand function to compose multiple scatter plot instances in a grid and synchronize their view, selection, and hover interactions.

Arguments: same as from compose()

Returns: a grid of linked scatter widgets.

Examples:

python
from jscatter import Scatter, link
from numpy.random import rand
link([Scatter(x=rand(500), y=rand(500)) for i in range(4)], rows=2)

Color Maps ​

okabe_ito ​

A colorblind safe categorical color map consisting of eight colors created by Okabe & Ito.

  • #56B4E9 Sky blue (#56B4E9)
  • #E69F00 Orange (#E69F00)
  • #009E73 Bluish green (#009E73)
  • #F0E442 Yellow (#F0E442)
  • #0072B2 Blue (#0072B2)
  • #D55E00 Vermillion (#D55E00)
  • #CC79A7 Reddish Purple (#CC79A7)
  • #000000 Black (#000000)

glasbey_light ​

A categorical color map consisting of 256 maximally distinct colors optimized for a bright background. The colors were generated with the fantastic Colorcet package, which employs an algorithm developed by Glasbey et al., 2007.

glasbey_dark ​

A categorical color map consisting of 256 maximally distinct colors optimized for a dark background. The colors were generated with the fantastic Colorcet package, which employs an algorithm developed by Glasbey et al., 2007.

Annotations ​

HLine ​

A horizontal line annotation.

Arguments:

  • y is a float value in the data space specifying the y coordinate at which the horizontal line should be drawn.
  • x_start is a float value in the data space specifying the x coordinate at which the horizontal line should start. [optional]
  • x_end is a float value in the data space specifying the x coordinate at which the horizontal line should end. [optional]
  • line_color is a tuple of floats or string value specifying the line color. [optional]
  • line_width is an Integer value specifying the line width. [optional]

Examples:

python
from jscatter import plot, HLine
from numpy.random import rand
plot(
  x=rand(500),
  y=rand(500),
  annotations=[HLine(0)]
)

VLine ​

A vertical line annotation.

Arguments:

  • x is a float value in the data space specifying the x coordinate at which the vertical line should be drawn.
  • y_start is a float value in the data space specifying the y coordinate at which the vertical line should start. [optional]
  • y_end is a float value in the data space specifying the y coordinate at which the vertical line should end. [optional]
  • line_color is a tuple of floats or string value specifying the line color. [optional]
  • line_width is an Integer value specifying the line width. [optional]

Examples:

python
from jscatter import plot, VLine
from numpy.random import rand
plot(
  x=rand(500),
  y=rand(500),
  annotations=[VLine(0)]
)

Line ​

A line annotation.

Arguments:

  • vertices is a list of float tuples in the data space specifying the line vertices.
  • line_color is a tuple of floats or string value specifying the line color. [optional]
  • line_width is an Integer value specifying the line width. [optional]

Examples:

python
from jscatter import plot, Line
from numpy.random import rand
plot(
  x=rand(500),
  y=rand(500),
  annotations=[Line([(-1, -1), (0, 0), (1, 1)])]
)

Rect ​

A rectangle annotation.

Arguments:

  • x_start is a float value in the data space specifying the x coordinate at which the rectangle should start.
  • x_end is a float value in the data space specifying the x coordinate at which the rectangle should end.
  • y_start is a float value in the data space specifying the y coordinate at which the rectangle line should start.
  • y_end is a float value in the data space specifying the y coordinate at which the rectangle line should end.
  • line_color is a tuple of floats or string value specifying the line color. [optional]
  • line_width is an Integer value specifying the line width. [optional]

Examples:

python
from jscatter import plot, Rect
from numpy.random import rand
plot(
  x=rand(500),
  y=rand(500),
  annotations=[Rect(-1, 1, -1, 1)]
)

Contour ​

A contour line annotation. Under the hood the annotation uses Seaborn's kdeplot.

Arguments:

  • by is a string value specifying a column of categorical values for generating separate contour lines. [optional]
  • line_color is a tuple of floats or string value specifying the line color. [optional]
  • line_width is an Integer value specifying the line width. [optional]
  • line_opacity_by_level is a Boolean value specifying if the line opacity should be linearly increased from the lowest to the highest level such that the highest level is fully opaque. [optional]
  • kwargs is a dictionary of additional arguments for Seaborn's kdeplot. [optional]

Examples:

python
from jscatter import plot, Contour
from numpy.random import rand
plot(
  x=rand(500),
  y=rand(500),
  annotations=[Contour()]
)