DOC: update docstring of pandas.Series.add_prefix docstring #20313

astrastefania · 2018-03-12T20:17:40Z

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.Series.add_prefix) #####################
################################################################################

Concatenate prefix string with panel items names.

Parameters
----------
prefix : str
    The string to add before each item name.

Returns
-------
Series
    Original Series with updated item names.

See Also
--------
pandas.Series.add_suffix: Add a suffix string to panel items names.

Examples
--------
>>> s = pd.Series([1,2,3,4])
>>> s
0    1
1    2
2    3
3    4
dtype: int64
>>> s.add_prefix('item_')
item_0    1
item_1    2
item_2    3
item_3    4
dtype: int64

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

Errors found:
	No extended summary found

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

datapythonista

Nice PR. Added couple of comments.

datapythonista · 2018-03-12T23:04:38Z

pandas/core/generic.py

+
+        Examples
+        --------
+        >>> s = pd.Series([1,2,3,4])


Missing spaces after commas to pass PEP-8

Interesting, the PEP-8 passed with any comments, it could be updated with this case?

datapythonista · 2018-03-12T23:05:45Z

pandas/core/generic.py

+
+        See Also
+        --------
+        pandas.Series.add_suffix: Add a suffix string to panel items names.


I think the preferred option is to not user the pandas. prefix.

I took it away. :)

datapythonista · 2018-03-12T23:08:18Z

pandas/core/generic.py

@@ -2967,11 +2967,33 @@ def add_prefix(self, prefix):



Panel is deprecated, we may want to use Series or DataFrame, or something generic.

I'd try to find uses cases on the internet for this method, and add in the extended summary when this method can be useful, if possible.

Thanks! I used Series as it is a Series module in this case.

For this and #20315, these apply to both Series and DataFrame (and Panel, but we don't care about that). So perhaps

Prefix row labels with a string `prefix`.

I want to avoid items, as (to me) I think dict.items so key-value pairs. But we're just touching the row labels here.

That summary is strange since we use Prefix as a verb and nound. Maybe "Prepend" would be better?

I see, thank you, my doubt is that on DataFrames add_prefix() adds a prefix on columns names not on rows, for example: df = pd.DataFrame({'A':[1,2,3,4], 'B':[3,4,5,6]}), df.add_suffix('_item'). For this motivations I decided to leave on Series.

Perhaps I could updated the docstring for pandas.DataFrame.add_prefix with the relative example to avoid confusion and let this as it is.

Let me know what sound better. :)

Ahh, good catch! I would say splitting the docstring is more complexity that warranted. How about somehting like

""" Prefix labels with string `prefix`. For Series, the row labels are prefixed. For DataFrame, the column labels are prefixed ... """

Yes, I do agree, thanks!

I didn't know about the issue of splitting docstring, so in this case is better have the same for both pandas.Series.add_prefix and pandas.DataFrame.add_prefix?

Yes, the docstring you've been editing in core/generic.py is used by both Series.add_prefix and DataFrame.add_prefix.

astrastefania · 2018-03-13T08:54:24Z

Docstring updated, thanks for the comments!

codecov · 2018-03-13T10:21:27Z

Codecov Report

Merging #20313 into master will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20313      +/-   ##
==========================================
+ Coverage    91.7%   91.73%   +0.02%     
==========================================
  Files         150      150              
  Lines       49165    49168       +3     
==========================================
+ Hits        45087    45102      +15     
+ Misses       4078     4066      -12

Flag	Coverage Δ
#multiple	`90.11% <ø> (+0.02%)`	⬆️
#single	`41.86% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`95.85% <ø> (ø)`	⬆️
pandas/core/algorithms.py	`94.17% <0%> (-0.01%)`	⬇️
pandas/core/frame.py	`97.18% <0%> (ø)`	⬆️
pandas/core/indexes/base.py	`96.66% <0%> (ø)`	⬆️
pandas/plotting/_converter.py	`66.81% <0%> (+1.73%)`	⬆️
pandas/core/arrays/base.py	`76.74% <0%> (+2.38%)`	⬆️

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 bfe6ebc...6d599ad. Read the comment docs.

TomAugspurger

Thanks. Do you have time to update this and #20315 with similar changes @astrastefania?

TomAugspurger · 2018-03-13T11:48:02Z

pandas/core/generic.py

@@ -2967,11 +2967,33 @@ def add_prefix(self, prefix):



For this and #20315, these apply to both Series and DataFrame (and Panel, but we don't care about that). So perhaps

Prefix row labels with a string `prefix`.

I want to avoid items, as (to me) I think dict.items so key-value pairs. But we're just touching the row labels here.

That summary is strange since we use Prefix as a verb and nound. Maybe "Prepend" would be better?

TomAugspurger · 2018-03-13T11:49:23Z

pandas/core/generic.py


        Returns
        -------
-        with_prefix : type of caller
+        Series


