Skip to content

Commit 921fefb

Browse files
akielbowiczjorisvandenbossche
authored andcommitted
DOC: Updating pandas.Interval docstring (#20057)
1 parent 28eb190 commit 921fefb

File tree

1 file changed

+56
-10
lines changed

1 file changed

+56
-10
lines changed

pandas/_libs/interval.pyx

Lines changed: 56 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -81,33 +81,79 @@ cdef class Interval(IntervalMixin):
8181
8282
Parameters
8383
----------
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.
8888
closed : {'left', 'right', 'both', 'neither'}, default 'right'
8989
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``.
9196
9297
Examples
9398
--------
99+
It is possible to build Intervals of different types, like numeric ones:
100+
94101
>>> iv = pd.Interval(left=0, right=5)
95102
>>> iv
96103
Interval(0, 5, closed='right')
104+
105+
You can check if an element belongs to it
106+
97107
>>> 2.5 in iv
98108
True
99109
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')
102138
>>> pd.Timestamp('2017-01-01 00:00') in year_2017
103139
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
104148
105149
See Also
106150
--------
107151
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.
111157
"""
112158
_typ = "interval"
113159

0 commit comments

Comments
 (0)