---
url: /get-started.md
description: An overview of the most important features and functions.
---

# Get Started

## What is Jupyter Scatter?

Jupyter Scatter is a scalable, interactive, and interlinked scatter plot widget
exploring datasets with up to several million data points that runs in Jupyter
Lab/Notebook and Google Colab. It focuses on data-driven visual encodings and
offers two-way pan+zoom and lasso interactions. Beyond a single plot, Jupyter
Scatter can compose multiple scatter plots and synchronize their views and point
selections.

### Key Features

* 🖱️ **Interactive**: Pan, zoom, and select data points interactively.
* 🚀 **Scalable**: Plot up to several millions data points smoothly.
* 🔗 **Interlinked**: Synchronize the view, hover, and selection across multiple plots.
* ✨ **Effective Defaults**: Perceptually effective point colors and opacity by default.
* 📚 **Friendly API:** A readable API that integrates with Pandas, Polars, and any Arrow-compatible DataFrame.
* 🛠️ **Integratable**: Use Jupyter Scatter in your own widgets by observing its traitlets.

## Simplest Example

In the simplest case, you can pass the x/y coordinates to the plot function as follows:

```python
import jscatter
import numpy as np

x = np.random.rand(500)
y = np.random.rand(500)

jscatter.plot(x, y)
```

## Bind a DataFrame

In most cases, however, it's more convenient to work with a DataFrame and
reference the x/y columns via their names. Jupyter Scatter supports Pandas,
Polars, and any DataFrame implementing the [Arrow PyCapsule Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html)
(e.g., DuckDB, cuDF).

```python
import jscatter
import numpy as np
import pandas as pd

df = pd.DataFrame(np.random.rand(500, 2), columns=['mass', 'speed'])

jscatter.plot(data=df, x='mass', y='speed')
```

The same works with Polars:

```python
import polars as pl

df = pl.DataFrame(np.random.rand(500, 2), schema=['mass', 'speed'])

jscatter.plot(data=df, x='mass', y='speed')
```

## Point Color, Opacity, and Size

Often times, we want to style the points. Jupyter Scatter allows you to do this
as follows:

```py{5-7}
jscatter.plot(
    data=df,
    x='mass',
    y='speed',
    color='red', # static visual encoding
    size=10, # static visual encoding
    opacity=0.5 # static visual encoding
)
```

However, more commonely, one wants to use these three point attributes (color,
opacity, and size) to visualize data properties.

For instance, in the following we're extending the data frame with a continuous
property called `pval` and a categorical property called `cat`.

```py{5,7}
df = pd.DataFrame({
  # Random floats
  "mass": np.random.rand(500),
  "speed": np.random.rand(500),
  "pval": np.random.rand(500),
  # Random letters A, B, C, D, E, F, G, H
  "cat": np.vectorize(lambda x: chr(65 + round(x * 7)))(np.random.rand(500)),
})
```

|   | x    | y    | pval | cat |
|---|------|------|------|-----|
| 0 | 0.13 | 0.27 | 0.51 | G   |
| 1 | 0.87 | 0.93 | 0.80 | B   |
| 2 | 0.10 | 0.25 | 0.25 | F   |
| 3 | 0.03 | 0.90 | 0.01 | G   |
| 4 | 0.19 | 0.78 | 0.65 | D   |

You can visualize the two properties by referencing their columns using the
`color_by`, `opacity_by`, or `size_by` arguments.

```py{5-6}
jscatter.plot(
    data=df,
    x='mass',
    y='speed',
    color_by='cat', # data-driven visual encoding
    size_by='pval', # data-driven visual encoding
)
```

