Note

Rendering widgets in a Jupyter notebook requires ipywidgets, an optional dependency. See the guide for installation and troubleshooting instructions.

However, you can still create widgets, and publish Workflows using them, without ipywidgets installed.

Widgets make it easy to interactively explore your Workflows code, without dealing with ipywidgets or callback functions. You can use widgets just like normal Workflows values.

All widget functions return subclasses of the Widget base class.

Read more in the widget section of the Workflows guide.

Widgets

Functions:

checkbox(name[, default, label])	A checkbox widget, which acts as a Bool parameter.
date(name, default[, label])	A date-picker widget, which acts as a Datetime parameter.
input(name, default[, label])	A box to type Str, Int, or Float values into.
image(name[, default_layer, label, map])	A widget, which acts as an Image parameter, to select one of the current layers on the map.
imagecollection(name[, default_layer, …])	A widget, which acts as an ImageCollection parameter, to select one of the current layers on the map.
select(name, options[, format, default, label])	A widget (dropdown, radio buttons, etc.) to select a value from a list of options.
slider(name, min, max[, step, default, label])	A slider, which acts as an Int or Float parameter.

checkbox(name: str, default: bool = False, label: str = '')

A checkbox widget, which acts as a Bool parameter.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.checkbox("param_name", default=True, label="A string parameter")  

>>> s2 = wf.ImageCollection.from_id(
...     "sentinel-2:L1C", "2018-01-01", "2018-04-01",
...     processing_level=wf.ifelse(
...         wf.widgets.checkbox("surface", default=True, label="Use surface reflectance"),
...         wf.Str("surface"),
...         wf.Str("toa"),
...     )
... ).pick_bands("red green blue")
>>> s2.visualize("Sentinel-2", scales=[[0, 0.4], [0, 0.4], [0, 0.4]])  
>>> # ^ when you call .visualize, the `checkbox` widget will automatically show up below

Clicking the checkbox above will toggle atmospheric correction on and off. (If you haven’t already, run wf.map in another notebook cell to see your layer.)

Parameters:

• name (str) – The name of the parameter.
• default (bool, default False) – The default value for the widget.
• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.

Returns:

widget – A Widget object that acts just like a Workflows Bool, and displays as a checkbox.

Return type:

Checkbox

date(name: str, default: Union[str, datetime.date, datetime.datetime], label: str = '')

A date-picker widget, which acts as a Datetime parameter.

The value of the widget and the date displayed on it are always in UTC.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.date("param_name", default="2020-11-03", label="The date")  

>>> s2 = wf.ImageCollection.from_id(
...     "sentinel-2:L1C",
...     start_datetime=wf.widgets.date("start", default="2020-11-03"),
...     end_datetime=wf.widgets.date("end", default="2020-12-03"),
... ).pick_bands("red green blue")
>>> s2.visualize("Sentinel-2", scales=[[0, 0.4], [0, 0.4], [0, 0.4]], reduction="median")  
>>> # ^ when you call .visualize, the two `date` widgets will automatically show up below

Selecting different dates will change the date range for the imagery. (If you haven’t already, run wf.map in another notebook cell to see your layer.)

Parameters:

• name (str) – The name of the parameter.
• default (Union[str, datetime.date, datetime.datetime]) –

  The default value for the widget, as an ISO-formatted timestamp string (like "2020-01-01"), or a Python date or datetime object.

  If given as a string without a timezone offset, or a Python datetime.date object, it’s assumed to be in UTC (consistent with Datetime.from_string).

  Otherwise, if given as a Python datetime.datetime object without a timezone, it’s assumed to be in system local time, and converted to UTC with default.astimezone(datetime.timezone.utc)

• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.

Returns:

widget – A Widget object that acts just like a Workflows Datetime, and displays as a date picker.

Return type:

Date

input(name: str, default: Primitive, label: str = '')

A box to type Str, Int, or Float values into.

Depending on the type of value you pass for default, the widget will represent a Str, an Int, or a Float parameter.

Note: updates happen when you press Enter or click out of the box, not on every keystroke.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.input("param_name", default="hello", label="A string parameter")  
>>> s2 = wf.ImageCollection.from_id("sentinel-2:L1C", "2018-01-01", "2018-04-01").pick_bands("red green blue")
>>> img = s2[wf.widgets.input("index", default=0)]
>>> img.visualize("One S2 image", scales=[[0, 0.4], [0, 0.4], [0, 0.4]])  
>>> # ^ when you call .visualize, the `input` widget will automatically show up below

Parameters:

• name (str) – The name of the parameter.
• default (str, int, float) – The default value for the widget.
• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.

Returns:

widget – A Widget object that acts just like a Workflows Str, Int, or Float and displays as an input box.

Return type:

Union[StringInput, IntInput, FloatInput]

Notes

Typing a different number into the input box above will cause the map to update and display the Image at that index in the ImageCollection. (If you haven’t already, run wf.map in another notebook cell to see your layer.)

image(name: str, default_layer: WorkflowsLayer = None, label: str = '', map: Union[Map, MapApp, None] = None)

