Pandas DatetimeIndex Usage Explained

Pandas DatetimeIndex makes it easier to work with Date and Time data in our DataFrame. DatetimeIndex() can contain metadata related to date and timestamp and is a great way to deal with datetime-related data and do the calculations on data and time. You can use the <a href="https://sparkbyexamples.com/tag/pd-to_datetime/">pd.to_datetime()</a> function to convert the DataFrame column from string type to datetime type or convert datetime to string type very easily.

1. DatetimeIndex() Syntax and Usage

Pandas DatetimeIndex() takes multiple parameters, below is the Syntax of the DatetimeIndex(). Let’s take a look at the parameters of the DatetimeIndex by examples.


# Syntax of DatetimeIndex()
pandas.DatetimeIndex(data=None, freq=_NoDefault.no_default, tz=None, normalize=False, closed=None, ambiguous='raise', dayfirst=False, yearfirst=False, dtype=None, copy=False, name=None)

Following is the list of parameters that you can pass to DateTimeIndex.

data — Datetime-like data.
freq — Stands for frequency. Check all the Possible values for the freq here.
tz — This keyword stands for timezone and sets the timezone of the data
normalize — It is used to set the start/end dates to midnight before generating the date range
closed — Can be set to “left” or “right”. Used for setting the boundary dates it should be included or not.
dayfirst — It takes a boolean value. If True, parse dates in data with the day’s first order.
yearfirst — It takes a boolean value as well. If True parse dates in data with the year first order.
copy — Use this keyword if you want to Make a copy of input ndarray.
name — the value you want to store in the index.

2. Attributes of Pandas DatetimeIndex

The DateTime Index has a lot of attributes for finding different properties of the DatetimeIndex from Pandas DataFrame. See the complete list with the examples below.

2.1 Extract Year from Pandas DatetimeIndex

The Pandas Datetimeindex has the “year” attribute, you can use this to get the year from the Datetimeindex. See the below code where we get the year of DatetimeIndex. We use the Datetimeindex.year attribute.


# Extract Year from Pandas DatetimeIndex
import pandas as pd
dt_index_obj = pd.DatetimeIndex(['2017-12-31 16:00:00-08:00', '2017-12-31 17:00:00-08:00',
               '2017-12-31 18:00:00-08:00'],
              dtype='datetime64[ns, US/Pacific]', freq='H')

# Get years of the dateTimeIndex
dt_index_obj.year
print("Get the year of the datetimeindex:\n", dt_index_obj.year)

Yields below output.

Related Article: Pandas Filter DataFrame Rows on Dates

2.2 Extract Month from Pandas DatetimeIndex

To get the month of the DatetimeIndex, use the DatetimeIndex.month attribute. DatetimeIndex.month is an attribute that returns the month of the DateTimeIndex object. See the following example.


# Get months of the dateTimeIndex
dt_index_obj.month
print("Get the month of the datetimeindex:\n", dt_index_obj.month)

Yields below output.

Related Article: Convert Pandas DatetimeIndex to String

2.3 Extract Day, Hour, Minute, and Time from DatetimeIndex

In the following example, you will see how we get the day, hour, minute, time, week, date, and more from the DatetimeIndex object.


# Get day of the dateTimeIndex
dt_index_obj.day

# Get hour of the dateTimeIndex
dt_index_obj.hour

# Get minute of the dateTimeIndex
dt_index_obj.minute

# Get date of the dateTimeIndex
dt_index_obj.date

# Get time of the dateTimeIndex
dt_index_obj.time

# Get timezone of the dateTimeIndex
dt_index_obj.timetz

# Get week of the dateTimeIndex
dt_index_obj.week

# Get month name of the dateTimeIndex
dt_index_obj.month_name

3. Find the Date is the First Day of the Month from Pandas DatatimeIndex

