pandas.to_timedelta#
- pandas.to_timedelta(arg, unit=None, errors='raise')[source]#
Convert argument to timedelta.
Timedeltas are absolute differences in times, expressed in difference units (e.g. days, hours, minutes, seconds). This method converts an argument from a recognized timedelta format / value into a Timedelta type.
- Parameters:
- argstr, timedelta, list-like or Series
The data to be converted to timedelta.
Changed in version 2.0: Strings with units ‘M’, ‘Y’ and ‘y’ do not represent unambiguous timedelta values and will raise an exception.
- unitstr, optional
Denotes the unit of the arg for numeric arg. Defaults to
"ns"
.Possible values:
‘W’
‘D’ / ‘days’ / ‘day’
‘hours’ / ‘hour’ / ‘hr’ / ‘h’ / ‘H’
‘m’ / ‘minute’ / ‘min’ / ‘minutes’ / ‘T’
‘s’ / ‘seconds’ / ‘sec’ / ‘second’ / ‘S’
‘ms’ / ‘milliseconds’ / ‘millisecond’ / ‘milli’ / ‘millis’ / ‘L’
‘us’ / ‘microseconds’ / ‘microsecond’ / ‘micro’ / ‘micros’ / ‘U’
‘ns’ / ‘nanoseconds’ / ‘nano’ / ‘nanos’ / ‘nanosecond’ / ‘N’
Must not be specified when arg contains strings and
errors="raise"
.Deprecated since version 2.2.0: Units ‘H’, ‘T’, ‘S’, ‘L’, ‘U’ and ‘N’ are deprecated and will be removed in a future version. Please use ‘h’, ‘min’, ‘s’, ‘ms’, ‘us’, and ‘ns’ instead of ‘H’, ‘T’, ‘S’, ‘L’, ‘U’ and ‘N’.
- errors{‘ignore’, ‘raise’, ‘coerce’}, default ‘raise’
If ‘raise’, then invalid parsing will raise an exception.
If ‘coerce’, then invalid parsing will be set as NaT.
If ‘ignore’, then invalid parsing will return the input.
- Returns:
- timedelta
If parsing succeeded. Return type depends on input:
list-like: TimedeltaIndex of timedelta64 dtype
Series: Series of timedelta64 dtype
scalar: Timedelta
See also
DataFrame.astype
Cast argument to a specified dtype.
to_datetime
Convert argument to datetime.
convert_dtypes
Convert dtypes.
Notes
If the precision is higher than nanoseconds, the precision of the duration is truncated to nanoseconds for string inputs.
Examples
Parsing a single string to a Timedelta:
>>> pd.to_timedelta('1 days 06:05:01.00003') Timedelta('1 days 06:05:01.000030') >>> pd.to_timedelta('15.5us') Timedelta('0 days 00:00:00.000015500')
Parsing a list or array of strings:
>>> pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan']) TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015500', NaT], dtype='timedelta64[ns]', freq=None)
Converting numbers by specifying the unit keyword argument:
>>> pd.to_timedelta(np.arange(5), unit='s') TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02', '0 days 00:00:03', '0 days 00:00:04'], dtype='timedelta64[ns]', freq=None) >>> pd.to_timedelta(np.arange(5), unit='d') TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'], dtype='timedelta64[ns]', freq=None)