Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Jul 27, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
867a7a2
Improve docs for `cumcount()` and `ngroups()`
oleksiyskononenko Jul 27, 2022
94fe6c5
Update ngroup.rst
samukweku Jul 27, 2022
d1e5a70
Fix one more typo
oleksiyskononenko Jul 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions docs/api/dt/cumcount.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
-- + ----- -----
Expand All @@ -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
Expand All @@ -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]


52 changes: 27 additions & 25 deletions docs/api/dt/ngroup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
-- + ----- -----
Expand All @@ -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
Expand All @@ -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]