From a41eb2f9cdeb057f4a2e21617825fba5988fc104 Mon Sep 17 00:00:00 2001 From: tp Date: Tue, 8 Aug 2017 22:00:15 +0100 Subject: [PATCH 1/5] Add examples to NDFrame.astype docs --- pandas/core/generic.py | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2d52eed81d22b..04395c92fd317 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3610,8 +3610,9 @@ def blocks(self): mapping={True: 'raise', False: 'ignore'}) def astype(self, dtype, copy=True, errors='raise', **kwargs): """ - Cast object to input numpy.dtype - Return a copy when copy = True (be really careful with this!) + Cast object to input numpy.dtype. + + Return a copy when ``copy=True`` (be really careful with this!). Parameters ---------- @@ -3636,6 +3637,34 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): Returns ------- casted : type of caller + + Examples + -------- + >>> ser = pd.Series([1, 2], dtype='int32') + >>> ser + 0 1 + 1 2 + dtype: int32 + >>> ser.astype('int64') + 0 1 + 1 2 + dtype: int64 + + Convert to pd.Categorial: + + >>> ser.astype('category') + 0 1 + 1 2 + dtype: category + Categories (2, int64): [1, 2] + + Convert to ordered pd.Categorial with custom ordering: + + >>> ser.astype('category', ordered=True, categories=[2, 1]) + 0 1 + 1 2 + dtype: category + Categories (2, int64): [2 < 1] """ if is_dict_like(dtype): if self.ndim == 1: # i.e. Series From d9b941108968977e94878a4e72ba4e63eda8324a Mon Sep 17 00:00:00 2001 From: tp Date: Tue, 8 Aug 2017 22:47:56 +0100 Subject: [PATCH 2/5] Polishing NDFrame.astype doc string --- pandas/core/generic.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 04395c92fd317..b33d02865a72f 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3610,9 +3610,7 @@ def blocks(self): mapping={True: 'raise', False: 'ignore'}) def astype(self, dtype, copy=True, errors='raise', **kwargs): """ - Cast object to input numpy.dtype. - - Return a copy when ``copy=True`` (be really careful with this!). + Cast a pandas object to new dtype ``dtype``. Parameters ---------- @@ -3621,6 +3619,8 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): the same type. Alternatively, use {col: dtype, ...}, where col is a column label and dtype is a numpy.dtype or Python type to cast one or more of the DataFrame's columns to column-specific types. + copy : bool, default True. + Return a copy when ``copy=True`` (be really careful with this!). errors : {'raise', 'ignore'}, default 'raise'. Control raising of exceptions on invalid data for provided dtype. From b36692580c5c26489d774789268ae93c04400ea0 Mon Sep 17 00:00:00 2001 From: tp Date: Tue, 8 Aug 2017 23:53:29 +0100 Subject: [PATCH 3/5] NDFrame.astype doc string, adding part with copy=False --- pandas/core/generic.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b33d02865a72f..bb47caef9c5cd 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3665,6 +3665,18 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): 1 2 dtype: category Categories (2, int64): [2 < 1] + + Note that using ``copy=False`` and changing data on a new + pandas object may propagate changes upwards: + + >>> cat1 = pd.Series([1,2], dtype='category') + >>> cat2 = cat1.astype('category', copy=False) + >>> cat2[0] = 2 + >>> cat1 # note that cat1[0] is changed too + 0 2 + 1 2 + dtype: category + Categories (2, int64): [1, 2] """ if is_dict_like(dtype): if self.ndim == 1: # i.e. Series From 43e27608e3754a2289b4d861fbf93aedba4b3799 Mon Sep 17 00:00:00 2001 From: tp Date: Wed, 9 Aug 2017 01:27:13 +0100 Subject: [PATCH 4/5] NDFrame.astype doc string, adding 'See also' part --- pandas/core/generic.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index bb47caef9c5cd..c60d78303d484 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3677,6 +3677,10 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): 1 2 dtype: category Categories (2, int64): [1, 2] + + See also + -------- + numpy.ndarray.astype : Cast a numpy array to a specified type. """ if is_dict_like(dtype): if self.ndim == 1: # i.e. Series From c90160ad67ac82cb1c4f6952be7ca333520b5b3a Mon Sep 17 00:00:00 2001 From: tp Date: Wed, 9 Aug 2017 10:33:47 +0100 Subject: [PATCH 5/5] NDFrame.astype doc string, some further cleanup --- pandas/core/generic.py | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index c60d78303d484..bd3297f66a469 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3610,7 +3610,7 @@ def blocks(self): mapping={True: 'raise', False: 'ignore'}) def astype(self, dtype, copy=True, errors='raise', **kwargs): """ - Cast a pandas object to new dtype ``dtype``. + Cast a pandas object to a specified dtype ``dtype``. Parameters ---------- @@ -3620,7 +3620,9 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): column label and dtype is a numpy.dtype or Python type to cast one or more of the DataFrame's columns to column-specific types. copy : bool, default True. - Return a copy when ``copy=True`` (be really careful with this!). + Return a copy when ``copy=True`` (be very careful setting + ``copy=False`` as changes to values then may propagate to other + pandas objects). errors : {'raise', 'ignore'}, default 'raise'. Control raising of exceptions on invalid data for provided dtype. @@ -3650,7 +3652,7 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): 1 2 dtype: int64 - Convert to pd.Categorial: + Convert to categorical type: >>> ser.astype('category') 0 1 @@ -3658,7 +3660,7 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): dtype: category Categories (2, int64): [1, 2] - Convert to ordered pd.Categorial with custom ordering: + Convert to ordered categorical type with custom ordering: >>> ser.astype('category', ordered=True, categories=[2, 1]) 0 1 @@ -3667,16 +3669,15 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): Categories (2, int64): [2 < 1] Note that using ``copy=False`` and changing data on a new - pandas object may propagate changes upwards: - - >>> cat1 = pd.Series([1,2], dtype='category') - >>> cat2 = cat1.astype('category', copy=False) - >>> cat2[0] = 2 - >>> cat1 # note that cat1[0] is changed too - 0 2 - 1 2 - dtype: category - Categories (2, int64): [1, 2] + pandas object may propagate changes: + + >>> s1 = pd.Series([1,2]) + >>> s2 = s1.astype('int', copy=False) + >>> s2[0] = 10 + >>> s1 # note that s1[0] has changed too + 0 10 + 1 2 + dtype: int64 See also --------