From 0d49def3eb98b960516892eac29a45056f26a152 Mon Sep 17 00:00:00 2001 From: Agustin Mendez Date: Sat, 15 Jul 2017 17:00:23 +0200 Subject: [PATCH 1/2] DOC: Improving docstring of take method --- pandas/core/generic.py | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index d9d75c870b20c..8c76cced680e6 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2063,7 +2063,8 @@ def __delitem__(self, key): def take(self, indices, axis=0, convert=True, is_copy=True, **kwargs): """ - Analogous to ndarray.take + Return an object formed from the elements in the given indices along an + axis Parameters ---------- @@ -2072,6 +2073,44 @@ def take(self, indices, axis=0, convert=True, is_copy=True, **kwargs): convert : translate neg to pos indices (default) is_copy : mark the returned frame as a copy + Examples + -------- + >>> import numpy as np + >>> import pandas as pd + >>> df = pd.DataFrame([('falcon', 'bird', 389.0), + ('parrot', 'bird', 24.0), + ('lion', 'mammal', 80.5), + ('monkey', 'mammal', np.nan)], + columns=('name', 'class', 'max_speed')) + >>> df + name class max_speed + 0 falcon bird 389.0 + 1 parrot bird 24.0 + 2 lion mammal 80.5 + 3 monkey mammal NaN + + Take elements at indices 0 and 3 along the axis 0 (default) + + >>> df.take([0, 3]) + 0 falcon bird 389.0 + 3 monkey mammal NaN + + Take elements at indices 1 and 2 along the axis 1 + + >>> df.take([1, 2], axis=1) + class max_speed + 0 bird 389.0 + 1 bird 24.0 + 2 mammal 80.5 + 3 mammal NaN + + Also, we may take elements using negative integers for pos indices + + >>> df.take([-1, -2]) + name class max_speed + 3 monkey mammal NaN + 2 lion mammal 80.5 + Returns ------- taken : type of caller From 0a077750951467c273368f113b26c7411e131b80 Mon Sep 17 00:00:00 2001 From: gfyoung Date: Sun, 20 Aug 2017 20:24:52 -0700 Subject: [PATCH 2/2] DOC: Address reviewer comments --- pandas/core/generic.py | 60 ++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 20 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8c76cced680e6..c83b1073afc8e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2063,57 +2063,77 @@ def __delitem__(self, key): def take(self, indices, axis=0, convert=True, is_copy=True, **kwargs): """ - Return an object formed from the elements in the given indices along an - axis + Return the elements in the given *positional* indices along an axis. + + This means that we are not indexing according to actual values in + the index attribute of the object. We are indexing according to the + actual position of the element in the object. Parameters ---------- - indices : list / array of ints + indices : array-like + An array of ints indicating which positions to take. axis : int, default 0 - convert : translate neg to pos indices (default) - is_copy : mark the returned frame as a copy + The axis on which to select elements. "0" means that we are + selecting rows, "1" means that we are selecting columns, etc. + convert : bool, default True + Whether to convert negative indices to positive ones, just as with + indexing into Python lists. For example, if `-1` was passed in, + this index would be converted ``n - 1``. + is_copy : bool, default True + Whether to return a copy of the original object or not. Examples -------- - >>> import numpy as np - >>> import pandas as pd >>> df = pd.DataFrame([('falcon', 'bird', 389.0), ('parrot', 'bird', 24.0), ('lion', 'mammal', 80.5), ('monkey', 'mammal', np.nan)], - columns=('name', 'class', 'max_speed')) + columns=('name', 'class', 'max_speed'), + index=[0, 2, 3, 1]) >>> df name class max_speed 0 falcon bird 389.0 - 1 parrot bird 24.0 - 2 lion mammal 80.5 - 3 monkey mammal NaN + 2 parrot bird 24.0 + 3 lion mammal 80.5 + 1 monkey mammal NaN + + Take elements at positions 0 and 3 along the axis 0 (default). - Take elements at indices 0 and 3 along the axis 0 (default) + Note how the actual indices selected (0 and 1) do not correspond to + our selected indices 0 and 3. That's because we are selecting the 0th + and 3rd rows, not rows whose indices equal 0 and 3. >>> df.take([0, 3]) 0 falcon bird 389.0 - 3 monkey mammal NaN + 1 monkey mammal NaN - Take elements at indices 1 and 2 along the axis 1 + Take elements at indices 1 and 2 along the axis 1 (column selection). >>> df.take([1, 2], axis=1) class max_speed 0 bird 389.0 - 1 bird 24.0 - 2 mammal 80.5 - 3 mammal NaN + 2 bird 24.0 + 3 mammal 80.5 + 1 mammal NaN - Also, we may take elements using negative integers for pos indices + We may take elements using negative integers for positive indices, + starting from the end of the object, just like with Python lists. >>> df.take([-1, -2]) name class max_speed - 3 monkey mammal NaN - 2 lion mammal 80.5 + 1 monkey mammal NaN + 3 lion mammal 80.5 Returns ------- taken : type of caller + An array-like containing the elements taken from the object. + + See Also + -------- + numpy.ndarray.take + numpy.take """ nv.validate_take(tuple(), kwargs) self._consolidate_inplace()