From f676c5f76f561d4ffb477bb31d63ce43b9561a9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Mon, 15 May 2023 16:46:45 +0200 Subject: [PATCH] DOC Fixing EX01 - added examples (#53181) * DOC Fixing EX01 - added examples * Removed Index.item from code_checks * Removed #GH13 * Added case for return value=False * Added False case for is_unique * Correct docstring * really minor clarification (there may be multiple groups, so "the group" isnt defined) --------- Co-authored-by: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com> --- ci/code_checks.sh | 9 ------- pandas/core/base.py | 46 ++++++++++++++++++++++++++++++++-- pandas/core/groupby/generic.py | 32 +++++++++++++++++++++-- pandas/core/series.py | 26 +++++++++++++++++++ 4 files changed, 100 insertions(+), 13 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 022b85b9eb55c..99bd90750b676 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -80,12 +80,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then MSG='Partially validate docstrings (EX01)' ; echo $MSG $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \ - pandas.Series.item \ - pandas.Series.pipe \ - pandas.Series.mode \ - pandas.Series.is_unique \ - pandas.Series.is_monotonic_increasing \ - pandas.Series.is_monotonic_decreasing \ pandas.Series.backfill \ pandas.Series.bfill \ pandas.Series.ffill \ @@ -319,7 +313,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Index.fillna \ pandas.Index.dropna \ pandas.Index.astype \ - pandas.Index.item \ pandas.Index.map \ pandas.Index.ravel \ pandas.Index.to_list \ @@ -462,8 +455,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.core.groupby.SeriesGroupBy.cumsum \ pandas.core.groupby.SeriesGroupBy.diff \ pandas.core.groupby.SeriesGroupBy.ffill \ - pandas.core.groupby.SeriesGroupBy.is_monotonic_increasing \ - pandas.core.groupby.SeriesGroupBy.is_monotonic_decreasing \ pandas.core.groupby.SeriesGroupBy.max \ pandas.core.groupby.SeriesGroupBy.median \ pandas.core.groupby.SeriesGroupBy.min \ diff --git a/pandas/core/base.py b/pandas/core/base.py index b281dace12fcb..e9a127259eb41 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -357,12 +357,24 @@ def item(self): Returns ------- scalar - The first element of Series. + The first element of Series or Index. Raises ------ ValueError - If the data is not length-1. + If the data is not length = 1. + + Examples + -------- + >>> s = pd.Series([1]) + >>> s.item() + 1 + + For an index: + + >>> s = pd.Series([1], index=['a']) + >>> s.index.item() + 'a' """ if len(self) == 1: return next(iter(self)) @@ -965,6 +977,16 @@ def is_unique(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([1, 2, 3]) + >>> s.is_unique + True + + >>> s = pd.Series([1, 2, 3, 1]) + >>> s.is_unique + False """ return self.nunique(dropna=False) == len(self) @@ -976,6 +998,16 @@ def is_monotonic_increasing(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([1, 2, 2]) + >>> s.is_monotonic_increasing + True + + >>> s = pd.Series([3, 2, 1]) + >>> s.is_monotonic_increasing + False """ from pandas import Index @@ -989,6 +1021,16 @@ def is_monotonic_decreasing(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([3, 2, 2, 1]) + >>> s.is_monotonic_decreasing + True + + >>> s = pd.Series([1, 2, 3]) + >>> s.is_monotonic_decreasing + False """ from pandas import Index diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index d26448dffc11a..36ad6e4a11123 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -1170,13 +1170,41 @@ def cov( return result @property - @doc(Series.is_monotonic_increasing.__doc__) def is_monotonic_increasing(self) -> Series: + """ + Return whether each group's values are monotonically increasing. + + Returns + ------- + Series + + Examples + -------- + >>> s = pd.Series([2, 1, 3, 4], index=['Falcon', 'Falcon', 'Parrot', 'Parrot']) + >>> s.groupby(level=0).is_monotonic_increasing + Falcon False + Parrot True + dtype: bool + """ return self.apply(lambda ser: ser.is_monotonic_increasing) @property - @doc(Series.is_monotonic_decreasing.__doc__) def is_monotonic_decreasing(self) -> Series: + """ + Return whether each group's values are monotonically decreasing. + + Returns + ------- + Series + + Examples + -------- + >>> s = pd.Series([2, 1, 3, 4], index=['Falcon', 'Falcon', 'Parrot', 'Parrot']) + >>> s.groupby(level=0).is_monotonic_decreasing + Falcon True + Parrot False + dtype: bool + """ return self.apply(lambda ser: ser.is_monotonic_decreasing) @doc(Series.hist.__doc__) diff --git a/pandas/core/series.py b/pandas/core/series.py index e70b217e08dff..540a770b1c897 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2085,6 +2085,32 @@ def mode(self, dropna: bool = True) -> Series: ------- Series Modes of the Series in sorted order. + + Examples + -------- + >>> s = pd.Series([2, 4, 2, 2, 4, None]) + >>> s.mode() + 0 2.0 + dtype: float64 + + More than one mode: + + >>> s = pd.Series([2, 4, 8, 2, 4, None]) + >>> s.mode() + 0 2.0 + 1 4.0 + dtype: float64 + + With and without considering null value: + + >>> s = pd.Series([2, 4, None, None, 4, None]) + >>> s.mode(dropna=False) + 0 NaN + dtype: float64 + >>> s = pd.Series([2, 4, None, None, 4, None]) + >>> s.mode() + 0 4.0 + dtype: float64 """ # TODO: Add option for bins like value_counts() values = self._values