Skip to main content
`Ctrl`+`K`

# pandas.Interval

class pandas.Interval

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

  An Interval represents a range of values between a left and right bound, with optional inclusion of the endpoints. It is used in `IntervalIndex` and `IntervalArray` for interval-based indexing and analysis.

  Attributes

  `left` | Left bound for the interval.
  `right` | Right bound for the interval.
  `closed` | String describing the inclusive side the intervals.

  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`(other) | Check whether two Interval objects overlap.