Added another example to the HeatMap user guide with more description

docs/user_guide/plugins/heatmap.md

@@ -1,17 +1,34 @@
 ## Heatmap
 
-```{code-cell} ipython3
-import numpy as np
+This plugin allows you to create a heat map to visualize the density of some feature on the map.
+Pass the data as a list of `[latitude, longitude]` pairs in the first argument.
 
-data = (
-    np.random.normal(size=(100, 3)) * np.array([[1, 1, 1]]) + np.array([[48, 5, 1]])
-).tolist()
-```
+As an example let us create a `HeatMap` of pizzerias in Rome using data from OpenStreetMap (2026).
 
 ```{code-cell} ipython3
 import folium
 from folium.plugins import HeatMap
 
+# List of latitude, longitude coordinates of pizza restaurants in Rome (acquired from OpenStreetMap)
+pizzeria_coords = [[41.8883, 12.4738], [41.897, 12.5127], [41.8821, 12.4762], [41.8741, 12.5135], [41.8983, 12.4704], [41.8742, 12.5171], [41.9067, 12.4467], [41.8995, 12.4762], [41.8876, 12.4717], [41.9091, 12.4573], [41.9142, 12.4501], [41.8762, 12.517], [41.9103, 12.448], [41.8792, 12.4514], [41.9077, 12.4466], [41.9202, 12.4415], [41.9059, 12.5052], [41.8989, 12.4926], [41.8896, 12.4955], [41.9126, 12.4542], [41.8931, 12.4882], [41.9008, 12.5145], [41.8995, 12.5168], [41.8908, 12.4707], [41.9, 12.5002], [41.9036, 12.462], [41.8984, 12.4754], [41.9117, 12.4416], [41.8926, 12.5057], [41.8974, 12.5128], [41.908, 12.4584], [41.8762, 12.5059], [41.8884, 12.4705], [41.9065, 12.5009], [41.8989, 12.4988], [41.896, 12.4995], [41.9135, 12.4415], [41.9091, 12.4554], [41.8932, 12.4752], [41.8957, 12.5131], [41.8999, 12.4798], [41.8948, 12.4767], [41.9003, 12.4695], [41.9001, 12.4711], [41.9057, 12.4457], [41.9169, 12.4582], [41.8976, 12.4708], [41.8887, 12.4978], [41.9006, 12.4836], [41.91, 12.5014], [41.9084, 12.4571], [41.8756, 12.4476], [41.9013, 12.4846], [41.8737, 12.4475], [41.8734, 12.4478], [41.8738, 12.4654], [41.899, 12.4959], [41.8818, 12.4585], [41.8963, 12.5133], [41.8974, 12.4965], [41.8976, 12.496], [41.88, 12.4757], [41.8868, 12.4719], [41.9076, 12.4978], [41.9047, 12.458], [41.889, 12.4977], [41.9085, 12.4612], [41.9062, 12.4631], [41.9137, 12.4413], [41.898, 12.4719], [41.8995, 12.4542], [41.8914, 12.4686], [41.9004, 12.4665], [41.8961, 12.4779], [41.8781, 12.5073], [41.9172, 12.501], [41.8859, 12.4725], [41.8996, 12.4988], [41.8998, 12.5012], [41.9, 12.5011], [41.8956, 12.5001], [41.907, 12.4608], [41.8983, 12.5144], [41.9126, 12.4757], [41.911, 12.4665], [41.9152, 12.4748], [41.8963, 12.4941], [41.883, 12.5143], [41.9018, 12.4855], [41.8962, 12.4729], [41.9107, 12.503], [41.8743, 12.4498], [41.8814, 12.5134], [41.9065, 12.4804], [41.8919, 12.5088], [41.8805, 12.506], [41.9083, 12.4678], [41.9122, 12.4756], [41.9069, 12.5006], [41.9101, 12.502], [41.8957, 12.4931], [41.9264, 12.5156], [41.8784, 12.4781], [41.9124, 12.5013], [41.9101, 12.4966], [41.8821, 12.4766], [41.8919, 12.4686], [41.8723, 12.4786], [41.8719, 12.4793], [41.8715, 12.4797], [41.877, 12.468], [41.8803, 12.4689], [41.913, 12.5071], [41.8989, 12.5155], [41.9046, 12.5049], [41.8975, 12.4791], [41.9056, 12.4537], [41.9048, 12.4458], [41.9256, 12.4872], [41.91, 12.5015], [41.9021, 12.4623], [41.8839, 12.5089], [41.9087, 12.4882], [41.913, 12.4975], [41.9038, 12.494], [41.9172, 12.4983], [41.8982, 12.5172], [41.8947, 12.4917], [41.8818, 12.4767], [41.9074, 12.4541], [41.9085, 12.4987], [41.8721, 12.4709], [41.8799, 12.4768], [41.892, 12.4685], [41.9051, 12.4775], [41.8738, 12.4807], [41.9005, 12.4756], [41.896, 12.4722], [41.8946, 12.5019], [41.8974, 12.4682], [41.8821, 12.5089], [41.8804, 12.4777], [41.8958, 12.514], [41.8857, 12.51], [41.893, 12.4776], [41.8921, 12.502], [41.892, 12.5018], [41.875, 12.4579], [41.9262, 12.4638], [41.8827, 12.4566], [41.8764, 12.4672], [41.8808, 12.5028], [41.9109, 12.5012], [41.8794, 12.4784], [41.88, 12.4618], [41.8721, 12.4799], [41.8827, 12.4865], [41.9023, 12.4941], [41.9023, 12.4939], [41.9017, 12.5035], [41.9053, 12.4998], [41.9038, 12.5033], [41.9039, 12.5005], [41.9046, 12.5007], [41.8898, 12.495], [41.8954, 12.4727], [41.9085, 12.4893], [41.9098, 12.4911], [41.9097, 12.4968], [41.906, 12.4958], [41.8728, 12.4845], [41.893, 12.5012], [41.8724, 12.5123], [41.9007, 12.5022], [41.8994, 12.4919], [41.8986, 12.501], [41.8952, 12.4905], [41.9086, 12.4625], [41.9119, 12.4564], [41.9128, 12.4756], [41.9105, 12.5003], [41.911, 12.5011], [41.8999, 12.453], [41.9066, 12.5168], [41.9067, 12.5163], [41.9079, 12.5167], [41.8771, 12.5162], [41.9117, 12.4989], [41.8997, 12.484], [41.9037, 12.4878], [41.8791, 12.5035], [41.9038, 12.4814], [41.8939, 12.4882], [41.909, 12.4498], [41.908, 12.4541], [41.8807, 12.5134], [41.9014, 12.5017], [41.8944, 12.4737], [41.8776, 12.4736], [41.8828, 12.5147], [41.8778, 12.4739], [41.8739, 12.4801], [41.9111, 12.5166], [41.8779, 12.5053], [41.871, 12.5157], [41.8777, 12.5085], [41.8764, 12.5093], [41.8981, 12.5153], [41.9099, 12.4522], [41.8976, 12.4568], [41.8886, 12.471], [41.9018, 12.4751], [41.9031, 12.4832], [41.8741, 12.4478], [41.8846, 12.4607], [41.9214, 12.5035], [41.8987, 12.4773], [41.8988, 12.4773], [41.914, 12.4748]]
+
+m = folium.Map([41.9, 12.5], zoom_start=12)
+
+HeatMap(pizzeria_coords).add_to(m)
+
+m
+```
+
+One can also set a weight for each coordinate by passing the data as a list of
+`[latitude, longitude, weight]` triples. Below is an example for this case using random data.
+See the API reference for more options.
+
+```{code-cell} ipython3
+import numpy as np
+
+# Generate some random data
+data = np.random.normal(size=(100, 3)) + np.array([[48, 5, 1]])
+
 m = folium.Map([48.0, 5.0], zoom_start=6)
 
 HeatMap(data).add_to(m)