What are folium natural dependencies ?

[BibMartin]

Just to open the question :

today, folium is officially depending on Jinja2, and the tests require vincent, pandas and eventually mock to run.

In practice, I guess we indirectly require numpy and maybe matplotlib or IPython, because we handle interaction with arrays, colormaps, notebook...

I wonder whether we shall extend the official dependency list ; provided that things like numpy are installed almost everywhere (?)

[ocefpaf]

👍 for adding numpy (and maybe matplotlib+pandas) as core dependencies.
👎 for vincent and IPython even though the latter is ubiquitous in everybody's python nowadays.

[themiurgo]

I would try to keep dependencies to a very minimum, so that people can generate maps even in low power environments. Installing matplotlib + numpy + pandas can be a pain on RPis / smartphones.

As long as one library is only needed for tests/examples, it's not a strong dependency for folium, as one can use it without testing it.

I made an extensive search on these imports and here are the results.

• pandas: various examples and documentation files, test_folium.py, utilities.py;
• numpy: examples and docs/docstrings, some functionalities in utilities.py;
• matplotlib: only examples and docstrings.

In utilities.py there is a way already to gracefully degrade in case there is no pandas or numpy.

try:
    import pandas as pd
except ImportError:
    pd = None

try:
    import numpy as np
except ImportError:
    np = None

So it seems at the moment none of these libraries are strong dependencies.

[ocefpaf]

My argument for adding numpy, matplotlib and pandas is to avoid all the workarounds we do to keep them as optional dependencies when most of the users already have them installed.

@andrewgiessel We need more votes. What do you think?

PS:

can be a pain on RPis / smartphones.

I had both numpy and matplotlib in my old N900. Pandas did not even existed at that time! It is sad to see the support for low power platform is going down with time.

[themiurgo]

My argument for adding numpy, matplotlib and pandas is to avoid all the workarounds we do to keep them as optional dependencies when most of the users already have them installed.

True, but from what I've seen they are all used in areas that are not essential to creating a map. For example, for matplotlib, here's what a search returns:

➜  folium git:(master) ack matplotlib
examples/plugins_examples.ipynb:89:    "            matplotlib figure with the same figsize.\n",
examples/plugins_examples.ipynb:115:    "            matplotlib figure with the same figsize.\n",
folium/element.py:212:                If you're a matplotlib addict, you can overwrite width and height.
folium/features.py:565:                Hint : you can use colormaps from `matplotlib.cm`.
folium/folium.py:661:            Hint : you can use colormaps from `matplotlib.cm`.
folium/folium.py:675:        # to make a rgba from a specific matplotlib colormap:
folium/folium.py:676:        >>> import matplotlib.cm as cm
folium/utilities.py:392:        Hint : you can use colormaps from `matplotlib.cm`.

There's no import of matplotlib, not even in tests, only docstrings.

[ocefpaf]

For the matplotlib case you are correct.

However, I do have plans to add some of the mplleaft functionality to folium to create things like a quiver plot. But that is a long term goal that I do not know if I will ever have the time to do.

@BibMartin do you have any short term plans that require more use of matplotlib?

[BibMartin]

do you have any short term plans that require more use of matplotlib?

No specific plan. I rather asked the question while looking backward. For example, ImageOverlay would have been simpler to implement if we assumed numpy as a dependency.
In the same way, I've created the (Hint : you can use colormaps from "matplotlib.cm".) to avoid calling matplotlib directly. I'm fine with this if there are folium users that work without mpl ; but it's less trivial, even for the user.

I agree with @ocefpaf that we can go quite close to mplleaflet if we accept matplotlib dependency.
In the same way, we may get closer to geopandas if we accept depending on pandas.

[themiurgo]

I agree with @ocefpaf that we can go quite close to mplleaflet if we accept matplotlib dependency.
In the same way, we may get closer to geopandas if we accept depending on pandas.

I just wanted to point out that those are not hard dependencies at the moment, and folium works just fine even without them. You will introduce those dependencies with the prospect of new functionalities. In the first message of this thread you were guessing we indirectly relying on those, but from what I've seen from inspecting the codebase this is not the case.

