Rename ak.choose and ak.cross.

docs-sphinx/ak.autograd.elementwise_grad.rst

@@ -0,0 +1,12 @@
+ak.autograd.elementwise_grad
+----------------------------
+
+.. py:function:: ak.autograd.elementwise_grad(fun)
+
+Decorator for differentiating a function that is applied elementwise to a NumPy or Awkward Array.
+
+See `Autograd <https://github.com/HIPS/autograd#readme>`__ for an example of
+``autograd.elementwise_grad``. This version of the decorator allows :doc:`_auto/ak.Array`
+as arguments to the function, not just NumPy arrays.
+
+To do: examples.

docs-sphinx/ak.layout.Content.rst

@@ -3,7 +3,7 @@ ak.layout.Content
 
 Superclass of array nodes that build up the structure of an
 :doc:`_auto/ak.Array`; the array layout returned by the
-`ak.Array.layout <_auto/ak.Array.html#ak-array-layout>`_ property.
+`ak.Array.layout <_auto/ak.Array.html#ak-array-layout>`__ property.
 
 The array node types are listed below.
 
@@ -180,12 +180,12 @@ ak.layout.Content.argmin
 
 Implements :doc:`_auto/ak.argmin`.
 
-ak.layout.Content.choose
-========================
+ak.layout.Content.combinations
+==============================
 
-.. py:method:: ak.layout.Content.choose(n, diagonal=False, keys=None, parameters=None, axis=1)
+.. py:method:: ak.layout.Content.combinations(n, replacement=False, keys=None, parameters=None, axis=1)
 
-Implements :doc:`_auto/ak.choose`.
+Implements :doc:`_auto/ak.combinations`.
 
 ak.layout.Content.count
 =======================
@@ -231,7 +231,7 @@ ak.layout.Content.fillna
 
 .. py:method:: ak.layout.Content.fillna(value)
 
-Implements :doc:`_auto/ak.fillna`.
+Implements :doc:`_auto/ak.fill_none`.
 
 ak.layout.Content.flatten
 =========================
@@ -280,8 +280,8 @@ ak.layout.Content.localindex
 Returns nested lists of integers (down to the chosen ``axis``) that count
 from `0` to the `length - 1` of the innermost list.
 
-This is used internally to generate :doc:`_auto/ak.argcross` from
-:doc:`_auto/ak.cross`, etc.
+This is used internally to generate :doc:`_auto/ak.argcartesian` from
+:doc:`_auto/ak.cartesian`, etc.
 
 ak.layout.Content.max
 =====================
@@ -372,14 +372,14 @@ ak.layout.Content.rpad
 
 .. py:method:: ak.layout.Content.rpad(arg0, arg1)
 
-Implements :doc:`_auto/ak.rpad` with ``clip=False``.
+Implements :doc:`_auto/ak.pad_none` with ``clip=False``.
 
 ak.layout.Content.rpad_and_clip
 ===============================
 
 .. py:method:: ak.layout.Content.rpad_and_clip(arg0, arg1)
 
-Implements :doc:`_auto/ak.rpad` with ``clip=True``.
+Implements :doc:`_auto/ak.pad_none` with ``clip=True``.
 
 ak.layout.Content.setidentities
 ===============================

docs-sphinx/ak.layout.Identities.rst

@@ -12,8 +12,8 @@ array (at every node of the tree) with the original ``__getitem__`` path
 from the root of a data structure to that element, the original "identity"
 of the element. As data are filtered with selections, shuffled with
 sorting operations, or duplicated in combinatorial functions like
-:doc:`_auto/ak.cross` and :doc:`_auto/ak.choose`, the Identities are selected,
-shuffled, and duplicated with them.
+:doc:`_auto/ak.cartesian` and :doc:`_auto/ak.combinations`, the Identities
+are selected, shuffled, and duplicated with them.
 
 The primary purpose of these Identities is to act as an index key for
 SQL-like join operations. At the time of this writing, such operations

docs-sphinx/ak.numba.register.rst

@@ -0,0 +1,13 @@
+ak.numba.register
+-----------------
+
+.. py:function:: ak.numba.register()
+
+Registers :doc:`_auto/ak.Array`, :doc:`_auto/ak.Record`, and :doc:`_auto/ak.ArrayBuilder`
+as types that can be used in a function compiled by `Numba <http://numba.pydata.org/>`__.
+
+Users shouldn't need to call this function, as it is an
+`entry point <https://numba.pydata.org/numba-doc/latest/extending/entrypoints.html>`__.
+
+(But if Numba doesn't recognize an :doc:`_auto/ak.Array`, :doc:`_auto/ak.Record`, or
+:doc:`_auto/ak.ArrayBuilder`, try calling this function anyway!)

docs-sphinx/ak.numexpr.evaluate.rst

