Skip to content

DOC: update the pandas.DataFrame.clip docstring #20212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 25 commits into from
Closed

DOC: update the pandas.DataFrame.clip docstring #20212

wants to merge 25 commits into from

Conversation

Dpananos
Copy link

@Dpananos Dpananos commented Mar 10, 2018

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:

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

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
		Unknown parameters {'*args, **kwargs'}
		Parameter "*args, **kwargs" has no type
(pandas_dev) Demetris-Retina-MacBook-Pro:pandas demetri$ git diff upstream/master -u -- "*.py" | flake8 --diff
(pandas_dev) Demetris-Retina-MacBook-Pro:pandas demetri$ python scripts/validate_docstrings.py pandas.DataFrame.clip

################################################################################
###################### Docstring (pandas.DataFrame.clip)  ######################
################################################################################

Trim values at input threshold(s).

Elements above/below the upper/lower thresholds will be changed to
upper/lower thresholds. Clipping data is a method for dealing with
out-of-range elements. If some elements are too large or too small,
clipping is one way to transform the data into a reasonable range.

Parameters
----------
lower : float, array-like or None, default None
    Lower threshold for clipping.  Values smaller than `lower` will be
    converted to `lower`.
upper : float, array-like or None, default None
    Upper threshold for clipping.  Values larger than `upper` will be
    converted to `upper`.
axis : {0 or 'index', 1 or 'columns', None}, default None
    Apply clip by index (i.e. by rows) or columns.
inplace : boolean, default False
    Whether to perform the operation in place on the data
        .. versionadded:: 0.21.0.
*args, **kwargs
    Additional keywords have no effect but might be accepted
    for compatibility with numpy.

Returns
-------
`Series` or `DataFrame`.
    Original input with those values above/below the
    `upper`/`lower` thresholds set to the threshold values.

References
-----
.. [1] Tukey, John W. "The future of data analysis." The annals of
    mathematical statistics 33.1 (1962): 1-67.

See Also
--------
DataFrame.clip : Trim values at input threshold(s).
Series.clip : Trim values at input threshold(s).
Series.clip_lower : Return copy of the input with values below given
    value(s) truncated.
Series.clip_upper : Return copy of input with values above given
    value(s) truncated.
DataFrame.clip_lower : Return copy of the input with values below given
    value(s) truncated.
DataFrame.clip_upper : Return copy of input with values above given
    value(s) truncated.
DataFrame.quantile : Return values at the given quantile over requested
    axis, a la numpy.percentile.

Examples
--------
>>> df = pd.DataFrame({'a': [-1, -2, -100],
...                    'b': [1, 2, 100]},
...                    index=['foo', 'bar', 'foobar'])
>>> df
     a  b
foo -1  1
bar -2  2
foobar  -100    100

>>> df.clip(lower=-10, upper=10)
     a  b
foo -1  1
bar -2  2
foobar  -10 10

You can clip each column or row with different thresholds by passing
a ``Series`` to the lower/upper argument. Use the axis argument to clip
by column or rows.

>>> col_thresh = pd.Series({'a': -5, 'b': 5})
>>> df.clip(lower=col_thresh, axis='columns')
     a  b
foo -1  5
bar -2  5
foobar  -5  100

Clip the foo, bar, and foobar rows with lower thresholds 5, 7, and 10.

>>> row_thresh = pd.Series({'foo': 0, 'bar': 1, 'foobar': 10})
>>> df.clip(lower=row_thresh, axis='index')
    a   b
foo 0   1
bar 1   2
foobar  10  100

Winsorizing [1]_ is a related method, whereby the data are clipped at
the 5th and 95th percentiles. The ``DataFrame.quantile`` method returns
a ``Series`` with column names as index and the quantiles as values.
Use ``axis='columns'`` to apply clipping to columns.

>>> lower, upper = df.quantile(0.05), df.quantile(0.95)
>>> df.clip(lower=lower, upper=upper, axis='columns')
     a  b
foo -1.1    1.1
bar -2.0    2.0
foobar  -90.2   90.2

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

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
		Unknown parameters {'*args, **kwargs'}
		Parameter "*args, **kwargs" has no type

Changes:

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Goo contribution, added some comments

@@ -5601,53 +5601,99 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
"""
Trim values at input threshold(s).

Elements above the upper threshold will be changed to upper threshold.
Elements below the lower threshold will be changed to lower threshold.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems duplicated.

@@ -5601,53 +5601,99 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
"""
Trim values at input threshold(s).

Elements above the upper threshold will be changed to upper threshold.
Elements below the lower threshold will be changed to lower threshold.

Parameters
----------
lower : float or array_like, default None
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if it's better or worse, but I think the standard we defined is to use float, array-like or None, default None (so the None is duplicated). Also note the hyphen and not underscore in array-like

Parameters
----------
lower : float or array_like, default None
Lower threshold for clipping. Values smaller than upper will be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For naming parameters it's better to have them in backticks. In this case I think it adds value, making it clearer that upper is a parameter (and lower).

upper : float or array_like, default None
Upper threshold for clipping. Values larger than upper will be
converted to upper.
axis : int or string axis name, optional
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We added a standard for axis to the documentation, at the end of the Paramters section. Basically it's axis : {0 or 'index', 1 or 'columns', None}, default None

.. versionadded:: 0.21.0
.. versionadded:: 0.21.0.
args : dictionary of arguments arguments passed to pandas.compat.numpy
kwargs : dictionary of keyword arguments passed to pandas.compat.numpy
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*args and **kwargs with the stars (even if the validate script complaints), and without the type (the description part goes in the nest line)


Returns
-------
clipped : Series
clipped : DataFrame/Series
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Series or DataFrame


Examples
--------
>>> df=pd.DataFrame({'a':[1, 2, 3], 'b':[4, 5, 6], 'c':[7, 8, 9001]})
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This have several PEP-8 issues because of missing spaces

a ``Series`` to the lower/upper argument.

>>> some_data={'A':[-19, 12, -5],'B':[1, 100, -5]}
>>> df=pd.DataFrame(data=some_data, index=['foo', 'bar', 'bizz'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

more PEP-8

Copy link

@cmdelatorre cmdelatorre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

args and kwargs are passed to validate_clip_with_axis, that is not trivial. It means that args and kwargs actually make sense. These should be clear in the docstring. Check here: https://github.com/pandas-dev/pandas/blob/master/pandas/compat/numpy/function.py#L137


Notes
-----
Clipping data is a method for dealing with dubious elements.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefer, out-of-range to dubious

See Also
--------
pandas.DataFrame.clip_upper : Return copy of input with values
above given value(s) truncated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add Series.clip

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is in generic, isn't it being reused by Series.clip?

of removing outliers from data. Columns of a DataFrame can be
winsorized by using clip.

>>> import numpy as np
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't need the numpy import

>>> import numpy as np
>>> x=np.random.normal(size=(1000,3))
>>> df=pd.DataFrame(x, columns=['a','b','c'])
>>> #Winsorize columns at 5% and 95%
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can add this as part of the text above

>>> x=np.random.normal(size=(1000,3))
>>> df=pd.DataFrame(x, columns=['a','b','c'])
>>> #Winsorize columns at 5% and 95%
>>> U=df.quantile(0.95)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

spaces around equals

@jreback jreback added Docs Numeric Operations Arithmetic, Comparison, and Logical operations labels Mar 10, 2018
@Dpananos
Copy link
Author

@cmdelatorre validate_clip_with_axis is going over my head. I'm not sure what validate_clip_with_axis does. Open to suggestions on what to add to docstring, or would appreciate reading suggestions.

Possible documentation for args and kwargs
Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like this contribution. Made some comments.

Align object with lower and upper along the given axis.
inplace : boolean, default False
Whether to perform the operation in place on the data
.. versionadded:: 0.21.0
.. versionadded:: 0.21.0.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the description of axis a bit complex.

.. versionadded:: 0.21.0
.. versionadded:: 0.21.0.
*args : arguments passed to pandas.compat.numpy
**kwargs : keyword arguments passed to pandas.compat.numpy
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not in the documentation yet, but after some discussion some minutes ago, we'll have *args, **kwargs in a single line (no colon), and a single description in the next, as it's rarely different between them.

clipped : Series
clipped : `Series` or `DataFrame`.
Elements above or below the upper and lower thresholds converted to
threshold values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can just have the type in the first row of Returns, providing a name doesn't add much value.

The description sounds a bit like if we could be returning only part of the original values.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure thing.

-----
Clipping data is a method for dealing with out-of-range elements.
If some elements are too large or too small, clipping is one way to
transform the data into a reasonable range.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds more like part of the extended summary to me, than Notes, which is usually left for details on the implementaiton (e.g. calling this function makes a copy of the data)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I just remove it then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's an interesting comment. May be you can also mention about the outlier thing you show in the example. But I'd have it in the extended summary. After moving it, make sure the whole summary makes sense and doesn't sound repetitive. Usually happens when you move blocks.

See Also
--------
pandas.DataFrame.clip_upper : Return copy of input with values
above given value(s) truncated.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is in generic, isn't it being reused by Series.clip?

a ``Series`` to the lower/upper argument.

>>> some_data = {'A': [-19, 12, -5], 'B': [1, 100, -5]}
>>> df = pd.DataFrame(data=some_data, index=['foo', 'bar', 'bizz'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would create df just once at the beginning (with 2 cols), and reuse it all the time.

I've usually seen foo, bar and foobar, not important, but I'd use that unless there is another convention that uses bizz

bizz -5 -5

Use the axis argument to clip by column or rows. Clip column A with
lower threshold of -10 and column B has lower threshold of 10.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

two spaces after the dot?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, bad habit.

>>> x = np.random.normal(size=(1000,3))
>>> U = df.quantile(0.95)
>>> L = df.quantile(0.5)
>>> winsorized_df = df.clip(lower=L, upper=U, axis=1)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like having this here. But couple of thoughts (feel free to disagree in both, they are open questions):

  • Should we add quantile to See Also, if we consider this a common case?
  • I'd probably like more to use the previous df even if this makes more sense with normally distributed data

Regardless of these two points, this example has some typos:

  • Missing space after the comma in the size tuple
  • x is defined but later you're using df
  • I don't see a reason to use capital letters for L and U, I don't see them as constants even if they are not modified again in the example
  • I would use descriptive names, not a single letter
  • Makes more sense to define lower first

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll work on these tomorrow and update the PR then. Thanks for the feedback.

@pep8speaks
Copy link

pep8speaks commented Mar 11, 2018

Hello @Dpananos! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 13, 2018 at 15:29 Hours UTC

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking great, I few more comments.

*args : Additional keywords have no effect but might be accepted
for compatibility with numpy.
**kwargs : Additional keywords have no effect but might be accepted
for compatibility with numpy.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was some change to the convention during the sprint, and args and kwargs should be in the same line *args, **kwargs and a common description in the next line. We didn't find any case where args and kwargs have different description, and it's repetitive the way it was originally defined.

Also, note that *args are positional arguments, I don't think it's correct to name they keywords.

clipped : Series
`Series` or `DataFrame`.
DataFrame is returned with those values above/below the
`upper`/`'lower` thresholds set to the threshold values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If return can be Series, the description is not accurate, saying the DataFrame is returned. May be something like "Original input with values above/below..."?


See Also
--------
pandas.Series.clip : Trim values at input threshold(s).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the prefix pandas is not needed, just Series.clip. Also, not sure if that was already discussed, but don't we want clip_lower and clip_upper here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you previously mentioned that those were generic. Did we want them included still?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I think I wasn't clear enough. You should check it, but as this docstring is in generic.py I assume it'll be used by both Series and DataFrame. That's why I said it was (the docstring) was generic.

So, as your assigned docstring was DataFrame.clip (and it's what it's in the title of the PR) but you're actually working also in Series.clip, I don't think it makes sense to only add Series.clip as @jreback suggested. I'd say that we probably want also DataFrame.clip. Even if it'll be a bit weird to have in the See Also the same method which is being documented, but I think it's all right. In a separate PR we could use a template and just have the right one.

So, summarizing, the see also should contain Series.clip, DataFrame.clip, and the clip_lower and clip_upper for each of them (I assume both classes have it). And assuming that clip is commonly used with quantile as in your example (I don't know), I would also add it.

@jreback do you agree?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yes I see, I was mistaken. Sure, I can add all those.


Examples
--------
>>> some_data = {'a': [1, 2, 3], 'b': [4, 5, 6], 'c': [7, 8, 9001]}
>>> df = pd.DataFrame(some_data, index = ['foo', 'bar', 'foobar'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spaces around = are not PEP-8 compliant. Sorry the validation script doesn't check it yet.

a b c
foo 1 4 7
bar 2 5 8
foobar 3 6 9
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this example could be more concise, and help people understand the concept faster.

I think 2 columns is enough, have 3 doesn't add much value, but takes some extra time to check what's going on with the example.

Also, the lower trimming by 1 not having effect, makes me a bit confused, on whether I'm understanding it or not. Also it's somethimg really minor, but I found the 9001 unnecessarily big and arbitrary (using 100 wouldn't make me thing there is any special on it..

Feel free to use the example you want, but using something like -1, -2, -100, 1, 2, 100 and trimming at -10 and 10 would make it more clear and straight to the point.

a ``Series`` to the lower/upper argument. Use the axis argument to clip
by column or rows.

>>> col_thresh = pd.Series({'a':4, 'b':5, 'c':6})
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

spaces after colons for PEP-8


>>> lwr_thresh = df.quantile(0.05)
>>> upr_thresh = df.quantile(0.95)
>>> dfw = df.clip(lower=lwr_thresh, upper=upr_thresh, axis='columns')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as you're using df now, I think you should show the output, instead of saving it to a variable.

Also, it's more a personal taste, feel free to ignore the commend, but these abbreviations feel a bit cryptic. lower_threshold would be better, but I think just lower it's probably even better.

And just an idea, in case you like it (it's how I'd write it and find more readable, but feel free to leave it as it):

>>> lower, upper = df.quantile(0.05), df.quantile(0.95)

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great, just a small PEP-8 issue, and I think it's perfect.


Examples
--------
>>> some_data = {'a': [-1, -2, -100], 'b': [1, 2, 100]}
>>> df = pd.DataFrame(some_data, index = ['foo', 'bar', 'foobar'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PEP-8 issue with spaces around =.

Also, as you need to change this, I'd directly have the dictionary in the constructor, and avoid creating some_data. Just for the sake of consistency, as all examples I've seen use this way. With one key of the dictionary in one line, and the index in a third one, I think line width should be a problem.

the 5th and 95th percentiles.

>>> lower, upper = df.quantile(0.05), df.quantile(0.95)
>>> df.clip(lower=lower, upper=upper, axis='columns')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if it's just because I'm too tired, but is axis useful here? If the threshold is a scalar, doesn't seem to have an effect, right?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Axis is required here since df.quantile returns a series with the quantiles for each column. Running without the axis argument results in an error.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd find useful having this comment in the explanations before the test. :)

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm.

Really nice documentation, I find it very useful.

Copy link
Author

@Dpananos Dpananos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Edited

DataFrame.clip : Trim values at input threshold(s).
Series.clip : Trim values at input threshold(s).
Series.clip_lower : Return copy of the input with values below given
value(s) truncated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would just mention Series.clip here (not upper/lower)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why don't you find clip_upper and clip_lower related? I suggested them, but actually I was wondering if I was missing something, or if it was being considered deprecating them. It seems to me that clip(upper=X) could be used for clip_upper.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

going to deprecate lower/upper but that’s not the reason
when showing a DataFrame method only like to show 1 Series method and and any related DataFrame method

just a preference to not have too many things in See Also

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense to me.

But if I'm not wrong, the title is misleading but this docstring is for the Series.clip method too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ahh ok in that case this is ok

3 0.230930 0.000000
4 1.100000 0.570967
a b
foo -1 1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

alignment doesn’t look right here

foobar 10 100

`Winsorizing <https://en.wikipedia.org/wiki/Winsorizing>`__ is a
related method, whereby the data are clipped at
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

put this reference in the Notes section

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want me to move the entire part about winsorization or just the link?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just the link, you can see the format in the 13. References section of this document: http://numpydoc.readthedocs.io/en/latest/format.html

@codecov
Copy link

codecov bot commented Mar 13, 2018

Codecov Report

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

Impacted file tree graph

@@            Coverage Diff            @@
##             master   #20212   +/-   ##
=========================================
  Coverage          ?   91.73%           
=========================================
  Files             ?      150           
  Lines             ?    49168           
  Branches          ?        0           
=========================================
  Hits              ?    45102           
  Misses            ?     4066           
  Partials          ?        0
Flag Coverage Δ
#multiple 90.11% <100%> (?)
#single 41.86% <50%> (?)
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...bd26d0f. Read the comment docs.

@@ -5629,6 +5629,12 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
Original input with those values above/below the
`upper`/`lower` thresholds set to the threshold values.

Notes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be in References and not in Notes. It wasn't in the documentation for the sprint, for simplicity, but you can check this document: http://numpydoc.readthedocs.io/en/latest/format.html

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, I agree. Done.

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@jorisvandenbossche
Copy link
Member

@Dpananos I merged the other PR that also edited the same docstring (#20256). This will cause conflicts for this one, so you will need to resolve them (sorry for that trouble, but wanted to acknowledge both PRs, and yours adds some extra than the other).

If you need any help with updating the PR (merge upstream/master), let me know!

@Dpananos
Copy link
Author

@jorisvandenbossche I'm not really certain what happened. So you merged another docstring and now I have a conflict? How should I go about updating the PR?

@jorisvandenbossche
Copy link
Member

jorisvandenbossche commented Mar 15, 2018

So to update the PR with the latest changes on master, you can do:

git checkout docstring_clip
git fetch upstream
git merge upstream/master

This will give conflicts in the generic.py file.

Solving these conflicts will mean merging somehow the two docstring (you can just use your judgement on which of the two versions you find best for each element of the docstring, certainly your examples were more elaborate I think).
Once you solved the conflicts, you need to do:

git add pandas/core/generic.py
git commit

and push again to the branch on origin.

I would say: try it out, and if you have troubles with, I can also do it.

@Dpananos Dpananos closed this Mar 15, 2018
@Dpananos Dpananos deleted the docstring_clip branch March 15, 2018 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Docs Numeric Operations Arithmetic, Comparison, and Logical operations
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants