diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index f969c5db5b902..5dbf509fda65e 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -20,28 +20,60 @@ 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 left-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 closed 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 closed on the left-side, else + ``False``. """ return not self.closed_right @@ -88,12 +120,25 @@ cdef class Interval(IntervalMixin): closed : {'left', 'right', 'both', 'neither'}, default 'right' Whether the interval is closed on the left-side, right-side, both or neither. + closed : {'right', 'left', 'both', 'neither'}, default 'right' + Whether the interval is closed on the left-side, right-side, both or + neither. See the Notes for more detailed explanation. Notes ----- The parameters `left` and `right` must be from the same type, you must be able to compare them and they must satisfy ``left <= right``. + A closed interval (in mathematics denoted by square brackets) contains + its endpoints, i.e. the closed interval ``[0, 5]`` is characterized by the + conditions ``0 <= x <= 5``. This is what ``closed='both'`` stands for. + An open interval (in mathematics denoted by parentheses) does not contain + its endpoints, i.e. the open interval ``(0, 5)`` is characterized by the + conditions ``0 < x < 5``. This is what ``closed='neither'`` stands for. + Intervals can also be half-open or half-closed, i.e. ``[0, 5)`` is + described by ``0 <= x < 5`` (``closed='left'``) and ``(0, 5]`` is + described by ``0 < x <= 5`` (``closed='right'``). + Examples -------- It is possible to build Intervals of different types, like numeric ones: @@ -107,12 +152,14 @@ cdef class Interval(IntervalMixin): >>> 2.5 in iv True - You can test the bounds + You can test the bounds (``closed='right'``, so ``0 < x <= 5``): >>> 0 in iv False >>> 5 in iv True + >>> 0.0001 in iv + True Calculate its length @@ -150,9 +197,10 @@ cdef class Interval(IntervalMixin): -------- IntervalIndex : An Index of Interval objects that are all closed on the same side. - cut : Bin values into discrete intervals. - qcut : Discretize values into equal-sized buckets based on rank or - based on sample quantiles. + cut : Convert continuous data into discrete bins (Categorical + of Interval objects). + qcut : Convert continuous data into bins (Categorical of Interval objects) + based on quantiles. Period : Represents a period of time. """ _typ = "interval"