ENH: Add optional argument keep_index to dataframe melt method
State: closed

Setting keep_index to True will reuse the original DataFrame index +
names of melted columns as additional level. closes issue #17440

- [ ] closes #17440
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

I appreciate any corrections, comments and/or help very much, as this is my first pull request on such a big project. Thank you.



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

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=h1) Report
> Merging [#17459](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/20fee85ede7f2052f855b8f3445cd1ffc17ee0c3?src=pr&el=desc) will **decrease** coverage by `0.02%`.
> The diff coverage is `33.33%`.

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

```diff
@@            Coverage Diff             @@
##           master   #17459      +/-   ##
==========================================
- Coverage   91.15%   91.13%   -0.03%     
==========================================
  Files         163      163              
  Lines       49591    49599       +8     
==========================================
- Hits        45207    45200       -7     
- Misses       4384     4399      +15
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.91% <33.33%> (-0.02%)` | :arrow_down: |
| #single | `40.24% <0%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.72% <ø> (-0.1%)` | :arrow_down: |
| [pandas/core/reshape/reshape.py](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS9yZXNoYXBlLnB5) | `98.25% <33.33%> (-1.04%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17459?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/17459?src=pr&el=footer). Last update [20fee85...0c64bf0](https://codecov.io/gh/pandas-dev/pandas/pull/17459?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks.

We'll need tests and docs as well. Test can go in `tests/reshape`. For the docs, it'll need a whatsnew note in `doc/source/whatsnew/v0.21.0.txt`, prose docs in `doc/source/reshaping.rst`. It'd also be nice to have an example in the docstring.

About the implementation, the `keep_index` keyword doesn't fully describe what we're, since it's "keep the index, *and append `var_name`*. I wonder it makes more sense to have a keyword like `index={None, 'full', 'original', 'var}` (names TBD).

- None: the current behavior, discard the original index and end with a RangeIndex
- 'full': original index + the metadata from var_name
- 'original': the original index
- 'var': The newly created `var` 

But as I write this, I wonder if the last two would ever be useful? Do we just need a better name than `keep_index`?
Thank you for the comments! 

I agree that ```keep_index``` is not descriptive enough. I find it hard to come up with something short that describes the whole idea within a boolean argument. Using your idea of an index keyword with multiple options looks good.

Maybe rename ```'full'``` to ```'append_variables'``` instead? So the whole options would be:
- ```index = {None, ‘original‘, ‘append_variables‘}```

```index = ‘append_variables‘``` would probably be intuitive to understand as ```index = index + variables```

I cannot think of a good usecase for the option ```'var'```, but I started using pandas not long ago, so there might be plenty.

Another idea:

```keep_index (boolean) if True```: 
- Just keep the original index (append nothing) and let the user decide what to append in a next step to make the index unique.

- Just keep the original index and append an additional RangeIndex level (the melt_id from issue #17440) to ensure uniqueness.

Anyway I would go for @TomAugspurger‘s idea to use a keyword with multiple options.

When we have decided what's best, I will challenge myself with writing tests and documentation :).
pls rebase. 
closing as stale
@NiklasKeck @TomAugspurger  What happened to this pull request? I came from #17440  and wish to contribute. 
1st time contributor here, what should i know?  
Below is what i currently think i should do

1. read https://pandas.pydata.org/pandas-docs/stable/contributing.html#committing-your-code,
2. find out which files/functions need to be changed (how do i find out all the paths a function call can take?)
3. find out which files/functions the changes can affect
4. identify their effects and ensure they do not damage existing usability (how is this done?)

 Do i have to choose 1 of Travis-CI, Appveyor , or CircleCI to hook onto my github?
We needed to merge master into this PR to see if the tests still passed.

You can see the changed fils in 
https://github.com/pandas-dev/pandas/pull/17459/files

And then run the tests as described in the contributing docs.

You don't have to do anything with the CI services.