Colormap

[BibMartin]

Create a colormap module, to help generating choropleth and other colouring jobs (like ImageOverlay ?).

It can address #289 (?)

I know there are plenty existing libs doing this (among which matplotlib), but I guess this will be rather simple to maintain and brings no new dependency.

Please see http://nbviewer.ipython.org/github/bibmartin/folium/blob/colormap/examples/Colormaps.ipynb for examples.

[ocefpaf]

@BibMartin this looks great. I will try to review it as soon as possible. (Unless someone beats me to it.)

[BibMartin]

@ocefpaf @themiurgo
I've realized that colormaps can do much more than what I expected before.

We have 3 commits here:

• ae0bf14 creates ColorMap objects
• aafec58 transforms it into a MacroElement so that it can replace ColorScale
• 373364e expands the method LinearColorscale.to_step so that it can replace split_six.

I'm not really sure about the third point, but I guess this can help refactoring former utilities methods.
You points of view will be more than welcome.

Please try some examples in a notebook:

import folium.colormap
import numpy as np
some_list = np.random.normal(loc=35000, scale=10000, size=300).tolist()

lc = folium.colormap.linear.YlOrRd
lc

lc.to_step(n=12)

lc.to_step(index=[0,2,4,6,8,10])

lc.to_step(data=some_list, n=12)

lc.to_step(data=some_list, n=12, method='linear')

lc.to_step(data=some_list, n=12, method='log')

lc.to_step(data=some_list, n=30, method='quantiles')

lc.to_step(data=some_list, quantiles=[0,0.3,0.7,1])

lc.to_step(data=some_list, quantiles=[0,0.3,0.7,1], round=True)

lc.to_step(data=some_list, quantiles=[0,0.3,0.7,1], base_round=True)

[ocefpaf]

There is a type in the notebook hugh → high

[ocefpaf]

I wonder if someone should create a tiny library with that...

[ocefpaf]

@BibMartin I made some minor comments. I'd really appreciate if someone else could take a look too.

Even though I really like this PR a lot I cannot shake the feeling that this is too much for folium. Maybe it is unavoidable... let's see what others have to say.

[BibMartin]

@ocefpaf

I wonder if someone should create a tiny library with that...

I was thinking of it when programming the first commit ae0bf14 ; in fact in this commit the module colormap.py is almost independent of folium (only imports text_type and binary_type).

It could be another (tiny) library supported by python-visualization community.

But on the other hand:

• It means more docs, releases, etc
• It would be another dependency for folium (with risks of inconsistencies)
• The other commits (aafec58 and 373364e) take advantage of having this module inside and have a colormap object that is also the colorscale Element.

Finally, I'm quite open to discuss that point, and would also appreciate other inputs (ping @themiurgo, @andrewgiessel ?)

If I got this you are keep the built-in function round as _round to protect it from being clobbered later on, right?
If so can we avoid clobbering it?
Again let's consider changing all min/max to vmin/vmax to avoid name clashing.

I like having simple and explicit kwarg names ; but I will trust your wise opinion.

As for your other comments, I'm okay and will apply changes asap.

[ocefpaf]

But on the other hand ...

I get that. That is why I said someone else. You not included 😉

I like having simple and explicit kwarg names ; but I will trust your wise opinion.

Wise? No so sure 😄

Note that I am biased here. I guess that matplotlib uses vmin/vmax, right?

[themiurgo]

I agree with the wise @ocefpaf on this. This functionality is great, but it feels a bit out of place here. Why don't you make a small library out of it?

Something that seems to be missing from scientific python community is a d3-like python library. There is d3py but the project looks abandoned. This library would be a good building block for something like that, which converts values to other scales or to colors.

[ocefpaf]

I agree with the wise @ocefpaf on this. This functionality is great, but it feels a bit out of place here. Why don't you make a small library out of it?

Just to be clear I am OK merging it. I would like to see this code as external library, but the maintenance burden would be too much on @BibMartin shoulders. (And I am selfish! I want to keep him focused on folium 😝)

Something that seems to be missing from scientific python community is a d3-like python library.

Indeed!

