From eb8ce9f372335544e56c74493fe7599990e290d8 Mon Sep 17 00:00:00 2001 From: akielbowicz Date: Thu, 8 Mar 2018 12:19:21 -0300 Subject: [PATCH 1/6] Added type to the parameter and extend the examples --- pandas/_libs/interval.pyx | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index c0b2ca66e30a6..6735f72dd829c 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -81,26 +81,45 @@ cdef class Interval(IntervalMixin): Parameters ---------- - left : value - Left bound for the interval - right : value - Right bound for the interval + left : orderable object + Left bound for the interval. + right : orderable object + Right bound for the interval. closed : {'left', 'right', 'both', 'neither'}, default 'right' Whether the interval is closed on the left-side, right-side, both or - neither + neither. + + Notes + ----- + You must be able to compare the parameters **left** and **right**, + and they must satisfy **left <= right**. Examples -------- + The examples below show how you can build Intervals of various types + of elements. In particular a numeric interval, a time interval and + finally a string interval. Given an Interval you can check whether + an element belongs to it. + >>> iv = pd.Interval(left=0, right=5) >>> iv Interval(0, 5, closed='right') >>> 2.5 in iv True - + >>> shifted_iv = iv + 3 + >>> shifted_iv + Interval(3, 8, closed='right') + >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'), ... pd.Timestamp('2017-12-31'), closed='both') >>> pd.Timestamp('2017-01-01 00:00') in year_2017 True + >>> year_2017.length + Timedelta('364 days 00:00:00') + + >>> volume_1 = pd.Interval('Ant','Dog',closed='both') + >>> 'Bee' in volume_1 + True See Also -------- @@ -283,4 +302,4 @@ cpdef intervals_to_interval_bounds(ndarray intervals): return left, right, closed -include "intervaltree.pxi" +include "intervaltree.pxi" \ No newline at end of file From 080654d170bb592dcd416b0172cc4ec0f8a83760 Mon Sep 17 00:00:00 2001 From: akielbowicz Date: Fri, 9 Mar 2018 21:49:57 -0300 Subject: [PATCH 2/6] Changed referece to parameters with sigle backticks --- pandas/_libs/interval.pyx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index 6735f72dd829c..0196fde4dfa88 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -91,8 +91,8 @@ cdef class Interval(IntervalMixin): Notes ----- - You must be able to compare the parameters **left** and **right**, - and they must satisfy **left <= right**. + You must be able to compare the parameters `left` and `right`, + and they must satisfy ``left <= right``. Examples -------- @@ -302,4 +302,4 @@ cpdef intervals_to_interval_bounds(ndarray intervals): return left, right, closed -include "intervaltree.pxi" \ No newline at end of file +include "intervaltree.pxi" From 713d975e6ad1b72ca9bce66746b1d75ca169525a Mon Sep 17 00:00:00 2001 From: akielbowicz Date: Fri, 9 Mar 2018 23:47:30 -0300 Subject: [PATCH 3/6] Improved the examples and replaced * to backticks --- pandas/_libs/interval.pyx | 53 ++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index 0196fde4dfa88..c4889ce557fa8 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -81,43 +81,68 @@ cdef class Interval(IntervalMixin): Parameters ---------- - left : orderable object + left : orderable scalar Left bound for the interval. - right : orderable object + right : orderable scalar Right bound for the interval. closed : {'left', 'right', 'both', 'neither'}, default 'right' Whether the interval is closed on the left-side, right-side, both or neither. - + Notes ----- You must be able to compare the parameters `left` and `right`, - and they must satisfy ``left <= right``. + and they must satisfy ``left <= right``. Examples -------- - The examples below show how you can build Intervals of various types - of elements. In particular a numeric interval, a time interval and - finally a string interval. Given an Interval you can check whether - an element belongs to it. + It is possible to build Intervals of different types, like numeric ones >>> iv = pd.Interval(left=0, right=5) >>> iv Interval(0, 5, closed='right') + + In which you can check if an element belongs to it + >>> 2.5 in iv True + + You can test the bounds + + >>> 0 in iv + False + >>> 5 in iv + True + + Calculate its length + + >>> iv.length + 5 + + You can operate with `+` and `*` over an Interval and the operation + is applied to each of its bounds, so the result depends on the type + of the bound elements + >>> shifted_iv = iv + 3 - >>> shifted_iv + >>> shifted_iv Interval(3, 8, closed='right') - - >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'), - ... pd.Timestamp('2017-12-31'), closed='both') + >>> extended_iv = iv * 10.0 + >>> extended_iv + Interval(0.0, 50.0, closed='right') + + To create a time interval you can use Timestamps as the bounds + + >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01 00:00:00'), + ... pd.Timestamp('2018-01-01 00:00:00'), + ... closed='left') >>> pd.Timestamp('2017-01-01 00:00') in year_2017 True >>> year_2017.length - Timedelta('364 days 00:00:00') + Timedelta('365 days 00:00:00') + + And also you can create string intervals - >>> volume_1 = pd.Interval('Ant','Dog',closed='both') + >>> volume_1 = pd.Interval('Ant', 'Dog', closed='both') >>> 'Bee' in volume_1 True From 7db6817be9e734333e6eefe47d35dac645911f9b Mon Sep 17 00:00:00 2001 From: akielbowicz Date: Sat, 10 Mar 2018 18:30:32 -0300 Subject: [PATCH 4/6] Update notes --- pandas/_libs/interval.pyx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index c4889ce557fa8..66077d79c5985 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -91,8 +91,8 @@ cdef class Interval(IntervalMixin): Notes ----- - You must be able to compare the parameters `left` and `right`, - and they must satisfy ``left <= right``. + The parameters `left` and `right` must be from the `same` type,you must be + able to `compare` them and they must satisfy ``left <= right``. Examples -------- @@ -150,8 +150,9 @@ 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 : Return indices of half-open bins. + qcut : Discretize variable into equal-sized buckets based on rank or + based on sample quantiles. """ _typ = "interval" From c1d72654e46c9de87b234db5a392b310622e1bf0 Mon Sep 17 00:00:00 2001 From: akielbowicz Date: Sat, 10 Mar 2018 18:39:54 -0300 Subject: [PATCH 5/6] Added Period to See Also --- pandas/_libs/interval.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index 66077d79c5985..f0d2aa03ed757 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -153,6 +153,7 @@ cdef class Interval(IntervalMixin): cut : Return indices of half-open bins. qcut : Discretize variable into equal-sized buckets based on rank or based on sample quantiles. + Period : Represents a period of time. """ _typ = "interval" From 46823869f0aec133139991f485e043d86430a85f Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 14 Mar 2018 14:11:03 +0100 Subject: [PATCH 6/6] Update interval.pyx --- pandas/_libs/interval.pyx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index f0d2aa03ed757..f969c5db5b902 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -91,18 +91,18 @@ cdef class Interval(IntervalMixin): 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``. + The parameters `left` and `right` must be from the same type, you must be + able to compare them and they must satisfy ``left <= right``. Examples -------- - It is possible to build Intervals of different types, like numeric ones + It is possible to build Intervals of different types, like numeric ones: >>> iv = pd.Interval(left=0, right=5) >>> iv Interval(0, 5, closed='right') - In which you can check if an element belongs to it + You can check if an element belongs to it >>> 2.5 in iv True @@ -149,9 +149,9 @@ cdef class Interval(IntervalMixin): See Also -------- IntervalIndex : An Index of Interval objects that are all closed on the - same side. - cut : Return indices of half-open bins. - qcut : Discretize variable into equal-sized buckets based on rank or + same side. + cut : Bin values into discrete intervals. + qcut : Discretize values into equal-sized buckets based on rank or based on sample quantiles. Period : Represents a period of time. """