From 68657f42e786036a7939c07fb5b908d01743ec4c Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 13:23:57 -0500 Subject: [PATCH 01/10] improved docs for pandas.Dataframe.all --- pandas/core/generic.py | 59 +++++++++++++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..168f0802f83da 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7523,11 +7523,10 @@ def _add_numeric_operations(cls): cls.any = _make_logical_function( cls, 'any', name, name2, axis_descr, 'Return whether any element is True over requested axis', - nanops.nanany) + nanops.nanany, '', '') cls.all = _make_logical_function( - cls, 'all', name, name2, axis_descr, - 'Return whether all elements are True over requested axis', - nanops.nanall) + cls, 'all', name, name2, axis_descr, _all_doc, + nanops.nanall, _all_examples, _all_see_also) @Substitution(outname='mad', desc="Return the mean absolute deviation of the values " @@ -7784,7 +7783,6 @@ def _doc_parms(cls): %(outname)s : %(name1)s or %(name2)s (if level specified)\n""" _bool_doc = """ - %(desc)s Parameters @@ -7792,17 +7790,58 @@ def _doc_parms(cls): axis : %(axis_descr)s skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result - will be NA + will be NA. level : int or level name, default None If the axis is a MultiIndex (hierarchical), count along a - particular level, collapsing into a %(name1)s + particular level, collapsing into a %(name1)s. bool_only : boolean, default None Include only boolean columns. If None, will attempt to use everything, then use only boolean data. Not implemented for Series. Returns ------- -%(outname)s : %(name1)s or %(name2)s (if level specified)\n""" +%(outname)s : %(name1)s or %(name2)s (if level specified) + +%(examples)s +%(see_also)s""" + +_all_doc = """\ +Return whether all elements are True over requested axis. + +Returns True if all elements along a dataframe +axis are non-zero, not-empty or not-False. +Also note that a series consisting of different data +types returns the first occurence of the non-zero, not-empty +or not-False element.""" + +_all_examples = """\ +Examples +-------- +First create a pandas dataframe:: + >>> d = {'col1': [True, True], 'col2': [True, False]} + >>> df = pd.DataFrame(data=d) + >>> df + col1 col2 + 0 True True + 1 True False +Default behaviour checks if column-wise values all return True + >>> df.all() + col1 True + col2 False + dtype: bool + +Adding axis=1 will check row-wise values + >>> df.all(axis=1) + 0 True + 1 False + dtype: bool +""" + +_all_see_also = """\ +See also +-------- +pandas.DataFrame.any : Checks if one (or more) items return True +""" _cnum_doc = """ @@ -7985,9 +8024,9 @@ def cum_func(self, axis=None, skipna=True, *args, **kwargs): return set_function_name(cum_func, name, cls) -def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f): +def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f, examples, see_also): @Substitution(outname=name, desc=desc, name1=name1, name2=name2, - axis_descr=axis_descr) + axis_descr=axis_descr, examples=examples, see_also=see_also) @Appender(_bool_doc) def logical_func(self, axis=None, bool_only=None, skipna=None, level=None, **kwargs): From 2088c9f6fad5b5c1949418bb97e246e58f3c3957 Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 13:34:46 -0500 Subject: [PATCH 02/10] fixed spacing in examples text --- pandas/core/generic.py | 66 +++++------------------------------------- 1 file changed, 7 insertions(+), 59 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 565db371347bb..c841a12c9e417 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3669,12 +3669,12 @@ def tail(self, n=5): Returns ------- - type of caller - The last `n` rows of the caller object. + obj_tail : type of caller + The last n rows of the caller object. See Also -------- - pandas.DataFrame.head : The first `n` rows of the caller object. + pandas.DataFrame.head Examples -------- @@ -4232,55 +4232,7 @@ def as_matrix(self, columns=None): @property def values(self): - """ - Return a Numpy representation of the DataFrame. - - Only the values in the DataFrame will be returned, the axes labels - will be removed. - - Returns - ------- - numpy.ndarray - The values of the DataFrame. - - Examples - -------- - A DataFrame where all columns are the same type (e.g., int64) results - in an array of the same type. - - >>> df = pd.DataFrame({'age': [ 3, 29], - ... 'height': [94, 170], - ... 'weight': [31, 115]}) - >>> df - age height weight - 0 3 94 31 - 1 29 170 115 - >>> df.dtypes - age int64 - height int64 - weight int64 - dtype: object - >>> df.values - array([[ 3, 94, 31], - [ 29, 170, 115]], dtype=int64) - - A DataFrame with mixed type columns(e.g., str/object, int64, float32) - results in an ndarray of the broadest type that accommodates these - mixed types (e.g., object). - - >>> df2 = pd.DataFrame([('parrot', 24.0, 'second'), - ... ('lion', 80.5, 1), - ... ('monkey', np.nan, None)], - ... columns=('name', 'max_speed', 'rank')) - >>> df2.dtypes - name object - max_speed float64 - rank object - dtype: object - >>> df2.values - array([['parrot', 24.0, 'second'], - ['lion', 80.5, 1], - ['monkey', nan, None]], dtype=object) + """Numpy representation of NDFrame Notes ----- @@ -4291,13 +4243,8 @@ def values(self): e.g. If the dtypes are float16 and float32, dtype will be upcast to float32. If dtypes are int32 and uint8, dtype will be upcast to - int32. By :func:`numpy.find_common_type` convention, mixing int64 - and uint64 will result in a float64 dtype. - - See Also - -------- - pandas.DataFrame.index : Retrievie the index labels - pandas.DataFrame.columns : Retrieving the column names + int32. By numpy.find_common_type convention, mixing int64 and uint64 + will result in a flot64 dtype. """ self._consolidate_inplace() return self._data.as_array(transpose=self._AXIS_REVERSED) @@ -7877,6 +7824,7 @@ def _doc_parms(cls): col1 col2 0 True True 1 True False + Default behaviour checks if column-wise values all return True >>> df.all() col1 True From 75e370e70e57b2e0da72fd2f97d5b72770386621 Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 13:37:37 -0500 Subject: [PATCH 03/10] passes pep8 styling --- pandas/core/generic.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index c841a12c9e417..678f27962faf4 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7810,7 +7810,7 @@ def _doc_parms(cls): Returns True if all elements along a dataframe axis are non-zero, not-empty or not-False. -Also note that a series consisting of different data +Also note that a series consisting of different data types returns the first occurence of the non-zero, not-empty or not-False element.""" @@ -7824,7 +7824,7 @@ def _doc_parms(cls): col1 col2 0 True True 1 True False - + Default behaviour checks if column-wise values all return True >>> df.all() col1 True @@ -8025,7 +8025,8 @@ def cum_func(self, axis=None, skipna=True, *args, **kwargs): return set_function_name(cum_func, name, cls) -def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f, examples, see_also): +def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f, + examples, see_also): @Substitution(outname=name, desc=desc, name1=name1, name2=name2, axis_descr=axis_descr, examples=examples, see_also=see_also) @Appender(_bool_doc) From adacc3498b418457b7d45686e76b01175b989cee Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 13:42:55 -0500 Subject: [PATCH 04/10] added axis description --- pandas/core/generic.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 678f27962faf4..41722e66c33d3 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7787,7 +7787,9 @@ def _doc_parms(cls): Parameters ---------- -axis : %(axis_descr)s +axis : int, default 0 + Select the axis that you would like to analyze. For column-wise + (axis=0), for row-wise (axis=1). skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result will be NA. From ce5a115d51a40207b7e47d14dbf6fc3e70892a1c Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 14:00:26 -0500 Subject: [PATCH 05/10] readded the axis paramerte reference and added a kwargs --- pandas/core/generic.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 41722e66c33d3..61e725fea23ed 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7787,9 +7787,7 @@ def _doc_parms(cls): Parameters ---------- -axis : int, default 0 - Select the axis that you would like to analyze. For column-wise - (axis=0), for row-wise (axis=1). +axis : %(axis_descr)s skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result will be NA. @@ -7799,6 +7797,9 @@ def _doc_parms(cls): bool_only : boolean, default None Include only boolean columns. If None, will attempt to use everything, then use only boolean data. Not implemented for Series. +**kwargs : any, default None + Additional keywords have no fect but might be accepted for + compatibility with numpy. Returns ------- From 3347753e6b79e209bf7565b9a45ead2be73acd40 Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 16:32:33 -0500 Subject: [PATCH 06/10] made changes requested by core developers --- pandas/core/generic.py | 62 ++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index bee2f6a8469fe..2b8a298db0198 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7802,7 +7802,7 @@ def _doc_parms(cls): Include only boolean columns. If None, will attempt to use everything, then use only boolean data. Not implemented for Series. **kwargs : any, default None - Additional keywords have no fect but might be accepted for + Additional keywords have no affect but might be accepted for compatibility with numpy. Returns @@ -7813,42 +7813,50 @@ def _doc_parms(cls): %(see_also)s""" _all_doc = """\ -Return whether all elements are True over requested axis. +Return whether all elements are True over series or dataframe axis. -Returns True if all elements along a dataframe -axis are non-zero, not-empty or not-False. -Also note that a series consisting of different data -types returns the first occurence of the non-zero, not-empty -or not-False element.""" +Returns True if all elements within a series or along a dataframe +axis or are non-zero, not-empty or not-False.""" _all_examples = """\ Examples -------- -First create a pandas dataframe:: - >>> d = {'col1': [True, True], 'col2': [True, False]} - >>> df = pd.DataFrame(data=d) - >>> df - col1 col2 - 0 True True - 1 True False - -Default behaviour checks if column-wise values all return True - >>> df.all() - col1 True - col2 False - dtype: bool - -Adding axis=1 will check row-wise values - >>> df.all(axis=1) - 0 True - 1 False - dtype: bool +Series + +>>> pd.Series([True, True]).all() +True +>>> pd.Series([True, False]).all() +False + +Dataframes + +Create a dataframe from a dictionary. + +>>> df = pd.DataFrame({'col1': [True, True], 'col2': [True, False]}) +>>> df + col1 col2 +0 True True +1 True False + +Default behaviour checks if column-wise values all return True. + +>>> df.all() +col1 True +col2 False +dtype: bool + +Adding axis=1 argument will check if row-wise values all return True. + +>>> df.all(axis=1) +0 True +1 False +dtype: bool """ _all_see_also = """\ See also -------- -pandas.DataFrame.any : Checks if one (or more) items return True +pandas.DataFrame.any : Return if one (or more) elements are True """ _cnum_doc = """ From 7ebd4dabdd18b23a1926f380f00a4c0e55965ba7 Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 16:43:51 -0500 Subject: [PATCH 07/10] removed changes from other branches --- pandas/core/generic.py | 65 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2b8a298db0198..b0a9d6ee5c88c 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3673,12 +3673,12 @@ def tail(self, n=5): Returns ------- - obj_tail : type of caller - The last n rows of the caller object. + type of caller + The last `n` rows of the caller object. See Also -------- - pandas.DataFrame.head + pandas.DataFrame.head : The first `n` rows of the caller object. Examples -------- @@ -4236,7 +4236,55 @@ def as_matrix(self, columns=None): @property def values(self): - """Numpy representation of NDFrame + """ + Return a Numpy representation of the DataFrame. + + Only the values in the DataFrame will be returned, the axes labels + will be removed. + + Returns + ------- + numpy.ndarray + The values of the DataFrame. + + Examples + -------- + A DataFrame where all columns are the same type (e.g., int64) results + in an array of the same type. + + >>> df = pd.DataFrame({'age': [ 3, 29], + ... 'height': [94, 170], + ... 'weight': [31, 115]}) + >>> df + age height weight + 0 3 94 31 + 1 29 170 115 + >>> df.dtypes + age int64 + height int64 + weight int64 + dtype: object + >>> df.values + array([[ 3, 94, 31], + [ 29, 170, 115]], dtype=int64) + + A DataFrame with mixed type columns(e.g., str/object, int64, float32) + results in an ndarray of the broadest type that accommodates these + mixed types (e.g., object). + + >>> df2 = pd.DataFrame([('parrot', 24.0, 'second'), + ... ('lion', 80.5, 1), + ... ('monkey', np.nan, None)], + ... columns=('name', 'max_speed', 'rank')) + >>> df2.dtypes + name object + max_speed float64 + rank object + dtype: object + >>> df2.values + array([['parrot', 24.0, 'second'], + ['lion', 80.5, 1], + ['monkey', nan, None]], dtype=object) Notes ----- @@ -4247,8 +4295,13 @@ def values(self): e.g. If the dtypes are float16 and float32, dtype will be upcast to float32. If dtypes are int32 and uint8, dtype will be upcast to - int32. By numpy.find_common_type convention, mixing int64 and uint64 - will result in a flot64 dtype. + int32. By By :func:`numpy.find_common_type` convention, mixing int64 + and uint64 will result in a float64 dtype. + + See Also + -------- + pandas.DataFrame.index : Retrievie the index labels + pandas.DataFrame.columns : Retrieving the column names """ self._consolidate_inplace() return self._data.as_array(transpose=self._AXIS_REVERSED) From 49da2fc84f17dc958b8928063609c8ea18675433 Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 16:45:41 -0500 Subject: [PATCH 08/10] removed typo --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b0a9d6ee5c88c..99fb1cd5a71c7 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4295,7 +4295,7 @@ def values(self): e.g. If the dtypes are float16 and float32, dtype will be upcast to float32. If dtypes are int32 and uint8, dtype will be upcast to - int32. By By :func:`numpy.find_common_type` convention, mixing int64 + int32. By :func:`numpy.find_common_type` convention, mixing int64 and uint64 will result in a float64 dtype. See Also From aceed8c9c16bc7f06bb60738334b39043d4e5bab Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 16:59:19 -0500 Subject: [PATCH 09/10] added series.all to see also --- pandas/core/generic.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 99fb1cd5a71c7..cab9577d88145 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7909,6 +7909,7 @@ def _doc_parms(cls): _all_see_also = """\ See also -------- +pandas.Series.all : Return if all elements are True pandas.DataFrame.any : Return if one (or more) elements are True """ From af464c8d606ca44a1fb84f0992fead488e432b3c Mon Sep 17 00:00:00 2001 From: Marcon Laforet Date: Sat, 10 Mar 2018 17:03:38 -0500 Subject: [PATCH 10/10] fixed doc typo --- 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 cab9577d88145..0078219eac260 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7869,7 +7869,7 @@ def _doc_parms(cls): Return whether all elements are True over series or dataframe axis. Returns True if all elements within a series or along a dataframe -axis or are non-zero, not-empty or not-False.""" +axis are non-zero, not-empty or not-False.""" _all_examples = """\ Examples @@ -7909,8 +7909,8 @@ def _doc_parms(cls): _all_see_also = """\ See also -------- -pandas.Series.all : Return if all elements are True -pandas.DataFrame.any : Return if one (or more) elements are True +pandas.Series.all : Return True if all elements are True +pandas.DataFrame.any : Return True if one (or more) elements are True """ _cnum_doc = """