chore: remove to_categorical

scikit-hep · Oct 27, 2023 · 62baa96 · 62baa96
1 parent 3f623ee
commit 62baa96
Show file tree

Hide file tree

Showing 17 changed files with 41 additions and 500 deletions.
diff --git a/docs/redirects.json b/docs/redirects.json
@@ -120,7 +120,7 @@
   "_auto/ak.to_arrow.any-ext": "../reference/generated/ak.to_arrow.html",
   "_auto/ak.to_arrow_table.any-ext": "../reference/generated/ak.to_arrow_table.html",
   "_auto/ak.to_buffers.any-ext": "../reference/generated/ak.to_buffers.html",
-  "_auto/ak.to_categorical.any-ext": "../reference/generated/ak.to_categorical.html",
+  "_auto/ak.to_categorical.any-ext": "../reference/generated/ak.str.to_categorical.html",
   "_auto/ak.to_cupy.any-ext": "../reference/generated/ak.to_cupy.html",
   "_auto/ak.to_jax.any-ext": "../reference/generated/ak.to_jax.html",
   "_auto/ak.to_json.any-ext": "../reference/generated/ak.to_json.html",

diff --git a/docs/reference/toctree.txt b/docs/reference/toctree.txt
@@ -232,10 +232,10 @@
 .. toctree::
     :caption: Arrays of categorical data
 
-    generated/ak.to_categorical
     generated/ak.from_categorical
     generated/ak.is_categorical
     generated/ak.categories
+    generated/ak.str.to_categorical
 
 .. toctree::
     :caption: Indexing and grouping

diff --git a/docs/user-guide/how-to-create-strings.md b/docs/user-guide/how-to-create-strings.md
@@ -95,15 +95,15 @@ Categorical strings
 
 A large set of strings with few unique values are more efficiently manipulated as integers than as strings. In Pandas, this is [categorical data](https://pandas.pydata.org/pandas-docs/stable/user_guide/categorical.html), in R, it's called a [factor](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/factor), and in Arrow and Parquet, it's [dictionary encoding](https://arrow.apache.org/blog/2019/09/05/faster-strings-cpp-parquet/).
 
-The {func}`ak.to_categorical` function makes Awkward Arrays categorical in this sense. {func}`ak.to_arrow` and {func}`ak.to_parquet` recognize categorical data and convert it to the corresponding Arrow and Parquet types.
+The {func}`ak.str.to_categorical` (requires PyArrow) function makes Awkward Arrays categorical in this sense. {func}`ak.to_arrow` and {func}`ak.to_parquet` recognize categorical data and convert it to the corresponding Arrow and Parquet types.
 
 ```{code-cell} ipython3
 uncategorized = ak.Array(["three", "one", "two", "two", "three", "one", "one", "one"])
 uncategorized
 ```
 
 ```{code-cell} ipython3
-categorized = ak.to_categorical(uncategorized)
+categorized = ak.str.to_categorical(uncategorized)
 categorized
 ```
 

diff --git a/src/awkward/operations/__init__.py b/src/awkward/operations/__init__.py
@@ -78,7 +78,6 @@
 from awkward.operations.ak_to_arrow_table import *
 from awkward.operations.ak_to_backend import *
 from awkward.operations.ak_to_buffers import *
-from awkward.operations.ak_to_categorical import *
 from awkward.operations.ak_to_cupy import *
 from awkward.operations.ak_to_dataframe import *
 from awkward.operations.ak_to_feather import *

diff --git a/src/awkward/operations/ak_categories.py b/src/awkward/operations/ak_categories.py
@@ -18,7 +18,7 @@ def categories(array, highlevel=True):
     #ak.contents.IndexedOptionArray labeled with parameter
     `"__array__" = "categorical"`), then this function returns its categories.
 
-    See also #ak.is_categorical, #ak.to_categorical, #ak.from_categorical.
+    See also #ak.is_categorical, #ak.str.to_categorical, #ak.from_categorical.
     """
     # Dispatch
     yield (array,)

diff --git a/src/awkward/operations/ak_from_categorical.py b/src/awkward/operations/ak_from_categorical.py
@@ -23,8 +23,7 @@ def from_categorical(array, *, highlevel=True, behavior=None):
     size of the dataset. (Conversion to categorical is expensive; conversion
     from categorical is cheap.)
 
-    See also #ak.is_categorical, #ak.categories, #ak.to_categorical,
-    #ak.str.to_categorical, #ak.from_categorical.
+    See also #ak.is_categorical, #ak.categories, #ak.str.to_categorical.
     """
     # Dispatch
     yield (array,)

diff --git a/src/awkward/operations/ak_is_categorical.py b/src/awkward/operations/ak_is_categorical.py
@@ -15,7 +15,7 @@ def is_categorical(array):
     `"__array__" = "categorical"`), then this function returns True;
     otherwise, it returns False.
 
-    See also #ak.categories, #ak.to_categorical, #ak.from_categorical.
+    See also #ak.categories, #ak.str.to_categorical, #ak.from_categorical.
     """
     # Dispatch
     yield (array,)

diff --git a/src/awkward/operations/ak_to_categorical.py b/src/awkward/operations/ak_to_categorical.py