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 Type      | Description                                                         |
|------------------|---------------------------------------------------------------------|
| `'range'`       | A filter limiting data to values within a specified range.         |
| `'select'`      | A filter limiting data to values that match one specific criteria.  |
| `'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.

### JavaScript

```javascript
map.addFilter({
  type: "range",
  sources: [
    {
      dataId: "test-dataset-filter",
      fieldName: "Magnitude",
    },
  ],
  value: [4, 5],
});
```

### Python

```python
# Adding the filter to the map
map.add_filter(PartialRangeFilter(
    sources=[PartialFilterSource(
        data_id="test-dataset-filter",
        field_name="Magnitude"
    )],
    value=(4,5)
))
```

### Arguments

| Argument                 | Type                  | Description                                              |
|--------------------------|-----------------------|----------------------------------------------------------|
| `filter`                 | `object`              | An object containing filter details.                      |
| `filter.id`              | `string`              | Unique identifier of the filter.                          |
| `filter.type`            | `string`              | Type of filter to create. See list above.                |
| `filter.sources`         | `object array`        | An array of filter sources. Only `TimeRangeFilter` supports multiple sources. |
| `filter.sources.data_id` | `string`              | The unique identifier for the dataset to filter.         |
| `filter.sources.field_name` | `string`           | The name of the field containing the data to filter.     |
| `filter.value`           | `string`, `number`, `timestamp`, `array` | The values to use in the filter.      |

## 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.

### JavaScript

```javascript
addFilterFromConfig(filterConfig: FilterCreationFromConfigProps): Filter
```

### Python

```python
add_filter_from_config(
  self,
  filter_config: Union[Dict, str]
) -> Filter:
```

### Arguments

| Argument                   | Type                  | Description                                              |
|----------------------------|-----------------------|----------------------------------------------------------|
| `filterConfig.id`         | `string`              | The ID of the filter.                                   |
| `filterConfig.type`       | `string`              | Type of filter to create. See list above.               |
| `filterConfig.dataId`     | `string[]`            | Dataset ids that the filter applies to.                 |
| `filterConfig.name`       | `string[]`            | Names of the fields that the filter applies to.         |
| `filterConfig.value`      | `object`              | Filter type-specific value for the filter.              |
| `filterConfig.view`       | `'side'`, `'enlarged'`, `'minified'` | Where the filter should be displayed.  |

## Get Filter by ID

Retrieve a filter by passing its `id`.

### JavaScript

```javascript
filter = map.getFilterById("test-filter-01");
```

### Python

```python
filter = map.get_filter_by_id('test-filter-01')
```

### Arguments

| Argument   | Type     | Description                                  |
|------------|----------|----------------------------------------------|
| `filterId` | `string` | The identifier for the filter to retrieve.   |

## 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.

### JavaScript

```javascript
filters = map.getFilters();
```

### Python

```python
filters = map.get_filters()
```

## Remove Filter

Remove a filter by passing its `filterId`.

### JavaScript

```javascript
map.removeFilter("test-filter-01");
```

### Python

```python
map.remove_filter('test-filter-01')
```

### Arguments

| Argument   | Type     | Description                                    |
|------------|----------|------------------------------------------------|
| `filterId` | `string` | The identifier for the filter to remove.       |

## Update Filter

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

### JavaScript

```javascript
map.updateFilter("test-filter-1", {
  type: "range",
  sources: [
    {
      dataId: "test-dataset-filter",
      fieldName: "Magnitude",
    },
  ],
  value: [5, 6],
});
```

### Python

```python
map.update_filter(
    "filter-id",
    PartialRangeFilter(
        value=(4, 5),
    ),
)
```

### Arguments

| Argument                 | Type                  | Description                                     |
|--------------------------|-----------------------|-------------------------------------------------|
| `filterId`               | `string`              | Unique identifier of the filter to update.      |
| `filter`                 | `object`              | An object containing filter details.             |
| `filter.type`            | `string`              | Type of filter to create. See list above.       |
| `filter.sources`         | `object array`        | An array of filter sources.                      |
| `filter.sources.data_id` | `string`              | The unique identifier for the dataset to filter. |
| `filter.sources.field_name` | `string`            | The name of the field containing the data to filter. |
| `filter.value`           | `string`, `number`, `timestamp`, `array` | The values to use in the filter.             |

## 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:

### JavaScript

```javascript
map.updateTimeline("test-timeline-1", {
  timeFormat: "DD/MM/YYYY",
  isAnimating: false,
});
```

### Python

```python
map.update_timeline("filter-id", FilterTimelineUpdateProps(
    view="side",
    is_animating=True
))
```

### Arguments

| Argument                | Type                  | Description                                            |
|-------------------------|-----------------------|--------------------------------------------------------|
| `filterId`              | `string`              | Unique identifier of the filter with the timeline to update. |
| `values`                | `object`              | An object containing parameters used to update the filter timeline. |
| `values.view`           | `string`              | Current timeline presentation.                         |
| `values.timeFormat`     | `string`              | Time format that the timeline is using in [day.js supported format](https://day.js.org/docs/en/display/format). |
| `values.timezone`       | `string`              | Timezone that the timeline is using in [tz format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
| `values.isAnimating`     | `boolean`             | Flag indicating whether the timeline is animating or not. |
| `values.animationSpeed`  | `number`              | Speed at which timeline is animating.                  |
| `values.step`           | `number`              | Minimum animation step size in milliseconds.