Python Pandas - PeriodIndex

---

---

A PeriodIndex in Pandas is a special index that represents intervals of time, nothing but a sequence of time-spans. Unlike other time indexes, PeriodIndex represents distinct intervals of time, which allows you to work time-related data more effectively, especially when dealing with sequences of time spans.

In this tutorial will learn about PeriodIndex and related topics such as period_range, period dtypes, partial string indexing, and frequency conversion.

Introduction to PeriodIndex

The PeriodIndex represents a sequence of periods (i.e., time spans), similar to how DatetimeIndex works with timestamps. The PeriodIndex is used to manage and manipulate sequences of intervals, such as months, quarters, or years.

In Pandas, Period objects represent regular intervals, and a sequence of Period objects is stored in a PeriodIndex.

Syntax

Following is the syntax PeriodIndex class −

class pandas.PeriodIndex(data=None, ordinal=None, freq=None, dtype=None, copy=False, name=None, **fields)

Where,

• data: Array-like or PeriodArray, containing period-like data.

• freq: Frequency string or object (e.g., 'M' for monthly).

• copy: If True, makes a copy of the input array.

• name: Optional name for the index.

• dtype: Specifies data type, by default it is set to None.

Example

Here is the example of creating a PeriodIndex using the PeriodIndex() constructor directly.

import pandas as pd

# Create a PeriodIndex 
p_index = pd.PeriodIndex(["2024-1", "2024-2", "2024-3"], freq="M")
print(p_index)

Following is the output of the above code −

PeriodIndex(['2024-01', '2024-02', '2024-03'], dtype='period[M]')

Creating a PeriodIndex with period_range

The PeriodIndex can be created by using the period_range() function, which is a convenient way to generate a sequence of Period objects. The period_range() function generates a series of periods from a start to an end date. Allows you to specify the frequency (e.g., monthly 'M', quarterly 'Q', or daily 'D').

Example

Here is the example of creating a PeriodIndex using the period_range() function.

import pandas as pd

# Create a PeriodIndex using period_range
p_indx = pd.period_range("1/1/2023", "1/1/2024", freq="M")
print(p_indx)

Following is the output of the above code −

PeriodIndex(['2023-01', '2023-02', '2023-03', '2023-04', '2023-05', '2023-06',
             '2023-07', '2023-08', '2023-09', '2023-10', '2023-11', '2023-12',
             '2024-01'],
            dtype='period[M]')

Using PeriodIndex in DataFrames and Series

You can use PeriodIndex to an index for Series or DataFrames, creating time-based data structures.

Example: Series with PeriodIndex

Here is an example of creating a pandas Series object with PeriodIndex.

import pandas as pd
import numpy as np

# Create a PeriodIndex using period_range
p_index = pd.PeriodIndex(["2024-1", "2024-2", "2024-3"], freq="M")

# Create a PeriodIndexed Series
ps = pd.Series(np.random.randn(len(p_index)), index=p_index)
print('Output PeriodIndexed Series:')
print(ps)

Following is the output of the above code −

Output PeriodIndexed Series:
2024-01   -1.039788
2024-02    1.655438
2024-03    1.174775
Freq: M, dtype: float64

Example: DataFrame with PeriodIndex

Here is an example of creating a pandas DataFrame object with PeriodIndex.

import pandas as pd
import numpy as np

# Create a PeriodIndex using period_range
p_indx = pd.period_range("1/1/2024", "7/1/2024", freq="M")

# Create a PeriodIndexed DataFrame
df = pd.DataFrame({'A':[1, 2, 3, 5, 6, 1, 5],
'B':[4, 5, 5, 1, 1, 1, 3]}, index=p_indx)
print('Output PeriodIndexed DataFrame:')
print(df)

Following is the output of the above code −

Output PeriodIndexed DataFrame:

	A	B
2024-01	1	4
2024-02	2	5
2024-03	3	5
2024-04	5	1
2024-05	6	1
2024-06	1	1
2024-07	5	3

Understanding Period Dtypes and Conversion

Pandas provides a custom dtype period[freq] for PeriodIndex, this period dtype holds frequency information (like, period[M] for monthly, period[D] for daily). The period dtype can be used to change frequencies or convert between DatetimeIndex and PeriodIndex using the .astype(...) method.

Example: Checking Period Dtype

This example checks the period dtype of the PeriodIndex object.

