API: add top-level melt function as method
State: closed

 - [x] (progress on?) #12640
   - [x] pd.melt (DataFrame) (xref #14876)

 - [x] tests added / passed
 - [x] passes ``git diff upstream/master | flake8 --diff``
 - [x] whatsnew entry

This is continued from [PR#15513](https://github.com/pandas-dev/pandas/pull/15513).

Labels:
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode
name: API Design

Comments:
How should this be tested?
where ``pd.melt`` is currently tests, you can add in a a test like

``test_api_method`` or something and just copy an existing tests and subtitute ``DataFrame.melt`` for ``pd.melt`` (or changing a tests is ok too)
Copying an entire test case would cause a lot of duplication though. Since `DataFrame.melt` is supposed to have the same method signature as `pd.melt`, can't we just replace `melt` with `DataFrame.melt` in the test bodies?
@ResidentMario yes you can simply replace them (though I would still add a *single* function to test the api (e.g. that pd.melt works)
also add this to ``api.rst``. and in the ``reshaing.rst`` I would change the docs.
And and addition to `whatsnew`, presumably. Where would that go under there?
you could put it in Enhancements
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=h1) Report
> Merging [#15521](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/da0523a346abd9575ab05746e242ec67c1c442d4?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #15521      +/-   ##
==========================================
+ Coverage   90.97%   90.97%   +<.01%     
==========================================
  Files         145      145              
  Lines       49483    49492       +9     
==========================================
+ Hits        45015    45024       +9     
  Misses       4468     4468
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.73% <100%> (ø)` | :arrow_up: |
| #single | `40.63% <77.77%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.57% <100%> (ø)` | :arrow_up: |
| [pandas/core/reshape.py](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS5weQ==) | `99.28% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15521?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/15521?src=pr&el=footer). Last update [da0523a...1657246](https://codecov.io/gh/pandas-dev/pandas/pull/15521?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
gtm?
lgtm. @jorisvandenbossche 
Will take a look tomorrow!
@jorisvandenbossche bump :)
can you rebase, this looks good though (mainly to fix the whatsnew)
Rebased.
@ResidentMario Sorry my 'tomorrow' took a lot longer .. !

To be clear: I am in the meantime fully convinced of the usefulness of `melt`, and having it as method on a DataFrame as counterpart of the `pivot` method is really nice.

My main concern I have (or maybe not really concern, bur rather opportunity) is about the exact API. There have been raised some issues about this (https://github.com/pandas-dev/pandas/issues/10109, https://github.com/pandas-dev/pandas/issues/14876#issuecomment-266907956), so I only think we should take this as an opportunity to look at the current `melt` API and see if we would implement it in the same way now. 
And conclusion can well be that we just want to keep it as is.

For example, IMO it would be useful to make a comparison between the R `melt` and `gather`, see how Hadley has improved it in the new `gather` version and see if we can learn something of it.

If we don't find the time for this before 0.20 release, I am OK with merging this.

ok @ResidentMario pls make those corrections and we can merge. If after this (in next week or two) we can figure out a better API we can discuss, otherwise can do it in next major version.

Note that also like to incorporate (and deprecate) ``wide_to_long`` here. 

btw should also look at ``cast`` and ``reshape`` R functions for inspiration.
-1 on incoroporating ``wide_to_long``. As far as I know, it is hardly used, and has an API that is not really 'pandonic'.
`stack`, `unstack`, `melt`, etcetera...agree that studying the possible advantages of data transforms in other languages would be a good thing.

I don't see this being done in the next two weeks however.
@ResidentMario 

> stack, unstack, melt, etcetera...agree that studying the possible advantages of data transforms in other languages would be a good thing.

> I don't see this being done in the next two weeks however.

not a problem
thanks @ResidentMario 

I made the doc-string a tiny bit more flexible (so the examples are more clear), but great patch!