From d0fadf391ccdfe2964b5b0ad25e7811716ed4367 Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Sun, 25 Nov 2018 23:57:16 +0100 Subject: [PATCH 1/6] docstring and PEP8 for function xs corrected --- pandas/core/generic.py | 53 ++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 20 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 5bb364e1d1605..9378d6eafe97e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -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). Parameters ---------- key : object - Some label contained in the index, or partially in a MultiIndex + Some label contained in the index, or partially in a MultiIndex. axis : int, 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 + + 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 ` + Examples -------- + >>> d = {'A': [4, 4, 9], 'B': [5, 0, 7], 'C': [2, 9, 3]} + >>> df = pd.DataFrame(data=d, index=['a', 'b', 'c']) >>> df A B C a 4 5 2 @@ -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 @@ -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 ` """ axis = self._get_axis_number(axis) labels = self._get_axis(axis) From 5ed330262c2d001b36321b800bb8722d19cc8416 Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Mon, 26 Nov 2018 00:35:17 +0100 Subject: [PATCH 2/6] object to label change and axis corrected --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 9378d6eafe97e..2de0aa09162b0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3278,9 +3278,9 @@ def xs(self, key, axis=0, level=None, drop_level=True): Parameters ---------- - key : object + key : label Some label contained in the index, or partially in a MultiIndex. - axis : int, default 0 + axis : {0 or 'index', 1 or 'columns'}, default 0 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 From 841a3cb4337d235434995064e2ad3f3c1d364016 Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Mon, 26 Nov 2018 01:36:25 +0100 Subject: [PATCH 3/6] remove name in output, add See Also and real life exemple --- pandas/core/generic.py | 102 ++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 47 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2de0aa09162b0..42131a5054df1 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3290,64 +3290,72 @@ def xs(self, key, axis=0, level=None, drop_level=True): Returns ------- - xs : Series or DataFrame + Series or DataFrame + + See Also + -------- + DataFrame.loc : Access a group of rows and columns + by label(s) or a boolean array. + DataFrame.iloc : Purely integer-location based indexing + for selection by position. Notes ----- - 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 - :ref:`MultiIndex Slicers ` + levels. It is a superset of 'xs' functionality, see + :ref:`MultiIndex Slicers `. Examples -------- - >>> d = {'A': [4, 4, 9], 'B': [5, 0, 7], 'C': [2, 9, 3]} - >>> df = pd.DataFrame(data=d, index=['a', 'b', 'c']) + >>> df = pd.DataFrame({"num_legs": [4, 4, 2], + ... "num_arms": [0, 0, 2], + ... "num_wings": [0, 0, 2]}, + ... ["dog", "cat", "duck"]) >>> df - A B C - a 4 5 2 - b 4 0 9 - c 9 7 3 - >>> df.xs('a') - A 4 - B 5 - C 2 - Name: a, dtype: int64 - >>> df.xs('C', axis=1) - a 2 - b 9 - c 3 - 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]} + num_legs num_arms num_wings + dog 4 0 0 + cat 4 0 0 + duck 2 2 2 + >>> df.xs('dog') + num_legs 4 + num_arms 0 + num_wings 0 + Name: dog, dtype: int64 + >>> df.xs('num_wings', axis=1) + dog 0 + cat 0 + duck 2 + Name: num_wings, dtype: int64 + >>> d = {'num_legs': [4, 4, 2, 4], + ... 'num_arms': [0, 0, 0, 0], + ... 'num_wings': [0, 0, 2, 0], + ... 'num_spec_seen': [9, 2, 7, 3], + ... 'class': ['mammal', 'mammal', 'sauropsida', 'sauropsida'], + ... 'animal': ['cat', 'dog', 'duck', 'turtle'], + ... 'area': [1, 1, 2, 3]} >>> df = pd.DataFrame(data=d) - >>> df = df.set_index(['first', 'second', 'third']) + >>> df = df.set_index(['class', 'animal', 'area']) >>> df - A B C D - first second third - bar one 1 4 1 8 9 - two 1 7 5 5 0 - baz one 1 6 6 8 0 - three 2 5 3 5 3 - >>> df.xs(('baz', 'three')) - A B C D - third - 2 5 3 5 3 - >>> df.xs('one', level=1) - A B C D - first third - bar 1 4 1 8 9 - baz 1 6 6 8 0 - >>> df.xs(('baz', 2), level=[0, 'third']) - A B C D - second - three 5 3 5 3 + num_legs num_arms num_wings num_spec_seen + class animal area + mammal cat 1 4 0 0 9 + dog 1 4 0 0 2 + sauropsida duck 2 2 0 2 7 + turtle 3 4 0 0 3 + >>> df.xs(('mammal', 'dog')) + num_legs num_arms num_wings num_spec_seen + area + 1 4 0 0 2 + >>> df.xs('cat', level=1) + num_legs num_arms num_wings num_spec_seen + class area + mammal 1 4 0 0 9 + >>> df.xs(('sauropsida', 2), level=[0, 'area']) + num_legs num_arms num_wings num_spec_seen + animal + duck 2 0 2 7 """ axis = self._get_axis_number(axis) labels = self._get_axis(axis) From 47e0fe2b6dfad6f1050033d441b4523b9c398f9c Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Mon, 26 Nov 2018 01:40:28 +0100 Subject: [PATCH 4/6] remove typo in df exemple (num_arm) --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 42131a5054df1..7c9158b264979 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3310,14 +3310,14 @@ def xs(self, key, axis=0, level=None, drop_level=True): Examples -------- >>> df = pd.DataFrame({"num_legs": [4, 4, 2], - ... "num_arms": [0, 0, 2], + ... "num_arms": [0, 0, 0], ... "num_wings": [0, 0, 2]}, ... ["dog", "cat", "duck"]) >>> df num_legs num_arms num_wings dog 4 0 0 cat 4 0 0 - duck 2 2 2 + duck 2 0 2 >>> df.xs('dog') num_legs 4 num_arms 0 From 5e39bfcae120488a0d6aae588c25dde59027ee93 Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Mon, 26 Nov 2018 22:22:40 +0100 Subject: [PATCH 5/6] short summary, key, returns, indent and quote typo, and exemples improved --- pandas/core/generic.py | 105 +++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 51 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7c9158b264979..a7fe95f2e7b59 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3272,14 +3272,13 @@ def xs(self, key, axis=0, level=None, drop_level=True): """ 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). + This methode takes a level argument to select data at a particular + level of a MultiIndex easier. Parameters ---------- - key : label - Some label contained in the index, or partially in a MultiIndex. + key : label or tuple of label, e.g. ['a', 'b', 'c'] + Label contained in the index, or partially in a MultiIndex. axis : {0 or 'index', 1 or 'columns'}, default 0 Axis to retrieve cross-section on. level : object, defaults to first n levels (n=1 or len(key)) @@ -3290,72 +3289,76 @@ def xs(self, key, axis=0, level=None, drop_level=True): Returns ------- - Series or DataFrame + Series or DataFrame of the cross-section (row(s) or column(s)) from + the original Series/DataFrame. See Also -------- DataFrame.loc : Access a group of rows and columns - by label(s) or a boolean array. + by label(s) or a boolean array. DataFrame.iloc : Purely integer-location based indexing - for selection by position. + for selection by position. Notes ----- - 'xs' can not be used to set 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 + levels. It is a superset of `xs` functionality, see :ref:`MultiIndex Slicers `. Examples -------- - >>> df = pd.DataFrame({"num_legs": [4, 4, 2], - ... "num_arms": [0, 0, 0], - ... "num_wings": [0, 0, 2]}, - ... ["dog", "cat", "duck"]) + >>> d = {'num_legs': [4, 4, 2, 2], + ... 'num_wings': [0, 0, 2, 2], + ... 'class': ['mammal', 'mammal', 'mammal', 'bird'], + ... 'animal': ['cat', 'dog', 'bat', 'penguin'], + ... 'locomotion': ['walks', 'walks', 'flies', 'walks']} + >>> df = pd.DataFrame(data=d) + >>> df = df.set_index(['class', 'animal', 'locomotion']) >>> df - num_legs num_arms num_wings - dog 4 0 0 - cat 4 0 0 - duck 2 0 2 - >>> df.xs('dog') - num_legs 4 - num_arms 0 - num_wings 0 - Name: dog, dtype: int64 + num_legs num_wings + class animal locomotion + mammal cat walks 4 0 + dog walks 4 0 + bat flies 2 2 + bird penguin walks 2 2 + >>> df.xs('mammal') + num_legs num_wings + animal locomotion + cat walks 4 0 + dog walks 4 0 + bat flies 2 2 >>> df.xs('num_wings', axis=1) - dog 0 - cat 0 - duck 2 + class animal locomotion + mammal cat walks 0 + dog walks 0 + bat flies 2 + bird penguin walks 2 Name: num_wings, dtype: int64 - >>> d = {'num_legs': [4, 4, 2, 4], - ... 'num_arms': [0, 0, 0, 0], - ... 'num_wings': [0, 0, 2, 0], - ... 'num_spec_seen': [9, 2, 7, 3], - ... 'class': ['mammal', 'mammal', 'sauropsida', 'sauropsida'], - ... 'animal': ['cat', 'dog', 'duck', 'turtle'], - ... 'area': [1, 1, 2, 3]} - >>> df = pd.DataFrame(data=d) - >>> df = df.set_index(['class', 'animal', 'area']) - >>> df - num_legs num_arms num_wings num_spec_seen - class animal area - mammal cat 1 4 0 0 9 - dog 1 4 0 0 2 - sauropsida duck 2 2 0 2 7 - turtle 3 4 0 0 3 >>> df.xs(('mammal', 'dog')) - num_legs num_arms num_wings num_spec_seen - area - 1 4 0 0 2 + num_legs num_wings + locomotion + walks 4 0 + >>> df.xs('num_wings', axis=1) + class animal locomotion + mammal cat walks 0 + dog walks 0 + bat flies 2 + bird penguin walks 2 + Name: num_wings, dtype: int64 + >>> df.xs(('mammal', 'bat')) + num_legs num_wings + locomotion + flies 2 2 >>> df.xs('cat', level=1) - num_legs num_arms num_wings num_spec_seen - class area - mammal 1 4 0 0 9 - >>> df.xs(('sauropsida', 2), level=[0, 'area']) - num_legs num_arms num_wings num_spec_seen + num_legs num_wings + class locomotion + mammal walks 4 0 + >>> df.xs(('bird', 'walks'), level=[0, 'locomotion']) + num_legs num_wings animal - duck 2 0 2 7 + penguin 2 2 """ axis = self._get_axis_number(axis) labels = self._get_axis(axis) From 3f11180af143f943eab53f3404b0eab31e7d1443 Mon Sep 17 00:00:00 2001 From: "thomas.lentali" Date: Sun, 2 Dec 2018 18:07:58 +0100 Subject: [PATCH 6/6] correction of remaining typo and examples by block --- pandas/core/generic.py | 59 +++++++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a7fe95f2e7b59..d4012d65580c6 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3272,12 +3272,12 @@ def xs(self, key, axis=0, level=None, drop_level=True): """ Return cross-section from the Series/DataFrame. - This methode takes a level argument to select data at a particular - level of a MultiIndex easier. + This method takes a `key` argument to select data at a particular + level of a MultiIndex. Parameters ---------- - key : label or tuple of label, e.g. ['a', 'b', 'c'] + key : label or tuple of label Label contained in the index, or partially in a MultiIndex. axis : {0 or 'index', 1 or 'columns'}, default 0 Axis to retrieve cross-section on. @@ -3289,8 +3289,9 @@ def xs(self, key, axis=0, level=None, drop_level=True): Returns ------- - Series or DataFrame of the cross-section (row(s) or column(s)) from - the original Series/DataFrame. + Series or DataFrame + Cross-section from the original Series or DataFrame + corresponding to the selected index levels. See Also -------- @@ -3303,8 +3304,9 @@ def xs(self, key, axis=0, level=None, drop_level=True): ----- `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 + 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 `. Examples @@ -3323,42 +3325,47 @@ class animal locomotion dog walks 4 0 bat flies 2 2 bird penguin walks 2 2 + + Get values at specified index + >>> df.xs('mammal') num_legs num_wings animal locomotion cat walks 4 0 dog walks 4 0 bat flies 2 2 - >>> df.xs('num_wings', axis=1) - class animal locomotion - mammal cat walks 0 - dog walks 0 - bat flies 2 - bird penguin walks 2 - Name: num_wings, dtype: int64 + + Get values at several indexes + >>> df.xs(('mammal', 'dog')) num_legs num_wings locomotion walks 4 0 - >>> df.xs('num_wings', axis=1) - class animal locomotion - mammal cat walks 0 - dog walks 0 - bat flies 2 - bird penguin walks 2 - Name: num_wings, dtype: int64 - >>> df.xs(('mammal', 'bat')) - num_legs num_wings - locomotion - flies 2 2 + + Get values at specified index and level + >>> df.xs('cat', level=1) num_legs num_wings class locomotion mammal walks 4 0 - >>> df.xs(('bird', 'walks'), level=[0, 'locomotion']) + + Get values at several indexes and levels + + >>> df.xs(('bird', 'walks'), + ... level=[0, 'locomotion']) num_legs num_wings animal penguin 2 2 + + Get values at specified column and axis + + >>> df.xs('num_wings', axis=1) + class animal locomotion + mammal cat walks 0 + dog walks 0 + bat flies 2 + bird penguin walks 2 + Name: num_wings, dtype: int64 """ axis = self._get_axis_number(axis) labels = self._get_axis(axis)