Skip to content

Commit 6c7507f

Browse files
rhshadrachrhshadrach
authored
DOC: Add docs for DataFrameGroupBy.fillna and SeriesGroupBy.fillna (#48771)
* DOC: Add docs for DataFrameGroupBy.fillna and SeriesGroupBy.fillna * fixup
1 parent 0eb6d33 commit 6c7507f

File tree

2 files changed

+199
-4
lines changed

2 files changed

+199
-4
lines changed

‎pandas/core/generic.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -6730,9 +6730,9 @@ def fillna(
67306730
each index (for a Series) or column (for a DataFrame). Values not
67316731
in the dict/Series/DataFrame will not be filled. This value cannot
67326732
be a list.
6733-
method : {{'backfill', 'bfill', 'pad', 'ffill', None}}, default None
6733+
method : {{'backfill', 'bfill', 'ffill', None}}, default None
67346734
Method to use for filling holes in reindexed Series
6735-
pad / ffill: propagate last valid observation forward to next valid
6735+
ffill: propagate last valid observation forward to next valid
67366736
backfill / bfill: use next valid observation to fill gap.
67376737
axis : {axes_single_arg}
67386738
Axis along which to fill missing values. For `Series`

‎pandas/core/groupby/generic.py

+197-2
Original file line numberDiff line numberDiff line change
@@ -750,7 +750,6 @@ def build_codes(lev_codes: np.ndarray) -> np.ndarray:
750750
out = ensure_int64(out)
751751
return self.obj._constructor(out, index=mi, name=self.obj.name)
752752

753-
@doc(Series.fillna.__doc__)
754753
def fillna(
755754
self,
756755
value: object | ArrayLike | None = None,
@@ -760,6 +759,92 @@ def fillna(
760759
limit: int | None = None,
761760
downcast: dict | None = None,
762761
) -> Series | None:
762+
"""
763+
Fill NA/NaN values using the specified method within groups.
764+
765+
Parameters
766+
----------
767+
value : scalar, dict, Series, or DataFrame
768+
Value to use to fill holes (e.g. 0), alternately a
769+
dict/Series/DataFrame of values specifying which value to use for
770+
each index (for a Series) or column (for a DataFrame). Values not
771+
in the dict/Series/DataFrame will not be filled. This value cannot
772+
be a list. Users wanting to use the ``value`` argument and not ``method``
773+
should prefer :meth:`.Series.fillna` as this
774+
will produce the same result and be more performant.
775+
method : {{'bfill', 'ffill', None}}, default None
776+
Method to use for filling holes. ``'ffill'`` will propagate
777+
the last valid observation forward within a group.
778+
``'bfill'`` will use next valid observation to fill the gap.
779+
axis : {0 or 'index', 1 or 'columns'}
780+
Unused, only for compatibility with :meth:`DataFrameGroupBy.fillna`.
781+
inplace : bool, default False
782+
Broken. Do not set to True.
783+
limit : int, default None
784+
If method is specified, this is the maximum number of consecutive
785+
NaN values to forward/backward fill within a group. In other words,
786+
if there is a gap with more than this number of consecutive NaNs,
787+
it will only be partially filled. If method is not specified, this is the
788+
maximum number of entries along the entire axis where NaNs will be
789+
filled. Must be greater than 0 if not None.
790+
downcast : dict, default is None
791+
A dict of item->dtype of what to downcast if possible,
792+
or the string 'infer' which will try to downcast to an appropriate
793+
equal type (e.g. float64 to int64 if possible).
794+
795+
Returns
796+
-------
797+
Series
798+
Object with missing values filled within groups.
799+
800+
See Also
801+
--------
802+
ffill : Forward fill values within a group.
803+
bfill : Backward fill values within a group.
804+
805+
Examples
806+
--------
807+
>>> ser = pd.Series([np.nan, np.nan, 2, 3, np.nan, np.nan])
808+
>>> ser
809+
0 NaN
810+
1 NaN
811+
2 2.0
812+
3 3.0
813+
4 NaN
814+
5 NaN
815+
dtype: float64
816+
817+
Propagate non-null values forward or backward within each group.
818+
819+
>>> ser.groupby([0, 0, 0, 1, 1, 1]).fillna(method="ffill")
820+
0 NaN
821+
1 NaN
822+
2 2.0
823+
3 3.0
824+
4 3.0
825+
5 3.0
826+
dtype: float64
827+
828+
>>> ser.groupby([0, 0, 0, 1, 1, 1]).fillna(method="bfill")
829+
0 2.0
830+
1 2.0
831+
2 2.0
832+
3 3.0
833+
4 NaN
834+
5 NaN
835+
dtype: float64
836+
837+
Only replace the first NaN element within a group.
838+
839+
>>> ser.groupby([0, 0, 0, 1, 1, 1]).fillna(method="ffill", limit=1)
840+
0 NaN
841+
1 NaN
842+
2 2.0
843+
3 3.0
844+
4 3.0
845+
5 NaN
846+
dtype: float64
847+
"""
763848
result = self._op_via_apply(
764849
"fillna",
765850
value=value,
@@ -2071,7 +2156,6 @@ def value_counts(
20712156
result = result_frame
20722157
return result.__finalize__(self.obj, method="value_counts")
20732158

2074-
@doc(DataFrame.fillna.__doc__)
20752159
def fillna(
20762160
self,
20772161
value: Hashable | Mapping | Series | DataFrame = None,
@@ -2081,6 +2165,117 @@ def fillna(
20812165
limit=None,
20822166
downcast=None,
20832167
) -> DataFrame | None:
2168+
"""
2169+
Fill NA/NaN values using the specified method within groups.
2170+
2171+
Parameters
2172+
----------
2173+
value : scalar, dict, Series, or DataFrame
2174+
Value to use to fill holes (e.g. 0), alternately a
2175+
dict/Series/DataFrame of values specifying which value to use for
2176+
each index (for a Series) or column (for a DataFrame). Values not
2177+
in the dict/Series/DataFrame will not be filled. This value cannot
2178+
be a list. Users wanting to use the ``value`` argument and not ``method``
2179+
should prefer :meth:`.DataFrame.fillna` as this
2180+
will produce the same result and be more performant.
2181+
method : {{'bfill', 'ffill', None}}, default None
2182+
Method to use for filling holes. ``'ffill'`` will propagate
2183+
the last valid observation forward within a group.
2184+
``'bfill'`` will use next valid observation to fill the gap.
2185+
axis : {0 or 'index', 1 or 'columns'}
2186+
Axis along which to fill missing values. When the :class:`DataFrameGroupBy`
2187+
``axis`` argument is ``0``, using ``axis=1`` here will produce
2188+
the same results as :meth:`.DataFrame.fillna`. When the
2189+
:class:`DataFrameGroupBy` ``axis`` argument is ``1``, using ``axis=0``
2190+
or ``axis=1`` here will produce the same results.
2191+
inplace : bool, default False
2192+
Broken. Do not set to True.
2193+
limit : int, default None
2194+
If method is specified, this is the maximum number of consecutive
2195+
NaN values to forward/backward fill within a group. In other words,
2196+
if there is a gap with more than this number of consecutive NaNs,
2197+
it will only be partially filled. If method is not specified, this is the
2198+
maximum number of entries along the entire axis where NaNs will be
2199+
filled. Must be greater than 0 if not None.
2200+
downcast : dict, default is None
2201+
A dict of item->dtype of what to downcast if possible,
2202+
or the string 'infer' which will try to downcast to an appropriate
2203+
equal type (e.g. float64 to int64 if possible).
2204+
2205+
Returns
2206+
-------
2207+
DataFrame
2208+
Object with missing values filled.
2209+
2210+
See Also
2211+
--------
2212+
ffill : Forward fill values within a group.
2213+
bfill : Backward fill values within a group.
2214+
2215+
Examples
2216+
--------
2217+
>>> df = pd.DataFrame(
2218+
... {
2219+
... "key": [0, 0, 1, 1, 1],
2220+
... "A": [np.nan, 2, np.nan, 3, np.nan],
2221+
... "B": [2, 3, np.nan, np.nan, np.nan],
2222+
... "C": [np.nan, np.nan, 2, np.nan, np.nan],
2223+
... }
2224+
... )
2225+
>>> df
2226+
key A B C
2227+
0 0 NaN 2.0 NaN
2228+
1 0 2.0 3.0 NaN
2229+
2 1 NaN NaN 2.0
2230+
3 1 3.0 NaN NaN
2231+
4 1 NaN NaN NaN
2232+
2233+
Propagate non-null values forward or backward within each group along columns.
2234+
2235+
>>> df.groupby("key").fillna(method="ffill")
2236+
A B C
2237+
0 NaN 2.0 NaN
2238+
1 2.0 3.0 NaN
2239+
2 NaN NaN 2.0
2240+
3 3.0 NaN 2.0
2241+
4 3.0 NaN 2.0
2242+
2243+
>>> df.groupby("key").fillna(method="bfill")
2244+
A B C
2245+
0 2.0 2.0 NaN
2246+
1 2.0 3.0 NaN
2247+
2 3.0 NaN 2.0
2248+
3 3.0 NaN NaN
2249+
4 NaN NaN NaN
2250+
2251+
Propagate non-null values forward or backward within each group along rows.
2252+
2253+
>>> df.groupby([0, 0, 1, 1], axis=1).fillna(method="ffill")
2254+
key A B C
2255+
0 0.0 0.0 2.0 2.0
2256+
1 0.0 2.0 3.0 3.0
2257+
2 1.0 1.0 NaN 2.0
2258+
3 1.0 3.0 NaN NaN
2259+
4 1.0 1.0 NaN NaN
2260+
2261+
>>> df.groupby([0, 0, 1, 1], axis=1).fillna(method="bfill")
2262+
key A B C
2263+
0 0.0 NaN 2.0 NaN
2264+
1 0.0 2.0 3.0 NaN
2265+
2 1.0 NaN 2.0 2.0
2266+
3 1.0 3.0 NaN NaN
2267+
4 1.0 NaN NaN NaN
2268+
2269+
Only replace the first NaN element within a group along rows.
2270+
2271+
>>> df.groupby("key").fillna(method="ffill", limit=1)
2272+
A B C
2273+
0 NaN 2.0 NaN
2274+
1 2.0 3.0 NaN
2275+
2 NaN NaN 2.0
2276+
3 3.0 NaN 2.0
2277+
4 3.0 NaN NaN
2278+
"""
20842279
result = self._op_via_apply(
20852280
"fillna",
20862281
value=value,

0 commit comments

Comments
 (0)