@@ -0,0 +1,18 @@
+ak.numexpr.evaluate
+-------------------
+
+.. py:function:: ak.numexpr.evaluate(expression, local_dict=None, global_dict=None, order="K", casting="safe", **kwargs)
+
+See `numexpr.evaluate <https://numexpr.readthedocs.io/projects/NumExpr3/en/latest/api.html#numexpr.evaluate>`__
+for a description of each parameter. This function reproduces NumExpr's interface, except that
+the expression can contain references to :doc:`_auto/ak.Array` objects as well as NumPy arrays.
+
+The arrays are broadcasted according to rules described in :doc:`_auto/ak.broadcast_arrays`. The
+expression applies to the numeric leaves of the data structure and the output maintains that
+structure, just as `ak.Array.__array_ufunc__ <_auto/ak.Array.html#ak-array-array-ufunc>`__
+preserves structure through NumPy
+[universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html).
+
+To do: examples.
+
+See also :doc:`ak.numexpr.re_evaluate`.

docs-sphinx/ak.numexpr.re_evaluate.rst

@@ -0,0 +1,10 @@
+ak.numexpr.re_evaluate
+----------------------
+
+.. py:function:: ak.numexpr.re_evaluate(local_dict=None)
+
+See `numexpr.re_evaluate <https://numexpr.readthedocs.io/projects/NumExpr3/en/latest/api.html#numexpr.re_evaluate>`__
+for a description of each parameter. This function reproduces NumExpr's interface, except that
+the expression can contain references to :doc:`_auto/ak.Array` objects as well as NumPy arrays.
+
+See also :doc:`ak.numexpr.evaluate`.

docs-sphinx/ak.pandas.df.rst

