API: add "level=" argument to MultiIndex.unique()

closes pandas-dev#17896

Author: toobaz

doc/source/whatsnew/v0.21.0.txt

@@ -792,6 +792,7 @@ Other API Changes
 - Pandas no longer registers matplotlib converters on import. The converters
   will be registered and used when the first plot is draw (:issue:`17710`)
 - Setting on a column with a scalar value and 0-len index now raises a ``ValueError`` (:issue:`16823`)
+- :func:`MultiIndex.unique` now supports the ``level=`` argument (:issue:`17896`)
 
 
 .. _whatsnew_0210.deprecations:

pandas/core/indexes/multi.py

@@ -886,7 +886,7 @@ def _try_mi(k):
 
             raise InvalidIndexError(key)
 
-    def _get_level_values(self, level):
+    def _get_level_values(self, level, unique=False):
         """
         Return vector of label values for requested level,
         equal to the length of the index
@@ -896,17 +896,23 @@ def _get_level_values(self, level):
         Parameters
         ----------
         level : int level
+        unique : bool
+            if True, drop duplicated values
+
+            .. versionadded:: 0.21.0
 
         Returns
         -------
         values : ndarray
         """
 
-        unique = self.levels[level]
+        values = self.levels[level]
         labels = self.labels[level]
-        filled = algos.take_1d(unique._values, labels,
-                               fill_value=unique._na_value)
-        values = unique._shallow_copy(filled)
+        if unique:
+            labels = algos.unique(labels[labels != -1])
+        filled = algos.take_1d(values._values, labels,
+                               fill_value=values._na_value)
+        values = values._shallow_copy(filled)
         return values
 
     def get_level_values(self, level):
@@ -945,6 +951,34 @@ def get_level_values(self, level):
         values = self._get_level_values(level)
         return values
 
+    def unique(self, level=None):
+        """
+        Return unique values in the index. Uniques are returned in order
+        of appearance, this does NOT sort.
+
+        Parameters
+        ----------
+        level : int, optional, defaults None
+            only return values from specific level
+
+            .. versionadded:: 0.21.0
+
+        Returns
+        -------
+        Index without duplicates (MultiIndex as long as level=None)
+
+        See Also
+        --------
+        unique
+        Index.unique
+        Series.unique
+        """
+
+        if level is None:
+            return super(MultiIndex, self).unique()
+        else:
+            return self._get_level_values(level=level, unique=True)
+
     def format(self, space=2, sparsify=None, adjoin=True, names=False,
                na_rep=None, formatter=None):
         if len(self) == 0:

pandas/tests/indexes/test_multi.py

@@ -2268,6 +2268,20 @@ def test_unique(self):
         exp = pd.MultiIndex.from_arrays([['a'], ['a']])
         tm.assert_index_equal(res, exp)
 
+        # GH #17896 - with level= argument
+        result = self.index.unique(level=0)
+        expected = Index(['foo', 'bar', 'baz', 'qux'],
+                         name='first')
+        tm.assert_index_equal(result, expected)
+        assert result.name == 'first'
+
+        # with NaNs
+        arrays = [['a', 'b', 'b'], [2, np.nan, 2]]
+        index = pd.MultiIndex.from_arrays(arrays)
+        values = index.unique(level=1)
+        expected = np.array([2], dtype=np.int64)
+        tm.assert_numpy_array_equal(values.values, expected)
+
     def test_unique_datetimelike(self):
         idx1 = pd.DatetimeIndex(['2015-01-01', '2015-01-01', '2015-01-01',
                                  '2015-01-01', 'NaT', 'NaT'])