Add Timeline plugin (#1870)

* Add interval support to timestamped_geo_json * Try with separate timeline * Fix error in documentation * Fixed breaking test * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Based on review comments * Add classes to namespace per review comments * Added documentation for timeline plugin Updated the documentation for timestamped_geojson to clarify the difference with timeline. Also used a simpler code example in timeline.py docstring. * Add test + fix CDN import * Piggyback on borders.json from the Skeat timeline repo * Update docs/user_guide/plugins/timestamped_geojson.md Co-authored-by: Frank Anema <[email protected]> * Updated after review comments * Made the example file smaller * Update folium/plugins/timeline.py Co-authored-by: Frank Anema <[email protected]> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Frank Anema <[email protected]>
python-visualization · Apr 4, 2024 · 007fa8c · 007fa8c
1 parent 5c2f3d1
commit 007fa8c
Show file tree

Hide file tree

Showing 7 changed files with 469 additions and 0 deletions.
diff --git a/docs/user_guide/plugins/timeline.md b/docs/user_guide/plugins/timeline.md
@@ -0,0 +1,74 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+##  Timeline and TimelineSlider
+Show changing geospatial data over time.
+
+### Comparison to TimestampedGeoJson
+This is a plugin with a similar purpose to `TimestampedGeoJson`. They both
+show geospatial information that changes over time.
+
+The main difference between the two is the input format.
+
+In the `Timeline` plugin each `Feature` has its own `start` and `end` time among its properties.
+In the `TimestampedGeojson` each `Feature` has an array of start times. Each start time in
+the array corresponds to a part of the `Geometry` of that `Feature`.
+
+`TimestampedGeojson` also does not have `end` times for each `Feature`. Instead you can
+specify a global `duration` property that is valid for all features.
+
+Depending on your input geojson, one plugin may be more convenient than the other.
+
+### Comparison to Realtime
+The `Timeline` plugin can only show data from the past. If you want live updates,
+you need the `Realtime` plugin.
+
+```{code-cell} ipython3
+import folium
+from folium.utilities import JsCode
+from folium.features import GeoJsonPopup
+from folium.plugins.timeline import Timeline, TimelineSlider
+import requests
+
+m = folium.Map()
+
+data = requests.get(
+    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/historical_country_borders.json"
+).json()
+
+timeline = Timeline(
+    data,
+    style=JsCode("""
+        function (data) {
+            function getColorFor(str) {
+                var hash = 0;
+                for (var i = 0; i < str.length; i++) {
+                    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+                }
+                var red = (hash >> 24) & 0xff;
+                var grn = (hash >> 16) & 0xff;
+                var blu = (hash >> 8) & 0xff;
+                return "rgb(" + red + "," + grn + "," + blu + ")";
+            }
+            return {
+                stroke: false,
+                color: getColorFor(data.properties.name),
+                fillOpacity: 0.5,
+            };
+        }
+    """)
+).add_to(m)
+GeoJsonPopup(fields=['name'], labels=True).add_to(timeline)
+TimelineSlider(
+    auto_play=False,
+    show_ticks=True,
+    enable_keyboard_controls=True,
+    playback_duration=30000,
+).add_timelines(timeline).add_to(m)
+m
+```
diff --git a/docs/user_guide/plugins/timestamped_geojson.md b/docs/user_guide/plugins/timestamped_geojson.md
@@ -7,6 +7,27 @@ import folium.plugins
 ```
 
 ##  TimestampedGeoJson
+Show changing geospatial data over time.
+
+### Relation to Timeline
+This is a plugin with a similar purpose to `Timeline`. They both
+show geospatial information that changes over time.
+
+The main difference between the two is the input format.
+
+In the `TimestampedGeojson` each `Feature` has an array of start times. Each start time in
+the array corresponds to a part of the `Geometry` of that `Feature`.
+In the `Timeline` plugin each `Feature` has its own `start` and `end` time among its properties.
+
+Also `TimestampedGeoJson` has a global `duration` property that is valid for all `Features`.
+In the `Timeline` plugin each `Feature` has its own `end` time property.
+
+Depending on your input geojson, one plugin may be more convenient than the other.
+
+### Relation to Realtime
+This plugin can only show data from the past. If you want live updates,
+you need the `Realtime` plugin.
+
 
 ### Example 1
 

diff --git a/examples/data/historical_country_borders.json b/examples/data/historical_country_borders.json
diff --git a/folium/plugins/__init__.py b/folium/plugins/__init__.py
@@ -29,6 +29,7 @@
 from folium.plugins.tag_filter_button import TagFilterButton
 from folium.plugins.terminator import Terminator
 from folium.plugins.time_slider_choropleth import TimeSliderChoropleth
+from folium.plugins.timeline import Timeline, TimelineSlider
 from folium.plugins.timestamped_geo_json import TimestampedGeoJson
 from folium.plugins.timestamped_wmstilelayer import TimestampedWmsTileLayers
 from folium.plugins.treelayercontrol import TreeLayerControl
@@ -65,6 +66,8 @@
     "TagFilterButton",
     "Terminator",
     "TimeSliderChoropleth",
+    "Timeline",
+    "TimelineSlider",
     "TimestampedGeoJson",
     "TimestampedWmsTileLayers",
     "TreeLayerControl",