DOC: Improve the docstring of DataFrame.equals() #22539

seantchan · 2018-08-30T01:41:21Z

closes DOC: Update docstring of DataFrame/Series .equals() to explain the behavior with indices #22462
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

################################################################################
##################### Docstring (pandas.DataFrame.equals)  #####################
################################################################################

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

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.equals" correct. :)

datapythonista

Great docstring, added some comments.

datapythonista · 2018-08-31T07:42:20Z

pandas/core/generic.py

+        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


they have the same shape...

datapythonista · 2018-08-31T07:43:56Z

pandas/core/generic.py

+
+        See Also
+        --------
+        pandas.Series.eq : Compare two Series objects of the same length


No need for the pandas. prefix, just Series.eq is enough.

I think we need eq and equals of both Series and DataFrame, not just Series.eq.

Would it be redundant to mention equals since this is the docstring for that method?

datapythonista · 2018-08-31T07:44:22Z

pandas/core/generic.py

+            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


no need for the blank line before this

datapythonista · 2018-08-31T07:51:03Z

pandas/core/generic.py

+        Examples
+        --------
+        >>> a = pd.DataFrame({1:[0], 0:[1]})
+        >>> b = pd.DataFrame({1.0:[0], 0.0:[1]})


to be consistent with other docstrings, it'd be good to use df for the main DataFrame the ones in which we'll call the method df.equals(), and something more descriptive for the other (e.g. exactly_equal, different_data_type, different_index_type...)

After creating the data, it'd be nice to display the content (i.e. >>> df)

Not sure in this case if it'd be better or worse, but in general we try to have somehow real-world (meaningful) data for the examples.

Used the same data in the updated PR - felt with text in order to use meaningful data it would be harder/more confusing to demonstrate. Can change that if needed.

datapythonista · 2018-08-31T07:57:10Z

pandas/core/generic.py

+        >>> 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.


"indices" are the row labels, which are the same, in this case the different type is in the column labels.

datapythonista · 2018-08-31T07:58:15Z

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 docstring is used for both Series and DataFrame, we should be generic.

Changed the DataFrame references in the docstring to NDFrame as originally written, however the validation script returned an error (Private classes (['NDFrame']) should not be mentioned in public docstring.). The updated PR still has NDFrame but can change it to something else (Series/DataFrame?) if that's better.

codecov · 2018-09-03T05:45:50Z

Codecov Report

❗ No coverage uploaded for pull request base (master@a5fe9cf). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master   #22539   +/-   ##
=========================================
  Coverage          ?   92.04%           
=========================================
  Files             ?      169           
  Lines             ?    50787           
  Branches          ?        0           
=========================================
  Hits              ?    46745           
  Misses            ?     4042           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.45% <ø> (?)`
#single	`42.29% <ø> (?)`

Impacted Files	Coverage Δ
pandas/core/generic.py	`96.44% <ø> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a5fe9cf...9730d0b. Read the comment docs.

…me_equals

datapythonista

The docstring looks really good. Just some comments about technicalities.

datapythonista · 2018-09-04T09:19:00Z

pandas/core/generic.py

@@ -1303,8 +1303,81 @@ 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 NDFrame objects contain the same elements.


I think you can leave Test whether two objects contain the same elements. for now.

The problem is that NDFrame is not a class we expect users to know about (it's private). So, it shouldn't be used in the documentation. Series or DataFrame or object are probably what we want to use in most cases.

datapythonista · 2018-09-04T09:22:32Z

pandas/core/generic.py

+            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.


We add the method being documented to the See Also, only in cases where the docstring is being reused by many methods, and we want those methods to reference each other. But this is not the case here. May be you can still add the pandas.utils.testing.assert_frame_equal and assert_series_equal here, but I don't think it adds value to reference .equals itself.

datapythonista · 2018-09-04T09:22:51Z

pandas/core/generic.py

+        Notes
+        -----
+        This function requires that the elements have the same dtype as their
+        respective elements in the other DataFrame. However, the column labels


in the other Series or DataFrame

datapythonista · 2018-09-04T09:23:06Z

pandas/core/generic.py

+
+        Examples
+        --------
+        >>> df = pd.DataFrame({1:[0], 0:[1]})


missing spaces after colons. I think using 0 -> 1 and 1 -> 0 is a bit confusing, may be 1 -> 10 and 2 -> 20 makes the example easier to read?

datapythonista · 2018-09-04T09:25:07Z

pandas/core/generic.py

+        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_type seems a clearer name to me

…ster' into docstring_DataFrame_equals

pep8speaks · 2018-09-05T00:00:16Z

Hello @seantchan! Thanks for updating the PR.

There are no PEP8 issues in the file pandas/core/generic.py !

datapythonista

lgtm, really good docstring, thanks for the work on this @seantchan

DOC: Improve the docstring of DataFrame.equals()

b2b685b

datapythonista added the Docs label Aug 31, 2018

datapythonista reviewed Aug 31, 2018

View reviewed changes

seantchan added 2 commits September 3, 2018 15:07

Merge remote-tracking branch 'upstream/master' into docstring_DataFra…

1460c0d

…me_equals

DOC: updating PR with suggested chains

faf0b04

datapythonista requested changes Sep 4, 2018

View reviewed changes

seantchan added 2 commits September 4, 2018 19:57

Fixing PR requested changes Merge remote-tracking branch 'upstream/ma…

e9ff405

…ster' into docstring_DataFrame_equals

DOC: fixed requested changes in latest updated PR

9730d0b

datapythonista approved these changes Sep 5, 2018

View reviewed changes

WillAyd merged commit 851b75a into pandas-dev:master Sep 5, 2018

aeltanawy pushed a commit to aeltanawy/pandas that referenced this pull request Sep 20, 2018

DOC: Improve the docstring of DataFrame.equals() (pandas-dev#22539)

4ed3760

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC: Improve the docstring of DataFrame.equals() (pandas-dev#22539)

3f607cc

simonjayhawkins mentioned this pull request Nov 5, 2019

DataFrame.equals incorrect See Also section of docstring for assert_*_equal #29408

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Improve the docstring of DataFrame.equals() #22539

DOC: Improve the docstring of DataFrame.equals() #22539

seantchan commented Aug 30, 2018 •

edited by datapythonista

Loading

datapythonista left a comment

datapythonista Aug 31, 2018

datapythonista Aug 31, 2018

seantchan Sep 3, 2018

datapythonista Aug 31, 2018

datapythonista Aug 31, 2018

seantchan Sep 3, 2018

datapythonista Aug 31, 2018

datapythonista Aug 31, 2018

seantchan Sep 3, 2018

codecov bot commented Sep 3, 2018 •

edited

Loading

datapythonista left a comment

datapythonista Sep 4, 2018

datapythonista Sep 4, 2018

datapythonista Sep 4, 2018

datapythonista Sep 4, 2018

datapythonista Sep 4, 2018

pep8speaks commented Sep 5, 2018

datapythonista left a comment

DOC: Improve the docstring of DataFrame.equals() #22539

DOC: Improve the docstring of DataFrame.equals() #22539

Conversation

seantchan commented Aug 30, 2018 • edited by datapythonista Loading

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Sep 3, 2018 • edited Loading

Codecov Report

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pep8speaks commented Sep 5, 2018

datapythonista left a comment

Choose a reason for hiding this comment

seantchan commented Aug 30, 2018 •

edited by datapythonista

Loading

codecov bot commented Sep 3, 2018 •

edited

Loading