Improve docs for cumcount() and ngroups() (#3320)

Cosmetic improvements of docs for `cumcount()` and `ngroups()`. WIP for #3279
h2oai · Aug 4, 2022 · f7905f4 · f7905f4
1 parent 310587b
commit f7905f4
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 50 deletions.
diff --git a/docs/api/dt/cumcount.rst b/docs/api/dt/cumcount.rst
@@ -7,19 +7,20 @@
 
     .. x-version-added:: 1.1.0
 
-    Returns the number of the current row within the group, counting from 0.
-    In the absence of :func:`by()`, it simply returns 0 to len(frame)-1.
+    Number rows within each group. In the absence of :func:`by()`
+    the frame is assumed to consist of one group only.
 
-    If `reverse = True`, the numbering is done in descending order.
 
     Parameters
     ----------
     reverse: bool
-        If ``False``, numbering is performed in the ascending order. 
-        If ``True``, the numbering is in descending order.
+        By default, when this parameter is ``False``, the numbering
+        is performed in the ascending order. Otherwise, when
+        this parameter is ``True``, the numbering is done
+        in the descending order.
 
     return: FExpr
-        f-expression that returns the number of the current row per group.
+        f-expression that returns row numbers within each group.
 
 
     Examples
@@ -28,7 +29,7 @@
     Create a sample datatable frame::
 
         >>> from datatable import dt, f, by
-        >>> DT = dt.Frame(['a','a','a','b','b','c','c','c'])
+        >>> DT = dt.Frame(['a', 'a', 'a', 'b', 'b', 'c', 'c', 'c'])
         >>> DT
            | C0
            | str32
@@ -43,9 +44,9 @@
          7 | c
         [8 rows x 1 column]
 
-    Compute the cumcount per group in ascending order::
+    Number rows within each group in the ascending order::
 
-        >>> DT[:, dt.cumcount(reverse = False), f.C0]
+        >>> DT[:, dt.cumcount(), f.C0]
            | C0        C1
            | str32  int64
         -- + -----  -----
@@ -59,7 +60,7 @@
          7 | c          2
         [8 rows x 2 columns]
 
-    Compute the cumcount per group in descending order::
+    Number rows within each group in the descending order::
 
         >>> DT[:, dt.cumcount(reverse = True), f.C0]
            | C0        C1
@@ -75,21 +76,20 @@
          7 | c          0
         [8 rows x 2 columns]
 
+    Number rows in the absence of :func:`by()`::
 
-    Compute in the absence of :func:`by()`::
-
-        >>> DT[:, dt.cumcount(reverse = False)]
-           |    C0
-           | int64
-        -- + -----
-         0 |     0
-         1 |     1
-         2 |     2
-         3 |     3
-         4 |     4
-         5 |     5
-         6 |     6
-         7 |     7
-        [8 rows x 1 column]
+        >>> DT[:, [f.C0, dt.cumcount()]]
+           | C0        C1
+           | str32  int64
+        -- + -----  -----
+         0 | a          0
+         1 | a          1
+         2 | a          2
+         3 | b          3
+         4 | b          4
+         5 | c          5
+         6 | c          6
+         7 | c          7
+        [8 rows x 2 columns]
 
 
diff --git a/docs/api/dt/ngroup.rst b/docs/api/dt/ngroup.rst
@@ -7,27 +7,29 @@
 
     .. x-version-added:: 1.1.0
 
-    Returns the group number for each row. If `reverse = True`, the numbering
-    is done in descending order.
+    For each row return a group number it belongs to. In the absence of
+    :func:`by()` the frame is assumed to consist of one group only.
+
 
     Parameters
     ----------
     reverse: bool
-        If ``False``, the group number is returned in ascending order. 
-        If ``True``, the group number is returned in descending order.
+        By default, when this parameter is ``False``, groups
+        are numbered in the ascending order. Otherwise, when
+        this parameter is ``True``, groups are numbered
+        in the descending order.
 
     return: FExpr
-        f-expression that returns the number for each group.
-        In the absence of :func:`by()`, this f-expression returns
-        `0` for each row.
+        f-expression that returns group numbers for each row.
+
 
     Examples
     --------
 
     Create a sample datatable frame::
 
         >>> from datatable import dt, f, by
-        >>> DT = dt.Frame(['a','a','a','b','b','c','c','c'])
+        >>> DT = dt.Frame(['a', 'a', 'a', 'b', 'b', 'c', 'c', 'c'])
         >>> DT
            | C0
            | str32
@@ -42,9 +44,9 @@
          7 | c
         [8 rows x 1 column]
 
-    Return the group number in ascending order::
+    Number groups in the ascending order::
 
-        >>> DT[:, dt.ngroup(reverse = False), f.C0]
+        >>> DT[:, dt.ngroup(), f.C0]
            | C0        C1
            | str32  int64
         -- + -----  -----
@@ -58,7 +60,7 @@
          7 | c          2
         [8 rows x 2 columns]
 
-    Return the group number in descending order::
+    Number groups in the descending order::
 
         >>> DT[:, dt.ngroup(reverse = True), f.C0]
            | C0        C1
@@ -74,19 +76,19 @@
          7 | c          0
         [8 rows x 2 columns]
 
-    Compute in the absence of :func:`by()`::
+    Number groups in the absence of :func:`by()`::
 
-        >>> DT[:, dt.ngroup(reverse = False)]
-           |    C0
-           | int64
-        -- + -----
-         0 |     0
-         1 |     0
-         2 |     0
-         3 |     0
-         4 |     0
-         5 |     0
-         6 |     0
-         7 |     0
-        [8 rows x 1 column]
+        >>> DT[:, dt.ngroup()]
+           | C0        C1
+           | str32  int64
+        -- + -----  -----
+         0 | a          0
+         1 | a          0
+         2 | a          0
+         3 | b          0
+         4 | b          0
+         5 | c          0
+         6 | c          0
+         7 | c          0
+        [8 rows x 2 columns]