From 80e3d7e0d4081e16433166c917ee8492da2d2d19 Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Sat, 10 Mar 2018 16:09:42 -0300 Subject: [PATCH 1/8] DOC: Improve the docstring of DataFrame.transpose() Co-authored-by: Carlos Eduardo Moreira dos Santos Signed-off-by: Igor C. A. de Lima Signed-off-by: Carlos Eduardo Moreira dos Santos --- pandas/core/frame.py | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 57aba8078f3c5..7b105375f6543 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2289,7 +2289,48 @@ def memory_usage(self, index=True, deep=False): return result def transpose(self, *args, **kwargs): - """Transpose index and columns""" + """ + Transpose index and columns. + + Reflect the dataframe over its main diagonal by writing rows as columns + and vice-versa. + + Parameters + ---------- + *args + These arguments will be passed to + :func:`pandas.compat.numpy.function.validate_transpose`. + **kwargs + Keyword arguments used to create the transposed DataFrame. + + Returns + ------- + :class:`~pandas.DataFrame` + The transposed DataFrame. + + See Also + -------- + numpy.transpose : Permute the dimensions of a given array. + + Examples + -------- + >>> d = {'col1': [1, 2], 'col2': [3, 4]} + >>> df = pd.DataFrame(data=d) + >>> df + col1 col2 + 0 1 3 + 1 2 4 + + >>> df.T + 0 1 + col1 1 2 + col2 3 4 + + >>> df.transpose() + 0 1 + col1 1 2 + col2 3 4 + """ nv.validate_transpose(args, dict()) return super(DataFrame, self).transpose(1, 0, **kwargs) From f135291b1f9efad8c4b08fac5635baf02737f020 Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Sat, 10 Mar 2018 18:29:47 -0300 Subject: [PATCH 2/8] Fix return type Co-authored-by: Carlos Eduardo Moreira dos Santos Signed-off-by: Igor C. A. de Lima Signed-off-by: Carlos Eduardo Moreira dos Santos --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 7b105375f6543..7ad4ed8a584f0 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2305,7 +2305,7 @@ def transpose(self, *args, **kwargs): Returns ------- - :class:`~pandas.DataFrame` + DataFrame The transposed DataFrame. See Also From 304f3f4ef320aba37c54da5a882dc212fdf7093d Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Thu, 22 Mar 2018 01:44:14 -0300 Subject: [PATCH 3/8] DOC: State that .T is an accessor property to .transpose() Signed-off-by: Igor C. A. de Lima --- pandas/core/frame.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 7ad4ed8a584f0..c20f97bf17e66 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2293,7 +2293,8 @@ def transpose(self, *args, **kwargs): Transpose index and columns. Reflect the dataframe over its main diagonal by writing rows as columns - and vice-versa. + and vice-versa. The property :attr:`.T` is an accessor to the method + :meth:`transpose`. Parameters ---------- From 395467555a46740dac52b297b2afd7174b4634cf Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Thu, 22 Mar 2018 02:53:17 -0300 Subject: [PATCH 4/8] DOC: Add more complete example to DataFrame.transpose() --- pandas/core/frame.py | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index c20f97bf17e66..07b10db087a3a 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2315,22 +2315,49 @@ def transpose(self, *args, **kwargs): Examples -------- - >>> d = {'col1': [1, 2], 'col2': [3, 4]} - >>> df = pd.DataFrame(data=d) - >>> df + >>> d1 = {'col1': [1, 2], 'col2': [3, 4]} + >>> df1 = pd.DataFrame(data=d1) + >>> df1 col1 col2 0 1 3 1 2 4 - >>> df.T + >>> df1.T 0 1 col1 1 2 col2 3 4 - >>> df.transpose() + >>> df1.transpose() 0 1 col1 1 2 col2 3 4 + + **Non-square DataFrame and mixed data types** + + >>> d2 = {'name': ['Alice', 'Bob'], + ... 'score': [9.5, 8], + ... 'employed': [False, True], + ... 'kids': [0, 0]} + + >>> df2 = pd.DataFrame(data=d2) + >>> df2 + name score employed kids + 0 Alice 9.5 False 0 + 1 Bob 8.0 True 0 + + >>> df2.T + 0 1 + name Alice Bob + score 9.5 8 + employed False True + kids 0 0 + + >>> df2.transpose() + 0 1 + name Alice Bob + score 9.5 8 + employed False True + kids 0 0 """ nv.validate_transpose(args, dict()) return super(DataFrame, self).transpose(1, 0, **kwargs) From 0c9dfd52fb2ceeaa8f86e9b16ed7c154cf717e13 Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Thu, 22 Mar 2018 23:49:05 -0300 Subject: [PATCH 5/8] DOC: Add compatibility docstring to args/kwargs Signed-off-by: Igor C. A. de Lima --- pandas/core/frame.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 07b10db087a3a..ac3b42882827d 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2298,11 +2298,9 @@ def transpose(self, *args, **kwargs): Parameters ---------- - *args - These arguments will be passed to - :func:`pandas.compat.numpy.function.validate_transpose`. - **kwargs - Keyword arguments used to create the transposed DataFrame. + *args, **kwargs + Additional keywords have no effect but might be accepted for + compatibility with numpy. Returns ------- From 1b414c31b8e30f728fa1847ec62c2e9c6471e067 Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Thu, 22 Mar 2018 23:52:42 -0300 Subject: [PATCH 6/8] DOC: Add docstring to the copy kwarg --- pandas/core/frame.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index ac3b42882827d..607a37ab4c570 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2298,6 +2298,8 @@ def transpose(self, *args, **kwargs): Parameters ---------- + copy : bool, default False + Whether to make a copy of the underlying data. *args, **kwargs Additional keywords have no effect but might be accepted for compatibility with numpy. From 7deea54d4674bbb1d0752530cca5fce7a54073d8 Mon Sep 17 00:00:00 2001 From: "Igor C. A. de Lima" Date: Fri, 23 Mar 2018 01:07:55 -0300 Subject: [PATCH 7/8] DOC: Add note and example about how transposing can change dtype Signed-off-by: Igor C. A. de Lima --- pandas/core/frame.py | 50 +++++++++++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 607a37ab4c570..298e0d82934f4 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2313,8 +2313,15 @@ def transpose(self, *args, **kwargs): -------- numpy.transpose : Permute the dimensions of a given array. + Notes + ----- + Transposing a DataFrame with mixed dtypes will result in a homogeneous + DataFrame with the `object` dtype. + Examples -------- + **Square DataFrame with homogeneous dtype** + >>> d1 = {'col1': [1, 2], 'col2': [3, 4]} >>> df1 = pd.DataFrame(data=d1) >>> df1 @@ -2322,42 +2329,57 @@ def transpose(self, *args, **kwargs): 0 1 3 1 2 4 - >>> df1.T + >>> df1_transposed = df1.T # or df1.transpose() + >>> df1_transposed 0 1 col1 1 2 col2 3 4 - >>> df1.transpose() - 0 1 - col1 1 2 - col2 3 4 + When the dtype is homogeneous in the original DataFrame, we get a + transposed DataFrame with the same dtype: + + >>> df1.dtypes + col1 int64 + col2 int64 + dtype: object + >>> df1_transposed.dtypes + 0 int64 + 1 int64 + dtype: object - **Non-square DataFrame and mixed data types** + **Non-square DataFrame with mixed dtypes** >>> d2 = {'name': ['Alice', 'Bob'], ... 'score': [9.5, 8], ... 'employed': [False, True], ... 'kids': [0, 0]} - >>> df2 = pd.DataFrame(data=d2) >>> df2 name score employed kids 0 Alice 9.5 False 0 1 Bob 8.0 True 0 - >>> df2.T + >>> df2_transposed = df2.T # or df2.transpose() + >>> df2_transposed 0 1 name Alice Bob score 9.5 8 employed False True kids 0 0 - >>> df2.transpose() - 0 1 - name Alice Bob - score 9.5 8 - employed False True - kids 0 0 + When the DataFrame has mixed dtypes, we get a transposed DataFrame with + the `object` dtype: + + >>> df2.dtypes + name object + score float64 + employed bool + kids int64 + dtype: object + >>> df2_transposed.dtypes + 0 object + 1 object + dtype: object """ nv.validate_transpose(args, dict()) return super(DataFrame, self).transpose(1, 0, **kwargs) From ead247c4c2f2083d001f387af780ebd66938fbee Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 23 Mar 2018 09:31:56 +0100 Subject: [PATCH 8/8] clarification of copy --- pandas/core/frame.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 298e0d82934f4..8ff2b6c85eeed 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -2292,14 +2292,15 @@ def transpose(self, *args, **kwargs): """ Transpose index and columns. - Reflect the dataframe over its main diagonal by writing rows as columns + Reflect the DataFrame over its main diagonal by writing rows as columns and vice-versa. The property :attr:`.T` is an accessor to the method :meth:`transpose`. Parameters ---------- copy : bool, default False - Whether to make a copy of the underlying data. + If True, the underlying data is copied. Otherwise (default), no + copy is made if possible. *args, **kwargs Additional keywords have no effect but might be accepted for compatibility with numpy. @@ -2316,7 +2317,8 @@ def transpose(self, *args, **kwargs): Notes ----- Transposing a DataFrame with mixed dtypes will result in a homogeneous - DataFrame with the `object` dtype. + DataFrame with the `object` dtype. In such a case, a copy of the data + is always made. Examples --------