Merge pull request #8153 from JanSchulz/categorical_fixups_2

Fixups for categoricals

Author: jreback

doc/source/10min.rst

@@ -652,11 +652,11 @@ Since version 0.15, pandas can include categorical data in a ``DataFrame``. For
     # Alternative: df["grade"] = df["raw_grade"].astype("category")
     df["grade"]
 
-    # Rename the levels
-    df["grade"].cat.levels = ["very good", "good", "very bad"]
+    # Rename the categories inplace
+    df["grade"].cat.categories = ["very good", "good", "very bad"]
 
-    # Reorder the levels and simultaneously add the missing levels
-    df["grade"].cat.reorder_levels(["very bad", "bad", "medium", "good", "very good"])
+    # Reorder the categories and simultaneously add the missing categories
+    df["grade"] = df["grade"].cat.set_categories(["very bad", "bad", "medium", "good", "very good"])
     df["grade"]
     df.sort("grade")
     df.groupby("grade").size()

doc/source/api.rst

@@ -555,26 +555,33 @@ Categorical
 
 .. currentmodule:: pandas.core.categorical
 
-If the Series is of dtype ``category``, ``Series.cat`` can be used to access the the underlying
-``Categorical``. This accessor is similar to the ``Series.dt`` or ``Series.str``and has the
+If the Series is of dtype ``category``, ``Series.cat`` can be used to change the the categorical
+data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the
 following usable methods and properties (all available as ``Series.cat.<method_or_property>``).
 
 .. autosummary::
    :toctree: generated/
 
-   Categorical.levels
+   Categorical.categories
    Categorical.ordered
-   Categorical.reorder_levels
-   Categorical.remove_unused_levels
+   Categorical.rename_categories
+   Categorical.reorder_categories
+   Categorical.add_categories
+   Categorical.remove_categories
+   Categorical.remove_unused_categories
+   Categorical.set_categories
+   Categorical.codes
+
+To create a Series of dtype ``category``, use ``cat = s.astype("category")``.
 
-The following methods are considered API when using ``Categorical`` directly:
+The following two ``Categorical`` constructors are considered API but should only be used when
+adding ordering information or special categories is need at creation time of the categorical data:
 
 .. autosummary::
    :toctree: generated/
 
    Categorical
    Categorical.from_codes
-   Categorical.codes
 
 ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts
 the Categorical back to a numpy array, so levels and order information is not preserved!