import pandas as pd
import numpy as np

# Create a PeriodIndex using period_range
p_indx = pd.period_range("1/1/2024", "1/10/2024", freq="D")

# Display the PeriodIndex
print("Input PeriodIndex:")
print(p_indx)

# Check period dtype
print("\nPeriod dtype:", p_indx.dtype)

Following is the output of the above code −

Input PeriodIndex:
PeriodIndex(['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04',
             '2024-01-05', '2024-01-06', '2024-01-07', '2024-01-08',
             '2024-01-09', '2024-01-10'],
            dtype='period[D]')

Period dtype: period[D]

Example: Changing Frequency of the Period Dtype

This example changes the Period dtype of a PeriodIndex object using the astype() function.

import pandas as pd
import numpy as np

# Create a PeriodIndex using period_range
p_indx = pd.period_range("2024-01-01", periods=3, freq="M")

# Display the PeriodIndex
print("Input PeriodIndex:")
print(p_indx)

# Change the PeriodIndex Frequency 
print('\nOutput PeriodIndex after changing the frequency:')
print(p_indx.astype("period[D]"))

Following is the output of the above code −

Input PeriodIndex:
PeriodIndex(['2024-01', '2024-02', '2024-03'], dtype='period[M]')

Output PeriodIndex after changing the frequency:
PeriodIndex(['2024-01-31', '2024-02-29', '2024-03-31'], dtype='period[D]')

Example: Conversion Between PeriodIndex and DatetimeIndex

This example performs the conversion between PeriodIndex and DatetimeIndex objects using the .astype() function.

import pandas as pd

# Create a PeriodIndex using period_range
p_indx = pd.period_range("2024-01-01", periods=3, freq="M")

# Display the PeriodIndex
print("Input PeriodIndex:")
print(p_indx)

# Convert a PeriodIndex to a DatetimeIndex
pindx_datetime = p_indx.astype("datetime64[ns]")
print("\nOutput Converted DatetimeIndex:")
print(pindx_datetime)

# Create a DatetimeIndex 
date_time = pd.date_range("2020-01-01", freq="M", periods=3)
# Display the DatetimeIndex 
print("\nInput DatetimeIndex:")
print(date_time )

# Convert a DatetimeIndex to PeriodIndex
print("\nOutput Converted PeriodIndex from DatetimeIndex:")
print( date_time.astype("period[M]"))

Following is the output of the above code −

Input PeriodIndex:
PeriodIndex(['2024-01', '2024-02', '2024-03'], dtype='period[M]')

Output Converted DatetimeIndex:
DatetimeIndex(['2024-01-01', '2024-02-01', '2024-03-01'], dtype='datetime64[ns]', freq='MS')

Input DatetimeIndex:
DatetimeIndex(['2020-01-31', '2020-02-29', '2020-03-31'], dtype='datetime64[ns]', freq='M')

Output Converted PeriodIndex from DatetimeIndex:
PeriodIndex(['2020-01', '2020-02', '2020-03'], dtype='period[M]')

Partial String Indexing with PeriodIndex

The PeriodIndex object supports the partial string slicing with non-monotonic indexes. It simplifies the process of retrieving data.

Example

This example demonstrates the retrieving of PeriodIndex Series object data using the partial string indexing and slicing.

import pandas as pd
import numpy as np

# Create a PeriodIndex using period_range
p_index = pd.period_range("1/1/2024", "7/1/2024", freq="M")

# Create a PeriodIndexed Series
ps = pd.Series(np.random.randn(len(p_index)), index=p_index)
print('PeriodIndexed Series:')
print(ps)

# Retrieve data for a specific month
print("\nRetrieve data for a specific month:")
print(ps["2024-02"])

# Retrieve data for a date range
print("\nRetrieve data for a date range:")
print(ps["2024-02":"2024-05"])

Following is the output of the above code −

PeriodIndexed Series:
2024-01   -0.422717
2024-02    0.810241
2024-03   -1.756957
2024-04    2.938013
2024-05   -0.714927
2024-06    3.340352
2024-07   -0.973727
Freq: M, dtype: float64

Retrieve data for a specific month:
0.810241143756745

Retrieve data for a date range:
2024-02    0.810241
2024-03   -1.756957
2024-04    2.938013
2024-05   -0.714927
Freq: M, dtype: float64