Skip to content

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

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.

Sign up for GitHub

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

Merged
merged 8 commits into from
Mar 13, 2018
Merged

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

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5e780e9
DOC: Improve the docstring of Series.add_prefix()
astrastefania Mar 12, 2018
397f05d
DOC: Fixe the issues in the comments
astrastefania Mar 13, 2018
c719d7a
DOC: Update panle to Series
astrastefania Mar 13, 2018
e14315d
DOC: Added DataFrame example
astrastefania Mar 13, 2018
f23e340
DOC: Fix PEP8
astrastefania Mar 13, 2018
177285d
DOC: Fix PEP8spaces
astrastefania Mar 13, 2018
67c8dbe
DOC: Fix last docstring issue
astrastefania Mar 13, 2018
6d599ad
Spacing
TomAugspurger Mar 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2963,15 +2963,37 @@ def _update_inplace(self, result, verify_is_copy=True):

def add_prefix(self, prefix):
"""
Concatenate prefix string with panel items names.
Concatenate prefix string with Series items names.

Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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. :)

Copy link
Contributor

@TomAugspurger TomAugspurger Mar 13, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

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

...
"""

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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?

Copy link
Contributor

Choose a reason for hiding this comment

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

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

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

Returns
-------
with_prefix : type of caller
Series
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Original Series with updated item names.

See Also
--------
Series.add_suffix: Add a suffix string to Series items names.
Copy link
Contributor

Choose a reason for hiding this comment

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

"items names" -> "row labels"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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


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
Copy link
Contributor

Choose a reason for hiding this comment

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

Add a blank line and then an example with DataFrame.

"""
new_data = self._data.add_prefix(prefix)
return self._constructor(new_data).__finalize__(self)
Expand Down