cut() converted into FExpr (#2576)

WIP for #2562

docs/api/dt/cut.rst

@@ -1,6 +1,6 @@
 .. py:currentmodule:: datatable
 
 .. xfunction:: datatable.cut
-    :src: src/core/expr/head_func_cut.cc pyfn_cut
-    :doc: src/core/expr/head_func_cut.cc doc_cut
+    :src: src/core/expr/fexpr_cut.cc pyfn_cut
+    :doc: src/core/expr/fexpr_cut.cc doc_cut
     :tests: tests/expr/test-cut.py

src/core/column/qcut.h

@@ -32,9 +32,10 @@ namespace dt {
 
 
 /**
-  *  Virtual column to bin input data into equal-population
-  *  discrete intervals, i.e. quantiles. In reality, for some data
-  *  these quantiles won't have exactly the same population.
+  *  Virtual column to bin input data into intervals with approximately
+  *  equal populations. If there are duplicate values in the
+  *  data, they will all be placed into the same bin. In extreme cases
+  *  this may cause the bins to be highly unbalanced.
   *
   *  Quantiles are generated based on the element/group information
   *  obtained from the groupby operation, i.e. rowindex and offsets.

src/core/expr/fexpr_cut.cc

@@ -0,0 +1,194 @@
+//------------------------------------------------------------------------------
+// Copyright 2020 H2O.ai
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+//------------------------------------------------------------------------------
+#include "_dt.h"
+#include "datatablemodule.h"
+#include "column/cut.h"
+#include "expr/eval_context.h"
+#include "expr/fexpr_func.h"
+#include "frame/py_frame.h"
+namespace dt {
+namespace expr {
+
+
+
+//------------------------------------------------------------------------------
+// FExpr_Cut
+//------------------------------------------------------------------------------
+
+class FExpr_Cut : public FExpr_Func {
+  private:
+    ptrExpr arg_;
+    py::oobj py_nbins_;
+    bool right_closed_;
+    size_t: 56;
+
+  public:
+    FExpr_Cut(py::oobj arg, py::robj py_nbins, bool right_closed)
+      : arg_(as_fexpr(arg)),
+        py_nbins_(py_nbins),
+        right_closed_(right_closed)
+    {}
+
+    std::string repr() const override {
+      std::string out = "cut(";
+      out += arg_->repr();
+      if (!py_nbins_.is_none()) {
+        out += ", nbins=";
+        out += py_nbins_.repr().to_string();
+        out += ", right_closed=";
+        out += right_closed_? "True" : "False";
+      }
+      out += ")";
+      return out;
+    }
+
+
+    Workframe evaluate_n(EvalContext& ctx) const override {
+      if (ctx.has_groupby()) {
+        throw NotImplError() << "cut() cannot be used in a groupby context";
+      }
+
+      int32_t nbins_default = 10;
+      Workframe wf = arg_->evaluate_n(ctx);
+      const size_t ncols = wf.ncols();
+
+      int32vec nbins(ncols);
+      bool defined_nbins = !py_nbins_.is_none();
+      bool nbins_list_or_tuple = py_nbins_.is_list_or_tuple();
+
+      if (nbins_list_or_tuple) {
+        py::oiter py_nbins = py_nbins_.to_oiter();
+        if (py_nbins.size() != ncols) {
+          throw ValueError() << "When `nbins` is a list or a tuple, its length must be "
+            << "the same as the number of columns in the frame/expression, i.e. `"
+            << ncols << "`, instead got: `" << py_nbins.size() << "`";
+
+        }
+
+        size_t i = 0;
+        for (auto py_nbin : py_nbins) {
+          int32_t nbin = py_nbin.to_int32_strict();
+          if (nbin <= 0) {
+            throw ValueError() << "All elements in `nbins` must be positive, "
+                                  "got `nbins[" << i << "`]: `" << nbin << "`";
+          }
+
+          nbins[i++] = nbin;
+        }
+        xassert(i == ncols);
+
+      } else {
+        if (defined_nbins) {
+          nbins_default = py_nbins_.to_int32_strict();
+          if (nbins_default <= 0) {
+            throw ValueError() << "Number of bins must be positive, "
+                                  "instead got: `" << nbins_default << "`";
+          }
+        }
+
+        for (size_t i = 0; i < ncols; ++i) {
+          nbins[i] = nbins_default;
+        }
+      }
+
+      // Cut workframe in-place
+      for (size_t i = 0; i < ncols; ++i) {
+        Column coli = wf.retrieve_column(i);
+        coli = Column(Cut_ColumnImpl::make(
+                 std::move(coli), i, nbins[i], right_closed_
+               ));
+        wf.replace_column(i, std::move(coli));
+      }
+
+      return wf;
+    }
+};
+
+
+
+
+//------------------------------------------------------------------------------
+// Python-facing `cut()` function
+//------------------------------------------------------------------------------
+
+static const char* doc_cut =
+R"(cut(cols, nbins=10, right_closed=True)
+--
+
+Cut all the columns from `cols` by binning their values into
+equal-width discrete intervals.
+
+Parameters
+----------
+cols: FExpr
+    Input data for equal-width interval binning.
+nbins: int | List[int]
+    When a single number is specified, this number of bins
+    will be used to bin each column of `cols`.
+    When a list or a tuple is provided, each column will be binned
+    by using its own number of bins. In the latter case,
+    the list/tuple length must be equal to the number of columns
+    in `cols`.
+right_closed: bool
+    Each binning interval is `half-open`_. This flag indicates which
+    side of the interval is closed.
+
+return: FExpr
+    f-expression that converts input columns into the columns filled
+    with the respective bin ids.
+
+See also
+--------
+:func:`qcut()` -- function for quantile binning.
+
+.. _`half-open`: https://en.wikipedia.org/wiki/Interval_(mathematics)#Terminology
+
+)";
+
+static py::PKArgs args_cut(
+  1, 0, 2, false, false,
+  {
+    "cols", "nbins", "right_closed"
+  },
+  "cut", doc_cut
+);
+
+static py::oobj pyfn_cut(const py::PKArgs& args) {
+  if (args[0].is_none_or_undefined()) {
+    throw TypeError() << "Function `cut()` requires one positional argument, "
+                         "but none were given";
+  }
+  py::oobj arg0 = args[0].to_oobj();
+  py::oobj arg1 = args[1].is_none_or_undefined()? py::None() : args[1].to_oobj();
+  bool arg2 = args[2].is_none_or_undefined()? true : args[2].to_bool_strict();
+
+  return PyFExpr::make(new FExpr_Cut(arg0, arg1, arg2));
+}
+
+
+
+}}  // dt::expr
+
+
+void py::DatatableModule::init_methods_cut() {
+  ADD_FN(&dt::expr::pyfn_cut, dt::expr::args_cut);
+}

src/core/expr/fexpr_qcut.cc

@@ -145,7 +145,7 @@ equal populations. Thus, the intervals are chosen according to
 the sample quantiles of the data.
 
 If there are duplicate values in the data, they will all be placed
-into the same been. In extreme cases this may cause the bins to be
+into the same bin. In extreme cases this may cause the bins to be
 highly unbalanced.
 
 Parameters

src/core/expr/head_func.cc

@@ -169,7 +169,6 @@ void Head_Func::init() {
   factory[static_cast<size_t>(Op::SETPLUS)]    = make_colsetop;
   factory[static_cast<size_t>(Op::SETMINUS)]   = make_colsetop;
   factory[static_cast<size_t>(Op::SHIFTFN)]    = &Head_Func_Shift::make;
-  factory[static_cast<size_t>(Op::CUT)]        = &Head_Func_Cut::make;
   factory[static_cast<size_t>(Op::COUNT0)]     = make_reduce0;
   factory[static_cast<size_t>(Op::COV)]        = make_reduce2;
   factory[static_cast<size_t>(Op::CORR)]       = make_reduce2;

src/core/expr/head_func.h

@@ -142,21 +142,6 @@ class Head_Func_IsClose : public Head_Func {
 
 
 
-class Head_Func_Cut : public Head_Func {
-  private:
-    py::oobj py_nbins_;
-    bool right_closed_;
-    size_t: 56;
-
-  public:
-    Head_Func_Cut(py::oobj py_nbins, py::oobj right_closed);
-    static ptrHead make(Op, const py::otuple& params);
-
-    Workframe evaluate_n(const vecExpr&, EvalContext&) const override;
-};
-
-
-
 
 }}  // namespace dt::expr
 #endif