Repository: dask/dask

Issue:
dask.dataframe.DataFrame.rename not allowed
Is it really not allowed to rename columns of Dask DataFrame's?

The code to reproduce it:

```python
import pandas as pd
import dask.dataframe as dd
df1 = pd.DataFrame(data={'a':[1,2,3],'b':[10,20,30]})
dd1 = dd.from_pandas(df1, npartitions=3)
dd1.rename(index=str, columns={'a':'A'})
```
gives
> Traceback (most recent call last):
>   File "<stdin>", line 1, in <module>
>   File "/path/to/Python-3.6.3/lib/python3.6/site-packages/dask/dataframe/core.py", line 2565, in rename
>     raise ValueError("Cannot rename index.")
> ValueError: Cannot rename index.

The corresponding line in the core.py says:
```python
        if index is not None:
            raise ValueError("Cannot rename index.")
```
However, even Dask's own documentation examples allow `index=str`:
http://dask.pydata.org/en/latest/dataframe-api.html#dask.dataframe.DataFrame.rename


Discussion:
Renaming can be done by just removing `index=str`:

```python
df1.rename(columns={'a':'A'})
dd1.rename(columns={'a':'A'})
```
I guess, documentation is the problem.
Good catch! 

The `rename` docstring for dask dataframes is taken from the `rename` docstring for pandas dataframes. That's why examples like 

```python
>>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})  
>>> df.rename(index=str, columns={"A": "a", "B": "c"})  
   a  c
0  1  4
1  2  5
2  3  6
```

are present in http://dask.pydata.org/en/latest/dataframe-api.html#dask.dataframe.DataFrame.rename. 

However, in the "Notes" section of the dask `rename` documentation, there is a "Dask doesn’t support the following argument(s)" list that specifies which arguments are supported in pandas, but not in dask. As you can see, `index` should be in this list, but is missing. 

@vss888 is this something that you are interested in fixing?
On second thought, I'm not actually sure why `index` in present in dask's `rename` to begin with. @TomAugspurger any thoughts on this? 
> On second thought, I'm not actually sure why index in present in dask's rename to begin with

What do you mean by "present in dask's"?

I think we can't (easily) rename index values, since that would break the partitioning scheme. We could no longer trust that the index values within a partition will be between the divisions for that partition.
I mean that if we can't rename index values easily, then why is `index` an input parameter in dask's `rename`? Could we have

```python
@derived_from(pd.DataFrame)
def rename(self, columns=None):
    # *args here is index, columns but columns arg is already used
    return self.map_partitions(M.rename, None, columns=columns)
```

instead of 

https://github.com/dask/dask/blob/390fc144d917aa13c47ed59925a78ad220377f82/dask/dataframe/core.py#L2568-L2574
I see what you mean now. I think it's preferable to have the same function signature, even if we can't support it. That way people writing code like `df.rename(str)`, which might work with pandas, will error with dask, rather than incorrectly changing your columns to strings.
> That way people writing code like df.rename(str), which might work with pandas, will error with dask, rather than incorrectly changing your columns to strings.

Oh I see, that seems reasonable. 

@vss888 is adding `index` to the "Dask doesn’t support the following argument(s)" list for `rename` something you're interested in doing?
@jrbourbeau I might, but  I do not understand the request. Are you asking to update the documentation?
> Are you asking to update the documentation?

Yes

`rename` is wrapped with a `derived_from` decorated to create the dask `rename` docstring from the pandas `rename` docstring

https://github.com/dask/dask/blob/6f9bf19a0f1bf2f410fef08b3cdaf8f78f024737/dask/dataframe/core.py#L2568-L2574

The `derived_from` function has an `ua_args` parameter that is a list of parameters that are supported in pandas, but aren't supported in dask

https://github.com/dask/dask/blob/6f9bf19a0f1bf2f410fef08b3cdaf8f78f024737/dask/utils.py#L463-L475

If you add `'index'` to the `ua_args` for `rename` in dask, then it will be added to the "Dask doesn’t support the following argument(s)" list for `rename` in the docstring. 
I am not sure I will have time to contribute to the code: work is overwhelming.

However, here is one more candidate for documentation update:

```python
import pandas as pd
import dask.dataframe as dd
df1 = pd.DataFrame(data={'a':[1,2,3],'b':[10,20,30]})
dd1 = dd.from_pandas(df1, npartitions=3)
dd1.drop(['a'], axis='columns', inplace=True)
```

gives

```
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: drop() got an unexpected keyword argument 'inplace'
```

However, documentation

http://dask.pydata.org/en/latest/dataframe-api.html#dask.dataframe.DataFrame.drop

has the 'inplace' parameter.

Resolving patch:
diff --git a/dask/dataframe/core.py b/dask/dataframe/core.py
--- a/dask/dataframe/core.py
+++ b/dask/dataframe/core.py
@@ -2565,7 +2565,7 @@ def assign(self, **kwargs):
         df2 = self._meta.assign(**_extract_meta(kwargs))
         return elemwise(methods.assign, self, *pairs, meta=df2)
 
-    @derived_from(pd.DataFrame)
+    @derived_from(pd.DataFrame, ua_args=['index'])
     def rename(self, index=None, columns=None):
         if index is not None:
             raise ValueError("Cannot rename index.")


Test patch: