DOC: Update the pandas.DataFrame.abs docstring #20194

myles · 2018-03-10T16:09:27Z

Improve description and returns, and added notes and examples.

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
####################### Docstring (pandas.DataFrame.abs) #######################
################################################################################

Return a Series/DataFrame with absolute numeric value of each element.

This function only applies to elements that are all numeric.

Returns
-------
abs
    Series/DataFrame containing the absolute value of each element.

Notes
-----
For ``complex`` inputs, ``1.2 + 1j``, the absolute value is
:math:`\sqrt{ a^2 + b^2 }`. See the Python

Examples
--------
Absolute numeric values in a ``Series``.

>>> s = pd.Series([-1.10, 2, -3.33, 4])
>>> s.abs()
0    1.10
1    2.00
2    3.33
3    4.00
dtype: float64

Absolute numeric values in a ``Series`` with ``complex`` numbers.

>>> s = pd.Series([1.2 + 1j])
>>> s.abs()
0    1.56205
dtype: float64

Select rows with data closest to certian value using argsort (from
`StackOverflow <https://stackoverflow.com/a/17758115>`__).

>>> df = pd.DataFrame({
...     'a': [4, 5, 6, 7],
...     'b': [10, 20, 30, 40],
...     'c': [100, 50, -30, -50]
... })
>>> df
     a    b    c
0    4   10  100
1    5   20   50
2    6   30  -30
3    7   40  -50
>>> df.loc[(df.c - 43).abs().argsort()]
     a    b    c
1    5   20   50
0    4   10  100
2    6   30  -30
3    7   40  -50

See Also
--------
numpy.absolute : calculate the absolute value element-wise.

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

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

I feel there aren't any similar methods for the See Also section.

Improve description and returns, and added notes and examples.

TomAugspurger · 2018-03-10T16:19:03Z

pandas/core/generic.py

+
+        Select rows with data closest to certian value using argsort (from
+        `StackOverflow
+        <http://stackoverflow.com/questions/17758023/return-rows-in-a-dataframe-closest-to-a-user-defined-number>`__).


Probably too long of a line. SO should have a "share" URL that is shorter.

TomAugspurger · 2018-03-10T16:19:43Z

pandas/core/generic.py

@@ -7115,12 +7115,61 @@ def _tz_localize(ax, tz, ambiguous):
    # Numeric Methods
    def abs(self):
        """
-        Return an object with absolute value taken--only applicable to objects
-        that are all numeric.
+        Return a Series/DataFrame with absolute numeric value of each object.


Can you repalce "object" with "element"? That's our usual noun for items in a frame.

TomAugspurger · 2018-03-10T16:19:58Z

pandas/core/generic.py

-        that are all numeric.
+        Return a Series/DataFrame with absolute numeric value of each object.
+
+        This function only applies to objects that are all numeric.


objects -> elements

TomAugspurger · 2018-03-10T16:22:06Z

pandas/core/generic.py

+        2    6   30  -30
+        3    7   40  -50
+        >>> a_value = 43.0
+        >>> df.loc[(df.c - a_value).abs().argsort()]


No reason to assign a_value I think? Just subtract 43? I also don't know if the argsort helps. It seems a bit complicated.

The example fails if argsort() is removed. Maybe it's not a good idea to provided that example. I thought it was a good idea because abs() is commonly used with other functions.

jreback

needs to merge in master. you have a lot of other commits here.

myles · 2018-03-10T17:18:45Z

@jreback sorry I was playing around with Git. I fixed the issue.

jreback · 2018-03-11T15:05:57Z

pandas/core/generic.py

+        Notes
+        -----
+        For ``complex`` inputs, ``1.2 + 1j``, the absolute value is
+        :math:`\\sqrt{ a^2 + b^2 }`. See the Python


looks like something missing from the end here?

Sorry I was going to referer to the Python documentation on complex inputs but then realised that the user would already know about them.

jreback · 2018-03-11T15:06:10Z

pandas/core/generic.py

+
+        Examples
+        --------
+        Absolute numeric values in a ``Series``.


no need for the quotes on Series

jreback · 2018-03-11T15:06:42Z

pandas/core/generic.py

+        3    4.00
+        dtype: float64
+
+        Absolute numeric values in a ``Series`` with ``complex`` numbers.


could add an example for a Series of timedelta64

Added a pd.Timedelta example.

codecov · 2018-03-11T20:50:28Z

Codecov Report

❗ No coverage uploaded for pull request base (master@5b0caf4). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20194   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49162           
  Branches          ?        0           
=========================================
  Hits              ?    45096           
  Misses            ?     4066           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.11% <100%> (?)`
#single	`41.86% <0%> (?)`

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

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 5b0caf4...5e83e23. Read the comment docs.

TomAugspurger · 2018-03-13T20:59:53Z

Thanks @myles

myles added 2 commits March 10, 2018 11:06

📝 Update the pandas.DataFrame.abs function documentation.

99332e4

Improve description and returns, and added notes and examples.

🚨 Adding spaces after comma.

7da5bb6

TomAugspurger added the Docs label Mar 10, 2018

TomAugspurger added this to the 0.23.0 milestone Mar 10, 2018

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

💡 Fix issues with style of docstring.

4165872

jreback added the Numeric Operations Arithmetic, Comparison, and Logical operations label Mar 10, 2018

jreback removed this from the 0.23.0 milestone Mar 10, 2018

jreback requested changes Mar 10, 2018

View reviewed changes

myles force-pushed the doc-update-the-pandas-DataFrame-abs branch from 6e2badf to 4165872 Compare March 10, 2018 17:17

myles added 2 commits March 10, 2018 12:59

💡 Add a see also section to the numpy module.

54fffbe

💡 Add more information about numpy.absolute.

150f849

jreback requested changes Mar 11, 2018

View reviewed changes

myles added 2 commits March 11, 2018 16:49

💡 Fixed some style issues.

34296b2

💡 Add a timedelta example.

5e83e23

TomAugspurger added this to the 0.23.0 milestone Mar 13, 2018

TomAugspurger merged commit 823b5d3 into pandas-dev:master Mar 13, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Update the pandas.DataFrame.abs docstring #20194

DOC: Update the pandas.DataFrame.abs docstring #20194

myles commented Mar 10, 2018 •

edited

Loading

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018 •

edited

Loading

myles Mar 10, 2018 •

edited

Loading

jreback left a comment

myles commented Mar 10, 2018

jreback Mar 11, 2018

myles Mar 11, 2018

jreback Mar 11, 2018

myles Mar 11, 2018

jreback Mar 11, 2018

myles Mar 11, 2018

codecov bot commented Mar 11, 2018

TomAugspurger commented Mar 13, 2018

DOC: Update the pandas.DataFrame.abs docstring #20194

DOC: Update the pandas.DataFrame.abs docstring #20194

Conversation

myles commented Mar 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomAugspurger Mar 10, 2018 • edited Loading

Choose a reason for hiding this comment

myles Mar 10, 2018 • edited Loading

Choose a reason for hiding this comment

jreback left a comment

Choose a reason for hiding this comment

myles commented Mar 10, 2018

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 Mar 11, 2018

Codecov Report

TomAugspurger commented Mar 13, 2018

myles commented Mar 10, 2018 •

edited

Loading

TomAugspurger Mar 10, 2018 •

edited

Loading

myles Mar 10, 2018 •

edited

Loading