pandas.Interval#

class pandas.Interval#

Immutable object implementing an Interval, a bounded slice-like interval.

Parameters:

leftorderable scalar: Left bound for the interval.
rightorderable scalar: 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. See the Notes for more detailed explanation.

See also

IntervalIndex: An Index of Interval objects that are all closed on the same side.
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.

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:

>>> iv = pd.Interval(left=0, right=5)
>>> iv
Interval(0, 5, closed='right')

You can check if an element belongs to it, or if it contains another interval:

>>> 2.5 in iv
True
>>> pd.Interval(left=2, right=5, closed='both') in iv
True

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

>>> 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
Interval(3, 8, closed='right')
>>> 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('365 days 00:00:00')

Attributes

`closed`	String describing the inclusive side the intervals.
`closed_left`	Check if the interval is closed on the left side.
`closed_right`	Check if the interval is closed on the right side.
`is_empty`	Indicates if an interval is empty, meaning it contains no points.
`left`	Left bound for the interval.
`length`	Return the length of the Interval.
`mid`	Return the midpoint of the Interval.
`open_left`	Check if the interval is open on the left side.
`open_right`	Check if the interval is open on the right side.
`right`	Right bound for the interval.

Methods

overlaps

Check whether two Interval objects overlap.