Repository: pandas-dev/pandas
Pull request: BUG: DataFrame.melt gives unexpected result when column "value" already exists
- [ x] closes #34731 
- [x ] tests added / passed
- [ X] passes `black pandas`
- [ x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ x] whatsnew entry


Problem statement:
BUG: DataFrame.melt gives unexpected result when column "value" already exists
- [x] I have checked that this issue has not already been reported.

- [x] I have confirmed this bug exists on the latest version of pandas.

- [ ] (optional) I have confirmed this bug exists on the master branch of pandas.

---

#### Code Sample, a copy-pastable example

```python
df = pd.DataFrame({'col':list('ABC'),
                   'value':range(10,16,2)})
print(df, '\n')

dfm = df.melt(id_vars='value')

print(dfm)

  col  value
0   A     10
1   B     12
2   C     14 

  value variable value
0     A      col     A
1     B      col     B
2     C      col     C
```

#### Problem description

When the column `value` already exists,  and we set it as index with `id_vars` it copies the `value` column of the melted dataframe and does not set the "old" `value` column of the original dataframe as `id_vars`
#### Expected Output
```python
# note change of column name 'val' instead of 'value'
df = pd.DataFrame({'col':list('ABC'),
                   'val':range(10,16,2)})

dfm = df.melt(id_vars='val')

print(dfm)
   val variable value
0   10      col     A
1   12      col     B
2   14      col     C
```
#### Output of ``pd.show_versions()``

<details>

INSTALLED VERSIONS
------------------
commit           : None
python           : 3.8.3.final.0
python-bits      : 64
OS               : Darwin
OS-release       : 19.5.0
machine          : x86_64
processor        : i386
byteorder        : little
LC_ALL           : None
LANG             : None
LOCALE           : None.UTF-8

pandas           : 1.0.3
numpy            : 1.18.1
pytz             : 2020.1
dateutil         : 2.8.1
pip              : 20.0.2
setuptools       : 47.1.1.post20200604
Cython           : None
pytest           : None
hypothesis       : None
sphinx           : None
blosc            : None
feather          : None
xlsxwriter       : None
lxml.etree       : None
html5lib         : None
pymysql          : None
psycopg2         : None
jinja2           : 2.11.2
IPython          : 7.13.0
pandas_datareader: None
bs4              : None
bottleneck       : None
fastparquet      : None
gcsfs            : None
lxml.etree       : None
matplotlib       : None
numexpr          : None
odfpy            : None
openpyxl         : None
pandas_gbq       : None
pyarrow          : None
pytables         : None
pytest           : None
pyxlsb           : None
s3fs             : None
scipy            : None
sqlalchemy       : None
tables           : None
tabulate         : None
xarray           : None
xlrd             : None
xlwt             : None
xlsxwriter       : None
numba            : None
</details>

Hints from issue discussion:
Hmm I don't agree with your expected output. We wouldn't want to change the name of the old one.

I'd prefer that we raise if we detect that we're going to overwrite a value / introduce duplicate labels, unless we document the current behavior.
Yes, I agree, it should at the minimum give a warning.
@TomAugspurger as someone having hard time to get started with contributing, would this be a good one to try? 
Not sure. This will be an API change so I think we'll need to warn first, and then in 2.x we can raise.

Commit message: enacted isortification on patch

Patch to review:
diff --git a/doc/source/whatsnew/v1.1.0.rst b/doc/source/whatsnew/v1.1.0.rst
index 60aa1759958f6..558878a0ca5d5 100644
--- a/doc/source/whatsnew/v1.1.0.rst
+++ b/doc/source/whatsnew/v1.1.0.rst
@@ -1082,6 +1082,7 @@ Reshaping
 - Fixed bug in :func:`melt` where melting MultiIndex columns with ``col_level`` > 0 would raise a ``KeyError`` on ``id_vars`` (:issue:`34129`)
 - Bug in :meth:`Series.where` with an empty Series and empty ``cond`` having non-bool dtype (:issue:`34592`)
 - Fixed regression where :meth:`DataFrame.apply` would raise ``ValueError`` for elements whth ``S`` dtype (:issue:`34529`)
+- Issue warning if value column name already exists when using :meth:`DataFrame.melt` (:issue:`34731`)
 
 Sparse
 ^^^^^^
diff --git a/pandas/core/reshape/melt.py b/pandas/core/reshape/melt.py
index 845f6b67693f4..f44f577f0e546 100644
--- a/pandas/core/reshape/melt.py
+++ b/pandas/core/reshape/melt.py
@@ -1,5 +1,6 @@
 import re
 from typing import TYPE_CHECKING, List, cast
+import warnings
 
 import numpy as np
 
@@ -40,6 +41,13 @@ def melt(
     else:
         cols = list(frame.columns)
 
+    if value_name in frame.columns:
+        warnings.warn(
+            'The value column name "%s" conflicts with an existing '
+            "column in the dataframe." % (value_name),
+            DeprecationWarning,
+        )
+
     if id_vars is not None:
         if not is_list_like(id_vars):
             id_vars = [id_vars]
diff --git a/pandas/tests/reshape/test_melt.py b/pandas/tests/reshape/test_melt.py
index 000a6354277ab..7793f1a96114d 100644
--- a/pandas/tests/reshape/test_melt.py
+++ b/pandas/tests/reshape/test_melt.py
@@ -1,3 +1,5 @@
+import warnings
+
 import numpy as np
 import pytest
 
@@ -1014,3 +1016,16 @@ def test_col_substring_of_stubname(self):
         )
         result = pd.wide_to_long(wide_df, stubnames="PA", i=["node_id", "A"], j="time")
         tm.assert_frame_equal(result, expected)
+
+    def test_warn_of_column_name_value(self):
+        # GH34731
+        # raise a warning if the resultant value column name matches
+        # a name in the dataframe already (default name is "value")
+        df = pd.DataFrame({"col": list("ABC"), "value": range(10, 16, 2)})
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            dfm = df.melt(id_vars="value")  # noqa F841
+            assert len(w) == 1
+            assert issubclass(w[-1].category, DeprecationWarning)
+            assert "conflicts" in str(w[-1].message)


Code review comments:
diff_hunk: @@ -1014,3 +1016,16 @@ def test_col_substring_of_stubname(self):
         )
         result = pd.wide_to_long(wide_df, stubnames="PA", i=["node_id", "A"], j="time")
         tm.assert_frame_equal(result, expected)
+
+    def test_warn_of_column_name_value(self):
+        # GH34731
+        # raise a warning if the resultant value column name matches
+        # a name in the dataframe already (default name is "value")
+        df = pd.DataFrame({"col": list("ABC"), "value": range(10, 16, 2)})
+
+        with warnings.catch_warnings(record=True) as w:
path: pandas/tests/reshape/test_melt.py
text: @user1:
Can you use tm.assert_produces_warning here (e.g., as in L580 of this file)?