From b2b685b1ecb157e497be62008bb829e9a4c0d24d Mon Sep 17 00:00:00 2001 From: seantchan <10970385+seantchan@users.noreply.github.com> Date: Wed, 29 Aug 2018 21:36:57 -0400 Subject: [PATCH 1/3] DOC: Improve the docstring of DataFrame.equals() --- pandas/core/generic.py | 55 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 85bd6065314f4..8043595c17668 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1303,8 +1303,59 @@ def __invert__(self): def equals(self, other): """ - Determines if two NDFrame objects contain the same elements. NaNs in - the same location are considered equal. + Test whether two DataFrame objects contain the same elements. + + This function allows two DataFrame objects to be compared against + each other to see if they same shape and elements. NaNs in the same + location are considered equal. The column headers do not need to have + the same type, but the elements within the columns must be + the same dtype. + + Parameters + ---------- + other : DataFrame + The other DataFrame to be compared with the first. + + Returns + ------- + bool + True if all elements are the same in both DataFrames, False + otherwise. + + See Also + -------- + pandas.Series.eq : Compare two Series objects of the same length + and return a Series where each element is True if the element + in each Series is equal, False otherwise. + + numpy.array_equal : Return True if two arrays have the same shape + and elements, False otherwise. + + Notes + ----- + This function requires that the elements have the same dtype as their + respective elements in the other DataFrame. However, the indices do + not need to have the same type, as long as they are still considered + equal. + + Examples + -------- + >>> a = pd.DataFrame({1:[0], 0:[1]}) + >>> b = pd.DataFrame({1.0:[0], 0.0:[1]}) + + DataFrames a and b have the same element types and values, but have + different types for the indices, which will still return True. + + >>> a.equals(b) + True + + DataFrames a and c have different types for the same values for their + elements, and will return False even though the indices are the same + values and types. + + >>> c = pd.DataFrame({1:[0.0], 0:[1.0]}) + >>> a.equals(c) + False """ if not isinstance(other, self._constructor): return False From faf0b04287b9beadb424b6d172c3e943dd716b77 Mon Sep 17 00:00:00 2001 From: seantchan <10970385+seantchan@users.noreply.github.com> Date: Mon, 3 Sep 2018 15:12:30 -0400 Subject: [PATCH 2/3] DOC: updating PR with suggested chains --- pandas/core/generic.py | 70 +++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 24 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8043595c17668..7fb7671a4e624 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1303,58 +1303,80 @@ def __invert__(self): def equals(self, other): """ - Test whether two DataFrame objects contain the same elements. + Test whether two NDFrame objects contain the same elements. - This function allows two DataFrame objects to be compared against - each other to see if they same shape and elements. NaNs in the same - location are considered equal. The column headers do not need to have - the same type, but the elements within the columns must be - the same dtype. + This function allows two NDFrame objects to be compared against + each other to see if they have the same shape and elements. NaNs in + the same location are considered equal. The column headers do not + need to have the same type, but the elements within the columns must + be the same dtype. Parameters ---------- - other : DataFrame - The other DataFrame to be compared with the first. + other : NDFrame + The other NDFrame to be compared with the first. Returns ------- bool - True if all elements are the same in both DataFrames, False + True if all elements are the same in both NDFrames, False otherwise. See Also -------- - pandas.Series.eq : Compare two Series objects of the same length + Series.eq : Compare two Series objects of the same length and return a Series where each element is True if the element in each Series is equal, False otherwise. - + DataFrame.eq : Compare two DataFrame objects of the same shape and + return a DataFrame where each element is True if the respective + element in each DataFrame is equal, False otherwise. numpy.array_equal : Return True if two arrays have the same shape and elements, False otherwise. Notes ----- This function requires that the elements have the same dtype as their - respective elements in the other DataFrame. However, the indices do - not need to have the same type, as long as they are still considered - equal. + respective elements in the other DataFrame. However, the column labels + do not need to have the same type, as long as they are still + considered equal. Examples -------- - >>> a = pd.DataFrame({1:[0], 0:[1]}) - >>> b = pd.DataFrame({1.0:[0], 0.0:[1]}) + >>> df = pd.DataFrame({1:[0], 0:[1]}) + >>> df + 1 0 + 0 0 1 + + DataFrames df and exactly_equal have the same types and values for + their elements and column labels, which will return True. + + >>> exactly_equal = pd.DataFrame({1:[0], 0:[1]}) + >>> exactly_equal + 1 0 + 0 0 1 + >>> df.equals(exactly_equal) + True - DataFrames a and b have the same element types and values, but have - different types for the indices, which will still return True. + DataFrames df and different_column_label have the same element + types and values, but have different types for the column labels, + which will still return True. - >>> a.equals(b) + >>> different_column_label = pd.DataFrame({1.0:[0], 0.0:[1]}) + >>> different_column_label + 1.0 0.0 + 0 0 1 + >>> df.equals(different_column_label) True - DataFrames a and c have different types for the same values for their - elements, and will return False even though the indices are the same - values and types. + DataFrames df and different_data_type have different types for the + same values for their elements, and will return False even though + their column labels are the same values and types. - >>> c = pd.DataFrame({1:[0.0], 0:[1.0]}) - >>> a.equals(c) + >>> different_data_type = pd.DataFrame({1:[0.0], 0:[1.0]}) + >>> different_data_type + 1 0 + 0 0.0 1.0 + >>> df.equals(different_data_type) False """ if not isinstance(other, self._constructor): From 9730d0b09fad2b6738b61093eaca7a0a955e577c Mon Sep 17 00:00:00 2001 From: seantchan <10970385+seantchan@users.noreply.github.com> Date: Tue, 4 Sep 2018 20:00:01 -0400 Subject: [PATCH 3/3] DOC: fixed requested changes in latest updated PR --- pandas/core/generic.py | 50 +++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7fb7671a4e624..dd5552151f61b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1303,9 +1303,9 @@ def __invert__(self): def equals(self, other): """ - Test whether two NDFrame objects contain the same elements. + Test whether two objects contain the same elements. - This function allows two NDFrame objects to be compared against + This function allows two Series or DataFrames to be compared against each other to see if they have the same shape and elements. NaNs in the same location are considered equal. The column headers do not need to have the same type, but the elements within the columns must @@ -1313,13 +1313,13 @@ def equals(self, other): Parameters ---------- - other : NDFrame - The other NDFrame to be compared with the first. + other : Series or DataFrame + The other Series or DataFrame to be compared with the first. Returns ------- bool - True if all elements are the same in both NDFrames, False + True if all elements are the same in both objects, False otherwise. See Also @@ -1330,52 +1330,56 @@ def equals(self, other): DataFrame.eq : Compare two DataFrame objects of the same shape and return a DataFrame where each element is True if the respective element in each DataFrame is equal, False otherwise. + assert_series_equal : Return True if left and right Series are equal, + False otherwise. + assert_frame_equal : Return True if left and right DataFrames are + equal, False otherwise. numpy.array_equal : Return True if two arrays have the same shape and elements, False otherwise. Notes ----- This function requires that the elements have the same dtype as their - respective elements in the other DataFrame. However, the column labels - do not need to have the same type, as long as they are still - considered equal. + respective elements in the other Series or DataFrame. However, the + column labels do not need to have the same type, as long as they are + still considered equal. Examples -------- - >>> df = pd.DataFrame({1:[0], 0:[1]}) + >>> df = pd.DataFrame({1: [10], 2: [20]}) >>> df - 1 0 - 0 0 1 + 1 2 + 0 10 20 DataFrames df and exactly_equal have the same types and values for their elements and column labels, which will return True. - >>> exactly_equal = pd.DataFrame({1:[0], 0:[1]}) + >>> exactly_equal = pd.DataFrame({1: [10], 2: [20]}) >>> exactly_equal - 1 0 - 0 0 1 + 1 2 + 0 10 20 >>> df.equals(exactly_equal) True - DataFrames df and different_column_label have the same element + DataFrames df and different_column_type have the same element types and values, but have different types for the column labels, which will still return True. - >>> different_column_label = pd.DataFrame({1.0:[0], 0.0:[1]}) - >>> different_column_label - 1.0 0.0 - 0 0 1 - >>> df.equals(different_column_label) + >>> different_column_type = pd.DataFrame({1.0: [10], 2.0: [20]}) + >>> different_column_type + 1.0 2.0 + 0 10 20 + >>> df.equals(different_column_type) True DataFrames df and different_data_type have different types for the same values for their elements, and will return False even though their column labels are the same values and types. - >>> different_data_type = pd.DataFrame({1:[0.0], 0:[1.0]}) + >>> different_data_type = pd.DataFrame({1: [10.0], 2: [20.0]}) >>> different_data_type - 1 0 - 0 0.0 1.0 + 1 2 + 0 10.0 20.0 >>> df.equals(different_data_type) False """