Skip to content
142 changes: 125 additions & 17 deletions python/cudf/cudf/core/groupby/groupby.py
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,25 @@ def _collect_series_key_column_names(obj, by) -> dict[int, Hashable]:
return result


class GroupByNthSelector:
"""Mirror of :class:`pandas.core.groupby.indexing.GroupByNthSelector`.

``GroupBy.nth`` supports both the call form ``gb.nth(n, dropna=...)``
and the index form ``gb.nth[n]``.
"""

def __init__(self, groupby_object: GroupBy) -> None:
self.groupby_object = groupby_object

def __call__(
self, n, dropna: Literal["any", "all", None] = None
) -> Series | DataFrame:
return self.groupby_object._nth(n, dropna)

def __getitem__(self, n) -> Series | DataFrame:
return self.groupby_object._nth(n)


class GroupBy(Serializable, Reducible, Scannable):
obj: Series | DataFrame

Expand Down Expand Up @@ -575,6 +594,10 @@ def __init__(
# Must be done before ``nans_to_nulls`` which breaks identity.
by_series_col_names = _collect_series_key_column_names(obj, by)

# Row-filter operations (``nth``) must return the original values,
# preserving the NaN-vs-null distinction that ``nans_to_nulls``
# erases below.
self._obj_original = obj
if get_option("mode.pandas_compatible"):
obj = obj.nans_to_nulls()
self.obj = obj
Expand Down Expand Up @@ -1196,9 +1219,23 @@ def agg(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs):
):
cast_dtype = orig_dtype
elif agg not in {list, "collect"}:
create_dtype = get_dtype_of_same_kind(
orig_dtype, create_dtype
)
if (
isinstance(orig_dtype, pd.DatetimeTZDtype)
and isinstance(create_dtype, np.dtype)
and create_dtype.kind == "M"
):
# libcudf has no timezone notion: a DatetimeTZColumn
# feeds its stored UTC instants to libcudf and the
# result comes back as a tz-naive timestamp column.
# Reattach the original tz (the values are unchanged
# UTC instants, so this is lossless).
create_dtype = pd.DatetimeTZDtype(
np.datetime_data(create_dtype)[0], orig_dtype.tz
)
else:
create_dtype = get_dtype_of_same_kind(
orig_dtype, create_dtype
)

result_col = ColumnBase.create(plc_result, create_dtype)
if agg == "cumcount":
Expand Down Expand Up @@ -1756,27 +1793,98 @@ def tail(self, n: int = 5, *, preserve_order: bool = True):
n, take_head=False, preserve_order=preserve_order
)

@_performance_tracking
def nth(self, n, dropna: Literal["any", "all", None] = None):
@property
def nth(self) -> GroupByNthSelector: # type: ignore[override]
"""
Return the nth row from each group.
Take the nth row from each group if n is an int, otherwise a
subset of rows.

Like pandas, supports both the call form ``gb.nth(n, dropna=...)``
and the index form ``gb.nth[n]`` (with ints, list-likes of ints and
non-negative-step slices).
Comment thread
galipremsagar marked this conversation as resolved.
Resolved
"""
return GroupByNthSelector(self)

@_performance_tracking
def _nth(self, n, dropna: Literal["any", "all", None] = None):
"""Positional row filter mirroring pandas' GroupBy.nth."""
if dropna is not None:
raise NotImplementedError("dropna is not currently supported.")
self.obj["__groupbynth_order__"] = range(0, len(self.obj))
# We perform another groupby here to have the grouping columns
# be a part of dataframe columns.
result = self.obj.groupby(self.grouping.keys).agg(lambda x: x.nth(n))
sizes = self.size().reindex(result.index)

result = result[sizes > n]
# Normalize and validate ``n`` like pandas'
# GroupByIndexingMixin._make_mask_from_positional_indexer.
if isinstance(n, (int, np.integer)):
args: list = [int(n)]
elif isinstance(n, slice):
args = [n]
elif isinstance(n, (list, tuple, np.ndarray)):
args = list(n)
else:
raise TypeError(
f"Invalid index {type(n)}. "
"Must be integer, list-like, slice or a tuple of "
"integers and slices"
)
for arg in args:
if isinstance(arg, slice):
if (arg.step or 1) < 0:
raise ValueError(
f"Invalid step {arg.step}. Must be non-negative"
)
elif not isinstance(arg, (int, np.integer)):
raise TypeError(
f"Invalid index {type(n)}. "
"Must be integer, list-like, slice or a tuple of "
"integers and slices"
)

# Per-row position within its group and group size, in group-major
# order (same construction as ``_head_tail``).
_, offsets, _, _ = self._grouped()
group_offsets = np.asarray(offsets, dtype=SIZE_TYPE_DTYPE)
size_per_group = np.diff(group_offsets)
sizes = np.repeat(size_per_group, size_per_group)
pos = np.arange(len(sizes), dtype=SIZE_TYPE_DTYPE) - np.repeat(
group_offsets[:-1], size_per_group
)