I did some more acking and it seems also numpy and pandas are used in things that are not related to the creation of maps. The only two places where they appear are docstring, tests and utilities.py. Then I searched which functions folium uses from utilities.py and this is the complete list:

_camelify, _parse_size, color_brewer, legend_scaler, _locations_mirror, _locations_tolist, write_png

all those functions do not use neither pandas nor numpy.

[ocefpaf]

I just wanted to point out that those are not hard dependencies at the moment

You are right. I guess that @BibMartin and I are thinking more about future releases than the current state of folium.

Keeping folium light is important, but code like

try:
    import pandas as pd
except ImportError:
    pd = None

is awkward and a little bit annoying to maintain. Not to mention cases like ImageOverlay.

With all that said... Let's just wait and see how the next PRs will look like. If we keep going in the direction of heavy use of numpy, etc we might re-discuss adding them as part of the core dependencies. (BTW I am a big 👍 on using geopandas here.)

PS: @themiurgo do you have use cases of folium in conditions where numpy and matplotlib is not available? Those are interesting use cases and we should document them if possible.

[themiurgo]

If we're talking about data science, research, ... then yes, pandas / numpy / matplotlib / ipython are probably already installed everywhere.

But in my opinion those are not the only people who could use folium. If I were a developing a webapp on flask / django, and wanted to show a simple map, I could simply import folium and display it. It'd put me off quite a bit if I had to install pandas, matplotlib, numpy and the likes to display a simple map with markers, and I'd use something else.

So the real question is: who are the users we are targeting? Everyone who wants to make a map or just data scientists / researchers?

Another "disadvantage" to keep in mind before including new dependencies, is that you make your codebase will be vulnerable to quirks of other codebases, bugs and API changes. If the advantages are substantial, it makes sense; otherwise, if you use the libraries only sparingly and for edge cases, it might not be worth it.

[andrewgiessel]

@andrewgiessel We need more votes. What do you think?

TL;DR: I'd keep our only hard requirement Jinja2 and leave all others optional. In practice a large proportion of our target user base has all of them installed. The django case is compelling but have we heard of anyone doing it?

numpy is used in utilities in the mercator projection function in utility.py, which is in turn used for ImageOverlay (but not by default). I'm not sure about anywhere else.

If we add features where we are passing in pandas data frames (as @jelmelk had suggested in the gitter) to construct a feature for every row of a df, then we should have it as a dependancy. This is kinda similar to ggplot2 or seaborn syntax, but isn't anything we implement currently. I will point out that numpy is a dependency for pandas, so requiring pandas means that numpy comes along for free.

[BibMartin]

Another "disadvantage" to keep in mind before including new dependencies, is that you make your codebase will be vulnerable to quirks of other codebases, bugs and API changes.

That's so true ; especially with pandas whose API is still quite changing. I would stay on this fact and make the effort not to add new dependencies to folium unless it's impossible to avoid it.

❗ Crazy idea : and could'nt we create other repositories in python-visualization community, like folium-numpy, folium-pandas, folium-matplotlib. That way, folium core would remain dependency-free, and further functionalities would be doable anyway. ❓

[ocefpaf]

If we're talking about data science, research, ... then yes, pandas / numpy / matplotlib / ipython are probably already installed everywhere.

That is where I am so I must confess I am biased!

So the real question is: who are the users we are targeting? Everyone who wants to make a map or just data scientists / researchers?

I don't think that is the question. We can target everyone who wants to make while still requiring pandas. Maybe we will lose a small subset people...

Anyway. Now that we have @andrewgiessel's option we are 2 x 2. Which means the status quo wins 😉

[ocefpaf]

Crazy idea

Crazy indeed! I prefer the optional dependencies than multiple packages.

[themiurgo]

Anyway. Now that we have @andrewgiessel's option we are 2 x 2. Which means the status quo wins 😉

I'm not against it a-priori, it's just that at the moment it doesn't seem there's a reason behind it. If @BibMartin then comes up with amazing module that makes heavy use of it, I'll definitely change my mind. 😉

Take a look at the case of ipython notebook, for instance, before it became jupyter. You had to install with a pip install ipython[notebook] in order to install all the dependencies that made the notebook work, the core package was not including it. Even if was such a useful thing, it wasn't a core functionality of ipython, so they kept it separated and now it's another module.