There is d3py but the project looks abandoned. This library would be a good building block for something like that, which converts values to other scales or to colors.

I guess we should make some twitter noise: "folium submodule for sale!"

[themiurgo]

Let's merge it then!

[BibMartin]

Something that seems to be missing from scientific python community is a d3-like python library

Yes, but it cannot be restricted to d3 ; d3 is often a brick among others to create a nice report (another example could be #251). This would be a python-visualization library based on HTML and JS.

I'm split between 3 scenarios:

1. Folium is python-visualization

As a folium user and contributor, I'm glad not needing to install fancy dependencies with folium. By fancy, I mean something that risk to be buggy, not to evolve anymore or evolve too fast etc.
I guess it's painful to have to wait for another library to move before fixing a bug/enhancement.
Plus the complexity of tracking which versions of which lib are compatible...

In a word, I would keep everything in folium as much as possible ; at the cost of doing a big split when mature.

2. Folium is the map plugin of python-visualization

Folium's goal is to enable easy map generation with Leaflet. We could factor-out everything that's not map-specific: Element, Figure, Link, Div, VegaDiv etc, and Colormap.

Finally, python-visualization would implement the core of the mindset (objects added the one to the other, render methods outputing result in a file or an iframe). And folium would focus on providing the leaflet-specific objects : Map, Marker, etc.

Other libraries could be created based on python-visualization (GeoJson, Crossfilter, NVD3, bootstrap...) but without involving folium.

3. Folium depends on an existing visualization library

There are several visualization libraies available in python community (matplotlib, mpld3, bokeh, plot.ly...). No one is perfect today, nor dominating (except for matplotlib ; but not really notebook-interactive), but I'm not sure it worth trying to create another competitor. We can decide to let folium depend on one of these and use their colormap function, ...

Anyway, I think these reflections are useful (and necessary), but they are middle or long-term thoughts. I would vote for merging colormap as-is today and finish v0.2 and tackle the refactoring in v0.3.

After that piece of (silly?) text, I looking forward for your reactions. 😧

[andrewgiessel]

Sorry I didn't get a chance to look at this over the week- these larger issues deserve some thought. I think colormap is a clear case of something that can be (and should be) either refactored out to another python-visualization project or use an existing library.

:+1 to merge for now, and include in v0.2

[themiurgo]

Yes, but it cannot be restricted to d3 ; d3 is often a brick among others to create a nice report (another example could be #251). This would be a python-visualization library based on HTML and JS.

I might have been unclear. What I meant by d3-like library is "something that converts values and ranges into geometrical objects". It might not be at all related to JS, HTML and it might use matplotlib, folium or anything as a backend.

[ocefpaf]

@BibMartin I see a future where we are 90% (2) + 10% (3). Folium is not python-visualization. I guess that, when @wrobstory created the organization, he wanted to add his other projects here too (vincent, bearcart, etc).

We could factor-out everything that's not map-specific: Element, Figure, Link, Div, VegaDiv etc, and Colormap.

Maybe yes. Definitely not now! Bare in mind that, if we re-factor, then folium would depend on those and we would start entering the 10% of (3) I mentioned above.

PS: Bokeh is improving their map support. However, I believe folium is very different from bokeh by providing easy maps (just a few lines of code) and close integration with Leaflet.

[BibMartin]

Thank you @ocefpaf @themiurgo @andrewgiessel for your comments.
I've created issue #320 to keep track of this discussion and think of factoring colormap (at least) out of folium.

For now it seems we are close to v0.2 release...
Can we close #289, #195 and #89 based on this PR ?

[wrobstory]

Folium is not python-visualization. I guess that, when @wrobstory created the organization, he wanted to add his other projects here too (vincent, bearcart, etc).

Hi everybody!

My biggest goal was largely to move Folium out of the github.com/wrobstory namespace when ownership was handed over to y'all. I had anticipated moving other projects into the python-visualization organization as well, but (obviously) have not done so.

One option is to rename the organization from python-visualization to folium, and then sub-libraries that Folium depends on could be added to that organization. I'm totally fine with doing that- the only pain is updating your local remote pointers for the new name.