DOC: clarify level argument of reindex

[jorisvandenbossche]

The current docstring explanation of the level argument:

Broadcast across a level, matching Index values on the passed MultiIndex level

is not very clarifying (match what on what?).

So it would be good to update that description and also add an example.

[jorisvandenbossche]

There is one example in the tutorial docs: http://pandas.pydata.org/pandas-docs/stable/advanced.html#advanced-reindexing-and-alignment

What is not clear about the argument, is that it seems to work for both the passed and calling index:

In [1]: s = pd.Series(range(2), index=['a', 'c'])

In [2]: s_multi = pd.Series(range(9), index=pd.MultiIndex.from_product([['A', 'B', 'C'], ['a', 'b', 'c']]))

# reindexing a specific level of the calling multi-indexed object
In [3]: s_multi.reindex(['a', 'c'], level=1)
Out[3]: 
A  a    0
   c    2
B  a    3
   c    5
C  a    6
   c    8
dtype: int64

# broadcasting the calling object along the level of the passed multi-index
In [4]: s.reindex(s_multi.index, level=1)
Out[4]: 
A  a    0.0
   b    NaN
   c    1.0
B  a    0.0
   b    NaN
   c    1.0
C  a    0.0
   b    NaN
   c    1.0
dtype: float64

[toobaz]

Right... while

In [22]: s_multi.reindex(s_multi.drop(('A', 'a')).index, level=1)
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-22-9e6994e0de21> in <module>()
----> 1 s_multi.reindex(s_multi.drop(('A', 'a')).index, level=1)

/home/pietro/nobackup/repo/pandas/pandas/core/series.py in reindex(self, index, **kwargs)
   2372     @Appender(generic._shared_docs['reindex'] % _shared_doc_kwargs)
   2373     def reindex(self, index=None, **kwargs):
-> 2374         return super(Series, self).reindex(index=index, **kwargs)
   2375 
   2376     @Appender(generic._shared_docs['fillna'] % _shared_doc_kwargs)

/home/pietro/nobackup/repo/pandas/pandas/core/generic.py in reindex(self, *args, **kwargs)
   2331         # perform the reindex on the axes
   2332         return self._reindex_axes(axes, level, limit, tolerance, method,
-> 2333                                   fill_value, copy).__finalize__(self)
   2334 
   2335     def _reindex_axes(self, axes, level, limit, tolerance, method, fill_value,

/home/pietro/nobackup/repo/pandas/pandas/core/generic.py in _reindex_axes(self, axes, level, limit, tolerance, method, fill_value, copy)
   2344             ax = self._get_axis(a)
   2345             new_index, indexer = ax.reindex(labels, level=level, limit=limit,
-> 2346                                             tolerance=tolerance, method=method)
   2347 
   2348             axis = self._get_axis_number(a)

/home/pietro/nobackup/repo/pandas/pandas/indexes/multi.py in reindex(self, target, method, level, limit, tolerance)
   1652             target, indexer, _ = self._join_level(target, level, how='right',
   1653                                                   return_indexers=True,
-> 1654                                                   keep_order=False)
   1655         else:
   1656             target = _ensure_index(target)

/home/pietro/nobackup/repo/pandas/pandas/indexes/base.py in _join_level(self, other, level, how, return_indexers, keep_order)
   2995 
   2996         if isinstance(self, MultiIndex) and isinstance(other, MultiIndex):
-> 2997             raise TypeError('Join on level between two MultiIndex objects '
   2998                             'is ambiguous')
   2999 

TypeError: Join on level between two MultiIndex objects is ambiguous

[jorisvandenbossche]

@toobaz yes, but I think that is to be expected? Presuming that it specifies level=1 for both calling and passed index, it is indeed not clear what the result should be (therefore " is ambiguous")

[toobaz]

Yes, you are right, I just think it is worth mentioning it in the docstring (users might expect something from it when the specified level of either of the two indexes is unique).