Repository: pandas-dev/pandas

Issue:
DataFrame.idxmax returns NaN if all entries are NaN, contradicts idxmax documentation
#### Code Sample, a copy-pastable example if possible

```python
(Pdb) df = pd.DataFrame({'a': [pd.np.nan]*10})
(Pdb) df.idxmax()
a   NaN
dtype: float64
(Pdb) df.idxmax(skipna=True)
a   NaN
dtype: float64
(Pdb) pd.__version__
'0.20.2'
```
#### Problem description

According to [DataFrame.idxmax documentation](https://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.idxmax.html): `If an entire row/column is NA, the result will be first index`

#### Expected Output
```
df.idxmax(skipna=True)
a     0
```
#### Output of ``pd.show_versions()``

<details>

------------------
commit: None
python: 3.4.2.final.0
python-bits: 64
OS: Linux
OS-release: 4.9.0-4-amd64
machine: x86_64
processor: 
byteorder: little
LC_ALL: None
LANG: en_CA.utf8
LOCALE: en_CA.UTF-8

pandas: 0.20.2
pytest: 2.9.1
pip: 9.0.1
setuptools: 36.2.7
Cython: None
numpy: 1.13.0
scipy: 0.19.0
xarray: None
IPython: 5.1.0
sphinx: None
patsy: None
dateutil: 2.5.3
pytz: 2016.4
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: 2.0.2
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: 1.0b10
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: 2.8
s3fs: None
pandas_gbq: None
pandas_datareader: None

</details>

Multiindex.fillna() throws NotImplementedError but docs indicate it should work 
#### Code Sample, a copy-pastable example if possible

```python
idx = pd.MultiIndex.from_arrays([['a','b'],[1,np.nan]])
idx.fillna()
idx.values

```
#### Problem description
Error trace:
```
---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
<ipython-input-63-feda4f0ee830> in <module>()
      1 idx = pd.MultiIndex.from_arrays([['a','b'],[1,np.nan]])
----> 2 idx.fillna()

~\Anaconda2\envs\python3\lib\site-packages\pandas\core\indexes\multi.py in fillna(self, value, downcast)
    784     def fillna(self, value=None, downcast=None):
    785         # isnull is not implemented for MultiIndex
--> 786         raise NotImplementedError('isnull is not defined for MultiIndex')
    787 
    788     @Appender(_index_shared_docs['dropna'])

NotImplementedError: isnull is not defined for MultiIndex
```

docs seem to state it should work: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.MultiIndex.fillna.html

I am running v20.3 (anaconda doesnt seem to have 21.0 yet). But i've checked code and docs from both v21.0 and master and it seems to be the same

#### Expected Output

`array([('a', 1.0), ('b', 999)], dtype=object)
`
#### Output of ``pd.show_versions()``

<details>

INSTALLED VERSIONS
------------------
commit: None
python: 3.6.3.final.0
python-bits: 64
OS: Windows
OS-release: 10
machine: AMD64
processor: Intel64 Family 6 Model 78 Stepping 3, GenuineIntel
byteorder: little
LC_ALL: None
LANG: None
LOCALE: None.None

pandas: 0.20.3
pytest: 3.2.1
pip: 9.0.1
setuptools: 36.5.0.post20170921
Cython: 0.26.1
numpy: 1.13.3
scipy: 0.19.1
xarray: 0.9.6
IPython: 6.1.0
sphinx: 1.6.3
patsy: 0.4.1
dateutil: 2.6.1
pytz: 2017.2
blosc: None
bottleneck: 1.2.1
tables: 3.4.2
numexpr: 2.6.2
feather: None
matplotlib: 2.1.0
openpyxl: 2.4.8
xlrd: 1.1.0
xlwt: 1.3.0
xlsxwriter: 1.0.2
lxml: 4.1.0
bs4: 4.6.0
html5lib: 0.999999999
sqlalchemy: 1.1.13
pymysql: None
psycopg2: None
jinja2: 2.9.6
s3fs: None
pandas_gbq: None
pandas_datareader: None

</details>



Discussion:
the result is correct, its the documentation that is wrong. If you have an all NaN column we have no choice but to return NaN. 

@TomAugspurger 
ok thanks @jreback for clarifying, I guessed so since series' `idxmax` doc. does not mention that clause.
I think I'll manually do `.fillna(df.apply(lambda x: x.index[0]))` in my code as a workaround
@ghasemnaddaf if you'd like to do a PR to clarify in the docs? (in Series as well) would be great.
very odd that the doc is showing up at all. Its simply not defined (though it is in a super-class), so maybe bleeding thru somehow.

cc @TomAugspurger 
It is defined, but it just raises `NotImplementedError`. The docstring is inherited though.

We could override the docstring saying it's not implemented, but that's just a short term fix. I'm going to spend some time on our docs over the next couple weeks, so I hope to fix it properly then.
Yes, this is completely expected. 

@robbuckley a short term fix of updating the MultiIndex.fillna docstring is still welcome if you want to do a PR!

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -5781,7 +5781,12 @@ def idxmin(self, axis=0, skipna=True):
             0 or 'index' for row-wise, 1 or 'columns' for column-wise
         skipna : boolean, default True
             Exclude NA/null values. If an entire row/column is NA, the result
-            will be NA
+            will be NA.
+
+        Raises
+        ------
+        ValueError
+            * If the row/column is empty
 
         Returns
         -------
@@ -5812,7 +5817,12 @@ def idxmax(self, axis=0, skipna=True):
             0 or 'index' for row-wise, 1 or 'columns' for column-wise
         skipna : boolean, default True
             Exclude NA/null values. If an entire row/column is NA, the result
-            will be first index.
+            will be NA.
+
+        Raises
+        ------
+        ValueError
+            * If the row/column is empty
 
         Returns
         -------
diff --git a/pandas/core/series.py b/pandas/core/series.py
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -1306,7 +1306,13 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs):
         Parameters
         ----------
         skipna : boolean, default True
-            Exclude NA/null values
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
+
+        Raises
+        ------
+        ValueError
+            * If the Series is empty
 
         Returns
         -------
@@ -1336,7 +1342,13 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
         Parameters
         ----------
         skipna : boolean, default True
-            Exclude NA/null values
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
+
+        Raises
+        ------
+        ValueError
+            * If the Series is empty
 
         Returns
         -------


Test patch: