Merge branch 'categorical-cleanup' of https://github.com/jseabold/pandas into jseabold-categorical-cleanup

Conflicts:
	RELEASE.rst

Author: jreback

RELEASE.rst

@@ -61,6 +61,7 @@ pandas 0.11.1
     - table writing performance improvements.
   - Add modulo operator to Series, DataFrame
   - Add ``date`` method to DatetimeIndex
+  - Simplified the API and added a describe method to Categorical
 
 **API Changes**
 

doc/source/groupby.rst

@@ -606,8 +606,8 @@ versions of pandas, but users were generally discarding the NA group anyway
 Grouping with ordered factors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Categorical variables represented as instance of pandas's ``Factor`` class can
-be used as group keys. If so, the order of the levels will be preserved:
+Categorical variables represented as instance of pandas's ``Categorical`` class
+can be used as group keys. If so, the order of the levels will be preserved:
 
 .. ipython:: python
 

pandas/core/categorical.py

@@ -5,6 +5,7 @@
 from pandas.core.algorithms import factorize
 from pandas.core.index import Index
 import pandas.core.common as com
+from pandas.core.frame import DataFrame
 
 
 def _cat_compare_op(op):
@@ -32,23 +33,68 @@ class Categorical(object):
     Parameters
     ----------
     labels : ndarray of integers
-    levels : Index-like (unique)
-
-    data : array-like
+        If levels is given, the integer at label `i` is the index of the level
+        for that label. I.e., the level at labels[i] is levels[labels[i]].
+        Otherwise, if levels is None, these are just the labels and the levels
+        are assumed to be the unique labels. See from_array.
+    levels : Index-like (unique), optional
+        The unique levels for each label. If not given, the levels are assumed
+        to be the unique values of labels.
+    name : str, optional
+        Name for the Categorical variable. If levels is None, will attempt
+        to infer from labels.
 
     Returns
     -------
     **Attributes**
       * labels : ndarray
       * levels : ndarray
+
+    Examples
+    --------
+    >>> from pandas import Categorical
+    >>> Categorical([0, 1, 2, 0, 1, 2], [1, 2, 3])
+    Categorical:
+    array([1, 2, 3, 1, 2, 3])
+    Levels (3): Int64Index([1, 2, 3])
+
+    >>> Categorical([0,1,2,0,1,2], ['a', 'b', 'c'])
+    Categorical:
+    array(['a', 'b', 'c', 'a', 'b', 'c'], dtype=object)
+    Levels (3): Index(['a', 'b', 'c'], dtype=object)
+
+    >>> Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
+    Categorical:
+    array(['a', 'b', 'c', 'a', 'b', 'c'], dtype=object)
+    Levels (3): Index(['a', 'b', 'c'], dtype=object)
     """
-    def __init__(self, labels, levels, name=None):
+    def __init__(self, labels, levels=None, name=None):
+        if levels is None:
+            if name is None:
+                name = getattr(labels, 'name', None)
+            if isinstance(labels, Index) and hasattr(labels, 'factorize'):
+                labels, levels = labels.factorize()
+            else:
+                try:
+                    labels, levels = factorize(labels, sort=True)
+                except TypeError:
+                    labels, levels = factorize(labels, sort=False)
+
         self.labels = labels
         self.levels = levels
         self.name = name
 
     @classmethod
     def from_array(cls, data):
+        """
+        Make a Categorical type from a single array-like object.
+
+        Parameters
+        ----------
+        data : array-like
+            Can be an Index or array-like. The levels are assumed to be
+            the unique values of `data`.
+        """
         if isinstance(data, Index) and hasattr(data, 'factorize'):
             labels, levels = data.factorize()
         else:
@@ -131,4 +177,28 @@ def equals(self, other):
         return (self.levels.equals(other.levels) and
                 np.array_equal(self.labels, other.labels))
 
-Factor = Categorical
+    def describe(self):
+        """
+        Returns a dataframe with frequency and counts by level.
+        """
+        #Hack?
+        grouped = DataFrame(self.labels).groupby(0)
+        counts = grouped.count().values.squeeze()
+        freqs = counts/float(counts.sum())
+        return DataFrame.from_dict(dict(
+                                    counts=counts,
+                                    freqs=freqs,
+                                    levels=self.levels)).set_index('levels')
+
+
+class Factor(Categorical):
+    def __init__(self, labels, levels=None, name=None):
+        from warnings import warn
+        warn("Factor is deprecated. Use Categorical instead", FutureWarning)
+        super(Factor, self).__init__(labels, levels, name)
+
+    @classmethod
+    def from_array(cls, data):
+        from warnings import warn
+        warn("Factor is deprecated. Use Categorical instead", FutureWarning)
+        return super(Factor, cls).from_array(data)

pandas/core/frame.py

@@ -1704,8 +1704,8 @@ def convert_objects(self, convert_dates=True, convert_numeric=False, copy=True):
         -------
         converted : DataFrame
         """
-        return self._constructor(self._data.convert(convert_dates=convert_dates, 
-                                                    convert_numeric=convert_numeric, 
+        return self._constructor(self._data.convert(convert_dates=convert_dates,
+                                                    convert_numeric=convert_numeric,
                                                     copy=copy))
 
     #----------------------------------------------------------------------
@@ -3375,7 +3375,7 @@ def fillna(self, value=None, method=None, axis=0, inplace=False,
             a reference to the filled object, which is self if inplace=True
         limit : int, default None
             Maximum size gap to forward or backward fill
-        downcast : dict, default is None, a dict of item->dtype of what to 
+        downcast : dict, default is None, a dict of item->dtype of what to
             downcast if possible
 
         See also
@@ -3425,7 +3425,7 @@ def fillna(self, value=None, method=None, axis=0, inplace=False,
                     result[k].fillna(v, inplace=True)
                 return result
             else:
-                new_data = self._data.fillna(value, inplace=inplace, 
+                new_data = self._data.fillna(value, inplace=inplace,
                                              downcast=downcast)
 
         if inplace:
@@ -3966,8 +3966,8 @@ def combine(self, other, func, fill_value=None, overwrite=True):
             result[col] = arr
 
         # convert_objects just in case
-        return self._constructor(result, 
-                                 index=new_index, 
+        return self._constructor(result,
+                                 index=new_index,
                                  columns=new_columns).convert_objects(
             convert_dates=True,
             copy=False)
@@ -4000,7 +4000,7 @@ def combiner(x, y, needs_i8_conversion=False):
                 y_values = y_values.view('i8')
             else:
                 mask = isnull(x_values)
-            
+
             return expressions.where(mask, y_values, x_values, raise_on_error=True)
 
         return self.combine(other, combiner, overwrite=False)
@@ -5581,11 +5581,11 @@ def group_agg(values, bounds, f):
 
 def factor_agg(factor, vec, func):
     """
-    Aggregate array based on Factor
+    Aggregate array based on Categorical
 
     Parameters
     ----------
-    factor : Factor
+    factor : Categorical
         length n
     vec : sequence
         length n
@@ -5594,7 +5594,11 @@ def factor_agg(factor, vec, func):
 
     Returns
     -------
-    ndarray corresponding to Factor levels
+    ndarray corresponding to factor levels
+
+    See Also
+    --------
+    pandas.Categorical
     """
     indexer = np.argsort(factor.labels)
     unique_labels = np.arange(len(factor.levels))

pandas/core/panel.py

@@ -10,7 +10,7 @@
                                 _try_sort, _default_index,
                                 _infer_dtype_from_scalar,
                                 notnull)
-from pandas.core.categorical import Factor
+from pandas.core.categorical import Categorical
 from pandas.core.index import (Index, MultiIndex, _ensure_index,
                                _get_combined_index)
 from pandas.core.indexing import _maybe_droplevels, _is_list_like
@@ -82,8 +82,8 @@ def panel_index(time, panels, names=['time', 'panel']):
                 (1962, 'C')], dtype=object)
     """
     time, panels = _ensure_like_indices(time, panels)
-    time_factor = Factor.from_array(time)
-    panel_factor = Factor.from_array(panels)
+    time_factor = Categorical.from_array(time)
+    panel_factor = Categorical.from_array(panels)
 
     labels = [time_factor.labels, panel_factor.labels]
     levels = [time_factor.levels, panel_factor.levels]

pandas/core/reshape.py

@@ -791,9 +791,9 @@ def make_axis_dummies(frame, axis='minor', transform=None):
     axis : {'major', 'minor'}, default 'minor'
     transform : function, default None
         Function to apply to axis labels first. For example, to
-        get "day of week" dummies in a time series regression 
+        get "day of week" dummies in a time series regression
         you might call::
-            
+
             make_axis_dummies(panel, axis='major',
                               transform=lambda d: d.weekday())
     Returns
@@ -852,6 +852,6 @@ def block2d_to_blocknd(values, items, shape, labels, ref_items=None):
 
 
 def factor_indexer(shape, labels):
-    """ given a tuple of shape and a list of Factor lables, return the expanded label indexer """
+    """ given a tuple of shape and a list of Categorical labels, return the expanded label indexer """
     mult = np.array(shape)[::-1].cumprod()[::-1]
     return com._ensure_platform_int(np.sum(np.array(labels).T * np.append(mult, [1]), axis=1).T)

pandas/tests/test_factor.py

@@ -9,6 +9,7 @@
 from pandas.core.api import value_counts
 from pandas.core.categorical import Categorical
 from pandas.core.index import Index, Int64Index, MultiIndex
+from pandas.core.frame import DataFrame
 from pandas.util.testing import assert_almost_equal
 import pandas.core.common as com
 
@@ -111,6 +112,29 @@ def test_na_flags_int_levels(self):
 
         self.assert_(np.array_equal(com.isnull(cat), labels == -1))
 
+    def test_levels_none(self):
+        factor = Categorical(['a', 'b', 'b', 'a',
+                              'a', 'c', 'c', 'c'])
+        self.assert_(factor.equals(self.factor))
+
+    def test_describe(self):
+        # string type
+        desc = self.factor.describe()
+        expected = DataFrame.from_dict(dict(counts=[3, 2, 3],
+                                            freqs=[3/8., 2/8., 3/8.],
+                                            levels=['a', 'b', 'c'])
+                                            ).set_index('levels')
+        tm.assert_frame_equal(desc, expected)
+
+        # check an integer one
+        desc = Categorical([1,2,3,1,2,3,3,2,1,1,1]).describe()
+        expected = DataFrame.from_dict(dict(counts=[5, 3, 3],
+                                            freqs=[5/11., 3/11., 3/11.],
+                                            levels=[1,2,3]
+                                            )
+                                            ).set_index('levels')
+        tm.assert_frame_equal(desc, expected)
+
 if __name__ == '__main__':
     import nose
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],

pandas/tools/merge.py

@@ -5,7 +5,7 @@
 import itertools
 import numpy as np
 
-from pandas.core.categorical import Factor
+from pandas.core.categorical import Categorical
 from pandas.core.frame import DataFrame, _merge_doc
 from pandas.core.generic import NDFrame
 from pandas.core.groupby import get_group_index
@@ -1200,7 +1200,7 @@ def _make_concat_multiindex(indexes, keys, levels=None, names=None):
             names = [None] * len(zipped)
 
         if levels is None:
-            levels = [Factor.from_array(zp).levels for zp in zipped]
+            levels = [Categorical.from_array(zp).levels for zp in zipped]
         else:
             levels = [_ensure_index(x) for x in levels]
     else:
@@ -1238,7 +1238,7 @@ def _make_concat_multiindex(indexes, keys, levels=None, names=None):
             levels.extend(concat_index.levels)
             label_list.extend(concat_index.labels)
         else:
-            factor = Factor.from_array(concat_index)
+            factor = Categorical.from_array(concat_index)
             levels.append(factor.levels)
             label_list.append(factor.labels)