From fe105a7a38e56474a034e040a03c0d752a6d4f56 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Thu, 11 May 2023 17:01:40 +0200 Subject: [PATCH 1/7] DOC Fixing EX01 - added examples --- ci/code_checks.sh | 8 -------- pandas/core/base.py | 34 ++++++++++++++++++++++++++++++++-- pandas/core/groupby/generic.py | 34 ++++++++++++++++++++++++++++++++-- pandas/core/series.py | 26 ++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 12 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index d450630227e2a..f6e52ba2a0d41 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -85,12 +85,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 \ @@ -467,8 +461,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..854d2a581d07f 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,12 @@ def is_unique(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([1, 2, 3, 1]) + >>> s.is_unique + False """ return self.nunique(dropna=False) == len(self) @@ -976,6 +994,12 @@ def is_monotonic_increasing(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([1, 2, 2]) + >>> s.is_monotonic_increasing + True """ from pandas import Index @@ -989,6 +1013,12 @@ def is_monotonic_decreasing(self) -> bool: Returns ------- bool + + Examples + -------- + >>> s = pd.Series([3, 2, 2, 1]) + >>> s.is_monotonic_decreasing + True """ from pandas import Index diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index d26448dffc11a..9f4d34824357a 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -1170,13 +1170,43 @@ def cov( return result @property - @doc(Series.is_monotonic_increasing.__doc__) def is_monotonic_increasing(self) -> Series: + # GH13 + """ + Return boolean if values in the group are monotonically increasing. + + Returns + ------- + bool + + 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: + # GH13 + """ + Return boolean if values in the group are monotonically decreasing. + + Returns + ------- + bool + + 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 84fa874831d85..4eca58f8aac4d 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2081,6 +2081,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 From fc9e863e394c10a2f05d9ffe07951daa2294f4d4 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Thu, 11 May 2023 17:13:46 +0200 Subject: [PATCH 2/7] Removed Index.item from code_checks --- ci/code_checks.sh | 1 - 1 file changed, 1 deletion(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index f6e52ba2a0d41..68f3698525945 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -318,7 +318,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 \ From 48837154e9b16862b4d79840281527f33d254a1c Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Fri, 12 May 2023 19:29:04 +0200 Subject: [PATCH 3/7] Removed #GH13 --- pandas/core/groupby/generic.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index 9f4d34824357a..45012effe3485 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -1171,7 +1171,6 @@ def cov( @property def is_monotonic_increasing(self) -> Series: - # GH13 """ Return boolean if values in the group are monotonically increasing. @@ -1191,7 +1190,6 @@ def is_monotonic_increasing(self) -> Series: @property def is_monotonic_decreasing(self) -> Series: - # GH13 """ Return boolean if values in the group are monotonically decreasing. From 6834b8c42189018b3c280a6365e9dab622493d3d Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Mon, 15 May 2023 12:40:02 +0200 Subject: [PATCH 4/7] Added case for return value=False --- pandas/core/base.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/pandas/core/base.py b/pandas/core/base.py index 854d2a581d07f..45b10c86945af 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -1000,6 +1000,10 @@ def is_monotonic_increasing(self) -> bool: >>> 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 @@ -1019,6 +1023,10 @@ def is_monotonic_decreasing(self) -> bool: >>> 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 From 07a10c8866492fff07a63b915d89c1f872f43521 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Mon, 15 May 2023 12:55:22 +0200 Subject: [PATCH 5/7] Added False case for is_unique --- pandas/core/base.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pandas/core/base.py b/pandas/core/base.py index 45b10c86945af..e9a127259eb41 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -980,6 +980,10 @@ def is_unique(self) -> bool: Examples -------- + >>> s = pd.Series([1, 2, 3]) + >>> s.is_unique + True + >>> s = pd.Series([1, 2, 3, 1]) >>> s.is_unique False From 1f1418e9542c37b6316d1173e032b6ddcc4fdd09 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Mon, 15 May 2023 15:57:16 +0200 Subject: [PATCH 6/7] Correct docstring --- pandas/core/groupby/generic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index 45012effe3485..b458a5c9ac4b8 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -1172,11 +1172,11 @@ def cov( @property def is_monotonic_increasing(self) -> Series: """ - Return boolean if values in the group are monotonically increasing. + Return a Series of booleans if values in the group are monotonically increasing. Returns ------- - bool + Series Examples -------- @@ -1191,11 +1191,11 @@ def is_monotonic_increasing(self) -> Series: @property def is_monotonic_decreasing(self) -> Series: """ - Return boolean if values in the group are monotonically decreasing. + Return Series of booleans if values in the group are monotonically decreasing. Returns ------- - bool + Series Examples -------- From f1195939fbc39d03a40687b1b943a022c7e6faf5 Mon Sep 17 00:00:00 2001 From: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Mon, 15 May 2023 14:30:53 +0100 Subject: [PATCH 7/7] really minor clarification (there may be multiple groups, so "the group" isnt defined) --- pandas/core/groupby/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index b458a5c9ac4b8..36ad6e4a11123 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -1172,7 +1172,7 @@ def cov( @property def is_monotonic_increasing(self) -> Series: """ - Return a Series of booleans if values in the group are monotonically increasing. + Return whether each group's values are monotonically increasing. Returns ------- @@ -1191,7 +1191,7 @@ def is_monotonic_increasing(self) -> Series: @property def is_monotonic_decreasing(self) -> Series: """ - Return Series of booleans if values in the group are monotonically decreasing. + Return whether each group's values are monotonically decreasing. Returns -------