From 8300b90019ba3d4c979c374c4be2c1345ec3acca Mon Sep 17 00:00:00 2001 From: Andreas Koeltringer Date: Sat, 10 Mar 2018 14:24:58 +0100 Subject: [PATCH 1/3] DOC: improved the docstrings of Interval and IntervalMixin Improved the docstrings of Interval (the class) and the following methods of IntervalMixin: * closed_right * closed_left * open_right * open_left --- pandas/_libs/interval.pyx | 63 ++++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 10 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index c0b2ca66e30a6..e72c7cebfffc5 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -20,28 +20,56 @@ cdef class IntervalMixin(object): @property def closed_left(self): """ - Return True if the Interval is closed on the left-side, else False + Check if the interval is closed on the left side. + + For the meaning of `closed` and `open` see :class:`~pandas.Interval`. + + Returns + ------- + bool + `True` if the Interval is closed on the left-side, else `False`. """ return self.closed in ('left', 'both') @property def closed_right(self): """ - Return True if the Interval is closed on the right-side, else False + Check if the interval is closed on the right side. + + For the meaning of `closed` and `open` see :class:`~pandas.Interval`. + + Returns + ------- + bool + `True` if the Interval is closed on the right-side, else `False`. """ return self.closed in ('right', 'both') @property def open_left(self): """ - Return True if the Interval is open on the left-side, else False + Check if the interval is open on the left side. + + For the meaning of `closed` and `open` see :class:`~pandas.Interval`. + + Returns + ------- + bool + `True` if the Interval is open on the left-side, else `False`. """ return not self.closed_left @property def open_right(self): """ - Return True if the Interval is open on the right-side, else False + Check if the interval is open on the right side. + + For the meaning of `closed` and `open` see :class:`~pandas.Interval`. + + Returns + ------- + bool + `True` if the Interval is open on the right-side, else `False`. """ return not self.closed_right @@ -82,12 +110,21 @@ cdef class Interval(IntervalMixin): Parameters ---------- left : value - Left bound for the interval + Left bound for the interval. right : value - Right bound for the interval - closed : {'left', 'right', 'both', 'neither'}, default 'right' + Right bound for the interval. + closed : {'right', 'left', 'both', 'neither'}, default 'right' Whether the interval is closed on the left-side, right-side, both or - neither + neither. + A closed interval (in mathematics denoted by square brackets) + contains the edge points, i.e. the closed interval `[1, 5]` consists + of the points `1, 2, 3, 4, 5`. + An open interval (in mathematics denoted by parentheses) does not + contain the edge points, i.e. the open interval `(1, 5)` consists of + the points 2, 3, 4. + Intervals can also be half-open or half closed, i.e. + `[1,5) = 1, 2, 3, 4` and `(1, 5] = 2, 3, 4, 5`. See also the examples + section below. Examples -------- @@ -96,6 +133,10 @@ cdef class Interval(IntervalMixin): Interval(0, 5, closed='right') >>> 2.5 in iv True + >>> 0 in iv + False + >>> 5 in iv + True >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'), ... pd.Timestamp('2017-12-31'), closed='both') @@ -106,8 +147,10 @@ cdef class Interval(IntervalMixin): -------- IntervalIndex : An Index of Interval objects that are all closed on the same side. - cut, qcut : Convert arrays of continuous data into Categoricals/Series of - Interval. + cut : Convert arrays of continuous data into bins of Series/Categoricals + of Interval. + qcut : Convert arrays of continuous data into bins of Series/Categoricals + of Interval based on quantiles. """ _typ = "interval" From 88977c8bf89c5eeb6a193c15881b874de42f3e8a Mon Sep 17 00:00:00 2001 From: Andreas Koeltringer Date: Sat, 10 Mar 2018 22:17:56 +0100 Subject: [PATCH 2/3] DOC: reflect also the continuous nature of pandas.Interval --- pandas/_libs/interval.pyx | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index e72c7cebfffc5..54fee38942778 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -117,14 +117,18 @@ cdef class Interval(IntervalMixin): Whether the interval is closed on the left-side, right-side, both or neither. A closed interval (in mathematics denoted by square brackets) - contains the edge points, i.e. the closed interval `[1, 5]` consists - of the points `1, 2, 3, 4, 5`. + contains its endpoints, i.e. the closed interval `[1, 5]` is + characterized by the conditions `1 <= x <= 5`. This is what + `closed='both'` stands for. An open interval (in mathematics denoted by parentheses) does not - contain the edge points, i.e. the open interval `(1, 5)` consists of - the points 2, 3, 4. - Intervals can also be half-open or half closed, i.e. - `[1,5) = 1, 2, 3, 4` and `(1, 5] = 2, 3, 4, 5`. See also the examples - section below. + contain its endpoints, i.e. the open interval `(1, 5)` is + characterized by the conditions `1 < x < 5`. This is what + `closed='neither'` stands for. + Intervals can also be half-open or half-closed, i.e. + `[1,5)` is described by `1 <= x < 5` (`closed='left'`) and `(1, 5]` + is described by `1 < x <= 5` (`closed='right'`). + + See also the examples section below. Examples -------- @@ -137,6 +141,8 @@ cdef class Interval(IntervalMixin): False >>> 5 in iv True + >>> 0.0001 in iv + True >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'), ... pd.Timestamp('2017-12-31'), closed='both') From 1db1fc30f193ec143d47a3a858f95cb1c36097bc Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 14 Mar 2018 15:20:01 +0100 Subject: [PATCH 3/3] minor formatting --- pandas/_libs/interval.pyx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index 196a544c14264..5dbf509fda65e 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -27,7 +27,8 @@ cdef class IntervalMixin(object): Returns ------- bool - `True` if the Interval is closed on the left-side, else `False`. + ``True`` if the Interval is closed on the left-side, else + ``False``. """ return self.closed in ('left', 'both') @@ -41,7 +42,8 @@ cdef class IntervalMixin(object): Returns ------- bool - `True` if the Interval is closed on the right-side, else `False`. + ``True`` if the Interval is closed on the left-side, else + ``False``. """ return self.closed in ('right', 'both') @@ -55,7 +57,8 @@ cdef class IntervalMixin(object): Returns ------- bool - `True` if the Interval is open on the left-side, else `False`. + ``True`` if the Interval is closed on the left-side, else + ``False``. """ return not self.closed_left @@ -69,7 +72,8 @@ cdef class IntervalMixin(object): Returns ------- bool - `True` if the Interval is open on the right-side, else `False`. + ``True`` if the Interval is closed on the left-side, else + ``False``. """ return not self.closed_right @@ -147,12 +151,8 @@ cdef class Interval(IntervalMixin): >>> 2.5 in iv True - >>> 0 in iv - False - >>> 5 in iv - True - You can test the bounds (``closed='right'``, so ``0 < x <= 5`): + You can test the bounds (``closed='right'``, so ``0 < x <= 5``): >>> 0 in iv False