mask = np.zeros(len(sizes), dtype=bool)
for arg in args:
if isinstance(arg, slice):
step = arg.step or 1
if arg.start is None:
start = np.zeros_like(sizes)
elif arg.start >= 0:
start = np.full_like(sizes, arg.start)
else:
# ``slice.indices`` clamps a negative start at 0 and
# the step alignment begins at the clamped value
start = np.maximum(sizes + arg.start, 0)
submask = pos >= start
if step > 1:
submask &= (pos - start) % step == 0
if arg.stop is not None:
if arg.stop >= 0:
submask &= pos < arg.stop
else:
submask &= pos < np.maximum(sizes + arg.stop, 0)
mask |= submask
elif arg >= 0:
mask |= pos == arg
else:
mask |= pos == sizes + arg

result.index = self.obj.index.take(
result._data["__groupbynth_order__"]
# Map the selected group-major rows back to positions in the
# original object and gather from the *pre-nans_to_nulls* object:
# pandas' nth is a row filter, so values, dtypes, index and row
# order are those of the original rows.
to_take = as_column(np.nonzero(mask)[0].astype(SIZE_TYPE_DTYPE))
_, _, (ordering,) = self._groups([self._range_column_from_obj])
original_positions = ordering.take(to_take)
original_positions = original_positions.take(
original_positions.argsort()
)
del result._data["__groupbynth_order__"]
del self.obj._data["__groupbynth_order__"]
return result
return self._obj_original.take(original_positions)

@_performance_tracking
def ngroup(self, ascending=True):
Expand Down
36 changes: 36 additions & 0 deletions python/cudf/cudf/pandas/_wrappers/pandas.py
Original file line number Diff line number Diff line change
Expand Up @@ -1167,10 +1167,45 @@ def Index__setattr__(self, name, value):
)


def _groupby_nth_call(gb, *args, **kwargs):
# ``nth`` is a selector object on both cudf and pandas GroupBy,
# supporting the call form gb.nth(n, dropna=...).
return gb.nth(*args, **kwargs)


def _groupby_nth_getitem(gb, key):
# Index form (gb.nth[k], gb.nth[k1:k2]).
return gb.nth[key]


class _GroupByNthSelector:
"""Fast-slow dispatching stand-in for pandas'
GroupByNthSelector: ``GroupBy.nth`` is a class-level property (not a
method), so the generic attribute machinery would leak the raw fast
object's selector with no call-time fallback.
Comment thread
galipremsagar marked this conversation as resolved.
Resolved
"""

def __init__(self, groupby_proxy):
self._groupby_proxy = groupby_proxy

def __call__(self, *args, **kwargs):
return _fast_slow_function_call(
_groupby_nth_call, None, self._groupby_proxy, *args, **kwargs
)[0]

def __getitem__(self, key):
return _fast_slow_function_call(
_groupby_nth_getitem, None, self._groupby_proxy, key
)[0]


SeriesGroupBy = make_intermediate_proxy_type(
"SeriesGroupBy",
cudf.core.groupby.groupby.SeriesGroupBy,
pd.core.groupby.SeriesGroupBy,
additional_attributes={
"nth": property(_GroupByNthSelector),
},
)

DataFrameGroupBy = make_intermediate_proxy_type(
Expand All @@ -1179,6 +1214,7 @@ def Index__setattr__(self, name, value):
pd.core.groupby.DataFrameGroupBy,
additional_attributes={
"_grouper": _FastSlowAttribute("_grouper", private=True),
"nth": property(_GroupByNthSelector),
},
)

