8000 DOC: Add examples for MultiIndex.get_locs + cleanups by topper-123 · Pull Request #17675 · pandas-dev/pandas · GitHub
[go: up one dir, main page]
Skip to content

DOC: Add examples for MultiIndex.get_locs + cleanups #17675

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 3 commits into from
Sep 30, 2017
Merged

DOC: Add examples for MultiIndex.get_locs + cleanups #17675

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6d25f00
Add examples for MultiIndex.get_locs + cleanups
Sep 25, 2017
6008e3c
clarifies input to get_loc is sequence
Sep 26, 2017
070e8f3
Small addition/cleanup + resolved merge conflict
Sep 28, 2017
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
Prev Previous commit
Next Next commit
clarifies input to get_loc is sequence
  • Loading branch information
tp committed Sep 29, 2017
commit 6008e3c7f9388e5b0246effad108cb21df68aee8
2 changes: 1 addition & 1 deletion pandas/core/categorical.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ class Categorical(PandasObject):

See also
--------
pandas.api.types.CategoricalDtype
Copy link
Contributor

Choose a reason for hiding this comment

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

does this property xref here? (CategoricalDtype is NOT in the main namespace)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, I've changed it to api.types.CategoricalDtype. I had misunderstood the location.

Copy link
Contributor Author
@topper-123 topper-123 Sep 26, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

Looking more into it, I actually think CategoricalDtype isn't shown at all in the generated API docs, so the reference will be not work in any case. Is this correct?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, the problem is not that 'pandas' is there (that is perfectly OK, and in this case I even prefer to show the full path for clarity, as api is not a commonly used submodule of pandas), the issue is that this page does not exist, so it cannot link to it

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'll put pandas. back in then.

Copy link
Member

Choose a reason for hiding this comment

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

Yep. You can also add it to the api.rst pages so the link will work

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Change uploaded.

There seems to be something in the API.rst (line 649), but it mustn't work. @TomAugspurger has started looking into it, I'll wait till he figures it out.

If I get to know what I should add to API.rst, I can add it to this PR.

Copy link
Contributor
@TomAugspurger TomAugspurger Sep 26, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

In api.rst it should be pandas.api.type.CategoricalDtype (missing the pandas).

But the autoclass fit the best with the rest of the autosummary's, so I may change it. For now, I'd just leave your reference as pandas.api.type.CategoricalDtype, and I'll make sure they're valid before the release.

pandas.api.types.CategoricalDtype : Type for categorical data
CategoricalIndex : An Index with an underlying ``Categorical``
"""

Expand Down
35 changes: 20 additions & 15 deletions pandas/core/indexes/multi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ class MultiIndex(Index):
Examples
---------
A new ``MultiIndex`` is typically constructed using one of the helper
methods :meth:`MultiIndex.from_arrays``, :meth:`MultiIndex.from_product``
and :meth:`MultiIndex.from_tuples``. For example (using ``.from_arrays``):
methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product`
and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``):

>>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
>>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color'))
Expand Down Expand Up @@ -1985,13 +1985,9 @@ def get_loc(self, key, method=None):
Get location for a label or a tuple of labels as an integer, slice or
boolean mask.

Copy link
Contributor

Choose a reason for hiding this comment

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

I would put this Note in Notes.

Note that the key cannot be a slice, list of same-level labels,
a boolean mask, or a sequence of such. If you want that, use
:meth:`get_locs` instead.

Parameters
----------
key : label or tuple of labels
key : label or tuple of labels (one for each level)
method : None

Returns
Expand All @@ -2003,17 +1999,24 @@ def get_loc(self, key, method=None):
Examples
---------
>>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])

>>> mi.get_loc('b')
slice(1, 3, None)

>>> mi.get_loc(('b', 'e'))
1

Notes
------
The key cannot be a slice, list of same-level labels, a boolean mask,
or a sequence of such. If you want to use those, use :meth:`get_locs`
Copy link
Member

Choose a reason for hiding this comment

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

get_locs -> MultiIndex.get_locs (I think, it would actually be interesting to know whether it works like this if it is a method of the same class. Did you build it locally and checked? But I think this will not work, because in the generated rst docstring pages, a .. currentmodule:: pandas is included)

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've Changed it.

It it possible to to build just the API docs or maybe a subgroup thereof? Working with doc is a but cumbersome, when building it takes so much time.

Copy link
Contributor

Choose a reason for hiding this comment

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

you pass the arg —�single api

Copy link
Member

Choose a reason for hiding this comment

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

Yes, it can indeed be very cumbersome. It's a very long time ago that I tried the --single flag. It was also meant to eg run only a single .rst file. But I can remember it also didn't work smoothly.

If you think of other ways to make this easier, very welcome! (I once had a script to build only a single docstring, I could try to look that up, but not sure that such links then would work anyhow)

instead.

See also
--------
Index.get_loc : get_loc method for (single-level) index.
get_locs : Given a tuple of slices/lists/labels/boolean indexer to a
level-wise spec, produce an indexer to extract those
locations.
get_locs : Get location for a label/slice/list/mask or a sequence of
Copy link
Member

Choose a reason for hiding this comment

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

get_locs -> MultiIndex.get_locs

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok

such.
"""
if method is not None:
raise NotImplementedError('only the default get_loc method is '
Expand Down Expand Up @@ -2122,7 +2125,9 @@ def get_loc_level(self, key, level=0, drop_level=True):

See Also
---------
MultiIndex.get_loc : Get location for a label or a tuple of labels.
MultiIndex.get_loc : Get location for a label or a tuple of labels.
MultiIndex.get_locs : Get location for a label/slice/list/mask or a
sequence of such
"""

def maybe_droplevels(indexer, levels, drop_level):
Expand Down Expand Up @@ -2332,14 +2337,14 @@ def convert_indexer(start, stop, step, indexer=indexer, labels=labels):
j = labels.searchsorted(loc, side='right')
return slice(i, j)

def get_locs(self, tup):
def get_locs(self, seq):
"""
Get location for a given label/slice/list/mask or a sequence of such as
a integer, slice or boolean mask.

Parameters
----------
key : label/slice/list/mask or a sequence of such.
seq : label/slice/list/mask or a sequence of such.
Copy link
Member

Choose a reason for hiding this comment

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

It might be good to explain how the 'sequence of such' should be interpreted

(I should check the code myself to actually know it, but are the different elements of the list mapped to the different levels?)

Copy link
Member

Choose a reason for hiding this comment

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

maybe add here "(one for each level)" as you did in get_loc

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've made a new proposal. This is very difficult to explain in short sentences, I find.


Returns
-------
Expand All @@ -2365,7 +2370,7 @@ def get_locs(self, tup):
"""

# must be lexsorted to at least as many levels
true_slices = [i for (i, s) in enumerate(is_true_slices(tup)) if s]
true_slices = [i for (i, s) in enumerate(is_true_slices(seq)) if s]
if true_slices and true_slices[-1] >= self.lexsort_depth:
raise UnsortedIndexError('MultiIndex slicing requires the index '
'to be lexsorted: slicing on levels {0}, '
Expand Down Expand Up @@ -2398,7 +2403,7 @@ def _update_indexer(idxr, indexer=indexer):
return indexer
return indexer & idxr

for i, k in enumerate(tup):
for i, k in enumerate(seq):

if is_bool_indexer(k):
# a boolean indexer, must be the same length!
Expand Down
0