Filter Functions

Filters are used to define custom ranges on your map's datasets. In addition, time filters can be leveraged to animate data over a span of time.


Add Filter

Apply a new filter to the map. This function requires that you specify a filter id, id, one or more sources (including a dataId and fieldName), and a value.

Filter TypeDescription
'range'A filter limiting data to values within a specified range.
'select'A filter limiting data to values that match one specific criteria. Can be a specific number, string, or boolean
'time-range'A filter limiting data to only that which falls within a range of time.
'multi-select'A filter limiting data to values that match one or more criteria.
'polygon'A filter limiting data to values that fall within a GeoJSON Polygon feature.

The value is restricted by the type of filter selected. For instance, 'range' filters support a value range in an array (e.g. [4,5], while a select filter will only support a single criteria.

map.addFilter({
  type: "range",
  sources: [
    {
      dataId: "test-dataset-filter",
      fieldName: "Magnitude",
    },
  ],
  value: [4, 5],
});
# Adding the filter to the map
map.add_filter(PartialRangeFilter(
    sources=[PartialFilterSource(
        data_id="test-dataset-filter",
        field_name="Magnitude"
    )],
    value=(4,5)
))

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
filterobjectAn object containing filter details.
filter.idstringUnique identifier of the filter.
filter.typestringType of filter to create. See list above.
filter.sourcesobject arrayAn array of filter sources. Only TimeRangeFilter supports multiple sources.
filter.sources.data_idstringThe unique identifier for the dataset to filter.
filter.sources.field_namestringThe name of the field containing the data to filter.
filter.valuestring, number, timestamp, arrayThe values to use in the filter. For more information, see the Filter object.

For more information, including full Python documentation, see addFilter() in the full API reference.


Add Filter From Config

Add a filter to the map based on its JSON config. These methods can use the content of filter JSON editors directly.

addFilterFromConfig(filterConfig: FilterCreationFromConfigProps): Filter
add_filter_from_config(
  self,
  filter_config: Union[Dict, str]
) -> Filter:

Arguments

ArgumentTypeDescription
filterConfig.idstringThe ID of the filter.
filterConfig.typestringType of filter to create. See list above.
filterConfig.dataIdstring[]Dataset ids that the filter applies to.
filterConfig.namestring[]Names of the fields that the filter applies to.
filterConfig.valueobjectFilter type-specific value for the filter.
filterConfig.view'side', 'enlarged', 'minified'Where the filter should be displayed.

Some filter types have additional properties and are specific to that type.

For more information, including full Python documentation, see addFilterFromConfig() in the full API reference..


Get Filter by ID

Retrieve a filter by passing its id.

filter = map.getFilterById("test-filter-01");
filter = map.get_filter_by_id('test-filter-01')

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
filterIdstringThe identifier for the filter to retrieve.

For more information, including full Python documentation, see getFilterById() in the full API reference.


Get Filters

Retrieve a list of all filters available on the map. Filters are returned as an array of Filter objects, containing each filter's id, public facing label and color, as well as other settings applied to the filters.

filters = map.getFilters();
filters = map.get_filters()

For more information, including full Python documentation, see getFilters() in the full API reference.


Remove Filter

Remove a filter by passing its filterId.

map.removeFilter("test-filter-01");
map.remove_filter('test-filter-01')

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
filterIdstringThe identifier for the filter to remove.

For more information, including full Python documentation, see removeFilter() in the full API reference.


Update Filter

Update an existing filter by passing its id along the settings you wish to update.

map.updateFilter("test-filter-1", {
  type: "range",
  sources: [
    {
      dataId: "test-dataset-filter",
      fieldName: "Magnitude",
    },
  ],
  value: [5, 6],
});
map.update_filter(
    "filter-id",
    PartialRangeFilter(
        value=(4, 5),
    ),
)

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
filterIdstringUnique identifier of the filter to update.
filterobjectAn object containing filter details.
filter.typestringType of filter to create. See list above.
filter.sourcesobject arrayAn array of filter sources. Only TimeRangeFilter supports multiple sources.
filter.sources.data_idstringThe unique identifier for the dataset to filter.
filter.sources.field_namestringThe name of the field containing the data to filter.
filter.valuestring, number, timestamp, arrayThe values to use in the filter. For more information, see the Filter object.

For more information, including full Python documentation, see updateFilter() in the full API reference.


Update Timeline

Updates an animated timeline by passing the associated time filter's id. The filter timeline object has options for several time formatting and animation settings:

map.updateTimeline("test-timeline-1", {
  timeFormat: "DD/MM/YYYY",
  isAnimating: false,
});
map.update_timeline("filter-id", FilterTimelineUpdateProps(
    view="side",
    is_animating=True
))

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
filterIdstringUnique identifier of the filter with the timeline to update.
valuesobjectAn object containing parameters used to update the filter timline.
values.viewstringCurrent timeline presentation.
values.timeFormatstringTime format that the timeline is using in day.js supported format.
values.timezonestringTimezone that the timeline is using in tz format.
values.isAnimatingbooleanFlag indicating whether the timeline is animating or not.
values.animationSpeednumberSpeed at which timeline is animating.
values.stepnumberMinimum animation step size in milliseconds.

For more information, including full Python documentation, see updateTimeline() in the full API reference.