This is a continuation of a mailing list thread where we talked about how to clip a plot inside a polygon. It is a very useful application for people who are visualizing data on maps since often times we want to plot everything inside one region (country, state or province).

http://matplotlib.1069221.n5.nabble.com/Clipping-a-plot-inside-a-polygon-td41950.html

Currently for many types of plots this is not that hard to do using the clip_path keyword for most of the plotting functions, since the kwargs are usually used to modify properties of the artists to be generated by the plotting function. For example, suppose that I had a polygon defining the border of a country, poly, and some data to overlay on top.

plt.pcolor(data, clip_path=poly)

Does what I want because the kwargs of pcolor let me modify the underlying PolyCollection instance. However, there are a few plotting functions where I cannot do this, most notably in contour / contourf:

plt.contourf(data, clip_path=poly)

Will work but the clip_path kwarg gets completely ignored. To get the result I want, I need to store the output of contourf and use the set_clip_path method on each collection instance:

cs = plt.contourf(data)
for col in cs.collections:
    col.set_clip_path(poly)

So I looked at the code in contour.py and realized that no kwargs get passed when instantiating the collections. @pelson mentioned that this might call for an overhaul of how the kwargs get passed into a ContourSet. His suggestion was either adding a set_clip_path method directly to ContourSet, or a more thorough change of how the kwargs are getting passed so they are more consistent with the other plotting functions. Ideally, I would prefer the latter case since then for my usage case I could always get what I want just by passing in the kwarg directly. Additionally it would make the functionality of contour(f) more similar to the other plotting functions, ie some of the kwargs can be passed to the collections. Any thoughts on this?