@@ -0,0 +1,23 @@
+ak.pandas.df
+------------
+
+.. py:function:: ak.pandas.df(array, how="inner", levelname=lambda i: "sub"*i + "entry", anonymous="values")
+
+    :param array: :doc:`_auto/ak.Array` to convert into a Pandas DataFrame that does not contain Awkward Arrays.
+    :param how: Passed to [pd.merge](https://pandas.pydata.org/pandas-docs/version/1.0.3/reference/api/pandas.merge.html) to combine DataFrames for each multiplicity into one DataFrame.
+    :param levelname: Computes a name for each level of the row index from the number of levels deep.
+    :param anonymous: Column name to use if the Array does not contain records; otherwise, column names are derived from record fields.
+
+Converts Awkward data structures into Pandas
+`MultiIndex <https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html>`__
+rows and columns *instead of* embedding the Awkward Array in the DataFrame as
+a column.
+
+:doc:`_auto/ak.Array` data structures cannot be losslessly converted into a single
+DataFrame; different fields in a record structure might have different nested list
+lengths, but a DataFrame can have only one index. This function actually calls
+:doc:`ak.pandas.dfs` to make as many DataFrames as are needed and then uses
+`pd.merge <https://pandas.pydata.org/pandas-docs/version/1.0.3/reference/api/pandas.merge.html>`__
+to combine those DataFrames using Pandas's ``how`` parameter.
+
+To do: examples.

docs-sphinx/ak.pandas.dfs.rst

@@ -0,0 +1,16 @@
+ak.pandas.dfs
+-------------
+
+.. py:function:: ak.pandas.dfs(array, levelname=lambda i: "sub"*i + "entry", anonymous="values")
+
+    :param array: :doc:`_auto/ak.Array` to convert into a Pandas DataFrame that does not contain Awkward Arrays.
+    :param levelname: Computes a name for each level of the row index from the number of levels deep.
+    :param anonymous: Column name to use if the Array does not contain records; otherwise, column names are derived from record fields.
+
+Converts Awkward data structures into a list of Pandas DataFrames with
+`MultiIndex <https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html>`__
+rows and columns, *instead of* embedding the Awkward Array inside any DataFrames.
+
+For convenience, you can additionally
+`pd.merge <https://pandas.pydata.org/pandas-docs/version/1.0.3/reference/api/pandas.merge.html>`__
+the DataFrames into a single DataFrame with the :doc:`ak.pandas.df` function.

docs-sphinx/ak.pandas.register.rst

@@ -0,0 +1,12 @@
+ak.pandas.register
+------------------
+
+.. py:function:: ak.pandas.register()
+
+Registers :doc:`_auto/ak.Array` as a column type for `Pandas <https://pandas.pydata.org/>`__
+DataFrames and Series.
+
+Users should not need to call this function because it is invoked whenever a Pandas-specific
+method on :doc:`_auto/ak.Array` is called.
+
+(But if Pandas doesn't recognize an :doc:`_auto/ak.Array`, try calling this function anyway!)

docs-sphinx/prepare_docstrings.py

@@ -261,7 +261,14 @@ def dofunction(link, shortname, name, astfcn):
         toctree.append("ak.behavior.rst")
     elif not done_extra and modulename.startswith("awkward1._"):
         done_extra = True
-        toctree.extend(["ak.layout.Content.rst",
+        toctree.extend(["ak.numba.register.rst",
+                        "ak.pandas.register.rst",
+                        "ak.pandas.df.rst",
+                        "ak.pandas.dfs.rst",
+                        "ak.numexpr.evaluate.rst",
+                        "ak.numexpr.re_evaluate.rst",
+                        "ak.autograd.elementwise_grad.rst",
+                        "ak.layout.Content.rst",
                         "ak.layout.EmptyArray.rst",
                         "ak.layout.NumpyArray.rst",
                         "ak.layout.RegularArray.rst",

include/awkward/Content.h

@@ -531,11 +531,11 @@ namespace awkward {
     /// @endcode
     ///
     /// @param n The number of items in each tuple/record.
-    /// @param diagonal If `true`, the tuples/records are allowed to include
+    /// @param replacement If `true`, the tuples/records are allowed to include
     /// the same item more than once, such as `(a, a, a)` and `(a, a, b)`.
-    /// In the above examples, `diagonal = false`. (If the output of this
+    /// In the above examples, `replacement = false`. (If the output of this
     /// function is thought of as the "upper triangle" elements of the
-    /// Cartesian product of the input with itself `n` times, the `diagonal`
+    /// Cartesian product of the input with itself `n` times, the `replacement`
     /// parameter determines whether elements on the diagonal are allowed.)
     /// @param recordlookup If `nullptr`, the output consists of tuples, a
     /// RecordArray indexed by `"0"`, `"1"`, `"2"`, etc. If `recordlookup`
@@ -563,12 +563,12 @@ namespace awkward {
     /// {@link IndexedArrayOf IndexedArray}, while any other `axis` is
     /// eagerly generated by duplicating elements (with #carry).
     virtual const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const = 0;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const = 0;
 
     /// @brief Returns a string representation of this array (multi-line XML).
     ///
@@ -753,17 +753,18 @@ namespace awkward {
     const ContentPtr
       localindex_axis0() const;
 
-    /// @brief Internal function to handle the `axis = 0` case of #choose.
+    /// @brief Internal function to handle the `axis = 0` case of
+    /// #combinations.
     ///
     /// The `axis = 0` case does not depend on array node type, so it is
     /// defined universally in the Content class.
     /// 
     /// @param n The number of items in each tuple/record.
-    /// @param diagonal If `true`, the tuples/records are allowed to include
+    /// @param replacement If `true`, the tuples/records are allowed to include
     /// the same item more than once, such as `(a, a, a)` and `(a, a, b)`.
-    /// In the above examples, `diagonal = false`. (If the output of this
+    /// In the above examples, `replacement = false`. (If the output of this
     /// function is thought of as the "upper triangle" elements of the
-    /// Cartesian product of the input with itself `n` times, the `diagonal`
+    /// Cartesian product of the input with itself `n` times, the `replacement`
     /// parameter determines whether elements on the diagonal are allowed.)
     /// @param recordlookup If `nullptr`, the output consists of tuples, a
     /// RecordArray indexed by `"0"`, `"1"`, `"2"`, etc. If `recordlookup`
@@ -774,10 +775,10 @@ namespace awkward {
     /// can be used to set `"__record_" = "\"record_name\\""` to give the
     /// records a custom behavior in Python.
     const ContentPtr
-      choose_axis0(int64_t n,
-                   bool diagonal,
-                   const util::RecordLookupPtr& recordlookup,
-                   const util::Parameters& parameters) const;
+      combinations_axis0(int64_t n,
+                         bool replacement,
+                         const util::RecordLookupPtr& recordlookup,
+                         const util::Parameters& parameters) const;
 
     /// @brief Internal function that propagates a generic #getitem request
     /// through one axis (including advanced indexing).

include/awkward/array/BitMaskedArray.h

@@ -277,12 +277,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,

include/awkward/array/ByteMaskedArray.h

@@ -251,12 +251,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,

include/awkward/array/EmptyArray.h

@@ -178,12 +178,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,

include/awkward/array/IndexedArray.h

@@ -254,12 +254,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,

include/awkward/array/ListArray.h

@@ -276,12 +276,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,

include/awkward/array/ListOffsetArray.h

@@ -265,12 +265,12 @@ namespace awkward {
       localindex(int64_t axis, int64_t depth) const override;
 
     const ContentPtr
-      choose(int64_t n,
-             bool diagonal,
-             const util::RecordLookupPtr& recordlookup,
-             const util::Parameters& parameters,
-             int64_t axis,
-             int64_t depth) const override;
+      combinations(int64_t n,
+                   bool replacement,
+                   const util::RecordLookupPtr& recordlookup,
+                   const util::Parameters& parameters,
+                   int64_t axis,
+                   int64_t depth) const override;
 
     const ContentPtr
       getitem_next(const SliceAt& at,