Expand Down
42 changes: 0 additions & 42 deletions python/cudf/cudf/pandas/scripts/pandas-testing-plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -1865,48 +1865,6 @@ def pytest_unconfigure(config):
"tests/groupby/methods/test_groupby_shift_diff.py::test_group_diff_real_frame[int8]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_groupby_shift_diff.py::test_group_diff_real_series[int16]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_groupby_shift_diff.py::test_group_diff_real_series[int8]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_first_last_nth": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_first_last_nth_dtypes": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_first_last_nth_nan_dtype": "AssertionError: Attributes of Series are different",
"tests/groupby/methods/test_nth.py::test_first_last_tz[data0-expected_first0-expected_last0]": "AssertionError: Attributes of DataFrame.iloc[:, 1] (column name='time') are different",
"tests/groupby/methods/test_nth.py::test_first_last_with_None[first]": "AssertionError: Attributes of DataFrame.iloc[:, 1] (column name='value') are different",
"tests/groupby/methods/test_nth.py::test_first_last_with_None[last]": "AssertionError: Attributes of DataFrame.iloc[:, 1] (column name='value') are different",
"tests/groupby/methods/test_nth.py::test_groupby_last_first_nth_with_none[NoneType-first]": "AssertionError: Attributes of Series are different",
"tests/groupby/methods/test_nth.py::test_groupby_last_first_nth_with_none[NoneType-last]": "AssertionError: Attributes of Series are different",
"tests/groupby/methods/test_nth.py::test_groupby_last_first_nth_with_none[NoneType-nth]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_head_tail_dropna_false": "AssertionError: DataFrame Expected type <class 'pandas.DataFrame'>, found <class 'cudf.core.dataframe.DataFrame'> ins...",
"tests/groupby/methods/test_nth.py::test_negative_step": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_np_ints": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth2": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth3": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth4": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth5": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[None-b]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[None-selection1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[None-selection2]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[all-b]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[all-selection1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[all-selection2]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[any-b]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[any-selection1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_after_selection[any-selection2]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_column_order": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_indexed": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_multi_grouper": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_multi_index_as_expected": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_nan_in_grouper[all]": "NotImplementedError: dropna is not currently supported.",
"tests/groupby/methods/test_nth.py::test_nth_nan_in_grouper[any]": "NotImplementedError: dropna is not currently supported.",
"tests/groupby/methods/test_nth.py::test_nth_nan_in_grouper_series[None]": "KeyError: 'Label scalar is out of bounds'",
"tests/groupby/methods/test_nth.py::test_nth_nan_in_grouper_series[all]": "NotImplementedError: dropna is not currently supported.",
"tests/groupby/methods/test_nth.py::test_nth_nan_in_grouper_series[any]": "NotImplementedError: dropna is not currently supported.",
"tests/groupby/methods/test_nth.py::test_nth_with_na_object[NoneType--1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_with_na_object[float0--1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_nth_with_na_object[float1--1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_slice[arg0-expected_rows0]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_slice[arg1-expected_rows1]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_slice[arg2-expected_rows2]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_nth.py::test_slice[arg3-expected_rows3]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_quantile.py::test_groupby_quantile_nonmulti_levels_order": "tm.assert_equal compares MultiIndex.levels, which cudf returns as a list rather than the FrozenList pandas produces",
"tests/groupby/methods/test_rank.py::test_rank_avg_even_vals[True-int32]": "TODO: Add a reason for failure",
"tests/groupby/methods/test_rank.py::test_rank_avg_even_vals[True-int64]": "TODO: Add a reason for failure",
Expand Down
48 changes: 47 additions & 1 deletion python/cudf/cudf/tests/groupby/test_nth.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
import numpy as np
import pandas as pd
Expand Down Expand Up @@ -58,3 +58,49 @@ def test_groupby_consecutive_operations():
expected = pg.cumsum()

assert_groupby_results_equal(actual, expected, check_dtype=False)


@pytest.mark.parametrize(
"arg",
[
0,
-1,
[0, 1],
slice(None, 2),
slice(1, None),
slice(None, None, 2),
slice(-2, None),
],
)
def test_nth_selector_indexing(arg):
# GroupBy.nth mirrors pandas' GroupByNthSelector: it supports both the
# call form gb.nth(n) and the index form gb.nth[n], acting as a
# positional row filter that keeps the original index and row order.
pdf = pd.DataFrame(
{
"a": [1, 1, 1, 2, 2, 3],
"b": [10, 20, 30, 40, 50, 60],
},
index=[5, 4, 3, 2, 1, 0],
)
gdf = cudf.from_pandas(pdf)

assert_groupby_results_equal(
pdf.groupby("a").nth[arg],
gdf.groupby("a").nth[arg],
)
if not isinstance(arg, slice):
assert_groupby_results_equal(
pdf.groupby("a").nth(arg),
gdf.groupby("a").nth(arg),
)


def test_nth_invalid_args():
gb = cudf.DataFrame({"a": [1, 1, 2], "b": [1, 2, 3]}).groupby("a")
with pytest.raises(TypeError, match="Invalid index"):
gb.nth(3.14)
with pytest.raises(ValueError, match="Invalid step"):
gb.nth(slice(None, None, -1))
with pytest.raises(NotImplementedError):
gb.nth(0, dropna="any")
8 changes: 8 additions & 0 deletions python/cudf/cudf/utils/dtypes.py
Original file line number Diff line number Diff line change
Expand Up @@ -593,6 +593,14 @@ def get_dtype_of_same_kind(source_dtype: DtypeObj, target_dtype: DtypeObj):
):
return dtype_to_pandas_arrowdtype(target_dtype)
return dtype_to_pandas_nullable_extension_type(target_dtype)
elif (
isinstance(source_dtype, np.dtype)
and source_dtype.kind == "O"
and isinstance(target_dtype, pd.StringDtype)
):
# a string-producing operation on an object-dtype column stays
# object, matching pandas
return source_dtype
else:
return target_dtype

Expand Down
Loading