to_timedelta(arg, unit=None, errors='raise')

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.

Notes

If the precision is higher than nanoseconds, the precision of the duration is truncated to nanoseconds for string inputs.

Parameters

arg : str, timedelta, list-like or Series

The data to be converted to timedelta.

deprecated

Strings with units 'M', 'Y' and 'y' do not represent unambiguous timedelta values and will be removed in a future version

unit : str, optional

Denotes the unit of the arg for numeric :None:None:`arg`. Defaults to "ns" .

Possible values:

• 'W'

• 'D' / 'days' / 'day'

• 'hours' / 'hour' / 'hr' / 'h'

• 'm' / 'minute' / 'min' / 'minutes' / 'T'

• 'S' / 'seconds' / 'sec' / 'second'

• 'ms' / 'milliseconds' / 'millisecond' / 'milli' / 'millis' / 'L'

• 'us' / 'microseconds' / 'microsecond' / 'micro' / 'micros' / 'U'

• 'ns' / 'nanoseconds' / 'nano' / 'nanos' / 'nanosecond' / 'N'

versionchanged

Must not be specified when :None:None:`arg` context strings and errors="raise" .

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

Convert argument to timedelta.

See Also

DataFrame.astype

Cast argument to a specified dtype.

convert_dtypes

Convert dtypes.

to_datetime

Convert argument to datetime.

Examples

Parsing a single string to a Timedelta:

This example is valid syntax, but we were not able to check execution

>>> pd.to_timedelta('1 days 06:05:01.00003')
Timedelta('1 days 06:05:01.000030')

This example is valid syntax, but we were not able to check execution

>>> pd.to_timedelta('15.5us')
Timedelta('0 days 00:00:00.000015500')

Parsing a list or array of strings:

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`unit` keyword argument:

This example is valid syntax, but we were not able to check execution

>>> 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)

This example is valid syntax, but we were not able to check execution

>>> pd.to_timedelta(np.arange(5), unit='d')
TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
               dtype='timedelta64[ns]', freq=None)

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

pandas.core.tools.numeric.to_numeric pandas.core.arrays.timedeltas.sequence_to_td64ns pandas.core.arrays.timedeltas.objects_to_td64ns pandas.core.generic.NDFrame.convert_dtypes pandas.core.generic.NDFrame.infer_objects pandas.core.tools.datetimes.to_datetime pandas.core.generic.NDFrame.astype

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/tools/timedeltas.py#27
type: <class 'function'>
Commit: