hexbin: Fixed incorrect "optional" attribute. Defined default behavior.
State: closed

`x` and `y` have no default values and are thus not optional.

The semantics of hexbin() with default arguments (i.e. when only `x` and `y` are given) is now defined.

It would be nice to describe what kind of argument `reduce_C_function()` expects (A sequence? A Series?), but this is not immediately obvious from the code.

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs
name: Visualization
description: plotting

Comments:
> :ref:`matplotlib.axes.Axes.hexbin`

yes, that should work I think. 

It could also be a See also section which would automatically generate a box with the link as well

```
See also
---------
matplotlib.axes.Axes.hexbin
```
> It would be nice to describe what kind of argument reduce_C_function() expects (A sequence? A Series?), but this is not immediately obvious from the code.

Feel free to copy over some of the user-guide text to the docstring. Maybe you could add an `Examples` section as well?
About the Matplotlib documentation: I checked it out and it is not obvious to me that Pandas' `hexbin()` documentation can benefit much from it, as Matplotlib's documentation contains many more options, etc. I would be confused by the reference, thinking that Pandas' version accepts Matplotlib's arguments. Or does it??

> Matplotlib's documentation contains many more options, etc. I would be confused by the reference, thinking that Pandas' version accepts Matplotlib's arguments. 

All additional keyword args are passed through to matplotlib.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=h1) Report
> Merging [#17578](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/37e23d03e1ba2298d9df05ded69028dfac0e823e?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/17578/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17578      +/-   ##
==========================================
- Coverage   91.22%    91.2%   -0.02%     
==========================================
  Files         163      163              
  Lines       49625    49625              
==========================================
- Hits        45270    45261       -9     
- Misses       4355     4364       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.99% <ø> (ø)` | :arrow_up: |
| #single | `40.19% <ø> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.73% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=footer). Last update [37e23d0...3645752](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=h1) Report
> Merging [#17578](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/37e23d03e1ba2298d9df05ded69028dfac0e823e?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/17578/graphs/tree.svg?height=150&width=650&token=eZ4WkYLtcO&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17578      +/-   ##
==========================================
- Coverage   91.22%    91.2%   -0.02%     
==========================================
  Files         163      163              
  Lines       49625    49625              
==========================================
- Hits        45270    45261       -9     
- Misses       4355     4364       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.99% <ø> (ø)` | :arrow_up: |
| #single | `40.19% <ø> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.73% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=footer). Last update [37e23d0...3645752](https://codecov.io/gh/pandas-dev/pandas/pull/17578?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Given that additional kwargs are passed to matplotlib's hexbin, I think it is useful to link to its docs
> It could also be a See also section which would automatically generate a box with the link as well

Oh, I didn't realize that worked across projects. Neat.
Ahh @lebigot can you also update the docstring for `scatter` (line 2381)? That must have been incorrect when I added hexbin originally and copied its docstring.
Interesting information, and good suggestions. I'll keep working on it later, as it is almost midnight here and I need to work tomorrow. So no need to merge yet. Thanks!
Since this is such a thin wrapper around matplotlib's hexbin, I'd prefer to
just keep matplotlib's names for everything.

On Thu, Sep 21, 2017 at 8:40 AM, Jeff Reback <notifications@github.com>
wrote:

> *@jreback* commented on this pull request.
>
> side issue
>
> we generally call his agg_func elsewhere rather than reduce_C_function
>
> so should create an issue to deprecate and change
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/17578#pullrequestreview-64286938>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIoSxfdI5dV9aUUjvYMAzAslhC8ifks5skmdrgaJpZM4Pbffy>
> .
>

oh if that is what mpl calls it then ok
It wouldn't have been my first choice :)

On Thu, Sep 21, 2017 at 8:46 AM, Jeff Reback <notifications@github.com>
wrote:

> oh if that is what mpl calls it then ok
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/17578#issuecomment-331161240>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHImS6Pam9-KtiWmsG9Gq948LmJ_7iks5skmjCgaJpZM4Pbffy>
> .
>

@lebigot Do you have time to update this?
Good question. I do have some time and still want to keep contributing. Thanks for putting this back in my radar. I'll do my best.
OK, also no problem if you don't directly have the time, but please indicate so as the current status is already an improvement (so I would rather merge it then). I think it's mainly missing the suggestion of linking to the matplotlib docs ?
can you rebase and update according to comments
closing as stale, if you want to work on this, pls ping.