From 641e51c743e3ce3a0b6563437296ef71580c71ff Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sat, 20 Oct 2018 22:39:31 +0100 Subject: [PATCH 1/8] Modified timedelta docstring to include M and Y units and examples --- pandas/core/tools/timedeltas.py | 60 +++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 14 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index db93820c6942f..f083f5e463c3a 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -16,32 +16,41 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): """ - Convert argument to timedelta + Convert argument to timedelta. + + Timedeltas are differences in times, expressed in difference units, + for example, years, momths, days, hours, minutes, seconds. + They can be both positive and negative. This method can create Timedelta + objects from pandas objects. Parameters ---------- arg : string, timedelta, list, tuple, 1-d array, or Series - unit : str, optional - Denote the unit of the input, if input is an integer. Default 'ns'. + unit : str, default 'ns' Possible values: {'Y', 'M', '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'} - box : boolean, default True - - If True returns a Timedelta/TimedeltaIndex of the results - - if False returns a np.timedelta64 or ndarray of values of dtype - timedelta64[ns] + box : Boolean, default True + If True returns a Timedelta/TimedeltaIndex of the results. + if False returns a np.timedelta64 or ndarray of values of dtype + timedelta64[ns]. 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 + 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 ------- ret : timedelta64/arrays of timedelta64 if parsing succeeded + See also + -------- + DataFrame.astype : Cast argument to a specified dtype. + to_datetime : Convert argument to datetime. + Examples -------- @@ -68,10 +77,33 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'], dtype='timedelta64[ns]', freq=None) - See Also - -------- - pandas.DataFrame.astype : Cast argument to a specified dtype. - pandas.to_datetime : Convert argument to datetime. + For `M` and `Y` units, `1M = 30D` and 1Y = 365D: + + >>> pd.to_timedelta(np.arange(5), unit='M') + TimedeltaIndex([ '0 days 00:00:00', '30 days 10:29:06', + '60 days 20:58:12', '91 days 07:27:18', + '121 days 17:56:24'], + dtype='timedelta64[ns]', freq=None) + >>> pd.to_timedelta(np.arange(5), unit='Y') + TimedeltaIndex([ '0 days 00:00:00', '365 days 05:49:12', + '730 days 11:38:24', '1095 days 17:27:36', + '1460 days 23:16:48'], + dtype='timedelta64[ns]', freq=None) + + Add new column of dates from existing dates in a `DataFrame` + using `timedelta` + + >>> Dates = pd.to_datetime(['26/10/2018','28/10/2018', '2/11/2018']) + >>> df = pd.DataFrame({'Start': Dates,'Days':[5, 10, 5]}) + >>> df['End'] = df['Start'] + pd.to_timedelta(df['Days'], unit='d') + >>> df + Start Days End + 0 2018-10-26 5 2018-10-31 + 1 2018-10-28 10 2018-11-07 + 2 2018-02-11 5 2018-02-16 + + See also + """ unit = parse_timedelta_unit(unit) From 2e6a20bd79eccd7480edd21a55426547ce6bb8ce Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sun, 21 Oct 2018 01:00:29 +0100 Subject: [PATCH 2/8] Corrected summary --- pandas/core/tools/timedeltas.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index f083f5e463c3a..5f60cb67ebe9c 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -18,10 +18,9 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): """ Convert argument to timedelta. - Timedeltas are differences in times, expressed in difference units, - for example, years, momths, days, hours, minutes, seconds. - They can be both positive and negative. This method can create Timedelta - objects from pandas objects. + Timedeltas are 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 ---------- From 5e904418f574b9cc51e24ec410d89172f75a8db2 Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sun, 21 Oct 2018 13:24:17 +0100 Subject: [PATCH 3/8] Added box example and removed M and Y unit references --- pandas/core/tools/timedeltas.py | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 5f60cb67ebe9c..396806bd1fa9e 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -18,8 +18,8 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): """ Convert argument to timedelta. - Timedeltas are differences in times, expressed in difference units - e.g. days, hours, minutes, seconds. This method converts an argument + 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 @@ -76,21 +76,13 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'], dtype='timedelta64[ns]', freq=None) - For `M` and `Y` units, `1M = 30D` and 1Y = 365D: + Returning an ndarray by using the 'box' keyword argument: - >>> pd.to_timedelta(np.arange(5), unit='M') - TimedeltaIndex([ '0 days 00:00:00', '30 days 10:29:06', - '60 days 20:58:12', '91 days 07:27:18', - '121 days 17:56:24'], - dtype='timedelta64[ns]', freq=None) - >>> pd.to_timedelta(np.arange(5), unit='Y') - TimedeltaIndex([ '0 days 00:00:00', '365 days 05:49:12', - '730 days 11:38:24', '1095 days 17:27:36', - '1460 days 23:16:48'], - dtype='timedelta64[ns]', freq=None) + >>> pd.to_timedelta(np.arange(5), box=False) + array([0, 1, 2, 3, 4], dtype='timedelta64[ns]') Add new column of dates from existing dates in a `DataFrame` - using `timedelta` + using `timedelta`: >>> Dates = pd.to_datetime(['26/10/2018','28/10/2018', '2/11/2018']) >>> df = pd.DataFrame({'Start': Dates,'Days':[5, 10, 5]}) From ed3a71103b00f17eafc291a9105e4c901dfb374b Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Wed, 24 Oct 2018 22:23:38 +0100 Subject: [PATCH 4/8] Removed last example --- pandas/core/tools/timedeltas.py | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 396806bd1fa9e..51f680904b788 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -81,18 +81,6 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): >>> pd.to_timedelta(np.arange(5), box=False) array([0, 1, 2, 3, 4], dtype='timedelta64[ns]') - Add new column of dates from existing dates in a `DataFrame` - using `timedelta`: - - >>> Dates = pd.to_datetime(['26/10/2018','28/10/2018', '2/11/2018']) - >>> df = pd.DataFrame({'Start': Dates,'Days':[5, 10, 5]}) - >>> df['End'] = df['Start'] + pd.to_timedelta(df['Days'], unit='d') - >>> df - Start Days End - 0 2018-10-26 5 2018-10-31 - 1 2018-10-28 10 2018-11-07 - 2 2018-02-11 5 2018-02-16 - See also """ From 8b580bb731360d899a98084d81eefb5d8789061a Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sat, 27 Oct 2018 00:20:54 +0100 Subject: [PATCH 5/8] improved styling --- pandas/core/tools/timedeltas.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 51f680904b788..6b64840c1e2e8 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -37,9 +37,9 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): if False returns a np.timedelta64 or ndarray of values of dtype timedelta64[ns]. 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. + - 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 ------- @@ -80,9 +80,12 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): >>> pd.to_timedelta(np.arange(5), box=False) array([0, 1, 2, 3, 4], dtype='timedelta64[ns]') +<<<<<<< HEAD See also +======= +>>>>>>> improved styling """ unit = parse_timedelta_unit(unit) From f85f0f61303ad1b86495f18b2ef19f26abf1a8ba Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sat, 27 Oct 2018 11:33:31 +0100 Subject: [PATCH 6/8] styling/linting --- pandas/core/tools/timedeltas.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 6b64840c1e2e8..97a18748a708b 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -19,7 +19,7 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): 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 + units e.g. (days, hours, minutes, seconds). This method converts an argument from a recognized timedelta format / value into a Timedelta type. Parameters @@ -43,7 +43,8 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): Returns ------- - ret : timedelta64/arrays of timedelta64 if parsing succeeded + timedelta64 or numpy.array of timedelta64 + Output type returned if parsing succeeded. See also -------- From 737ac0b4e93985e1546775d2ceee14f1f2ecea79 Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Sat, 27 Oct 2018 14:50:07 +0100 Subject: [PATCH 7/8] Final fixes and Fixed merge conflict/included recent upstream changes --- pandas/core/tools/timedeltas.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 97a18748a708b..7fcefddee5b93 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -19,22 +19,24 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): 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. + units (e.g. days, hours, minutes, seconds). This method converts + an argument from a recognized timedelta format / value into + a Timedelta type. Parameters ---------- - arg : string, timedelta, list, tuple, 1-d array, or Series + arg : str, timedelta, list-like or Series + The argument which needs to be converted to timedelta. unit : str, default 'ns' - Possible values: - {'Y', 'M', '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'} - box : Boolean, default True + ('Y', 'M', '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'). + box : bool, default True If True returns a Timedelta/TimedeltaIndex of the results. - if False returns a np.timedelta64 or ndarray of values of dtype + If False returns a np.timedelta64 or ndarray of values of dtype timedelta64[ns]. errors : {'ignore', 'raise', 'coerce'}, default 'raise' - If 'raise', then invalid parsing will raise an exception. From a67649a239eb3b5e7b6ec84209f2006d4eed22af Mon Sep 17 00:00:00 2001 From: Ryan Nazareth Date: Tue, 20 Nov 2018 00:11:07 +0000 Subject: [PATCH 8/8] Additional small fixes --- pandas/core/tools/timedeltas.py | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/pandas/core/tools/timedeltas.py b/pandas/core/tools/timedeltas.py index 7fcefddee5b93..b6ceabb759954 100644 --- a/pandas/core/tools/timedeltas.py +++ b/pandas/core/tools/timedeltas.py @@ -26,18 +26,19 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): Parameters ---------- arg : str, timedelta, list-like or Series - The argument which needs to be converted to timedelta. + The data to be converted to timedelta. unit : str, default 'ns' - ('Y', 'M', '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'). + Denotes the unit of the arg. Possible values: + ('Y', 'M', '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'). box : bool, default True - If True returns a Timedelta/TimedeltaIndex of the results. - If False returns a np.timedelta64 or ndarray of values of dtype - timedelta64[ns]. + - If True returns a Timedelta/TimedeltaIndex of the results. + - If False returns a numpy.timedelta64 or numpy.darray of + values of dtype timedelta64[ns]. 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. @@ -83,12 +84,6 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'): >>> pd.to_timedelta(np.arange(5), box=False) array([0, 1, 2, 3, 4], dtype='timedelta64[ns]') -<<<<<<< HEAD - - See also - -======= ->>>>>>> improved styling """ unit = parse_timedelta_unit(unit)