Does anyone have opinions on deprecating and remove support for marginals altogether? I'd say it's an oddity within Matplotlib (we don't support it for pcolormesh, imshow etc.), and is high enough level to be out of scope (but probably the remit of say, seaborn)

@dstansby, I think the marginals are an orthogonal issue. The point is that the hexes are asymmetric. I think its easier to see if we set the aspect ratio of the data and plot to 1:

import matplotlib.pyplot as plt
import numpy as np

np.random.seed(19680801)
n = 100000
x = np.random.standard_normal(n)
y = np.random.standard_normal(n)

fig, ax = plt.subplots(figsize=(6, 6))
h = ax.hexbin(x, y, gridsize=(10, 10), marginals=True, reduce_C_function=np.sum)
ax.set_aspect(1)
plt.show()

(I agree with @dstansby re: deprecating marginals, although it should be possible to write an example showcasing how to do them -- not only for hexbin, but also for other 2D maps.)

Sorry for the off topic comment - I'll open a new issue for that.

We talked about this on the call this week https://hackmd.io/49a-u44CTja02xQRaG88JA?view#hexbin

The consensus action is :

• update the docstring to be clear about what it is doing
• possibly add a second mutually-exclusive keyword to go with gridsize that has the meaning expected

The docstring currently says:

       Alternatively, if a tuple (*nx*, *ny*), the number of hexagons
       in the *x*-direction and the *y*-direction.

Which is at best ambigious as if in these examples you count between hexs that are vertically aligned you (rather than zig-zag) you do get the expected number. To be clear, the stacking is ABAB, if you count the number of A you get the expected number.

We also need to inspect the code and make sure that this is not doing something about counting along the 60-degree diagonal and then filling in how many y rows we need. This would be consistent with what is done in the case of only passing 1 number (where the number of y-bins is xbin / sqrt(3) )

I think clear documentation is sufficient. The common use case of regular hexagons is handled by the single-integer parameter. Asymmetric relations are less common and can be achieved using an appropriate scaling factor. We don't need additional mutually exclusive parameters for that.