Функция interval_range() модуля pandas в Python

Создает IntervalIndex фиксированной частоты

Синтаксис:

import pandas

idx = pandas.interval_range(start=None, end=None, periods=None, 
                                 freq=None, name=None, closed='right')

Параметры:

start=None - левая граница для создания интервалов. Приминает число для цифровых интервалов или объект pandas.Timestamp для временных интервалов.
end=None - правая граница для создания интервалов. Приминает число для цифровых интервалов или объект pandas.Timestamp для временных интервалов.
periods=None - целое число - количество периодов для генерации.
freq=None - длина каждого интервала. Должно соответствовать передаваемому типу аргументам start и end, например, 2 для числового интервала или '5H' для временного интервала. По умолчанию - 1 для числовых значений и 'D' для даты/времени.
name=None - имя результирующего IntervalIndex.
closed='right' - как закрывать или вообще НЕ закрывать интервалы. Принимает следующие строки: 'left', 'right', 'both', 'neither'.
Аргумент closed на примере числовых интервалов: замкнутый интервал (в математике обозначаемый квадратными скобками) содержит свои конечные точки, т. е. замкнутый интервал [0, 5] характеризуется условиями 0 <= x <= 5. Это то, что означает closed='both'. Открытый интервал (в математике обозначаемый круглыми скобками) не содержит своих конечных точек, т. е. открытый интервал (0, 5) характеризуется условиями 0 < x < 5. Это то, что означает closed='neither'. Интервалы также могут быть полуоткрытыми или полузакрытыми, т.е. [0, 5) описывается 0 <= x < 5 (closed='left'), а (0, 5] описывается 0 < x <= 5 (closed='right').

Возвращаемое значение:

Индекс интервалов IntervalIndex.

Описание:

Функция interval_range() модуля pandas создает и возвращает IntervalIndex фиксированной частоты по заданным параметрам.

Из четырех аргументов start, end, period и freq необходимо указать ровно три. Если аргумент freq опущен, то результирующий IntervalIndex будет содержать элементы с интервалами, линейно расположенными между началом start и концом end включительно.

Примеры использования:

Создание числовых интервалов:

>>> import pandas as pd
>>> pd.interval_range(start=0, end=5)
# IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]],
#               dtype='interval[int64, right]')

Также поддерживается создание временных интервалов.

>>> pd.interval_range(start=pd.Timestamp('2024-01-01'), end=pd.Timestamp('2024-01-04'))
# IntervalIndex([(2024-01-01 00:00:00, 2024-01-02 00:00:00],
#                (2024-01-02 00:00:00, 2024-01-03 00:00:00],
#                (2024-01-03 00:00:00, 2024-01-04 00:00:00]],
#               dtype='interval[datetime64[ns], right]')

Аргумент freq определяет частоту между левым start и правым end конечными точками интервалов в результирующем индексе IntervalIndex. Для создания числовых интервалов частота должна быть числом.

>>> pd.interval_range(start=0, periods=4, freq=1.5)
# IntervalIndex([(0.0, 1.5], (1.5, 3.0], (3.0, 4.5], (4.5, 6.0]],
#               dtype='interval[float64, right]')

Для создания временных интервалов частота должна быть конвертирована в DateOffset. Это значит что можно пользоваться значениями псевдонимами периодов временных рядов pandas.

>>> pd.interval_range(start=pd.Timestamp('2024-01-01'), periods=3, freq='MS')
# IntervalIndex([(2024-01-01 00:00:00, 2024-02-01 00:00:00],
#                (2024-02-01 00:00:00, 2024-03-01 00:00:00],
#                (2024-03-01 00:00:00, 2024-04-01 00:00:00]],
#               dtype='interval[datetime64[ns], right]')

Если в функцию pandas.interval_range() передать начало start, конец end и периодичность periods, то частота будет генерироваться автоматически (линейно).

>>> pd.interval_range(start=0, end=6, periods=4)
# IntervalIndex([(0.0, 1.5], (1.5, 3.0], (3.0, 4.5], (4.5, 6.0]],
#           dtype='interval[float64, right]')

Аргумент closed указывает, какие конечные точки отдельных интервалов в IntervalIndex будут закрыты.

>>> pd.interval_range(end=5, periods=4, closed='both')
# IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]],
#               dtype='interval[int64, both]')

Бывают случаи, когда прочитанные данные уже содержат столбец интервалов, но представленный как простая строка Python. В таких случаях встает задача: как разобрать строку с интервалом в фактический интервал библиотеки pandas? Так вот, можно проанализировать строку вручную, а затем преобразовать ячейки в IntervalIndex:

import ast
import pandas as pd

def parse_str_interval(s):
    """Разбор СТРОКИ с интервалом"""
    
    table = str.maketrans({'[': '(', ']': ')'})
    left_closed = s.startswith('[')
    right_closed = s.endswith(']')
    left, right = ast.literal_eval(s.translate(table))

    t = 'neither'
    if left_closed and right_closed:
        t = 'both'
    elif left_closed:
        t = 'left'
    elif right_closed:
        t = 'right'

    return pd.Interval(left, right, closed=t)


df1 = pd.DataFrame({'interval': {4: '(-0.001, 2.0]', 5: '(2.0, 6.0]'}, 'variable': {4: 'A', 5: 'A'}})
df1['interval'] = df1['interval'].apply(parse_str_interval)
df2 = pd.DataFrame({'A': [1, 1, 3]})
bins = df1[df1.variable.eq('A')].interval
new_series = pd.cut(df2['A'], bins=pd.IntervalIndex(bins))
print(new_series)

# 0    (-0.001, 2.0]
# 1    (-0.001, 2.0]
# 2       (2.0, 6.0]
# Name: A, dtype: category
# Categories (2, interval[float64, right]): [(-0.001, 2.0] < (2.0, 6.0]]