Notice how `jscatter` uses a reasonable color and size map by default. Both are
based on the properties' data types. In this examples, the `jscatter` picked the
color blindness safe color map from [Okabe and Ito](https://jfly.uni-koeln.de/color/#pallet) as the number of
categories is less than 9.

When visualizing the `pval` via the color we see how the default color map
switches to Viridis given that `pval` is a continuous property.

```py{5}
jscatter.plot(
    data=df,
    x='mass',
    y='speed',
    color_by='pval', # pval is continuous data
    size_by='pval', # pval is categorical data
)
```

You can of course customize the color map and many other parameters of the visual encoding as shown next.

```py{7-19}
jscatter.plot(
    data=df,
    x='mass',
    y='speed',
    color_by='cat',
    size_by='pval',
    # Custom categorical color map 
    color_map=dict(
      A='red',    B='#00ff00', C=(0,0,1),   D='DeepSkyBlue',
      E='orange', F='#702AF7', G='#2AF7C0', H='teal'
    ),
    # Custom size map (specified as a linspace)
    size_map=(2, 20, 10),
)
```

## Functional API

The flat API (that we used before) can get overwhelming when we customize a lot
of properties. Therefore, `jscatter` provides a functional API that groups
properties by type and exposes them via meaningfully-named methods that can
almost be read like a sentence.

For instance, in line two of the example below, the scatter plot colors points
by the `mass` column by mapping its values to the plasma color map in reverse
order.

```py{2}
scatter = jscatter.Scatter(data=df, x='mass', y='speed')
scatter.color(by='mass', map='plasma', order='reverse')
scatter.opacity(by='density')
scatter.size(by='pval', map=[2, 4, 6, 8, 10])
scatter.background('#1E1E20')
scatter.show()
```

## Update Properties After Plotting

You don't have to specify all properties upfront. Using the functional API
you can update scatter plot instances after having plotted the scatter and the
plot will automatically re-render.

For instance, in the following we're changing the color map to `magma` in
reverse order.

```py
scatter.color(map='magma', order='reverse')
```

## Chaining Method Calls

Inspired by [D3](https://d3js.org/) you can also chain methods calls as follows
to update multiple property groups at once.

```py
scatter.legend(True).axes(False)
```

## Animating Point Coordinates

When you update the x/y coordinates dynamically and the number of points match,
the points will animate in a smooth transition from the previous to their new
point location.

For instance, try calling [`scatter.xy('speed', 'mass')`](./api#scatter.xy) and
you will see how the points are mirrored along the diagonal.

## Retrieving Properties

Lastly, all method arguments are optional. If you specify arguments, the methods
will act as setters and change the properties. However, if you call a method
without any arguments it will act as a getter and return the related properties.

For example, `scatter.color()` will return the current coloring settings.

```py
{'default': (0, 0, 0, 0.66),
 'selected': (0, 0.55, 1, 1),
 'hover': (0, 0, 0, 1),
 'by': 'mass',
 'map': [[0.001462, 0.000466, 0.013866, 1.0],
  [0.002258, 0.001295, 0.018331, 1.0],
  ...
  [0.987387, 0.984288, 0.742002, 1.0],
  [0.987053, 0.991438, 0.749504, 1.0]],
 'norm': <matplotlib.colors.Normalize at 0x15f23feb0>,
 'order': 'reverse',
 'labeling': None}
```

---

---
url: /interactions.md
description: A guide on the supported mouse interactions in Jupyter Scatter.
---

# Interactions

Jupyter Scatter's scatter plots are interactive by default. You can pan, zoom,
hover, click, and lasso with your mouse. Moreover, Jupyter Scatter offers APIs
for filtering and zooming.

## Pan & Zoom the View

Like in Google Maps, you can pan and zoom to adjust the view and explore
different areas of the scatter plot in detail.

To pan, click and hold the primary mouse button and drag your mouse.

To zoom, simply engage your mouse's scroll wheel.

## Hover a Point

To help locate a point and where it's located, when you mouse over a point, a
reticle will appear.

## Click a Point

In order to select a point you can click on it.

## Double Click into the Void

To deselect points, simply double click into the background.

## Lasso Points

To select more than a single point, you can lasso multiple points.

To activate the lasso, click and hold down your primary mouse button. An open
circle will appear and slowly close in clockwise order. Once the circle is fully
closed it'll turn blue. At this point the lasso is active.

Once the lasso is active, keep holding down your primary mouse button and move
your mouse cursor around the points you want to select. Finally, release your
primary mouse key.

::: info
To permanently activate the lasso, you can click on the crosshair icon in the
top-left of the scatter plot.
:::

### Add and Remove Selected Points

To add more points to an existing selection, hold down the [*meta* key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/metaKey) as you
lasso select the points you want to add. To remove points from a selection, hold
down the [*alt* key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/altKey) as you lasso select the points you want to remove.

::: info
On macOS, the meta key is `Command` or `⌘` and the alt key is `Option` or `⌥`.
:::

### Brush and Rectangle Lasso Selections

Beyond this *freeform* lasso selection, Jupyter Scatter also offers
*rectangular* and *brush* style lasso selections. You can change the lasso type
either via the *lasso* button in the top-left corner of the plot or via
`scatter.lasso(type=lasso_type)`, where `lasso_type` must be one of
`'freeform'`, `'brush'`, or `'rectangle'`.

Below is an example of the brush lasso selection.

And finally an example of the classic rectangular lasso selection.

## Filter Points

Sometimes it can be useful to exclusively focus on a subset of points and
temporarily hide other points. This can be achieved using [`scatter.filter()`](/api#scatter.filter):

```py
scatter.filter([0, 1, 2])
```

The filtering is blazing fast as it's only hiding non-filtered points. To unset
the filter simply call the filter function with `None`:

```py
scatter.filter(None)
```

## Zoom to Points

When trying to focus on a subset of points (in particular point clusters), it
can help to zoom in. To zoom to a specific set of points, you can use
[`scatter.zoom()`](/api#scatter.zoom):

```py
scatter.zoom([0, 1, 2])
```

You can customize how much padding you want to leave when you zoom in as follows:

```py{3}
scatter.zoom(
  to=[0, 1, 2],
  padding=1,
)
```

In this case we're instructing our scatter plot instance to have the padding be
the same size as the bounding box of the first, second, and third point we're
zooming to.

Lastly, a cool feature of Jupyter Scatter is the ability to automatically zoom
to selected or filtered points to make it as simple as possible for you to focus
on a certain set of points.

```py
scatter.zoom(on_selection=True)
```

## Overview+Detail Interface

Using everything we've learned so far and combining it with Jupyter Scatter's
ability to [synchronize/link multiple scatter plots](/link-multiple-plots)
we can easily create an overview+detail interface as follows:

```py
from jscatter import Scatter, compose
from numpy.random import rand

x, y = rand(500), rand(500)

sc_overview = Scatter(x, y)
sc_detail = Scatter(x, y, zoom_on_filter=True, zoom_padding=1)

def filter_on_select(change):
    sc_detail.filter(change['new'] if len(change['new']) > 0 else None)

sc_overview.widget.observe(filter_on_select, names='selection')

compose(
    [(sc_overview, "Overview"), (sc_detail, "Detail")],
    sync_hover=True,
)
```

---

---
url: /selections.md
description: A guide on how to select points and clusters, and extract such selections.
---

# Selections

A primary way to interact with a scatter plot is through selections.
Jupyter Scatter makes this easy by offering selections that synchronize
between the Python and JavaScript kernel.

There are two ways to select points in a scatter plot:

1. [Programmatically using the `scatter.selection()` method](#set-programmatic)
2. [Interactively using the mouse-based lasso](#set-interactive)

Similarly, to act upon selected data points, you can

1. [Use the `scatter.selection()` method](#get-programmatic)
2. [Observe `scatter.widget.selection`](#get-interactive)

***

To demonstrate how these approaches work, we're going to use the following
DataFrame of random value:

```python
import jscatter
import numpy as np
import pandas as pd

df = pd.DataFrame({
  # Random floats
  "mass": np.random.rand(500),
  "speed": np.random.rand(500),
  "pval": np.random.rand(500),
  # Random letters A, B, C, D, E, F, G, H
  "cat": np.vectorize(lambda x: chr(65 + round(x * 8)))(np.random.rand(500)),
})

scatter = jscatter.Scatter(data=df, x="mass", y="speed", color_by="cat")
scatter.show()
```

## Programmatically Select Points {#set-programmatic}

To select a specific set of points, you can use the [`scatter.selection()`](./api#scatter.selection) method
which accepts as input a list of point indices.

```py
scatter.selection([1, 2, 3])
```

With the help of Panda's `query` method, we can easily select specific points
matching some criteria as follows:

```py
scatter.selection(df.query("cat == 'A'").index)
```

With the above call, for instance, we would select all points that belong to
category `A`.

::: info
By default, Jupyter Scatter references points by their range index. Meaning,
`scatter.selection([0, 1, 2])` will select the first, second, and third point.
This works consistently across Pandas, Polars, and other supported DataFrames.

Alternatively, if you're binding a Pandas DataFrame with a custom index, you can
make the `Scatter` instance reference data points by the DataFrame's label index
via `Scatter(data=df, data_use_index=True)`. Note that `data_use_index` is only
supported for Pandas DataFrames.
:::

## Lasso Select Points {#set-interactive}

As you might have seen already in the [interactions guide](./interactions), we
can also select points interactively using the lasso tool.

## Get Selected Points {#get-programmatic}

Importantly, once you have selected some points, you can retrieve the
interaction using the same method [`scatter.selection()`](./api#scatter.selection)
that we used earlier. This time just don't pass any arguments to the function.

```py
scatter.selection()
# => [0, 1, 2]
```

This will return a the indices of the selected points.

If you have bound a DataFrame to the scatter instance, you can use these indices
to retrieve the original data records.

```py{2}
scatter.selection(df.query("cat == 'A'").index)
df.loc[scatter.selection()]
```

|      | x    | y    | pval | cat |
|------|------|------|------|-----|
| 0    | 0.13 | 0.27 | 0.51 | A   |
| 42   | 0.87 | 0.93 | 0.80 | A   |
| …    | …    | …    | …    | …   |
| 1337 | 0.10 | 0.25 | 0.25 | A   |

## Observe Selected Points {#get-interactive}

Real *magic* can about to happen when you react to selections automatically. You
can do this by observing scatter widget's `selection` property:

```py{1,17-23}
import ipywidgets
import jscatter
import numpy as np
import pandas as pd

df = pd.DataFrame({
  # Random floats
  "mass": np.random.rand(500),
  "speed": np.random.rand(500),
  "pval": np.random.rand(500),
  # Random letters A, B, C, D, E, F, G, H
  "cat": np.vectorize(lambda x: chr(65 + round(x * 8)))(np.random.rand(500)),
})

scatter = jscatter.Scatter(data=df, x="mass", y="speed", color_by="cat")

output = ipywidgets.Output()

@output.capture(clear_output=True)
def selection_change_handler(change):
    display(df.loc[change.new].style.hide(axis='index'))
            
scatter.widget.observe(selection_change_handler, names=["selection"])

ipywidgets.HBox([scatter.show(), output])
```

If you want to learn how the point selections can be used to help you explore
large-scale datasets, check out our [in-depth talk+tutorial from SciPy '23](https://github.com/flekschas/jupyter-scatter-tutorial).

---

---
url: /link-multiple-plots.md
description: How to link and synchronize multiple Jupyter Scatter instances.
---

# Link Multiple Scatter Plots

There are many use cases where one wants to create two or more scatter plot and
potentially link the view, selection, and hover state.

For instance, we might want to

* visualize different properties of a dataset
* compare different facets of a dataset
* compare different embedding methods of a dataset
* compare multiple datasets with shared labels

Jupyter Scatter can help with this by composing and linking multiple scatter
instances.

## Simplest Example

We'll start out with a very simple example to get familiar with the API.

In the following, we'll compose two scatter plots next to each other using
[`compose()`](./api#compose).

```py{7}
import jscatter
import numpy as np

x, y = np.random.rand(500), np.random.rand(500)
a, b = jscatter.Scatter(x=x, y=y), jscatter.Scatter(x=x, y=y)

jscatter.compose([a, b])
```

By default, jscatter arranges scatter plots into a single row but we can
customize this of course.

```py
jscatter.compose([a, b], rows=2)
```

We can also change the row height as follows to shrink or grow the plots.

```py
jscatter.compose([a, b], rows=2, row_height=240)
```

## Synchronize View, Selection, & Hover

So good so far but the fun part starts when we link/synchronize the scatter
plots' views and selections.

```py{3-5}
jscatter.compose(
    [a, b],
    sync_view=True,
    sync_selection=True,
    sync_hover=True,
)
```

Since a common use case is to synchronize everything, `jscatter` offers the
shorthand method [`link()`](./api#link):

```py
jscatter.link([a, b])
```

The result is the same as the previous [`compose()`](./api#compose) call.

---

---
url: /axes-legends.md
description: How to configure axes and legends.
---

# Axes & Legends

Now that we know how to create, configure, compose, and link scatter plots, it's
time learn about axes and legends which are often essential in making sense of
the visualized data.

## Axes

You might have noticed already that axes are drawn by default. E.g.:

```py{7}
from jscatter import Scatter
from numpy.random import rand

scatter = jscatter.Scatter(x=rand(500), y=rand(500))
scatter.show()
```

::: info
You can also hide the axes via `scatter.axes(False)` in case they are not
informative like for t-SNE or UMAP embeddings.
:::

In addition, you can also enable a grid, which can be helpful to better locate
points.

```py
scatter.axes(grid=True)
```

And finally, you can also label the axes

```py
scatter.axes(labels=['Speed (km/h)', 'Weight (tons)'])
```

## Legend

When you encode data properties with the point color, opacity, or size, it's
immensly helpful to know how the encoded data properties relate to the visual
properties by showing a legend.

```py{22-24}
import jscatter
import numpy as np
import pandas as pd

df = pd.DataFrame({
  # Random floats
  "mass": np.random.rand(500),
  "speed": np.random.rand(500),
  "pval": np.random.rand(500),
  # Gaussian-distributed floats
  "effect_size": np.random.normal(.5, .2, 500),
  # Random letters A, B, C, D, E, F, G, H
  "cat": np.vectorize(lambda x: chr(65 + round(x * 8)))(np.random.rand(500)),
  # Random letters X, Y, Z
  "group": np.vectorize(lambda x: chr(88 + round(x * 2)))(np.random.rand(500)),
})

scatter = jscatter.Scatter(
  data=df,
  x="mass",
  y="speed",
  color_by="cat",
  size_by="pval",
  legend=True,
)
scatter.show()
```

When you encode a categorical data property (like `cat`) using color, Jupyter
Scatter will list out each category in the legend. In contrast, for continuous
data properties (like `pval`), only five values are shown in the legend: the
minimum, maximum, and three equally spaced values in between.

```py
scatter.color(by="pval").opacity(by="cat").size(5)
```

Notice how the legend now only shows five entries for `color` as it encodes a
continuous variable.

In addition to just showing a mapping of data and visual properties, Jupyter
Scatter can also label continuous properties.

```py
scatter.color(labeling={
    "variable": "p-value",
    "minValue": "significant",
    "maxValue": "insignificant", 
})
```

Annotating numerical range like this can make it easier for yourself but
primarily for collaborators and others to grasp the color mapping.

---

---
url: /labels.md
description: How to show text labels for points and clusters.
---

# Labels

When your points are labeled it can be helpful to show these labels in the
scatterplot.

You can draw text labels with Jupyter Scatter's `label()` function:

```py
scatter.label(by='df_column_name')
```

The referenced column needs to be either categorical or contain strings. For all
points with the same value, a text label is drawn.

For instance, say we have the following DataFrame:

|   | x | y | cat | pval |
|---|---|---|-----|------|
| 0 | 0 | 0 | A   | 0.51 |
| 1 | 1 | 0 | A   | 0.80 |
| 2 | 1 | 1 | A   | 0.25 |
| 3 | 0 | 1 | A   | 0.01 |
| 4 | 2 | 2 | B   | 0.65 |
| 5 | 3 | 2 | B   | 0.99 |
| 6 | 3 | 3 | B   | 1.33 |
| 7 | 2 | 3 | B   | 0.01 |

We can label points using the `cat` column via `scatter.label(by='cat')`.

When displaying labels, Jupyter Scatter automatically manages label collision
and overcrowding. It uses an importance-based static placement strategy such
that overlapping labels with a lower priority are visualized at a higher zoom
when the collision is resolved. To handle many labels, Jupyter Scatter uses a
tiling approach where only a limited number of labels (default: `100`) are shown
per tile.

You can control the label density with the `max_number` parameter. For instance,
to show fewer labels per tile do `scatter.label(by='cat', max_number=50)`.

::: info
For demo notebooks on how to use labels, see https://github.com/flekschas/jupyter-scatter-tutorial.
:::

## Importance

Whenever two text labels would collide, the label with the lower priority is
hidden. You can specify the importance via the `importance` parameter as shown
below. If no importance information is used, the number of points labeled by a
value is used.

```py
scatter.label(by='cat', importance='pval')
```

Since importance values are point specific, we need to aggregate multiple values
to derive the label importance. By default, Jupyter Scatter uses the mean but
you can change this behavior to `'min'`, `'median'`, `'max'`, or `'sum'`.

For instance, in the following we use the maximum point importance as the label
importance.

```py
scatter.label(by='cat', importance='pval', importance_aggregation='max')
```

Additionally, it's also possible to specify a custom aggregator function that
takes as input an array of floats and must return a single float.

::: tip
If you want to count the points and use this as the importance, simply omit
`importance` altogether as that's the default behavior.
:::

## Customization

### Appearance

You can customize the appearance and placement of labels in various ways. The
`font`, `color`, and `size` parameters allow you to adjust the font face, color,
and size.

```py{3-5}
scatter.label(
  by='cat',
  font='arial bold',
  color='red',
  size=36,
)
```

By default, the label size is constant (i.e., zoom invariant) but you can also
enlarge labels as you soon in. To do this, set `scale_function` to `"asinh"`,
which enlarges the label using the inverse hyperbolic sine function.

```py{3-4}
scatter.label(
  by='cat',
  size=36,
  scale_function='asinh'
)
```

The inverse hyperbolic sine function is only applied when zooming in and
increases the label size sublinearly compared to the camera zoom as follows:

```
label_scale = asinh(zoom_scale) / asinh(1)
```

::: info
Resolving collisions with inverse hyperbolic sine-scaled labels is computationally
more involved than constant scaling. Hence, if you have many labels (i.e., >=1000)
we recommend using constant scaling.
:::

### Position

You can also control the center position of labels, their alignment around
this position, and offset using the `positioning`, `align`, and `offset`
parameters.

```py{3-5}
scatter.label(
  by='cat',
  positioning='largest_cluster',
  align='top',
  offset=(2, 2),
)
```

Jupyter Scatter offers three positioning algorithms with different tradeoffs as
outlined below. You may want to experiment to see which one works best for your
specific use case.

#### Highest Density

The default positioning method (`'highest_density'`) places the label at the
point of highest density within the group. This algorithm:

* Is fast
* Calculates density based on how many points are clustered in each area
* Places labels where the most points are concentrated
* Works well for irregular clusters with varying densities
* Gives okay results for many datasets

#### Center of Mass

The `'center_of_mass'` method places the label at the geometric center of all
points in the group:

* Is fast
* Calculates the center position using the Shoelace formula
* Creates a balanced label position
* Works well for single-cluster and evenly-distributed points
* Not recommended when your labels consist of disconnected clusters

#### Largest Cluster

The `'largest_cluster'` method identifies the largest sub-cluster within the
group using [HDBSCAN](https://github.com/scikit-learn-contrib/hdbscan) and
places the label at its center of mass:

* Slowest method
* Detects clusters within each group
* Places the label at the center of mass of the largest cluster
* Works well when points naturally form multiple clusters
* Typically results in the best label placement overall

::: info
`"largest_cluster"` is an additional feature that's not included in the default
installation as it relies on HDBSCAN. To use the feature install Jupyter Scatter
via `pip install "jupyter-scatter[all]"`.
:::

### Line Breaks

If your labels tend to be on the longer side, you might want to
introduce line breaks. To make your life easier, you can specify an target
aspect ratio for which Jupyter Scatter will then try to find optimial line
breaks.

```py{3}
scatter.label(
  by='cat',
  target_aspect_ratio=5,
)
```

## Point Labels

By default, all points with the same value in a column are grouped and given a
single label. However, sometimes you may want to label each individual data
point instead. Jupyter Scatter supports this through a special syntax - simply
append an exclamation mark to the column name:

For example, with the following DataFrame, using `scatter.label(by='city!')`
will label each individual city. Hence, even though there are two cities called
"Berlin", they each get their own label.

|   | x    | y    | city     |
|---|------|------|----------|
| 0 | 0.13 | 0.27 | Paris    |
| 1 | 0.87 | 0.93 | New York |
| 2 | 0.10 | 0.25 | Berlin   |
| 3 | 0.03 | 0.90 | Rome     |
| 4 | 0.19 | 0.78 | Tokyo    |
| 4 | 0.99 | 0.81 | Berlin   |

```py
scatter.label(by='city!')
```

This is useful when each data point represents a unique entity but their labels
are not unique (like cities on a map)

::: info
Currently, only one column can be marked as a point label. If multiple columns
are marked with exclamation marks, only the first one will be used as a point
label.
:::

## Multiple and Hierarchical Label Types

Jupyer Scatter also supports multiple and even hierarchical label types. For
instance, let's assume the data frame contains another categorical or string
column.

|   | x    | y    | cat | sub | pval |
|---|------|------|-----|-----|------|
| 0 | 0.13 | 0.27 | A   | A1  | 0.51 |
| 1 | 0.87 | 0.93 | B   | B1  | 0.80 |
| 2 | 0.10 | 0.25 | A   | A1  | 0.25 |
| 3 | 0.03 | 0.90 | A   | A2  | 0.01 |
| 4 | 0.19 | 0.78 | B   | B1  | 0.65 |

We can render out labels for both `"cat"` and `"sub"` as follows:

```py
scatter.label(by=["cat", "sub"])
```

You can customize multiple labels in two ways. You can provide a list of values.
For instance, to draw `cat` labels in black bold at 24px and `sub` labels in
red italics at 18px, you can do:

```py{3-5}
scatter.label(
  by=['cat', 'sub']
  font=['bold', 'italic'],
  color=['black', '#ff0000'],
  size=[24, 18],
)
```

If you want to be even more specific with settings, you can also pass a
dictionary of `<type>:<value>` pairs. For instance, if you want all `cat` to be
black but `B` to be green, you can do the following:

```py{4}
scatter.label(
  by=['cat', 'sub'],
  font=['bold', 'italic'],
  color={'cat': 'black', 'cat:B': 'green', 'sub': '#ff0000'},
  size=[24, 18],
)
```

When working with multiple label types, collisions are still resolved in order
of importance such that the colliding labels with lower priorities appear only
at higher zoom levels when they no longer collide with labels of higher
importance. To adjust this behavior you can specify type-specific zoom ranges.
Zoom ranges are declared as zoom levels where `zoom_scale = 2 ^ zoom_level`.

```py{3}
scatter.label(
  by=['cat', 'sub'],
  zoom_ranges={'cat': (-math.inf, 2), 'sub': (2, 10)}
)
```

In the above example, `cat` labels are allowed to appear up until zoom level `2`
and `sub` labels are allowed to appear from zoom level `2` onward.

::: info
Note, zoom ranges do not enforce that labels are shown in that given range but
rather they specify the allowed zoom range at which they can appear given the
labels' importance and overlap with other labels.
:::

If your label types describe a strict hierarchy, as is the case for the example
specified above, then you can set `hierarchical` to `True`. For hierarchical
label types, Jupyter Scatter automatically enforces that labels in at a lower
hierarchical level are shown before labels with a higher hierarchical level.

```py{3}
scatter.label(
  by=['cat', 'sub'],
  hierarchical=True
)
```

For instance, in the example above, irrespective of the labels' importance,
`cat` labels will be shown before `sub` labels if they collide. Non-colliding
labels might be shown at the same time.

## Exclude Labels

Sometimes you do not want to show all labels. For instance, when clustering
labels it's common to label unclear points as *noise*. You can exclude unwanted
labels using the `exclude` parameter. For instance, in the following we exclude
the label `B`.

```py
scatter.label(by=['cat'], exclude=['B'])
```

When using multiple label types, you need to specify excluded labels via
`<type>:<label>`. For instance, in the following we exclude `sub` label `A2`

```py
scatter.label(by=['cat', 'sub'], exclude=['sub:A2'])
```

## Precompute Labels

When working with many labels it can take a moment to compute the labels. If you
want to use the same labels in multiple scenarios, it can be beneficial to
precompute labels and later load them from file.

To precompute labels, use the `LabelPlacement` class. It accepts many of the
same parameters as the `Scatter`'s `label` function.

```py
labels = LabelPlacement(data=df, x='x', y='y', by='cat')
labels.compute()
```

::: tip
For tracking the progress while precomputing very large label sets you can show
a progress bar via `labels.compute(show_progress=True)`. This feature requires
the complete installation via `pip install "jupyter-scatter[all]"`.
:::

Once the labels placement has been precomputed, you can persist them to disk as
parquet files.

```py
labels.to_parquet('my_labels')
```

Later on you can then recreate the label placement instance.

```py
labels.from_parquet('my_labels')
```

Importantly, you can pass this label placement instance directly to your scatter
instance.

```py
scatter.labels(using=labels)
```

::: info
The label placement class is responsible for statically resolving label
collisions by determining at which zoom level labels should appear. This
calculation is based on a tile size parameter, which defaults to 256 × 256
pixels.

It's important to understand that font size and zoom ranges are relative to this
tile size. When using `Scatter`'s `label()` function directly, the tile size
defaults to height × height (the widget's height), which means labels are
optimized for the initial view.

When precomputing labels with a different tile size than your widget's height,
you may notice differences in how labels appear:

* If you specify a smaller tile size (e.g., `100`) for a taller visualization
  (e.g., `height=200`), labels using the `'asinh'` scale function will appear
  larger than expected in the initial view.
* With the `'constant'` scale function, font size remains consistent regardless
  of tile size.

For most reliable results when precomputing labels for various display sizes,
the `'constant'` scale function is recommended.
:::

---

---
url: /annotations.md
description: How to use annotations to help relate points and clusters.
---

# Annotations

To help navigating and relating points and clusters, Jupyter Scatter offers
annotations such a lines and rectangles.

::: info
Currently, Jupyter Scatter supports line-based annotations only. In the future,
we plan to add support for text annotations as well.
:::

## Line, HLine, VLine, and Rect

To draw annotations, create instances of `Line`, `HLine`, `VLine`, or `Rect`.
You can then either pass the annotations into the constructor, as shown below,
or call `scatter.annotations()`.

```py{9-17,22}
import jscatter
import numpy as np

x1, y1 = np.random.normal(-1, 0.2, 1000), np.random.normal(+1, 0.05, 1000)
x2, y2 = np.random.normal(+1, 0.2, 1000), np.random.normal(+1, 0.05, 1000)
x3, y3 = np.random.normal(+1, 0.2, 1000), np.random.normal(-1, 0.05, 1000)
x4, y4 = np.random.normal(-1, 0.2, 1000), np.random.normal(-1, 0.05, 1000)

y0 = jscatter.HLine(0)
x0 = jscatter.VLine(0)
c1 = jscatter.Rect(x_start=-1.5, x_end=-0.5, y_start=+0.75, y_end=+1.25)
c2 = jscatter.Rect(x_start=+0.5, x_end=+1.5, y_start=+0.75, y_end=+1.25)
c3 = jscatter.Rect(x_start=+0.5, x_end=+1.5, y_start=-1.25, y_end=-0.75)
c4 = jscatter.Rect(x_start=-1.5, x_end=-0.5, y_start=-1.25, y_end=-0.75)
l = jscatter.Line([
    (-2, -2), (-1.75, -1), (-1.25, -0.5), (1.25, 0.5), (1.75, 1), (2, 2)
])

scatter = jscatter.Scatter(
    x=np.concatenate((x1, x2, x3, x4)), x_scale=(-2, 2),
    y=np.concatenate((y1, y2, y3, y4)), y_scale=(-2, 2),
    annotations=[x0, y0, c1, c2, c3, c4, l],
    width=400,
    height=400,
)
scatter.show()
```

## Line Color & Width

You can customize the line color and width of `Line`, `HLine`, `VLine`, or
`Rect` via the `line_color` and `line_width` attributes.

```py
y0 = jscatter.HLine(0, line_color=(0, 0, 0, 0.1))
x0 = jscatter.VLine(0, line_color=(0, 0, 0, 0.1))
c1 = jscatter.Rect(x_start=-1.5, x_end=-0.5, y_start=+0.75, y_end=+1.25, line_color="#56B4E9", line_width=2)
c2 = jscatter.Rect(x_start=+0.5, x_end=+1.5, y_start=+0.75, y_end=+1.25, line_color="#56B4E9", line_width=2)
c3 = jscatter.Rect(x_start=+0.5, x_end=+1.5, y_start=-1.25, y_end=-0.75, line_color="#56B4E9", line_width=2)
c4 = jscatter.Rect(x_start=-1.5, x_end=-0.5, y_start=-1.25, y_end=-0.75, line_color="#56B4E9", line_width=2)
l = jscatter.Line(
    [(-2, -2), (-1.75, -1), (-1.25, -0.5), (1.25, 0.5), (1.75, 1), (2, 2)],
    line_color="red",
    line_width=3
)
```

## Contour Line

Beyond basic line-based annotations, Jupyter Scatter also supports composite
annotations like [contour line](https://en.wikipedia.org/wiki/Contour_line).

::: info
This feature requires [Seaborn](https://seaborn.pydata.org) which you can install via `pip install "jupyter-scatter[all]"`.
:::

A contour line estimates the density and is internally computed with
[Seaborn's kdeplot](https://seaborn.pydata.org/generated/seaborn.kdeplot.html).

```py
import jscatter
import seaborn as sns

jscatter.plot(
    data=sns.load_dataset("geyser"),
    x='waiting',
    y='duration',
    annotations=[jscatter.Contour()],
)
```

To draw contour lines by a group of points, you can use the `by` argument of
`Contour`. Internally, the `by` property maps to the `hue` argument of the
kdeplot. When `color_by` is the same as the Contour's `by` property, the color
of the contour lines match the color of the points.

```py{5-6}
jscatter.plot(
    data=sns.load_dataset("geyser"),
    x='waiting',
    y='duration',
    color_by='kind',
    annotations=[jscatter.Contour(by='kind')],
)
```

To emphasize higher levels and deemphasize lower levels of the contour lines,
you can set the `line_opacity_by_level` argument to `True`.

```py{6}
jscatter.plot(
    data=sns.load_dataset("geyser"),
    x='waiting',
    y='duration',
    color_by='kind',
    annotations=[jscatter.Contour(by='kind', line_opacity_by_level=True)],
)
```

---

---
url: /tooltip.md
description: How to show and configure a tooltip on point hover.
---

# Tooltip

To further aid in making sense of the data points and patterns in a scatter
plot, Jupyter Scatter supports a tooltip that can show a point's properties and
related media to facilitate sense making.

```py
scatter.tooltip(True)
```

Each row in the tooltip corresponds to a property. From left to right, each
property features the:

1. visual property (like `x`, `y`, `color`, `opacity`, or `size`) or data property
2. name as specified by the column name in the bound DataFrame
3. actual data value
4. histogram or treemap of the property distribution

For numerical properties, the histogram is visualized as a bar chart. For
categorical properties, the histogram is visualized as a
[treemap](https://en.wikipedia.org/wiki/Treemapping) where the rectangles
represents the proportion of categories compared to the whole. Treemaps are
useful in scenarios with a lot of categories as shown below.

In both cases, the highlighted bar / rectangle indicates how the hovered point
compares to the other points.

::: info
For demos of how to use tooltips with a variety of data, see https://github.com/flekschas/jupyter-scatter-tutorial.
:::

## Properties

By default, the tooltip shows all properties that are visually encoded but you
can limit which properties are shown:

```py
scatter.tooltip(properties=["color", "opacity"])
```

Importantly, you can also show other properties in the tooltip that are not
directly visualized with the scatter plot. Other properties have to be
referenced by their respective column names.

```py{5-6}
scatter.tooltip(
  properties=[
    "color",
    "opacity",
    "group",
    "effect_size",
  ]
)
```

Here, for instance, we're showing the point's `group` and `effect_size`
properties, which are two other DataFrame columns we didn't visualize.

::: tip
The order of `properties` defines the order of the entries in the tooltip.
:::

## Customize Numerical Histograms

The histograms of numerical data properties consists of `20` bins, by default,
and is covering the entire data range, i.e., it starts at the minumum and ends
at the maximum value. You can adjust both aspects either globally for all
histograms as follows:

```py
scatter.tooltip(histograms_bins=40, histograms_ranges=(0, 1))
```

To customize the number of bins and the range by property you can do:

```py
scatter.tooltip(
  histograms_bins={"color": 10, "effect_size": 30},
  histograms_ranges={"color": (0, 1), "effect_size": (0.25, 0.75)}
)
```

Since an increased number of bins can make it harder to read the histogram, you
can also adjust the size as follows:

```py
scatter.tooltip(histograms_size="large")
```

If you set the histogram range to be smaller than the data extent, some points
might lie outside the histogram. For instance, previously we restricted the
`effect_size` to `[0.25, 0.75]`, meaning we disregarded part of the lower and
upper end of the data.

In this case, hovering a point with an `effect_size` less than `.25` will be
visualized by a red `]` to the left of the histogram to indicate it's value is
smaller than the value represented by the left-most bar.

Likewise, hovering a point with an `effect_size` larger than `0.75` will be
visualized by a red `[` to the right of the histogram to indicate it's value is
larger than the value represented by the right-most bar.

Finally, if you want to transform the histogram in some other way, use your
favorite method and save the transformed data before referencing it. For
instance, in the following, we winsorized the `effect_size` to the `[10, 90]`
percentile:

```py
from scipy.stats.mstats import winsorize

df['effect_size_winsorized'] = winsorize(df.effect_size, limits=[0.1, 0.1])
scatter.tooltip(properties=['effect_size_winsorized'])
```

## Media Previews

In cases where your data has a media representation like text, images, or audio,
you can show a preview of the media in the tooltip by referencing a column name
that holds either plain text, URLs referencing images, or URLs referencing
audio.

```py
scatter.tooltip(preview="headline")
```

By default, the media type is set to `text`. If you want to show an image or
audio file as the preview, you additionally need to specify the corresponding
media type.

```py
scatter.tooltip(preview="url", preview_type="image")
```

You can further customize the media preview via media type-specific arguments.
For instance in the following, we limit the audio preview to 2 seconds and
loop the audio playback.

```py
scatter.tooltip(
  preview="audio_url",
  preview_type="audio",
  preview_audio_length=2,
  preview_audio_loop=True
)
```

For more details on how to customize the tooltip preview, see the API docs for
[`tooltip()`](/api#scatter.tooltip).

---

---
url: /scales.md
description: How to customize the X and Y scales.
---

# Scales

In the following we'll go over all supported X/Y scale functions.

::: info
We'll add support for more scale functions in the future, so make sure to check
back from time to time.
:::

## Linear

By default, points are plotted linearly along the x and y coordinate.

```py
jscatter.plot(x=np.random.rand(500), y=np.random.rand(500))
```

## Time

While technically identical to linear scaling, if you have temporal data, you
can render out axes with nice tick marks by setting the X or Y scale to `time`.

```py{8}
jscatter.plot(
  x=np.random.randint(
    low=1672549200000, # Jan 1, 2023 00:00:00
    high=1704085200000, # Jan 1, 2024 00:00:00
    size=500
  ),
  y=np.random.rand(500),
  x_scale='time',
)
```

::: warning
For the time scale to work, the data needs to be in the form of [timestamps given as the number of milliseconds since the beginning of the Unix epoch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date)!
:::

## Log

If your data is following, you can plot points

```py{4}
jscatter.plot(
  x=np.random.rand(500),
  y=np.random.rand(500),
  x_scale='log',
)
```

## Power

Similarly, you can also plot points according to a power scale along the x or y
axis.

```py{4}
jscatter.plot(
  x=np.random.rand(500),
  y=np.random.rand(500),
  x_scale='pow',
)
```

---

---
url: /connected-scatterplots.md
description: A guide for connected scatterplots.
---

# Connected Scatterplot

If your data represents series of variables, it can be useful to visualize the
evolution the variables through point connections.

::: info
Connected scatterplots are most commonly used for temporal or timeseries data.
:::

## Basics

By default, points are plotted linearly along the x and y coordinate.

```py
import datetime
import jscatter
import math
import numpy as np
import pandas as pd

def get_web_timestamp(month):
    return math.floor(
        datetime.datetime(2023, month, 1).timestamp() * 1000
    )

dates = [get_web_timestamp(month) for month in range(1, 13)]

df = DataFrame({
    'date': dates * 3,
    'value': np.concatenate(
        (
            np.random.rand(12),
            np.random.rand(12) + 0.5,
            np.random.rand(12) + 1
        ),
        axis=0
    ),
    'group': ['A'] * 12 + ['B'] * 12 + ['C'] * 12,
})

scatter = jscatter.Scatter(
    data=df,
    x='date',
    x_scale='time',
    y='value',
    connect_by='group'
)
scatter.show()
```

::: tip
By default, line connections are spline interpolated curves. If you instead want
straight lines, call `scatter.options({ 'pointConnectionTolerance': 1 })`.
:::

## Styling

Similar to how you can visually style and encode the point color, opacity, and
size, you can visually style and encode the color, opacity, and size of the
point connections.

Since one might often want to use the point color as the line color, the
connection color can be set to `'inherit'` in order to inherit the color
encoding.

```py{4-6}
scatter.color(by='group')
scatter.size(10)
scatter.opacity(1)
scatter.connection_color('inherit')
scatter.connection_size(5)
scatter.connection_opacity(0.5)
```

In additional, it's also possible to color the point connections by line
segments to visually distinguish the start and end of connected points.

```py
scatter.color(by='date', map='coolwarm')
scatter.connection_color(by='segment', map='coolwarm')
```

---

---
url: /export-image.md
description: How to export a view as an image.
---

# Export View as Image

There are two ways to export a scatter plot as an image. You can either download
it as a PNG or save it to the widget's `view_data` property.

::: info
Image exports follow [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG), meaning
that the exported image will have the exact same size and viewport as the
widget. Hence, if you want to export a higher resolution image you have to
increase the scatter's width and height. See [custom PNG export](#customize-png-export)
on how to easily adjust the export resolution.
:::

## Export as PNG

To download the current scatter plot view as a PNG click on the download icon.

For instance, given the following scatter.

```py
import jscatter
import numpy as np

x = np.random.normal(0, 0.1, 1000)
y = np.random.normal(0, 0.1, 1000)

scatter = jscatter.Scatter(x, y)
scatter.show()
```

The downloaded image will look as follows:

::: info
By default, the background color of the image is the same as
`scatter.widget.background_color`. However, you can also download the view with
a transparent background by holding down Alt while clicking on the
camera button.
:::

### Customize PNG Export

To better control the resolution of the exported PNG, enter the full-screen mode
(via the widget button on the left) and open up the resize panel (via the up
arrow button in the bottom-left corner). This panel allows you to easily
customize the width/height of the scatter plot and offers the ability to
up-scale the exported image.

::: info
Note, the exported image is subject to your [device pixel ratio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio), which cannot be changed. This means that if your plot is
100 by 100 pixels in size and your display has a pixel ratio of `2`, the
exported PNG is going to be 200 by 200 pixels.
:::

## Export to `widget.view_data`

When you click on the camera icon, the current view will be exported and saved
to the widget's `view_data` property. You can use that property to print the
image or manipulate it in some way if you like.

For instance, given the following scatter.

```py
import jscatter
import numpy as np

x = np.random.rand(500)
y = np.random.rand(500)

scatter = jscatter.Scatter(x, y)
scatter.show()
```

After having clicked on the camera icon button on the left of the plot, you can
access the exported image via `scatter.widget.view_data` and, for instance, plot
it with Matplotlib as follows:

```py
from matplotlib import pyplot as plt
plt.imshow(scatter.widget.view_data, interpolation='nearest')
plt.show()
```

---

---
url: /api.md
description: Complete API reference.
---

# API Reference

* [Scatter](#scatter)
  * [Methods](#methods)
    * [x()](#scatter.x), [y()](#scatter.x), [xy()](#scatter.xy), and [data()](#scatter.data)
    * [selection()](#scatter.selection), [filter()](#scatter.filter), and [order()](#scatter.order)
    * [color()](#scatter.color), [opacity()](#scatter.opacity), and [size()](#scatter.size)
    * [connect()](#scatter.connect), [connection\_color()](#scatter.connection_color), [connection\_opacity()](#scatter.connection_opacity), and [connection\_size()](#scatter.connection_size)
    * [axes()](#scatter.axes), [legend()](#scatter.legend), [label()](#scatter.label), and [annotations()](#scatter.annotations)
    * [tooltip()](#scatter.tooltip) and [show\_tooltip()](#scatter.show_tooltip)
    * [zoom()](#scatter.zoom) and [camera()](#scatter.camera)
    * [lasso()](#scatter.lasso), [reticle()](#scatter.reticle), and [mouse()](#scatter.mouse),
    * [background()](#scatter.background) and [options()](#scatter.options)
  * [Properties](#properties)
  * [Widget](#widget)
* [Plotting Shorthand](#plotting)
* [Composing & Linking](#composing-linking)
* [Color Maps](#color-maps)
* [Annotations](#annotations)
* [LabelPlacement](#labelplacement)

## Scatter

### Scatter(*x*, *y*, *data=None*, *\*\*kwargs*) {#Scatter}

**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 or Polars DataFrame, or any object implementing the [Arrow PyCapsule Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html). \[optional]
* `kwargs` is a dictionary of additional [properties](#properties). \[optional]

**Returns:** a new scatter instance.

**Examples:**

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

## Methods {#methods}

### scatter.show(*buttons=Undefined*) {#scatter.show}

Show the scatter plot widget.

**Arguments:**

* `buttons`: The buttons to show in the widget. Can be one of the following:
  * `"pan_zoom"`: Button to activate the pan and zoom mode.
  * `"lasso"`: Button to activate the lasso mode.
  * `"full_screen"`: Button to enter full screen mode.
  * `"save"`: Button to save the current view in `scatter.widget.view_data`.
  * `"download"`: Button to download the current view as a PNG image.
  * `"reset"`: Button to reset the view.
  * `"divider"`: Not a button, but a divider between buttons.

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

**Examples:**

```python
# Show the widget with all buttons
scatter.show()

# Show the widget with only a subset of buttons
scatter.show(['full_screen', 'download', 'reset'])
```

### scatter.x(*x=Undefined*, *scale=Undefined*, *\*\*kwargs*) {#scatter.x}

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*) {#scatter.y}

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*) {#scatter.xy}

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*) {#scatter.data}

Get or set the referenced DataFrame.

**Arguments:**

* `data` is a Pandas or Polars DataFrame, or any object implementing the [Arrow PyCapsule Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html).
* `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*) {#scatter.selection}

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*) {#scatter.filter}

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.order(*by=Undefined*, *map=Undefined*, *direction=Undefined*, *na\_values=Undefined*) {#scatter.order}

Get or set the draw order of points. Points drawn later appear on top of earlier points. By default, points are drawn in the order they appear in the data. This method allows you to control the draw order without reordering the underlying data.

**Arguments:**

* `by` is either a string referencing a column in `data` (for sorting by column values), an array-like list of integers (used directly as the draw order), or `None` (to reset to the default input order).
* `map` is a list of category values defining a custom draw sequence. Values earlier in the list are drawn first (behind), values later are drawn last (on top). When set, `direction` is ignored. Missing values (NaN) are still controlled by `na_values`.
* `direction` is either `'asc'` or `'desc'`. Controls the sort direction when `by` is a column name. `'asc'` draws points with smaller values first (behind). Defaults to `'asc'`.
* `na_values` is either `'first'`, `'last'`, or `None`. Controls where NaN/missing values are placed in the sort order. `'first'` draws them behind all other points, `'last'` draws them on top. Defaults to `'last'`.

**Returns:** either the current order settings when all arguments are `Undefined` or `self`.

**Examples:**

```python
# Order by a column (ascending: small values behind, large on top)
scatter.order(by='price')

# Descending order with NaN behind everything
scatter.order(by='price', direction='desc', na_values='first')

# Custom category order: B drawn on top
scatter.order(by='cluster', map=['A', 'C', 'B'])

# Provide a custom draw order directly
scatter.order(by=[2, 0, 1, 4, 3])

# Reset to default input order
scatter.order(by=None)

# Get the current order settings
scatter.order()
# => {'by': 'price', 'map': None, 'direction': 'desc', 'na_values': 'first'}
```

### scatter.color(*default=Undefined*, *selected=Undefined*, *hover=Undefined*, *by=Undefined*, *map=Undefined*, *norm=Undefined*, *order=Undefined*, *labeling=Undefined*, *\*\*kwargs*) {#scatter.color}

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](https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.Normalize.html).
* `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*) {#scatter.opacity}

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](https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.Normalize.html).
* `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*, *scale\_function=Undefined*, *\*\*kwargs*) {#scatter.size}

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](https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.Normalize.html).
* `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.
* `scale_function` is the function used for adjusting the size of points when zooming in. It can either be `asinh`, `linear`, or `constant`. The default is `asinh`. `constant` is a special case that does not scale the size of points when zooming in.
* `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*) {#scatter.connect}

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:

|   | x    | y    | group | order |
|---|------|------|-------|-------|
| 0 | 0.13 | 0.27 | A     | 2     |
| 1 | 0.87 | 0.93 | A     | 1     |
| 2 | 0.10 | 0.25 | B     | 2     |
| 3 | 0.03 | 0.90 | A     | 3     |
| 4 | 0.19 | 0.78 | B     | 1     |

```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*) {#scatter.connection\_color}

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*) {#scatter.connection\_opacity}

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*) {#scatter.connection\_size}

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

### scatter.axes(*axes=Undefined*, *grid=Undefined*, *labels=Undefined*) {#scatter.axes}

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*) {#scatter.legend}

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.label(*legend=Undefined*, *position=Undefined*, *size=Undefined*) {#scatter.label}

Set or get the label settings.

**Arguments:**

* `by` is a string or list of strings referencing columns in `data`. The
  columns should define a hierarchy of points by which you want to
  label these points. When set to `None`, labeling is turned off.

  To display individual point labels (where each row gets its own label),
  append an exclamation mark to the column name. For instance, `"city!"`
  would indicate that each value in this column should be treated as a
  unique label rather than grouping identical values together.

  Note: Currently only one column can be marked with an exclamation mark.
  If multiple columns are marked, only the first one is treated as
  containing point labels.
* `font` is a font or list of fonts for rendering the labels. A list of fonts
  must match `by` in terms of the length. A dict can map specific
  label types or label values to fonts.
* `color` is a single, list or dict of colors for rendering the labels. A list of
  colors must match `by` in terms of the length. A dict of colors must
  define a color for every unique label. By default, the color is set
  to `"auto"` meaning a default color is assigned based on the
  background color.
* `size` is the font size(s) for label text. Can be a single integer for uniform
  size, a list matching the length of `by` for hierarchical sizes, or
  a dictionary mapping specific label types or values to sizes.
* `shadow_color` is The outline color for rendering the labels. By default, the
  color is set to `"auto"` meaning a default color is assigned based on the
  background color.
* `importance` is the column name containing importance values that determine
  which labels to prioritize when there are conflicts. If not specified, all
  labels have equal importance.
* `importance_aggregation` is the method used to aggregate importance values
  when multiple points share the same label. Can be one of `'min'`, `'mean'`,
  `'median'`, `'max'`, `'sum'`. Default is `'mean'`.
* `max_number` is the maximum number of labels per tile. Controls label density
  by limiting how many labels can appear in a given region. Default is `100`.
* `align` is the label alignment relative to the labeled point or group. Can be
  one of `'center'`, `'top-left'`, `'top'`, `'top-right'`, `'left'`, `'right'`,
  `'bottom-left'`, `'bottom'`, `'bottom-right'`. Default is `'center'`.
* `offset` is the x and y offset of the label from the center of the bounding
  box of points it's labeling. Note, this only has an effect when `align`
  is not `'center'`.
* `scale_function` is the scale function by which the text size is adjusted when
  zooming in. Can be one of:
  * `'asinh'`: Scales labels by the inverse hyperbolic sine, initially
    increasing linearly but quickly plateauing (default).
  * `'constant'`: No scaling with zoom, labels maintain the same size.
* `zoom_range`: The range at which labels of a specific type (as specified with
  `by`) are allowed to appear. The zoom range is a tuple of zoom levels,
  where `zoom_scale == 2 ** zoom_level`. Defaults to (-∞, ∞) for all
  labels. Can be specified as:
  * Single tuple: Applied to all label types
  * List of tuples: One range per label type in `by`
  * Dict: Maps label types or specific labels to their zoom ranges
* `hierarchical` is a flag. If `True`, the label types specified by `by` are
  treated as hierarchical. This affects label priority, with labels having a
  lower hierarchical index (earlier in the `by` list) displayed first when there
  are conflicts. Default is `False`.
* `exclude` is a list of string that specifies which labels should be excluded.
  Can contain:
  * Column names (e.g., `'country'`) to exclude an entire category
  * Column-value pairs (e.g., `'country:Germany'`) to exclude specific labels
* `positioning` is the method for determining label position. Options are:
  * `'highest_density'` (default): Position label at the highest density point
  * `'center_of_mass'`: Position label at the center of mass of all points
  * `'largest_cluster'`: Position label at the center of the largest cluster
* `target_aspect_ratio` is a float in `]0, ∞[`. If not `None`, labels will
  potentially receive line breaks such that their bounding box is as close to
  the specified aspect ratio as possible. The aspect ratio is width/height.
  Default is `None`.
* `max_lines` is the maximum number of lines a label can be broken into when
  `target_aspect_ratio` is set. Default is `None` (no limit).
* `using` is an en existing `LabelPlacement` instance to use for labels. This
  allows reusing pre-computed label placements instead of calculating them
  from scratch.

**Returns:** either the label settings when all arguments are `Undefined` or `self`.

**Example:**

```python
scatter.label(by='group')

scatter.label(by=['state', 'city'], hierarchical=True)

scatter.label(by='city!', color='red', size=12)

scatter.label(by='category', exclude=['category:Other'])
```

### scatter.annotations(*annotations=Undefined*) {#scatter.annotations}

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\_image\_height=Undefined*, *preview\_audio\_length=Undefined*, *preview\_audio\_loop=Undefined*, *preview\_audio\_controls=Undefined*, *size=Undefined*) {#scatter.tooltip}

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 or list of property names specifying if histograms should be shown. When set to `True`, the tooltip will show histograms for all properties. Alternatively, you can provide a list of properties for which you want to show a histogram.

* `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_image_height` The height of the image container pixels. By default, it is `None`, which makes the height deffault to 6em.

* `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*) {#scatter.show\_tooltip}

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*) {#scatter.zoom}

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*, *is\_fixed=Undefined*) {#scatter.camera}

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.
* `is_fixed` is a Boolean value specifying whether the camera position is fixed to it's current location. If `True`, manual pan and zoom interactions are disabled. Note, you can still programmatically zoom via `scatter.zoom()`.

**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*) {#scatter.mouse}

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(*type=Undefined*, *color=Undefined*, *initiator=Undefined*, *min\_delay=Undefined*, *min\_dist=Undefined*, *on\_long\_press=Undefined*, *brush\_size=Undefined*) {#scatter.lasso}

Get or set the lasso for selecting multiple points.

**Arguments:**

* `type` is a string specifying the lasso type. Must be one of `'freeform'`, `'brush'`, or `'rectangle'`.
* `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.
* `brush_size` is an integer specifying the size of the brush in pixels. This has only an effect if `type` is set to `'brush'`'. Defaults to `24`.

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

**Example:**

```python
scatter.lasso(initiator=True)
```

### scatter.reticle(*show=Undefined*, *color=Undefined*) {#scatter.reticle}

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*) {#scatter.background}

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](https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.pyplot.imshow.html)

**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*) {#scatter.options}

Get or set other Jupyter Scatter and [regl-scatterplot](https://github.com/flekschas/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](https://github.com/flekschas/regl-scatterplot/#properties).

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

### scatter.pixels() {#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 {#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', ...)`.

| Name                       | Type                                                                                     | Default                                        |
| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `data`                     | pandas.DataFrame | polars.DataFrame | ArrowPyCapsule                                   | `None`                                         |
| `x`                        | str | list\[float] | ndarray                                                            | `None`                                         |
| `x_scale`                  | 'linear' | 'log' | 'pow' | tuple\[float] | [LogNorm][lognorm] | [PowerNorm][pownorm] | `linear`                                       |
| `y`                        | str | list\[float] | ndarray                                                            | `None`                                         |
| `y_scale`                  | 'linear' | 'log' | 'pow' | tuple\[float] | [LogNorm][lognorm] | [PowerNorm][pownorm] | `linear`                                       |
| `selection`                | list\[int]                                                                                | `[]`                                           |
| `order_by`                 | str | list\[int] | None                                                                 | `None`                                         |
| `order_map`                | list\[str] | None                                                                        | `None`                                         |
| `order_direction`          | 'asc' | 'desc'                                                                          | `'asc'`                                        |
| `order_na_values`          | 'first' | 'last' | None                                                                | `'last'`                                       |
| `width`                    | int | 'auto'                                                                            | `'auto'`                                       |
| `height`                   | int                                                                                      | `240`                                          |
| `color`                    | str | tuple\[float] | list\[float]                                                       | `(0, 0, 0, 0.66)`                              |
| `color_selected`           | str | tuple\[float] | list\[float]                                                       | `(0, 0.55, 1, 1)`                              |
| `color_hover`              | str | tuple\[float] | list\[float]                                                       | `(0, 0, 0, 1)`                                 |
| `color_by`                 | str | list\[float | str]                                                                | `None`                                         |
| `color_map`                | str | list\[str] | [Colormap][colormap] | dict | 'auto'                               | `None`                                         |
| `color_norm`               | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `color_order`              | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `opacity`                  | float                                                                                    | `0.66`                                         |
| `opacity_unselected`       | float                                                                                    | `0.5`                                         |
| `opacity_by`               | str | list\[float]                                                                       | `'density'`                                    |
| `opacity_map`              | triple\[float] | list\[float] | dict | 'auto'                                           | `None`                                         |
| `opacity_norm`             | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `opacity_order`            | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `size`                     | int                                                                                      | `3`                                            |
| `size_by`                  | str | list\[int]                                                                         | `None`                                         |
| `size_map`                 | triple\[float] | list\[int] | dict | 'auto'                                             | `None`                                         |
| `size_norm`                | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `size_order`               | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `connect_by`               | str | list\[int]                                                                         | `None`                                         |
| `connect_order`            | str | list\[int]                                                                         | `None`                                         |
| `connection_color`         | str | tuple\[float] | list\[float]                                                       | `(0, 0, 0, 0.1)`                               |
| `connection_color_selected`| str | tuple\[float] | list\[float]                                                       | `(0, 0.55, 1, 1)`                              |
| `connection_color_hover`   | str | tuple\[float] | list\[float]                                                       | `(0, 0, 0, 0.66)`                              |
| `connection_color_by`      | str | list\[float | str]                                                                | `None`                                         |
| `connection_color_map`     | str | list\[str] | [Colormap][colormap] | dict | 'auto'                               | `None`                                         |
| `connection_color_norm`    | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `connection_color_order`   | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `connection_opacity`       | float                                                                                    | `0.1`                                          |
| `connection_opacity_by`    | str | list\[float]                                                                       | `None`                                         |
| `connection_opacity_map`   | triple\[float] | list\[float] | dict | 'auto'                                           | `None`                                         |
| `connection_opacity_norm`  | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `connection_opacity_order` | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `connection_size`          | int                                                                                      | `2`                                            |
| `connection_size_by`       | str | list\[int]                                                                         | `None`                                         |
| `connection_size_map`      | triple\[float] | list\[int] | dict | 'auto'                                             | `None`                                         |
| `connection_size_norm`     | tuple\[float] | [Normalize][linnorm]                                                     | `matplotlib.colors.Normalize(0, 1, clip=True)` |
| `connection_size_order`    | list\[str | int] | 'reverse'                                                            | `None`                                         |
| `axes`                     | bool                                                                                     | `True`                                         |
| `axes_grid`                | bool                                                                                     | `False`                                        |
| `lasso_color`              | str | tuple\[float] | list\[float]                                                       | `(0, 0.666666667, 1, 1)`                       |
| `lasso_initiator`          | bool                                                                                     | `False`                                        |
| `lasso_min_delay`          | int                                                                                      | `10`                                           |
| `lasso_min_dist`           | int                                                                                      | `3`                                            |
| `lasso_on_long_press`      | bool                                                                                     | `True`                                         |
| `reticle`                  | bool                                                                                     | `True`                                         |
| `reticle_color`            | str | 'auto'                                                                            | `'auto'`                                       |
| `background_color`         | str                                                                                      | `'white'`                                      |
| `background_image`         | str | array-like or PIL image                                                           | `None`                                         |
| `mouse_mode`               | 'panZoom' | 'lasso' | 'rotate'                                                         | `'panZoom'`                                    |
| `camera_target`            | tuple\[float]                                                                             | `[0, 0]`                                       |
| `camera_distance`          | float                                                                                    | `1`                                            |
| `camera_rotation`          | float                                                                                    | `0`                                            |
| `camera_view`              | list\[float]                                                                              | `None`                                         |
| `zoom_to`                  | list\[int]                                                                                | `None`                                         |
| `zoom_animation`           | int                                                                                      | `500`                                          |
| `zoom_on_selection`        | list\[float]                                                                              | `0.33`                                         |
| `zoom_on_filter`           | list\[float]                                                                              | `False`                                        |
| `zoom_padding`             | list\[float]                                                                              | `False`                                        |
| `options`                  | dict                                                                                     | `{}`                                           |

[LogNorm]: https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.LogNorm.html

[PowNorm]: https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.PowerNorm.html

[LinNorm]: https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.Normalize.html

[Colormap]: https://matplotlib.org/3.5.0/api/_as_gen/matplotlib.colors.Colormap.html

## Widget {#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](#methods) are the idiomatic and recommended way to set widget properties.
:::

| Name                                     | Type                                                                                                                                   | Default      | Allow None | Read Only | Note  |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------- | --------- | ------------- |
| `dom_element_id`                         | str                                                                                                                                                                  |                                            |            | `True`    | For debugging |
| `data`                                   | 2D numerical array                                                                                                                                                   |                                            |            |           |               |
| `prevent_filter_reset`                   | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `selection`                              | int\[]                                                                                                                                                                |                                            | `True`     |           | Point indices |
| `filter`                                 | int\[]                                                                                                                                                                |                                            | `True`     |           | Point indices |
| `hovering`                               | int                                                                                                                                                                  |                                            | `True`     |           |               |
| `x_title`                                | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `y_title`                                | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `color_title`                            | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `opacity_title`                          | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `size_title`                             | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `x_scale`                                | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `y_scale`                                | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `color_scale`                            | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `opacity_scale`                          | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `size_scale`                             | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `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_histogram`                            | float\[]                                                                                                                                                              |                                            | `True`     |           |               |
| `y_histogram`                            | float\[]                                                                                                                                                              |                                            | `True`     |           |               |
| `color_histogram`                        | float\[]                                                                                                                                                              |                                            | `True`     |           |               |
| `opacity_histogram`                      | float\[]                                                                                                                                                              |                                            | `True`     |           |               |
| `size_histogram`                         | float\[]                                                                                                                                                              |                                            | `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_distance`                        | float                                                                                                                                                                |                                            |            |           |               |
| `camera_rotation`                        | float                                                                                                                                                                |                                            |            |           |               |
| `camera_view`                            | float\[]                                                                                                                                                              |                                            | `True`     |           | View matrix   |
| `zoom_to`                                | int\[]                                                                                                                                                                |                                            |            |           | Point indices |
| `zoom_animation`                         | int                                                                                                                                                                  | `1000`                                     |            |           | Animation time in milliseconds |
| `zoom_padding`                           | float                                                                                                                                                                | `0.333`                                    |            |           | Zoom padding relative to the bounding box of the points to zoom to |
| `zoom_on_selection`                      | bool                                                                                                                                                                 | `False`                                    |            |           | If `True` zoom to selected points automatically |
| `zoom_on_filter`                         | bool                                                                                                                                                                 | `False`                                    |            |           | If `True` zoom to filtered points automatically |
| `mouse_mode`                             | `"panZoom"` | `"lasso"` | `"rotate"`                                                                                                                               | `"panZoom"`                                |            |           |               |
| `lasso_initiator`                        | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `lasso_on_long_press`                    | bool                                                                                                                                                                 | `True`                                     |            |           |               |
| `axes`                                   | bool                                                                                                                                                                 | `True`                                     |            |           |               |
| `axes_grid`                              | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `axes_color`                             | \[float, float, float, float]                                                                                                                                         |                                            |            |           | RGBA          |
| `axes_labels`                            | bool | str\[]                                                                                                                                                        | `False`                                    |            |           |               |
| `legend`                                 | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `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_enable`                         | bool                                                                                                                                                                 | `False`                                    |            |           | Why 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_properties`                     | str\[]                                                                                                                                                                | `['x', 'y', 'color', 'opacity', 'size']`   |            |           |               |
| `tooltip_properties_non_visual_info`     | {}                                                                                                                                                                   |                                            |            |           |               |
| `tooltip_histograms`                     | bool                                                                                                                                                                 | `True`                                     |            |           |               |
| `tooltip_histograms_ranges`              | dict                                                                                                                                                                 | `True`                                     |            |           |               |
| `tooltip_histograms_size`                | `"small"` | `"medium"` | `"large"`                                                                                                                                 | `"small"`                                  |            |           |               |
| `tooltip_preview`                        | str                                                                                                                                                                  |                                            | `True`     |           |               |
| `tooltip_preview_type`                   | `"text"` | `"image"` | `"audio"`                                                                                                                                   | `"text"`                                   |            |           |               |
| `tooltip_preview_text_lines`             | int                                                                                                                                                                  | `3`                                        | `True`     |           |               |
| `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_image_height`           | int                                                                                                                                                                  | `None`                                     | `True`     |           |               |
| `tooltip_preview_audio_length`           | int                                                                                                                                                                  | `None`                                     | `True`     |           |               |
| `tooltip_preview_audio_loop`             | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `tooltip_preview_audio_controls`         | bool                                                                                                                                                                 | `True`                                     |            |           |               |
| `color`                                  | str| 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_selected`                         | str| str\[]| \[float, float, float, float]| \[float, float, float, float]\[]                                                                           | `[0, 0.55, 1, 1]`                          |            |           |               |
| `color_hover`                            | str| 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"`                                                                                                                                             | `None`                                     | `True`     |           |               |
| `opacity`                                | float | float\[]                                                                                                                                                     | `0.66`                                     |            |           |               |
| `opacity_unselected`                     | float | float\[]                                                                                                                                                     | `0.5`                                      |            |           |               |
| `opacity_by`                             | `"valueA"` | `"valueB"` | `"density"`                                                                                                                              | `"density"`                                | `True`     |           |               |
| `size`                                   | int | int\[] | float | float\[]                                                                                                                                     | `3`                                        |            |           |               |
| `size_by`                                | `"valueA"` | `"valueB"`                                                                                                                                             | `None`                                     | `True`     |           |               |
| `connect`                                | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `connection_color`                       | str| 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"`                                                                                                                            | `None`                                     | `True`     |           | Default value depends on the luminance of the background color. |
| `connection_color_selected`              | str| str\[]| \[float, float, float, float]| \[float, float, float, float]\[]                                                                           | `[0, 0.55, 1, 1]`                          |            |           |               |
| `connection_color_hover`                 | str| 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_opacity`                     | float | float\[]                                                                                                                                                     | `0.1`                                      |            |           |               |
| `connection_opacity_by`                  | `"valueA"` | `"valueB"` | `"segment"`                                                                                                                              | `None`                                     | `True`     |           |               |
| `connection_size`                        | int | int\[] | float | float\[]                                                                                                                                     | `2`                                        |            |           |               |
| `connection_size_by`                     | `"valueA"` | `"valueB"` | `"segment"`                                                                                                                              | `None`                                     | `True`     |           |               |
| `width`                                  | int | `"auto"`                                                                                                                                                      | `"auto"`                                   |            |           |               |
| `height`                                 | int                                                                                                                                                                  | `240`                                      |            |           |               |
| `background_color`                       | str | \[float, float, float, float]                                                                                                                                  | `"white"`                                  |            |           |               |
| `background_image`                       | str                                                                                                                                                                  | `None`                                     | `True`     |           |               |
| `lasso_color`                            | str | \[float, float, float, float]                                                                                                                                  | `[0, 0.666666667, 1, 1]`                   |            |           |               |
| `lasso_min_delay`                        | int                                                                                                                                                                  | `10`                                       |            |           |               |
| `lasso_min_dist`                         | float                                                                                                                                                                | `3`                                        |            |           |               |
| `reticle`                                | bool                                                                                                                                                                 | `True`                                     |            |           |               |
| `reticle_color`                          | str| \[float, float, float, float]| `"auto"`                                                                                                              | `"auto"`                                   |            |           |               |
| `other_options`                          | dict                                                                                                                                                                 | `{}`                                       |            |           | For setting other [regl-scatterplot properties](https://github.com/flekschas/regl-scatterplot/?tab=readme-ov-file#properties). Note that whatever is defined in options will be overwritten by the short-hand options |
| `view_reset`                             | bool                                                                                                                                                                 | `False`                                    |            |           |               |
| `view_download`                          | bool                                                                                                                                                                 | `None`                                     | `True`     |           |               |
| `view_data`                              | int\[]                                                                                                                                                                | `None`                                     | `True`     | `True`    | [Uint8ClampedArray](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/data) |
| `view_shape`                             | \[int, int]                                                                                                                                                           | `None`                                     | `True`     | `True`    |               |
| `view_sync`                              | str                                                                                                                                                                  | `None`                                     | `True`     |           | For synchronyzing view changes across scatter plot instances |

## Plotting Shorthand {#plotting}

### plot(*x=Undefined*, *y=Undefined*, *data=Undefined*, *\*\*kwargs*) {#plot}

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

**Arguments:** are the same as of [`Scatter`](#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*) {#compose}

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
)
```

### link(*scatters*, *match\_by="index"*, *cols=None*, *rows=1*, *row\_height=320*) {#link}

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()`](#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 {#okabe-ito}

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

* ![#56B4E9](https://placehold.co/16x16/56B4E9/56B4E9) `Sky blue (#56B4E9)`
* ![#E69F00](https://placehold.co/16x16/E69F00/E69F00) `Orange (#E69F00)`
* ![#009E73](https://placehold.co/16x16/009E73/009E73) `Bluish green (#009E73)`
* ![#F0E442](https://placehold.co/16x16/F0E442/F0E442) `Yellow (#F0E442)`
* ![#0072B2](https://placehold.co/16x16/0072B2/0072B2) `Blue (#0072B2)`
* ![#D55E00](https://placehold.co/16x16/D55E00/D55E00) `Vermillion (#D55E00)`
* ![#CC79A7](https://placehold.co/16x16/CC79A7/CC79A7) `Reddish Purple (#CC79A7)`
* ![#000000](https://placehold.co/16x16/000000/000000) `Black (#000000)`

**Example:**

```py
from jscatter import Scatter, okabe_ito
```

### glasbey\_light {#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](https://colorcet.holoviz.org) package, which employs an algorithm developed by [Glasbey et al., 2007](https://strathprints.strath.ac.uk/30312/1/colorpaper_2006.pdf).

**Example:**

```py
from jscatter import Scatter, glasbey_light
```

### glasbey\_dark {#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](https://colorcet.holoviz.org) package, which employs an algorithm developed by [Glasbey et al., 2007](https://strathprints.strath.ac.uk/30312/1/colorpaper_2006.pdf).

**Example:**

```py
from jscatter import Scatter, glasbey_dark
```

### 2D Color Maps

We provide 2D colormaps from [pycolormap-2d](https://pypi.org/project/pycolormap-2d/).

* `ColorMap2DBremm`
* `ColorMap2DCubeDiagonal`
* `ColorMap2DSchumann`
* `ColorMap2DSteiger`
* `ColorMap2DTeuling2`
* `ColorMap2DZiegler`

**Example:**

```py
from jscatter import Scatter, ColorMap2DBremm
from matplotlib.colors import to_hex

cmap = ColorMap2DBremm(
    range_x=(df.x.min(), df.x.max()),
    range_y=(df.y.min(), df.y.max()),
)

group_cmap = {}

for group in df.groups.unique():
    mask = df.groups == group
    
    # Determine the median center of the group
    cx = df[mask].x.median()
    cy = df[mask].y.median()

    # Get color from Brenn's 2D color map
    color = cmap(cx, cy)

    # Convert to HEX
    group_cmap[group] = to_hex(color / 255)

scatter = Scatter(data=df, x='x', y='y', color_by='groups', color_map=group_cmap)
scatter.show()
```

### Utility Functions

Jupyter Scatter exposes the following utility functions for coloring points:

* `brighten(color: Color, factor: float)`
* `darken(color: Color, factor: float)`
* `saurate(color: Color, factor: float)`
* `desaturate(color: Color, factor: float)`

## 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](https://en.wikipedia.org/wiki/Contour_line) annotation. Under
the hood the annotation uses [Seaborn's `kdeplot`](https://seaborn.pydata.org/generated/seaborn.kdeplot.html).

**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`](https://seaborn.pydata.org/generated/seaborn.kdeplot.html). \[optional]

**Examples:**

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

## LabelPlacement

The `LabelPlacement` class handles the positioning of labels for data points
while managing collisions and optimizing label density using a tiling approach.

* [LabelPlacement](#LabelPlacement)
  * [Methods](#labelplacement.methods)
    * [compute()](#labelplacement.compute), [reset()](#labelplacement.reset), and [clone()](#labelplacement.clone)
    * [to\_parquet()](#labelplacement.to_parquet) and [from\_parquet()](#labelplacement.from_parquet)
    * [get\_labels\_from\_tiles()](#labelplacement.get_labels_from_tiles)
  * [Properties](#labelplacement.properties)

### LabelPlacement(*data*, *by*, *x*, *y*, *\*\*kwargs*) {#LabelPlacement}

Creates a new label placement instance that positions labels based on data
coordinates while handling label collisions.

**Arguments:**

* `data` : pandas.DataFrame
  * DataFrame with x, y coordinates and categorical columns.

* `by` : str or list of str
  * Column name(s) used for labeling points. The referenced columns must contain either string or categorical values and are treated as categorical internally such that each category marks a group of points to be labeled as the category.

  * To display individual point labels (where each row gets its own label), append an exclamation mark to the column name. For instance, `"city!"` would indicate that each value in this column should be treated as a unique label rather than grouping identical values together.

  * Note: Currently only one column can be marked with an exclamation mark. If multiple columns are marked, only the first one is treated as containing point labels.

* `x` : str
  * Name of the x-coordinate column.

* `y` : str
  * Name of the y-coordinate column.

* `tile_size` : int, default=256
  * Size of the tiles used for label placement in pixels. This determines the granularity of label density control and affects how labels are displayed at different zoom levels.

* `importance` : str, optional
  * Column name containing importance values. These values determine which labels are prioritized when there are conflicts.

* `importance_aggregation` : {'min', 'mean', 'median', 'max', 'sum'}, default='mean'
  * Method used to aggregate importance values when multiple points share the same label. This affects how label importance is calculated for groups of points.

* `hierarchical` : bool, default=False
  * If True, the label types specified by `by` are expected to be hierarchical, which will affect the priority sorting of labels such that labels with a lower hierarchical index are displayed first.

* `zoom_range` : tuple of floats or list of tuple of floats or dict of tuple of floats, default=(-∞, ∞)
  * The range at which labels of a specific type (as specified with `by`) are allowed to appear. The zoom range is a tuple of zoom levels, where `zoom_scale == 2 ** zoom_level`. Default is (-∞, ∞) for all labels.

* `font` : Font or list of Font or dict of Font, default=DEFAULT\_FONT\_FACE
  * Font object(s) for text measurement. Can be specified as:
    * Single Font: Applied to all label types
    * List of Fonts: One font per label type in `by`
    * Dict: Maps label types or specific labels to fonts

* `size` : int or list of int or dict of int or 'auto', default='auto'
  * Font size(s) for label text. Can be specified as:
    * 'auto': Automatically assign sizes (hierarchical if hierarchical=True)
    * Single int: Uniform size for all labels
    * List of ints: One size per label type in `by`
    * Dict: Maps label types or specific labels to sizes

* `color` : color or list of color or dict of color or 'auto', default='auto'
  * Color specification for labels. Can be:
    * 'auto': Automatically choose based on background
    * str: Named color or hex code
    * tuple: RGB(A) values
    * list: Different colors for different hierarchy levels
    * dict: Mapping of label types or specific labels to colors

* `background` : color, default='white'
  * Background color. Used for determining label colors when color='auto'.

* `bbox_percentile_range` : tuple of float, default=(5, 95)
  * Range of percentiles to include when calculating the bounding box of points for label placement. This helps exclude outliers when determining where to place labels.

* `max_labels_per_tile` : int, default=100
  * Maximum number of labels per tile. Controls label density by limiting how many labels can appear in a given region. Set to 0 for unlimited.

* `scale_function` : {'asinh', 'constant'}, default='constant'
  * Label zoom scale function for zoom level calculations:
    * 'asinh': Scales labels by the inverse hyperbolic sine, initially increasing linearly but quickly plateauing
    * 'constant': No scaling with zoom, labels maintain the same size

* `positioning` : {'highest\_density', 'center\_of\_mass', 'largest\_cluster'}, default='highest\_density'
  * Method used to determine the position of each label:
    * 'highest\_density': Position label at the highest density point
    * 'center\_of\_mass': Position label at the center of mass of all points
    * 'largest\_cluster': Position label at the center of the largest cluster

* `exclude` : list of str, default=\[]
  * Specifies which labels should be excluded. Can contain:
    * Column names (e.g., `"country"`) to exclude an entire category
    * Column-value pairs (e.g., `"country:USA"`) to exclude specific labels

* `target_aspect_ratio` : float, optional
  * If not `None`, labels will potentially receive line breaks such that their bounding box is as close to the specified aspect ratio as possible. The aspect ratio is width/height.

* `max_lines` : int, optional
  * Specify the maximum number of lines a label should be broken into if `target_aspect_ratio` is not `None`.

* `verbosity` : {'debug', 'info', 'warning', 'error', 'critical'}, default='warning'
  * Controls the level of logging information displayed during label placement computation.

**Returns:** A new `LabelPlacement` instance.

**Examples:**

```python
from jscatter import LabelPlacement

# Basic usage
label_placement = LabelPlacement(
    data=df,
    by='country',
    x='longitude',
    y='latitude'
)

# Computing the labels
label_placement.compute()

# Use in a scatter plot
scatter.label(using=label_placement)
```

### Methods  {#labelplacement.methods}

#### compute(*show\_progress=False*, *chunk\_size=1024*) {#labelplacement.compute}

Compute the labels with full collision detection and density control.

**Arguments:**

* `show_progress` : bool, default=False
  * Whether to show a progress bar during computation.
* `chunk_size` : int, default=1024
  * The chunk size for parallel processing.

**Returns:**

* pandas.DataFrame - Computed labels ready for rendering

**Example:**

```python
label_placement = LabelPlacement(data=df, by='country', x='x', y='y')
labels = label_placement.compute(show_progress=True)
```

#### reset() {#labelplacement.reset}

Reset the computed labels, allowing spatial properties to be modified before recomputing labels.

**Note:** This method clears existing labels and tiles to allow spatial properties to be changed. Call compute() again after modifying properties.

**Example:**

```python
label_placement.reset()
label_placement.color = {'country': 'red'}
label_placement.compute()
```

#### clone(*\*\*kwargs*) {#labelplacement.clone}

Create a new LabelPlacement instance with the same configuration, optionally overriding specific parameters.

**Arguments:**

* `**kwargs` - Any parameters to override from the current instance

**Returns:**

* LabelPlacement - A new instance with the specified configuration

**Example:**

```python
# Clone the current instance but with different positioning
new_label_placement = label_placement.clone(positioning='center_of_mass')
```

#### to\_parquet(*path*, *format='parquet'*) {#labelplacement.to\_parquet}

Export label placement data to storage.

**Arguments:**

* `path` : str
  * Path where the data will be stored. For parquet format, this should be a directory.
  * For arrow\_ipc format, this should be a file path.
* `format` : str, default="parquet"
  * Format to use for persistence. Options are "parquet" or "arrow\_ipc".

**Example:**

```python
label_placement.to_parquet('my_dataset')
```

#### from\_parquet(*path*, *format=None*) {#labelplacement.from\_parquet}

Load label placement data from storage.

**Arguments:**

* `path` : str
  * Path where the data is stored. For parquet format, this should be a directory.
  * For "arrow\_ipc" format, this should be a file path.
* `format` : "parquet" or "arrow\_ipc", optional
  * Format to use for loading. Options are "parquet" or "arrow\_ipc".
  * If None, will be determined from the path.

**Returns:**

* LabelPlacement - Loaded label placement object

**Example:**

```python
label_placement = LabelPlacement.from_parquet('my_dataset')
```

#### get\_labels\_from\_tiles(*tile\_ids*) {#labelplacement.get\_labels\_from\_tiles}

Get labels from data tiles.

**Arguments:**

* `tile_ids` : list of str
  * Tile IDs

**Returns:**

* pandas.DataFrame - Labels from the data tiles

**Example:**

```python
tile_labels = labels.get_labels_from_tiles(['0,0,0', '1,0,0'])
```

### Properties {#labelplacement.properties}

#### computed {#labelplacement.computed}

Get whether labels have been computed or not.

**Returns:**

* bool - If `True` the labels have been computed

#### loaded\_from\_persistence {#labelplacement.loaded\_from\_persistence}

Get whether this is a restored instance.

**Returns:**

* bool - If `True` the labels have been restored from files.

#### background {#labelplacement.background}

Get or set the current background color.

**Returns:**

* Color - The background color

#### color {#labelplacement.color}

Get or set the current font color mapping.

**Returns:**

* Dict\[str, str] - A dictionary mapping each label type and specific label to its color.

#### font {#labelplacement.font}

Get the current font face mapping.

**Returns:**

* Dict\[str, Font] - A dictionary mapping each label type and specific label to its font face.

**Note:** This property is read-only after labels have been computed as changing font faces may affect spatial placement.

#### size {#labelplacement.size}

Get the current font size mapping.

**Returns:**

* Dict\[str, int] - A dictionary mapping each label type and specific label to its size.

**Note:** This property is read-only after labels have been computed as changing font sizes may affect spatial placement.

#### zoom\_range {#labelplacement.zoom\_range}

Get the current zoom range mapping.

**Returns:**

* Dict\[str, Tuple\[np.float64, np.float64]] - A dictionary mapping each label type and specific label to its zoom range.

**Note:** This property is read-only after labels have been computed as changing zoom ranges affects spatial placement.

#### exclude {#labelplacement.exclude}

Get or set the current exclude mapping.

**Returns:**

* List\[str] - A list of label types and specific labels to be excluded.

#### data {#labelplacement.data}

Get the input data.

**Returns:**

* pandas.DataFrame - The input data

#### x {#labelplacement.x}

Get the name of the x-coordinate column.

**Returns:**

* str - Column name

#### y {#labelplacement.y}

Get the name of the y-coordinate column.

**Returns:**

* str - Column name

#### by {#labelplacement.by}

Get the column name(s) defining the label hierarchy.

**Returns:**

* List\[str] - Column names

#### hierarchical {#labelplacement.hierarchical}

Get whether the labels are hierarchical.

**Returns:**

* bool - True if labels are hierarchical

#### importance {#labelplacement.importance}

Get the name of the importance column.

**Returns:**

* Optional\[str] - Column name or None

#### importance\_aggregation {#labelplacement.importance\_aggregation}

Get the importance aggregation method.

**Returns:**

* str - The aggregation method ('min', 'mean', 'median', 'max', or 'sum')

#### bbox\_percentile\_range {#labelplacement.bbox\_percentile\_range}

Get the percentile range for bounding box calculation.

**Returns:**

* Tuple\[float, float] - The percentile range

#### tile\_size {#labelplacement.tile\_size}

Get the tile size.

**Returns:**

* int - Tile size in pixels

#### max\_labels\_per\_tile {#labelplacement.max\_labels\_per\_tile}

Get the maximum number of labels per tile.

**Returns:**

* int - Maximum number of labels per tile

#### scale\_function {#labelplacement.scale\_function}

Get the label zoom scale function.

**Returns:**

* str - The scale function ('asinh' or 'constant')

#### positioning {#labelplacement.positioning}

Get the label positioning method.

**Returns:**

* str - The positioning method ('highest\_density', 'center\_of\_mass', or 'largest\_cluster')

#### target\_aspect\_ratio {#labelplacement.target\_aspect\_ratio}

Get the target aspect ratio for line break optimization.

**Returns:**

* Optional\[float] - The target aspect ratio or None

#### max\_lines {#labelplacement.max\_lines}

Get the maximum number of lines for line break optimization.

**Returns:**

* Optional\[int] - The maximum number of lines or None

#### verbosity {#labelplacement.verbosity}

Get or set the current log level.

**Returns:**

* str - The current log level

#### labels {#labelplacement.labels}

Get the computed labels, if available.

**Returns:**

* Optional\[pandas.DataFrame] - The computed labels or None

#### tiles {#labelplacement.tiles}

Get the tile mapping, if available.

**Returns:**

* Optional\[Dict\[str, List\[int]]] - The tile mapping or None