Python Pandas - Timedelta

Timedelta in Pandas represents a duration, or the difference between two dates or times, expressed in units such as days, hours, minutes, or seconds. They are useful for performing arithmetic operations on datetime objects and can be both positive and negative duration's.

Pandas Timedelta Class

Thepandas.Timedelta class is a powerful tool to represent a duration or the difference between two dates or times. It is equivalent of Python'sdatetime.timedelta object and can be used interchangeably in most cases.

Syntax

Following is the syntax of the class −

class pandas.Timedelta(value=<object object>, unit=None, **kwargs)

Where,

• value − Accepts the any of the following time object: Timedelta, timedelta, np.timedelta64, str, or int.

• unit − It is a optional parameter specifies the unit of the input if the input is an integer. Supported units include: 'W', 'D', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', 'nanoseconds'.

• **kwargs − Accepts keyword arguments like days, seconds, microseconds, milliseconds, minutes, hours, and weeks.

Example

Following is the basic example of creating theTimedelta object.

import pandas as pd# Initialize Timedelta with value and unittd = pd.Timedelta(1, "d")print(td)print('Data Type of the Resultant Object:',type(td))

Following is the output of the above code −

1 days 00:00:00Data Type of the Resultant Object: <class 'pandas._libs.tslibs.timedeltas.Timedelta'>

Also, you can createTimedelta objects in various ways, such as by passing a string, integer, or by using data offsets. Additionally, Pandas provides a top-level functionto_timedelta() to convert scalar, array, list, or series intoTimedelta type.

Creating Timedelta with a String

You can create a Timedelta object by passing a string that represents a duration.

Example

Here is the example of creating theTimedelta object using the string.

import pandas as pdprint(pd.Timedelta('2 days 2 hours 15 minutes 30 seconds'))

Itsoutput is as follows −

2 days 02:15:30

Creating Timedelta with an Integer

By passing an integer value with the unit, an argument creates aTimedelta object.

Example

This example converts an integer into theTimedelta object.

import pandas as pdprint(pd.Timedelta(6,unit='h'))

Itsoutput is as follows −

0 days 06:00:00

Creating Timedelta with Data Offsets

Data offsets such as - weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds can also be used in construction.

Example

Here is the example −

import pandas as pdprint(pd.Timedelta(days=2))

Itsoutput is as follows −

Creating Timedelta with an Integer2 days 00:00:00

Using pd.to_timedelta() Function

Thepd.to_timedelta function converts a scalar, array, list, or series from a recognizedtimedelta format or value into aTimedelta type. It will construct a Series if the input is a Series, a scalar if the input is scalar-like, or aTimedeltaIndex otherwise.

import pandas as pdprint(pd.Timedelta(days=2))

Itsoutput is as follows −

2 days 00:00:00

Timedelta Operations

You can perform arithmetic operations on Series or DataFrames containingdatetime64[ns] andtimedelta64[ns] data types.

Example − Addition Operation

Let us now create a DataFrame with Timedelta and datetime objects and perform Addition operation on it −

import pandas as pds = pd.Series(pd.date_range('2012-1-1', periods=3, freq='D'))td = pd.Series([ pd.Timedelta(days=i) for i in range(3) ])df = pd.DataFrame(dict(A = s, B = td))df['C']=df['A']+df['B']print(df)

Itsoutput is as follows −

           A      B          C0 2012-01-01 0 days 2012-01-011 2012-01-02 1 days 2012-01-032 2012-01-03 2 days 2012-01-05

Example − Subtraction Operation

Here is the example of subtracting theTimedelta values.

import pandas as pds = pd.Series(pd.date_range('2012-1-1', periods=3, freq='D'))td = pd.Series([ pd.Timedelta(days=i) for i in range(3) ])df = pd.DataFrame(dict(A = s, B = td))df['C']=df['A']+df['B']df['D']=df['C']-df['B']print(df)

Itsoutput is as follows −

           A      B          C          D0 2012-01-01 0 days 2012-01-01 2012-01-011 2012-01-02 1 days 2012-01-03 2012-01-042 2012-01-03 2 days 2012-01-05 2012-01-07

Timedelta Class Properties and Methods

TheTimedelta object provides various properties and methods that are useful in date-time manipulation.

Properties

Following are the list of attributes of theTimedelta object.

Methods

In the following table you can found the list of method of theTimedelta object.