From e78d558c0386aa9b3ba5f43c960e19f9fb611db9 Mon Sep 17 00:00:00 2001 From: KhadeerBasha1232 Date: Mon, 16 Nov 2026 17:44:56 +0530 Subject: [PATCH] Add start_index option to HeatMapWithTime Let users choose which time step the slider shows when the map opens, instead of always starting at the first one. Negative values count from the end, and out-of-range values raise a ValueError. Closes #1243 Co-Authored-By: Claude Opus 5.5 --- folium/plugins/heat_map_withtime.py | 12 +++++++++++- tests/plugins/test_heat_map_withtime.py | 21 ++++++++++++++++++++- 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/folium/plugins/heat_map_withtime.py b/folium/plugins/heat_map_withtime.py index 9f62fb4b31..6c62fafd44 100644 --- a/folium/plugins/heat_map_withtime.py +++ b/folium/plugins/heat_map_withtime.py @@ -40,6 +40,9 @@ class HeatMapWithTime(JSCSSMixin, Layer): Display the index (usually time) in the time control. index_steps: default 1 Steps to take in the index dimension between animation steps. + start_index: int, default 0 + Position (0-based) in `data` of the time step shown when the map opens. + Negative values count from the end, so -1 starts at the last time step. min_speed: default 0.1 Minimum fps speed for animation. max_speed: default 10 @@ -144,7 +147,7 @@ class HeatMapWithTime(JSCSSMixin, Layer): var times = {{this.times}}; {{this._parent.get_name()}}.timeDimension = L.timeDimension( - {times : times, currentTime: new Date(1)} + {times : times, currentTime: new Date({{this.start_index + 1}})} ); var {{this._control_name}} = new L.Control.TimeDimensionCustom({{this.index}}, { @@ -225,6 +228,7 @@ def __init__( auto_play=False, display_index=True, index_steps=1, + start_index=0, min_speed=0.1, max_speed=10, speed_step=0.1, @@ -247,6 +251,12 @@ def __init__( "Input data and index are not of compatible lengths." ) # noqa self.times = list(range(1, len(data) + 1)) + if data and not -len(data) <= start_index < len(data): + raise ValueError( + f"start_index must be between {-len(data)} and {len(data) - 1}, " + f"got {start_index}." + ) + self.start_index = start_index % len(data) if data else 0 # Heatmap settings. self.radius = radius diff --git a/tests/plugins/test_heat_map_withtime.py b/tests/plugins/test_heat_map_withtime.py index 320cfc77d7..7c30f3a3ce 100644 --- a/tests/plugins/test_heat_map_withtime.py +++ b/tests/plugins/test_heat_map_withtime.py @@ -4,6 +4,7 @@ """ import numpy as np +import pytest import folium from folium import plugins @@ -38,7 +39,7 @@ def test_heat_map_with_time(): var times = {{this.times}}; {{this._parent.get_name()}}.timeDimension = L.timeDimension( - {times : times, currentTime: new Date(1)} + {times : times, currentTime: new Date({{this.start_index + 1}})} ); var {{this._control_name}} = new L.Control.TimeDimensionCustom({{this.index}}, { @@ -93,3 +94,21 @@ def test_heat_map_with_time_bounds(): assert hm.get_bounds() == [[48.0, 3.0], [52.0, 6.0]] assert m.get_bounds() == [[48.0, 3.0], [52.0, 7.0]] + + +@pytest.mark.parametrize("start_index, expected", [(0, 1), (5, 6), (-1, 10)]) +def test_heat_map_with_time_start_index(start_index, expected): + data = [[[48.0, 5.0]] for _ in range(10)] + m = folium.Map() + hm = plugins.HeatMapWithTime(data, start_index=start_index).add_to(m) + + out = normalize(m._parent.render()) + assert f"currentTime: new Date({expected})" in out + assert hm.start_index == expected - 1 + + +@pytest.mark.parametrize("start_index", [10, -11]) +def test_heat_map_with_time_start_index_out_of_range(start_index): + data = [[[48.0, 5.0]] for _ in range(10)] + with pytest.raises(ValueError, match="start_index"): + plugins.HeatMapWithTime(data, start_index=start_index)