A widget, which acts as an Image parameter, to select one of the current layers on the map.

Using this widget, you can create layers which use other layers as input, and update themselves when those input layers change.

Its value is equivalent to the selected layer, with all of its current parameter values applied. If you’ve selected a layer showing an ImageCollection, that layer’s current reduction is also applied.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.image("param_name", default_layer=some_layer, label="The input Image", map=wf.map)  

Use image widgets to show areas that have changed between any two layers on the map:

>>> # add some layers to the map, one for each year
>>> layers = []
>>> for year in [2017, 2018, 2019, 2020]:
...     ic = (
...         wf.ImageCollection.from_id("sentinel-2:L1C", f"{year}-01-01", f"{year}-04-01")
...         .pick_bands("red green blue")
...     )
...     lyr = ic.visualize(
...         f"Winter {year}", scales=[[0, 0.4], [0, 0.4], [0, 0.4]], reduction="median"
...     ) 
...     layers.append(lyr)  

>>> before = wf.widgets.image("before", default_layer=layers[0])  
>>> after = wf.widgets.image("after", default_layer=layers[-1])  
>>> delta = after.mean(axis="bands") - before.mean(axis="bands")  
>>> change = abs(delta) > 0.15  
>>> changed = change.mask(~change)  
>>> changed.visualize("Changed", scales=[0, 2], colormap="Reds")  
>>> # ^ when you call .visualize, the two `image` widgets will automatically show up below

As you select different layers for the before and after dropdowns, the map will update to show which pixels are different between them. Notice that changes to the input layers, such as switching the redution operation, will also cause the changed layer to update. (If you haven’t already, run wf.map in another notebook cell to see your layers on the map.)

Parameters:

• name (str) – The name of the parameter.
• default_layer (Optional[WorkflowsLayer], default None) –

  The layer selected by default. (A WorkflowsLayer is the object returned by visualize). If None, no layer will be selected, and nothing will display until you pick a layer from the dropdown.

  Unlike with other widget types, when you publish an object that depend on an image widget, the default_layer isn’t stored. Anyone who accesses your published object won’t see the same default layer; for them, it will be None.

• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.
• map (Optional[Union[Map, MapApp]], default None) – The Map or MapApp object to list layers from. If None (default), lists the layers on wf.map.

Returns:

widget – A Widget object that acts just like a Workflows Image, and displays as a dropdown listing the layer names currently on the map.

Return type:

Image

imagecollection(name: str, default_layer: WorkflowsLayer = None, label: str = '', map: Union[Map, MapApp] = None)

A widget, which acts as an ImageCollection parameter, to select one of the current layers on the map.

Using this widget, you can create layers which use other layers as input, and update themselves when those input layers change.

Its value is equivalent to the selected layer, with all of its current parameter values applied.

Unlike image, this widget will only list layers that display ImageCollections, not Images.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.imagecollection(
...     "param_name",
...     default_layer=some_layer,
...     label="The input ImageCollection",
...     map=wf.map,
... )  

Use an imagecollection widget to filter out cloudy scenes from any layer on the map:

>>> # add some layers to the map, one for each product (Sentinel-2 and Landsat-8)
>>> layers = []
>>> for product in ["sentinel-2:L1C", "landsat:LC08:01:T1:TOAR"]:
...     ic = (
...         wf.ImageCollection.from_id(product, "2019-01-01", "2019-03-01")
...         .pick_bands("red green blue")
...     )
...     lyr = ic.visualize(
...         product, scales=[[0, 0.4], [0, 0.4], [0, 0.4]], reduction="mean"
...     )  
...     layers.append(lyr)  

>>> ic = wf.widgets.imagecollection("ic", default_layer=layers[0])  
>>> low_cloud = ic.filter(lambda img: img.properties["cloud_fraction"] < 0.3)  
>>> low_cloud.visualize("Low-cloud", scales=[[0, 0.4], [0, 0.4], [0, 0.4]], reduction="mean")  
>>> # ^ when you call .visualize, the the `imagecollection` widget will automatically show up below

Selecting a different layer from the dropdown will show a basic cloud-filtered composite of that layer. (If you haven’t already, run wf.map in another notebook cell to see your layers on the map.)

Parameters:

• name (str) – The name of the parameter.
• default_layer (Optional[WorkflowsLayer], default None) –

  The layer selected by default. (A WorkflowsLayer is the object returned by visualize). If None, no layer will be selected, and nothing will display until you pick a layer from the dropdown.

  Unlike with other widget types, when you publish an object that depend on an imagecollection widget, the default_layer isn’t stored. Anyone who accesses your published object won’t see the same default layer; for them, it will be None.

• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.
• map (Optional[Union[Map, MapApp]], default None) – The Map or MapApp object to list layers from. If None (default), lists the layers on wf.map.

Returns:

widget – A Widget object that acts just like a Workflows ImageCollection, and displays as a dropdown listing the layer names currently on the map.

Return type:

ImageCollection

select(name: str, options: Sequence[Primitive], format: str = 'dropdown', default: Optional[Primitive] = None, label: str = '')

