@@ -81,33 +81,79 @@ cdef class Interval(IntervalMixin):
81
81
82
82
Parameters
83
83
----------
84
- left : value
85
- Left bound for the interval
86
- right : value
87
- Right bound for the interval
84
+ left : orderable scalar
85
+ Left bound for the interval.
86
+ right : orderable scalar
87
+ Right bound for the interval.
88
88
closed : {'left', 'right', 'both', 'neither'}, default 'right'
89
89
Whether the interval is closed on the left-side, right-side, both or
90
- neither
90
+ neither.
91
+
92
+ Notes
93
+ -----
94
+ The parameters `left` and `right` must be from the same type, you must be
95
+ able to compare them and they must satisfy ``left <= right``.
91
96
92
97
Examples
93
98
--------
99
+ It is possible to build Intervals of different types, like numeric ones:
100
+
94
101
>>> iv = pd.Interval(left=0, right=5)
95
102
>>> iv
96
103
Interval(0, 5, closed='right')
104
+
105
+ You can check if an element belongs to it
106
+
97
107
>>> 2.5 in iv
98
108
True
99
109
100
- >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
101
- ... pd.Timestamp('2017-12-31'), closed='both')
110
+ You can test the bounds
111
+
112
+ >>> 0 in iv
113
+ False
114
+ >>> 5 in iv
115
+ True
116
+
117
+ Calculate its length
118
+
119
+ >>> iv.length
120
+ 5
121
+
122
+ You can operate with `+` and `*` over an Interval and the operation
123
+ is applied to each of its bounds, so the result depends on the type
124
+ of the bound elements
125
+
126
+ >>> shifted_iv = iv + 3
127
+ >>> shifted_iv
128
+ Interval(3, 8, closed='right')
129
+ >>> extended_iv = iv * 10.0
130
+ >>> extended_iv
131
+ Interval(0.0, 50.0, closed='right')
132
+
133
+ To create a time interval you can use Timestamps as the bounds
134
+
135
+ >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01 00:00:00'),
136
+ ... pd.Timestamp('2018-01-01 00:00:00'),
137
+ ... closed='left')
102
138
>>> pd.Timestamp('2017-01-01 00:00') in year_2017
103
139
True
140
+ >>> year_2017.length
141
+ Timedelta('365 days 00:00:00')
142
+
143
+ And also you can create string intervals
144
+
145
+ >>> volume_1 = pd.Interval('Ant', 'Dog', closed='both')
146
+ >>> 'Bee' in volume_1
147
+ True
104
148
105
149
See Also
106
150
--------
107
151
IntervalIndex : An Index of Interval objects that are all closed on the
108
- same side.
109
- cut, qcut : Convert arrays of continuous data into Categoricals/Series of
110
- Interval.
152
+ same side.
153
+ cut : Bin values into discrete intervals.
154
+ qcut : Discretize values into equal-sized buckets based on rank or
155
+ based on sample quantiles.
156
+ Period : Represents a period of time.
111
157
"""
112
158
_typ = " interval"
113
159
0 commit comments