From d6ad5b14be52c2b2c9f1ac7906dd1e8fddff8365 Mon Sep 17 00:00:00 2001 From: Victor Villas Date: Sun, 11 Mar 2018 01:12:44 +0000 Subject: [PATCH 1/3] DOC: update NDFrame.squeeze docstring --- pandas/core/generic.py | 90 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 86 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 397726181d2fb..839b9ea8e9985 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -699,18 +699,100 @@ def pop(self, item): def squeeze(self, axis=None): """ - Squeeze length 1 dimensions. + Squeeze 1 dimensional axis objects into scalars. + + If the given axis consists of one dimensional objects, they are turned + into scalars. In case no axis is specified, all axes are subject to + squeezing. In any case, objects in axes that can't be squeezed are + left unchanged. Parameters ---------- - axis : None, integer or string axis name, optional - The axis to squeeze if 1-sized. + axis : integer or string, optional + A specific axis to squeeze. .. versionadded:: 0.20.0 Returns ------- - scalar if 1-sized, else original object + DataFrame, Series or scalar + The projection after squeezing axis. + + See Also + -------- + Series.iloc : Integer-location based indexing for selecting scalars + DataFrame.iloc : Integer-location based indexing for selecting Series + + Examples + -------- + >>> primes = pd.Series([2, 3, 5, 7]) + + Slicing might produce a Series with a single value: + + >>> even_primes = primes[primes % 2 == 0] + >>> even_primes + 0 2 + dtype: int64 + >>> even_primes.squeeze() + 2 + + Squeezing objects with more than 1 dimension does nothing: + + >>> odd_primes = primes[primes % 2 == 1] + >>> odd_primes + 1 3 + 2 5 + 3 7 + dtype: int64 + >>> odd_primes.squeeze() + 1 3 + 2 5 + 3 7 + dtype: int64 + + Squeezing is even more effective when used with DataFrames. + + >>> df = pd.DataFrame([[1,2], [3, 4]], columns=['a', 'b']) + >>> df + a b + 0 1 2 + 1 3 4 + + Slicing a single column will produce a DataFrame with one of the + axis having only 1 dimension: + + >>> df_a = df[['a']] + >>> df_a + a + 0 1 + 1 3 + + Objects along the column are 1 dimensional, so they can be squeezed + into scalars: + + >>> df_a.squeeze('columns') + 0 1 + 1 3 + Name: a, dtype: int64 + + Slicing a single row from a single column will produce a single + scalar DataFrame: + + >>> df_0a = df[['a']].iloc[[0]] + >>> df_0a + a + 0 1 + + Squeezing along the rows produces a single scalar Series: + + >>> df_0a.squeeze('rows') + a 1 + Name: 0, dtype: int64 + + Squeezing all axes wil project directly into a scalar: + + >>> df_0a.squeeze() + 1 """ axis = (self._AXIS_NAMES if axis is None else (self._get_axis_number(axis),)) From c9069eebc961411a99cf809fe9dd4abb1c5f8a43 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 14 Mar 2018 14:39:06 -0500 Subject: [PATCH 2/3] Updated --- pandas/core/generic.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 839b9ea8e9985..06a1d3611cbd8 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -701,15 +701,20 @@ def squeeze(self, axis=None): """ Squeeze 1 dimensional axis objects into scalars. - If the given axis consists of one dimensional objects, they are turned - into scalars. In case no axis is specified, all axes are subject to - squeezing. In any case, objects in axes that can't be squeezed are - left unchanged. + Series or DataFrames with a single element are squeezed to a scalar. + DataFrames with a single column or a single row are squeezed to a + Series. Otherwise the object is unchanged. + + This method is most useful when you don't know if your + object is a Series or DataFrame, but you do know it has just a single + column. In that case you can safely call `squeeze` to ensure you have a + Series. Parameters ---------- axis : integer or string, optional - A specific axis to squeeze. + A specific axis to squeeze. By default, all length-1 axes are + squeezed. .. versionadded:: 0.20.0 From d512d93ddb46cf6bc944aa97b892dc6e7faf030c Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 14 Mar 2018 14:49:03 -0500 Subject: [PATCH 3/3] Updates [ci skip] [ci skip] --- pandas/core/generic.py | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 06a1d3611cbd8..7a5c3989089cc 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -712,7 +712,7 @@ def squeeze(self, axis=None): Parameters ---------- - axis : integer or string, optional + axis : axis : {0 or ‘index’, 1 or ‘columns’, None}, default None A specific axis to squeeze. By default, all length-1 axes are squeezed. @@ -720,13 +720,15 @@ def squeeze(self, axis=None): Returns ------- - DataFrame, Series or scalar - The projection after squeezing axis. + DataFrame, Series, or scalar + The projection after squeezing `axis` or all the axes. See Also -------- Series.iloc : Integer-location based indexing for selecting scalars DataFrame.iloc : Integer-location based indexing for selecting Series + Series.to_frame : Inverse of DataFrame.squeeze for a + single-column DataFrame. Examples -------- @@ -738,10 +740,11 @@ def squeeze(self, axis=None): >>> even_primes 0 2 dtype: int64 + >>> even_primes.squeeze() 2 - Squeezing objects with more than 1 dimension does nothing: + Squeezing objects with more than one value in every axis does nothing: >>> odd_primes = primes[primes % 2 == 1] >>> odd_primes @@ -749,6 +752,7 @@ def squeeze(self, axis=None): 2 5 3 7 dtype: int64 + >>> odd_primes.squeeze() 1 3 2 5 @@ -757,14 +761,14 @@ def squeeze(self, axis=None): Squeezing is even more effective when used with DataFrames. - >>> df = pd.DataFrame([[1,2], [3, 4]], columns=['a', 'b']) + >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['a', 'b']) >>> df a b 0 1 2 1 3 4 - Slicing a single column will produce a DataFrame with one of the - axis having only 1 dimension: + Slicing a single column will produce a DataFrame with the columns + having only one value: >>> df_a = df[['a']] >>> df_a @@ -772,8 +776,7 @@ def squeeze(self, axis=None): 0 1 1 3 - Objects along the column are 1 dimensional, so they can be squeezed - into scalars: + So the columns can be squeezed down, resulting in a Series: >>> df_a.squeeze('columns') 0 1 @@ -783,12 +786,12 @@ def squeeze(self, axis=None): Slicing a single row from a single column will produce a single scalar DataFrame: - >>> df_0a = df[['a']].iloc[[0]] + >>> df_0a = df.loc[df.index < 1, ['a']] >>> df_0a a 0 1 - Squeezing along the rows produces a single scalar Series: + Squeezing the rows produces a single scalar Series: >>> df_0a.squeeze('rows') a 1