A widget (dropdown, radio buttons, etc.) to select a value from a list of options.

Depending on the types of the values you pass for options, the widget will act as a Str, an Int, or a Float parameter.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.select(
...     "param_name",
...     ["one", "two", "three"],
...     format="radio",
...     default="two",
...     label="A select parameter",
... )  

>>> s2 = wf.ImageCollection.from_id("sentinel-2:L1C", "2018-01-01", "2018-04-01")
>>> s2_bands = s2.pick_bands(
...     wf.widgets.select(
...         "band_combo",
...         ["red green blue", "nir red green", "swir1 nir blue"],
...         format="radio",
...         label="Band combination"
...     )
... )
>>> s2_bands.visualize("Sentinel-2", scales=[[0, 0.4], [0, 0.4], [0, 0.4]])  
>>> # ^ when you call .visualize, the `select` widget will automatically show up below

Selecting a band combination from the radio buttons will update the map. (If you haven’t already, run wf.map in another notebook cell to see your layer.)

You may want to display user-friendly terms for your options, rather than the actual values. A typical way to do this is to make a Dict mapping the user-friendly terms to their values, then use the dict’s keys as options:

>>> band_combos = {
...     "Natural color": "red green blue",
...     "Vegetation": "nir red green",
...     "Agriculture": "swir1 nir blue"
... }
>>> band_combo_name = wf.widgets.select(
...     "band_combo",
...     options=band_combos.keys(),
...     format="radio",
...     label="Band combination",
... )
>>> band_combos_wf = wf.Dict[wf.Str, wf.Str](band_combos)
>>> s2_bands = s2.pick_bands(band_combos_wf[band_combo_name])
>>> s2_bands.visualize("Sentinel-2", scales=[[0, 0.4], [0, 0.4], [0, 0.4]])  

Parameters:

• name (str) – The name of the parameter.
• options (Sequence[str, int, or float]) – The available options to display. All values in the sequence must be the same type.
• format (str, default "dropdown") –

  Which sort of widget to display. Options are:

  • ”dropdown” (default): a dropdown selector
  • ”radio”: radio buttons
  • ”slider”: a slider to pick between the options in the order they’re given. Displays the currently-selected option on the right side.
• default (str, int, float, optional, default None) – The default value to have selected. If None (default), picks the first value in options. If not None, the value must be in the options list.
• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name.

Returns:

widget – A Widget object that acts just like a Workflows Str, Int, or Float, and displays as a selector widget.

Return type:

Union[StringSelect, IntSelect, FloatSelect]

slider(name: str, min: Union[int, float], max: Union[int, float], step: Union[int, float, None] = None, default: Union[int, float, None] = None, label: str = '')

A slider, which acts as an Int or Float parameter.

If any of min, max, or step are a float, then the slider will represent a Float value, otherise an Int.

Example

>>> import descarteslabs.workflows as wf
>>> wf.widgets.slider("param_name", 0, 10, step=0.5, default=3, label="A float parameter")  

>>> s2 = wf.ImageCollection.from_id("sentinel-2:L1C", "2018-01-01", "2018-04-01")
>>> nir, red = s2.unpack_bands("nir red")
>>> ndvi = (nir - red) / (nir + red)
>>> high_ndvi = ndvi > wf.widgets.slider("thresh", 0, 0.8, default=0.24, label="Minimum NDVI threshold")
>>> high_ndvi.visualize("NDVI", scales=[0, 1], colormap="Greens")  
>>> # ^ when you call .visualize, the `slider` widget will automatically show up below

The map will show areas where NDVI is greater than the amount on the slider, and update when you drag the slider. (If you haven’t already, run wf.map in another notebook cell to see your layer.)

Parameters:

• name (str) – The name of the parameter.
• min (int, float) – The minimum value for the slider. Must be less than max.
• max (int, float) – The maximum value for the slider. Must be greater than min.
• step (int, float, optional, default None) –

  The interval between “ticks” on the slider. Must be less than max - min.

  If None (default) and one of min or max are floats, defaults to (min - max) / 10, meaning having 10 steps on the slider.

  If None and both are ints, and 5 <= (min - max) <= 10, step becomes 1, meaning 5-10 steps on the slider. Otherwise, step becomes (min - max) / 10, rounded to an int if that int would evenly divide the slider, otherwise a float.

• default (int, float, optional, default None) – The default value for the slider. If None (default), defaults to min. Must be between min and max.
• label (str, default "") – The longform label to display next to the widget. If not given, the widget will display as name

Returns:

widget – A Widget object that acts just like a Workflows Str, Int, or Float and displays as a slider.

Return type:

Union[IntSlider, FloatSlider]

class Widget(name, default, label='')

Base class for all Workflows widgets.

Workflows widgets act just like normal Workflows objects, such as Int, Str, or ImageCollection.

They just have a few extra fields you can use to interact with the current value of the widget.

property observe

Register a handler function to be called when the widget’s value changes. Shorthand for self.widget.observe.

See the traitlets docs for more information.

property value

The current value of the widget. Shorthand for self.widget.value.

widget = None

The ipywidgets Widget instance used to display this widget