Функция Pandas pd.date_range()

Pandas 通用函数Pandas: общие функции

pd.date_range()используется в библиотеке Pandas длягенерации диапазонов датфункции. Она создаёт DatetimeIndex, содержащий последовательные даты, который обычно используется для создания, индексации и выравнивания данных временных рядов.

В анализе временных рядов часто необходимо генерировать последовательности дат с фиксированной частотой, например ежедневные, ежемесячные или годовые данные. pd.date_range() предоставляет гибкие параметры для удовлетворения различных требований к частоте.

Определение термина： date_rangeОзначает "диапазон дат", то есть генерацию набора последовательных дат.

Базовый синтаксис и параметры

pd.date_range()является функцией верхнего уровня библиотеки Pandas, используемой для генерации индексов даты и времени с заданной частотой.

Формат синтаксиса

pd.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, closed=None)

Описание параметра

Параметр Type Обязательный Описание Значение по умолчанию
start Строка или datetime Optional Дата начала. Отсутствует
end Строка или datetime Optional Дата окончания. Отсутствует
periods Integer Optional Количество дат для генерации. Используйте любые два из start, end и periods. Отсутствует
freq String или DateOffset Optional Частота: 'D' (день), 'H' (час), 'M' (конец месяца), 'MS' (начало месяца), 'Y' (конец года), 'W' (неделя) и т. д. 'D'
tz String Optional Название часового пояса, например 'UTC', 'Asia/Shanghai'. Отсутствует
normalize Boolean Optional Если True, нормализует время к полуночи. False
name String Optional Имя результирующего DatetimeIndex. Отсутствует
closed String Optional Включение границ интервала: 'left', 'right', None (по умолчанию, обе включены). Отсутствует

Описание возвращаемого значения

  • Возвращаемое значение: Возвращает объект DatetimeIndex, содержащий последовательные значения даты и времени.
  • Действие: Генерирует последовательность дат на основе указанных начальной даты, конечной даты и частоты.

Примеры

Давайте досконально освоим с помощью серии примеров от простых к сложнымpd.date_range()его использование.

Пример 1: Базовое использование — Генерация диапазона дат

Пример

import pandas as pd

# 1. Используйте параметры start и end для генерации диапазона дат (частота по умолчанию — ежедневная)
print("=== С 2023-01-01 по 2023-01-10 ===")
dates = pd.date_range(start='2023-01-01', end='2023-01-10')
print(dates)
print(f"Тип: {type(dates)}")
print(f"Тип данных: {dates.dtype}")

# 2. Используйте параметр periods, чтобы указать количество генерируемых дат
print("n=== Сгенерировать даты на 7 дней ===")
week_dates = pd.date_range(start='2023-01-01', periods=7)
print(week_dates)

# 3. Используйте параметр freq для указания частоты
print("n=== Одна дата в неделю (freq='W') ===")
weekly_dates = pd.date_range(start='2023-01-01', periods=5, freq='W')
print(weekly_dates)

# 4. Дата в начале каждого месяца (freq='MS' = начало месяца)
print("n=== Начало месяца (freq='MS') ===")
monthly_dates = pd.date_range(start='2023-01-01', periods=6, freq='MS')
print(monthly_dates)

# 5. Дата в конце каждого года (freq='YE' = конец года)
print("n=== Конец года (freq='YE') ===")
yearly_dates = pd.date_range(start='2023-01-01', periods=3, freq='YE')
print(yearly_dates)

Вывод:

=== 从 2023-01-01 到 2023-01-10 ===
DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05',
               '2023-01-06', '2023-01-07', '2023-01-08', '2023-01-09', '2023-01-10'],
              dtype='datetime64[ns]', freq='D')
Type: <class 'pandas.core.indexes.datetimes.DatetimeIndex'>
数据类型: datetime64[ns]

=== 生成 7 天的日期 ===
DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05',
               '2023-01-06', '2023-01-07'], dtype='datetime64[ns]', freq='D')

=== 每周一个日期 (freq='W') ===
DatetimeIndex(['2023-01-01', '2023-01-08', '2023-01-15', '2023-01-22', '2023-01-29'], dtype='datetime64[ns]', freq='W-SUN')

=== 每月初 (freq='MS') ===
DatetimeIndex(['2023-01-01', '2023-02-01', '2023-03-01', '2023-04-01', '2023-05-01',
               '2023-06-01'], dtype='datetime64[ns]', freq='MS')

=== 每年末 (freq='YE') ===
DatetimeIndex(['2023-12-31', '2024-12-31', '2025-12-31'], dtype='datetime64[ns]', freq='YE-DEC')

Пояснение кода:

  1. pd.date_range()Генерирует последовательность дат с дневной частотой по умолчанию.
  2. freqПараметр поддерживает несколько сокращений частоты: 'D' (день), 'W' (неделя), 'M' (конец месяца), 'MS' (начало месяца), 'Y' (конец года), 'H' (час) и т. д.
  3. Возвращается объект DatetimeIndex, который можно напрямую использовать как индекс Series или DataFrame.

Пример 2: Генерация данных временного ряда

Создайте DataFrame с индексом дат для анализа временных рядов.

Пример

import pandas as pd
import numpy as np

# 1. Создайте DataFrame с индексом дат
print("=== Создать простой временной ряд ===")

# Сгенерировать даты за 30 дней
date_index = pd.date_range(start='2023-01-01', periods=30, freq='D')

# Создать DataFrame
df = pd.DataFrame({
    'date': date_index,
    'value': np.random.randint(10, 100, size=30),  # Случайные значения
    'category': ['A', 'B'] * 15  # Чередующиеся категории
})

