🕹 Jupyter Widgets

EOmaps provides a set of pre-configured Jupyter Widgets that can be used to create interactive browser controls for a map.

These widgets work just like any other Jupyter Widgets, but they have a pre-configured handler to perform commonly used tasks (switching layers, overlay layers, add/remove callbacks etc.)

Note

Widgets are intended for Jupyter Notebooks and require the additional dependencies: ipywidgets and ipympl.
They will only work if you use the interactive ipympl (widget) backend. To activate, use the %matplotlib widget magic command.

You can install the required additional dependencies with one of the following commands:

pip

pip install ipywidgets, ipympl

conda / mamba

conda install -c conda-forge ipywidgets, ipympl

or

mamba install -c conda-forge ipywidgets, ipympl

Layer selector widgets

Layer selector widgets can be used to change the visible layer of a map.

How to use the widgets

To attach a widget to a map, all you need to do is to pass the associated Maps object as first argument on initialization. (e.g. use Widget(m) to connect the widget to the Maps object m)

In addition to the ipywidget-arguments, they support the following (optional) arguments:

layers: A list of layer specs [<specs 1>, <specs 2>, ...] to use in the widget.
<specs>can be one of:
- A single layer-name "layer_name" or a tuple ("layer_name", transparency)
- A tuple of multiple layer-names (and/or transparencies): ("layer_name_1", ("layer_name_2", 0.5), ...)
- A list of a custom labels and a layer-assignments: ["Custom label", <layer specs>]

For example, here’s how you can connect the available layer-selection widgets to the following map:

%matplotlib widget
from eomaps import Maps, widgets

m = Maps(figsize=(6, 2), layer="coastline")
m.add_feature.preset.coastline()

m.add_feature.preset.countries(layer="countries")
m.add_feature.preset.ocean(layer="ocean")
m.show()

Widgets to display a single specific layer

layer_button = widgets.LayerButton(m, layer="ocean", description="Show ocean layer")

display(layer_button)

Widgets to select one layer of a list of layers

selector_widgets = [
    widgets.LayerToggleButtons(m),
    widgets.LayerRadioButtons(m),
    widgets.LayerSelect(m),
    widgets.LayerDropdown(m),
    widgets.LayerSelectionSlider(m)
]

display(*selector_widgets)

Widgets to overlay multiple layers

multi_selector_widgets = [
    widgets.LayerSelectMultiple(m),
    widgets.LayerSelectionRangeSlider(m)
]

display(*multi_selector_widgets)

Tip

You can style the widgets as any other Jupyter Widget (more info in the Widget Styling section of the ipywidgets docs.)

To display widgets next to a figure, use the canvas of the figure:

display(m.f.canvas, ... other widgets...)

To arrange widgets, checkout the container and Layout widgets like HBox([list of widgets]), VBox([list of widgets])!

from ipywidgets import HBox, VBox

custom_selector = widgets.LayerSelectMultiple(
    m,
    layers=[["A nice coastline", "coastline"], 
            ["Overlay 'coastline' + 'ocean'", ("coastline", "ocean")],
            ["Transparent overlay: 'coastline' + 'ocean'", ("coastline", ("ocean", 0.4))]
           ],
    layout=dict(width='35%', height='80px', )
)

display(HBox([custom_selector, m.f.canvas]))

buttons = [
    widgets.LayerButton(m, layer="ocean", description="Show ocean layer", layout=dict(width="25ex", height="5ex")),
    widgets.LayerButton(m, layer="coastline", description="Show coastline layer", layout=dict(width="25ex", height="5ex"))
]
for b in buttons:
    b.style.font_weight = 'bold'
    b.style.font_size = '20px'
buttons[0].style.button_color = 'lightblue'
buttons[1].style.button_color = '#d0a2b9'

display(HBox([VBox(buttons), m.f.canvas]))

Callback Widgets

Callback widgets are used to toggle callbacks on a map.

How to use the widgets

To attach a widget to a map, all you need to do is to pass the associated Maps object as first argument on initialization. (e.g. use Widget(m) to connect the widget to the Maps object m)

All additional arguments will be passed to the corresponding callback (e.g. m.cb.< METHOD >.attach.< NAME >(**kwargs))

checkboxes = [
    widgets.ClickAnnotateCheckbox(m),
    widgets.ClickMarkCheckbox(m),
    widgets.ClickPrintToConsoleCheckbox(m),
    widgets.ClickPeekLayerCheckbox(m, layer="ocean"),
    widgets.ClickMarkCheckbox(m),
    widgets.ClickPrintToConsoleCheckbox(m),
    widgets.PickAnnotateCheckbox(m),
    widgets.PickMarkCheckbox(m),
    widgets.PickPrintToConsoleCheckbox(m)
]

display(*checkboxes)

`LayerDropdown`	A Dropdown list to select the visible layer.
`LayerSelect`	A list-box to select a single visible layer.
`LayerSelectMultiple`	A list-box to select multiple visible layers.

`LayerSelectionSlider`	A slider to select a single visible layer.
`LayerSelectionRangeSlider`	A range-slider to view a combination of a range of layers.

`LayerButton`	A Button to show a selected layer.
`LayerRadioButtons`	Radio buttons to select a single visible layer.
`LayerToggleButtons`	Toggle buttons to select a single visible layer.

`ClickAnnotateCheckbox`	Checkbox to toggle the 'click.annotate' callback.
`ClickMarkCheckbox`	Checkbox to toggle the 'click.mark' callback.
`ClickPrintToConsoleCheckbox`	Checkbox to toggle the 'click.print_to_console' callback.
`ClickPeekLayerCheckbox`	Checkbox to toggle the 'click.peek_layer' callback.

`ClickMarkCheckbox`	Checkbox to toggle the 'click.mark' callback.
`ClickPrintToConsoleCheckbox`	Checkbox to toggle the 'click.print_to_console' callback.