Skip to content

Fix the docstring of xs in pandas/core/generic.py #22892 #23913

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 6 commits into from
Dec 2, 2018
Merged

Fix the docstring of xs in pandas/core/generic.py #22892 #23913

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d0fadf3
docstring and PEP8 for function xs corrected
tlentali Nov 25, 2018
5ed3302
object to label change and axis corrected
tlentali Nov 25, 2018
841a3cb
remove name in output, add See Also and real life exemple
tlentali Nov 26, 2018
47e0fe2
remove typo in df exemple (num_arm)
tlentali Nov 26, 2018
5e39bfc
short summary, key, returns, indent and quote typo, and exemples impr…
tlentali Nov 26, 2018
3f11180
correction of remaining typo and examples by block
tlentali Dec 2, 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
53 changes: 33 additions & 20 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3270,23 +3270,40 @@ class max_speed

def xs(self, key, axis=0, level=None, drop_level=True):
"""
Returns a cross-section (row(s) or column(s)) from the
Series/DataFrame. Defaults to cross-section on the rows (axis=0).
Return cross-section from the Series/DataFrame.

Returns a cross-section (row(s) or column(s))
from the Series/DataFrame.
Defaults to cross-section on the rows (axis=0).
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 a bit repetitive of the short summary. Can you try to explain in an easier way what the method does. I don't think a person who hasn't used it can understand by just reading the description.


Parameters
----------
key : object
Copy link
Member

Choose a reason for hiding this comment

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

can you rename object to label here

Some label contained in the index, or partially in a MultiIndex
Some label contained in the index, or partially in a MultiIndex.
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 more than one level can be provided, right? Can you make it clear here.

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 am not sure to understand this one, do you want me to precise the key ?

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 you can dodf.xs(key=('mammal', 'dog')), and if that's the case, the type label seems incorrect (or not clear). label or tuple of label and an a description that explains what is expected would be better

axis : int, default 0
Copy link
Member

Choose a reason for hiding this comment

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

Can you do a grep of axis : and see what we usually use for the axis type?, it's something like {0 or 'index', 1 or 'columns'}, default 0

Axis to retrieve cross-section on
Axis to retrieve cross-section on.
level : object, defaults to first n levels (n=1 or len(key))
In case of a key partially contained in a MultiIndex, indicate
which levels are used. Levels can be referred by label or position.
drop_level : boolean, default True
drop_level : bool, default True
If False, returns object with same levels as self.

Returns
-------
xs : Series or DataFrame
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
xs : Series or DataFrame
Series or DataFrame

We don't name the output anymore, just say the type. But in the next line we should have a short description on what's returned.


Notes
-----
xs is only for getting, not setting values.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
xs is only for getting, not setting values.
`xs` can not be used to set values.


MultiIndex Slicers is a generic way to get/set values on any level or
levels. It is a superset of xs functionality, see
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
levels. It is a superset of xs functionality, see
levels. It is a superset of `xs` functionality, see

:ref:`MultiIndex Slicers <advanced.mi_slicers>`
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
:ref:`MultiIndex Slicers <advanced.mi_slicers>`
:ref:`MultiIndex Slicers <advanced.mi_slicers>`.


Examples
--------
>>> d = {'A': [4, 4, 9], 'B': [5, 0, 7], 'C': [2, 9, 3]}
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 be nice to use a more real-world example. I think it makes things more complicated that the values used are arbitrary.

We've been using examples with animals, so for example df.xs(('mammal', 'cat')) returning num_legs 4 makes it very clear what is going on.

>>> df = pd.DataFrame(data=d, index=['a', 'b', 'c'])
>>> df
A B C
a 4 5 2
Expand All @@ -3296,13 +3313,21 @@ def xs(self, key, axis=0, level=None, drop_level=True):
A 4
B 5
C 2
Name: a
Name: a, dtype: int64
>>> df.xs('C', axis=1)
a 2
b 9
c 3
Name: C

Name: C, dtype: int64
>>> d = {'A': [4, 7, 6, 5],
... 'B': [1, 5, 6, 3],
... 'C': [8, 5, 8, 5],
... 'D': [9, 0, 0, 3],
... 'first': ['bar', 'bar', 'baz', 'baz'],
... 'second': ['one', 'two', 'one', 'three'],
... 'third': [1, 1, 1, 2]}
>>> df = pd.DataFrame(data=d)
>>> df = df.set_index(['first', 'second', 'third'])
>>> df
A B C D
first second third
Expand All @@ -3323,18 +3348,6 @@ def xs(self, key, axis=0, level=None, drop_level=True):
A B C D
second
three 5 3 5 3

Returns
-------
xs : Series or DataFrame

Notes
-----
xs is only for getting, not setting values.

MultiIndex Slicers is a generic way to get/set values on any level or
levels. It is a superset of xs functionality, see
:ref:`MultiIndex Slicers <advanced.mi_slicers>`
"""
axis = self._get_axis_number(axis)
labels = self._get_axis(axis)
Expand Down