Series or DataFrame Same type as the calling object, with updated row labels.

TomAugspurger · 2018-03-13T11:49:34Z

pandas/core/generic.py

+
+        See Also
+        --------
+        Series.add_suffix: Add a suffix string to Series items names.


"items names" -> "row labels"

I see your point for "item names", please check the comment above related to include DataFrame or not (if not could make the change to "row labels" suggested here).

So anywhere we say "item names", let's say "labels." or "row labels" or "column labels".

TomAugspurger · 2018-03-13T11:49:54Z

pandas/core/generic.py

+        item_1    2
+        item_2    3
+        item_3    4
+        dtype: int64


Add a blank line and then an example with DataFrame.

TomAugspurger · 2018-03-13T16:39:30Z

pandas/core/generic.py


        Returns
        -------
-        with_prefix : type of caller
+        Series or DataFrame
+            Original Series or DataFrame with updated labels.


This make it sound a bit like the object is modified inplace. Could you instead say

Series or DataFrame New Series or DataFrame with updated labels.

Actually is modified inplace, should it be specified?

Hmm I don't think so

In [6]: s = pd.Series(1, ['a', 'b']) In [7]: s Out[7]: a 1 b 1 dtype: int64 In [8]: s.add_prefix('foo_') Out[8]: foo_a 1 foo_b 1 dtype: int64 In [9]: s Out[9]: a 1 b 1 dtype: int64

s is unmodified.

Sorry, I meant it's unmodified! I agree is not modified inplace.

TomAugspurger · 2018-03-13T16:40:02Z

pandas/core/generic.py

+        1  2  4
+        2  3  5
+        3  4  6
+        >>> df.add_suffix('_item')


This should be the add_prefix example I think :)

Yes!!! 😄

TomAugspurger · 2018-03-13T16:40:43Z

LGTM other than those two minor issues.

astrastefania · 2018-03-13T16:41:42Z

@TomAugspurger @datapythonista, if it's all fine in here now I'll proceed to modify #20315 (otherwise I'll update this one first)

TomAugspurger · 2018-03-13T17:50:37Z

Looks great! Just added a tiny commit adjusting the spacing. Thanks!

DOC: Improve the docstring of Series.add_prefix()

5e780e9

jorisvandenbossche added the Docs label Mar 12, 2018

datapythonista reviewed Mar 12, 2018

View reviewed changes

datapythonista mentioned this pull request Mar 12, 2018

DOC: update the pandas.Series.add_suffix docstring #20315

Merged

5 tasks

DOC: Fixe the issues in the comments

397f05d

DOC: Update panle to Series

c719d7a

TomAugspurger reviewed Mar 13, 2018

View reviewed changes

astrastefania added 3 commits March 13, 2018 17:31

DOC: Added DataFrame example

e14315d

DOC: Fix PEP8

f23e340

DOC: Fix PEP8spaces

177285d

TomAugspurger reviewed Mar 13, 2018

View reviewed changes

astrastefania and others added 2 commits March 13, 2018 17:58

DOC: Fix last docstring issue

67c8dbe

Spacing

6d599ad

TomAugspurger merged commit 7c5bae3 into pandas-dev:master Mar 13, 2018

TomAugspurger added this to the 0.23.0 milestone Mar 13, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update docstring of pandas.Series.add_prefix docstring #20313

DOC: update docstring of pandas.Series.add_prefix docstring #20313

astrastefania commented Mar 12, 2018

datapythonista left a comment

datapythonista Mar 12, 2018

astrastefania Mar 13, 2018

datapythonista Mar 12, 2018

astrastefania Mar 13, 2018

datapythonista Mar 12, 2018

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018 •

edited

Loading

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania commented Mar 13, 2018

codecov bot commented Mar 13, 2018 •

edited

Loading

TomAugspurger left a comment

TomAugspurger Mar 13, 2018

TomAugspurger Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018

TomAugspurger Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania Mar 13, 2018

TomAugspurger Mar 13, 2018

astrastefania Mar 13, 2018

TomAugspurger commented Mar 13, 2018

astrastefania commented Mar 13, 2018

TomAugspurger commented Mar 13, 2018 •

edited

Loading

DOC: update docstring of pandas.Series.add_prefix docstring #20313

DOC: update docstring of pandas.Series.add_prefix docstring #20313

Conversation

astrastefania commented Mar 12, 2018

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

TomAugspurger Mar 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

astrastefania commented Mar 13, 2018

codecov bot commented Mar 13, 2018 • edited Loading

Codecov Report

TomAugspurger 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomAugspurger commented Mar 13, 2018

astrastefania commented Mar 13, 2018

TomAugspurger commented Mar 13, 2018 • edited Loading

TomAugspurger Mar 13, 2018 •

edited

Loading

codecov bot commented Mar 13, 2018 •

edited

Loading

TomAugspurger commented Mar 13, 2018 •

edited

Loading