print(df.head(10))

# 2. Установить дату как индекс
print("n=== Установить дату как индекс ===")
df_indexed = df.set_index('date')
print(df_indexed.head())

# 3. Сгенерировать почасовые данные (для анализа логов)
print("n=== Почасовой временной ряд ===")
hourly_index = pd.date_range(start='2023-01-01 08:00', periods=24, freq='H')
hourly_data = pd.DataFrame({
    'timestamp': hourly_index,
    'visitors': np.random.randint(0, 100, size=24)
})
print(hourly_data)

Вывод:

=== 创建一个简单的时间序列 ===
        date  value category
0 2023-01-01     67        A
1 2023-01-02     23        B
2 2023-01-03     45        A
3 2023-01-04     89        B
4 2023-01-05     12        A
5 2023-01-06     34        B
6 2023-01-07     56        A
7 2023-01-08     78        B
8 2023-01-09     91        A
9 2023-01-10     55        B

=== 设置日期为索引 ===
             value category
date
2023-01-01     67        A
2023-01-02     23        B
2023-01-03     45        A
2023-01-04     89        B
2023-01-05     12        A
2023-01-06     34        B

=== 每小时的时间序列 ===
                 timestamp  visitors
0  2023-01-01 08:00:00      25
1  2023-01-01 09:00:00      41
2  2023-01-01 10:00:00      77
3  2023-01-01 11:00:00      12
4  2023-01-01 12:00:00      58
5  2023-01-01 13:00:00      33
6  2023-01-01 14:00:00      45
7  2023-01-01 15:00:00      67
8  2023-01-01 16:00:00      29
9  2023-01-01 17:00:00      51
10 2023-01-01 18:00:00      44
11 2023-01-01 19:00:00      36
12 2023-01-01 20:00:00      28
13 2023-01-01 21:00:00      62
14 2023-01-01 22:00:00      19
15 2023-01-01 23:00:00      73
16 2023-01-02 00:00:00      41
17 2023-01-02 01:00:00      55
18 2023-01-02 02:00:00      38
19 2023-01-02 03:00:00      27
20 2023-01-02 04:00:00      49
21 2023-01-02 05:00:00      63
22 2023-01-02 06:00:00      34
23 2023-01-02 07:00:00      56

Пояснение кода:

  • DatetimeIndex можно напрямую использовать в качестве индекса DataFrame.
  • DataFrame с индексом даты поддерживают широкий набор операций над временными рядами, таких как передискретизация и скользящие вычисления.
  • freq='H'Можно генерировать данные с почасовой детализацией, что подходит для таких сценариев, как анализ логов.

Пример 3: часовой пояс и параметр closed

Пример

import pandas as pd

# 1. Используйте параметр tz для указания часового пояса
print("=== Диапазон дат с часовым поясом ===")
dates_tz = pd.date_range(start='2023-01-01', periods=3, freq='D', tz='Asia/Shanghai')
print(dates_tz)
print(f"Часовой пояс: {dates_tz.tz}")

# 2. Используйте часовой пояс UTC
print("n=== Часовой пояс UTC ===")
dates_utc = pd.date_range(start='2023-01-01', periods=3, freq='D', tz='UTC')
print(dates_utc)

# 3. Используйте параметр closed для управления включением границ интервала
print("n=== Сравнение параметра closed ===")
print("closed=None (по умолчанию, обе границы включены):", pd.date_range('2023-01-01', '2023-01-03', freq='D', closed=None))
print("closed='left':", pd.date_range('2023-01-01', '2023-01-03', freq='D', closed='left'))
print("closed='right':", pd.date_range('2023-01-01', '2023-01-03', freq='D', closed='right'))

# 4. Используйте параметр normalize для нормализации времени
print("n=== параметр normalize ===")
dates_with_time = pd.date_range(start='2023-01-01 14:30:00', periods=3, freq='H')
print("Перед нормализацией:", dates_with_time)

dates_normalized = pd.date_range(start='2023-01-01 14:30:00', periods=3, freq='H', normalize=True)
print("После нормализации:", dates_normalized)

Вывод:

=== 带时区的日期范围 ===
DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03'], dtype='datetime64[ns, Asia/Shanghai]')
时区: Asia/Shanghai

=== UTC 时区 ===
DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03'], dtype='datetime64[ns, UTC]')

=== closed 参数对比 ===
closed=None (默认, 两端都闭): DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03'])
closed='left': DatetimeIndex(['2023-01-01', '2023-01-02'])
closed='right': DatetimeIndex(['2023-01-02', '2023-01-03'])

=== normalize 参数 ===
归一化前: DatetimeIndex(['2023-01-01 14:30:00', '2023-01-01 15:30:00', '2023-01-01 16:30:00'])
归一化后: DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03'])

Пояснение кода:

  • tzПараметр может указывать часовой пояс, что очень полезно при обработке данных в разных часовых поясах.
  • closedПараметр может управлять включением границ интервала дат, по умолчанию включены обе границы.
  • normalize=TrueНормализует время к полуночи, что удобно для агрегирования данных по дате.

Примечания

Важные замечания:

  • Необходимо указатьstartиend, или указатьstartиperiods, или указатьendиperiods, но нельзя указать только один одновременно.
  • Сокращения частоты чувствительны к регистру; например, 'D' означает день, а 'd' вызовет ошибку.
  • При работе с данными часовых поясов убедитесь, что все даты используют единый часовой пояс; в противном случае могут возникнуть неожиданные результаты.
  • При генерации большого количества дат (например, данных за несколько лет) обращайте внимание на использование памяти.

Pandas 通用函数Pandas: общие функции

Другие расширения