Let’s say you want to do calculations on data that contain the first day of the month, you can get this by using the Pandas datetimeinedex.is_month_start attribute. datetimeindex.is_month_start indicates whether the date is the first day of the month. It returns true if a day is the first day of the month otherwise it will return false.


# Find if the date is first day of the month
dt_index_obj.is_month_start

# Output:
# Array([ True, False, False])

Related Articles: Pandas Index Explained with Examples

4. Find Date is the End of the Month

Datetimeindex.is_month_end attribute is useful when you want to find the end of the month. For example, do some calculation on those data that comes at the end of a month. See the following code example.

In the following example, an array is the returned value that returns true if the value of the corresponding date is the last day of the month.


# Find if the date is the end of the month
dt_index_obj.is_month_end

# Output:
# Array([False,  True,  True])

5. Find Day is the Start Day of the Year

To find out if a day is the start of the year in pandas DatetimeIndex, use the DatetimeIndex.is_year_start. It will return true if the day is the start of the year otherwise it will return a false value.

See the following example where we use the is_year_start of pandas DatetimeIndex.


# Find day is the start day of the year
dt_index_obj.is_year_start

# Output:
# Array([ True, False, False])

6. Find Day is the End of the Year

The recommended way to find out if a day is the end of the year in pandas DatetimeIndex, use the DatetimeIndex.is_year_end. It will return true if the day is the last day of the year otherwise it will return a false value.


# Find day is the end of the year
dt_index_obj.is_year_end

# Output:
# Array([False,  True,  True])

7. Find Year is a Leap in Pandas DatetimeIndex

In cases where you want to find the leap years out of all the dates in pandas DatetimeIndex we use the DatetimeIndex.is_leap_year. It returns a boolean value of true if the year is a leap year otherwise it will return false.


# Find year is a leap year
dt_index_obj.is_leap_year

# Output:
# Array([ True, False, False])

8. Find Day of Week DatetimeIndex

Monday will be considered is the zeroth Day and the last day of the week will be Sunday which is the seventh day of the week. DatetimemIndex.dayofweek which returns the day number of the week.

See the following example.


# Find day of the week
dt_index_obj.dayofweek

# Output:
# Int64Index([2, 5, 6], dtype='int64')

9. Round Date in Pandas DatetimeIndex

We can also round the date in a DatetimeIndex, to do so we have to use the Pandas Datetimeindex.round() function. It returns a rounded date. In the following example, we have passed a parameter of ‘H’, which stands for hours and tells the function to round the date by hours.

See the following example and look at the output. The date is rounded by Hours.


# Round date
dt_index_obj.round('H')

# Output:
# DatetimeIndex(['2020-01-01 16:00:00-08:00', '2017-12-30 17:00:00-08:00',
#                '2017-12-31 18:00:00-08:00'],
#               dtype='datetime64[ns, US/Pacific]', freq=None)

FAQ on Pandas DatetimeIndex

What is a DatetimeIndex in Pandas?

It’s an index object that holds datetime-like data, allowing time-based indexing and slicing of data in a DataFrame or Series.

How do you create a DatetimeIndex?

Using pd.date_range(), converting a column with pd.to_datetime(), or directly initializing it with datetime objects.

How do you filter data by a date range with DatetimeIndex?

Use slicing: df['2023-01-01':'2023-01-10'] to select rows within a range.

What are some common attributs of DatetimeIndex?

The DatetimeIndex in Pandas provides several useful attributes to extract specific parts of the date or time. For example, .year, .month, .day, .hour, .weekday, etc., to extract specific date parts.

How do you convert a DatetimeIndex back to a column?

To convert a DatetimeIndex back to a column in a Pandas DataFrame, you can use the reset_index() method. By default, reset_index() moves the DatetimeIndex to a new column and creates a new default integer index.

Conclusion

In this article, you have learned about Pandas DatetimeIndex, its syntax, usage, and different attributes. Please feel free to ask questions if you have any or leave a comment of appreciation.

Table of contents