Skip to content

DataFilterExtension

lonboard.layer_extension.DataFilterExtension

Adds GPU-based data filtering functionalities to layers. It allows the layer to show/hide objects based on user-defined properties.

Example

from lonboard import Map, ScatterplotLayer
from lonboard.colormap import apply_continuous_cmap
from lonboard.layer_extension import DataFilterExtension

gdf = gpd.GeoDataFrame(...)
extension = DataFilterExtension()
layer = ScatterplotLayer.from_geopandas(
    gdf,
    extensions=[extension],
    get_filter_value=gdf["filter_value"], # replace with desired column
    filter_range=[0, 5] # replace with desired filter range
)

The DataFilterExtension allows filtering on 1 to 4 attributes at the same time. So if you have four numeric columns of interest, you can filter on the intersection of all of them.

For easy visualization, we suggest connecting the DataFilterExtension to an interactive slider from ipywidgets.

from ipywidgets import FloatRangeSlider

slider = FloatRangeSlider(
    value=(2, 5),
    min=0,
    max=10,
    step=0.1,
    description="Slider: "
)
slider

jsdlink(
    (slider, "value"),
    (layer, "filter_range")
)

If you have 2 to 4 columns, use a MultiRangeSlider, which combines multiple FloatRangeSlider objects in a form that the DataFilterExtension expects.

from ipywidgets import FloatRangeSlider, jsdlink

slider1 = FloatRangeSlider(
    value=(2, 5),
    min=0,
    max=10,
    step=0.1,
    description="First slider: "
)
slider2 = FloatRangeSlider(
    value=(30, 40),
    min=0,
    max=50,
    step=1,
    description="Second slider: "
)
multi_slider = MultiRangeSlider([slider1, slider2])
multi_slider

jsdlink(
    (multi_slider, "value"),
    (layer, "filter_range")
)

Important notes

  • The DataFilterExtension only supports float32 data, so integer data will be casted to float32.
  • The DataFilterExtension copies all data referenced by get_filter_value to the GPU, so it will increase memory pressure on the GPU.

Layer Properties

This extension dynamically enables the following properties onto the layer(s) where it is included:

filter_categories

The list of categories that should be rendered. If an object's filtered category is in the list, the object will be rendered; otherwise it will be hidden. This prop can be updated on user input or animation with very little cost.

Format:

  • If category_size is 1: ['category1', 'category2']
  • If category_size is 2 to 4: [['category1', 'category2', ...], ['category3', ...], ...] for each filtered property, respectively.

The maximum number of supported is determined by the category_size:

  • If category_size is 1: 128 categories
  • If category_size is 2: 64 categories per dimension
  • If category_size is 3 or 4: 32 categories per dimension.

If this value is exceeded any categories beyond the limit will be ignored.

Default: [0]

filter_enabled

Enable/disable the data filter. If the data filter is disabled, all objects are rendered.

  • Type: bool, optional
  • Default: True

filter_range

The bounds which defines whether an object should be rendered. If an object's filtered value is within the bounds, the object will be rendered; otherwise it will be hidden. This prop can be updated on user input or animation with very little cost.

Format:

If filter_size is 1, provide a single tuple of (min, max).

If filter_size is 2 to 4, provide a list of tuples: [(min0, max0), (min1, max1), ...] for each filtered property, respectively.

  • Type: either Tuple[float, float] or List[Tuple[float, float]], optional
  • Default: (-1, 1)

filter_soft_range

If specified, objects will be faded in/out instead of abruptly shown/hidden.

When the filtered value is outside of the bounds defined by filter_soft_range but still within the bounds defined by filter_range, the object will be rendered as "faded".

  • Type: Tuple[float, float], optional
  • Default: None

filter_transform_size

When an object is "faded", manipulate its size so that it appears smaller or thinner. Only works if filter_soft_range is specified.

  • Type: bool, optional
  • Default: True

filter_transform_color

When an object is "faded", manipulate its opacity so that it appears more translucent. Only works if filter_soft_range is specified.

  • Type: bool, optional
  • Default: True

get_filter_value

Accessor to retrieve the value for each object that it will be filtered by.

  • Type: FilterValueAccessor
    • If a scalar value is provided, it is used as the value for all objects.
    • If an array is provided, each value in the array will be used as the value for the object at the same row index.

get_filter_category

Accessor to retrieve the category for each object that it will be filtered by.

  • Type: FilterValueAccessor
    • If a scalar value is provided, it is used as the value for all objects.
    • If an array is provided, each value in the array will be used as the value for the object at the same row index.

category_size class-attribute instance-attribute 

category_size = tag(sync=True)

The size of the category filter (number of columns to filter by).

The category filter can show/hide data based on 1-4 properties of each object.

  • Type: int. This is required if using category-based filtering.
  • Default 0.

filter_size class-attribute instance-attribute 

filter_size = tag(sync=True)

The size of the filter (number of columns to filter by).

The data filter can show/hide data based on 1-4 numeric properties of each object.

  • Type: int. This is required if using range-based filtering.
  • Default 1.