diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 47a2cf93a4f89..c2a43c5838a0c 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -416,13 +416,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then MSG='Partially validate docstrings (ES01)' ; echo $MSG $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=ES01 --ignore_functions \ - pandas.Categorical.__array__\ - pandas.Categorical.as_ordered\ - pandas.Categorical.as_unordered\ pandas.Categorical.dtype\ - pandas.Categorical.ordered\ - pandas.Categorical.remove_unused_categories\ - pandas.Categorical.rename_categories\ pandas.CategoricalDtype\ pandas.CategoricalDtype.categories\ pandas.CategoricalDtype.ordered\ diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 49b8ba4c47811..b7ae841344293 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -842,6 +842,11 @@ def ordered(self) -> Ordered: """ Whether the categories have an ordered relationship. + Returns whether the categories can be ordered. + Ordered categories can be sorted, and operations such + as .min() and .max() make sense and do not raise a + TypeError. + Examples -------- For :class:`pandas.Series`: @@ -986,6 +991,11 @@ def as_ordered(self) -> Self: """ Set the Categorical to be ordered. + Creates a new object that contains the same categories + as the input, but is ordered. This means that the + categories can be sorted, and .min() and .max() operations + do not raise a TypeError. + Returns ------- Categorical @@ -1017,6 +1027,11 @@ def as_unordered(self) -> Self: """ Set the Categorical to be unordered. + Creates a new object that contains the same categories + as the input, but is not ordered. This means that the + categories cannot be sorted, and .min() and .max() + operations raise a TypeError. + Returns ------- Categorical @@ -1160,6 +1175,9 @@ def rename_categories(self, new_categories) -> Self: """ Rename categories. + Renames the categories using an array, a map, or + a lambda function. + Parameters ---------- new_categories : list-like, dict-like or callable @@ -1436,6 +1454,11 @@ def remove_unused_categories(self) -> Self: """ Remove categories which are not used. + Categorical arrays are mutable, and as such + it is possible that some of the initial categories + are no longer used down the line. This removes + original categories that are no longer in use. + Returns ------- Categorical @@ -1663,6 +1686,13 @@ def __array__(self, dtype: NpDtype | None = None) -> np.ndarray: """ The numpy array interface. + This defines the __array__ method within a Pandas Categorical + class, making it compatible with numpy arrays. + + The method returns a numpy array representation of the categorical + data. It accepts an optional dtype parameter, allowing the user + to specify the data type of the resulting numpy array. + Parameters ---------- dtype : np.dtype or None