DOC: Created an indexing how-to #20093
Conversation
There was a problem hiding this comment.
Thanks for getting started on this @Mukulikaa ! I feel like we could have a couple more examples, and maybe we should link to Nicolas Rougier's exercises?
doc/source/user/how-to-index.rst
Outdated
| >>> arr = np.arange(3*4).reshape(3, 4) | ||
| >>> column_indices = [[1, 3], [0, 2], [2, 2]] | ||
| >>> np.arange(arr.shape[0])[:, np.newaxis] | ||
| array([[0], | ||
| [1], | ||
| [2]]) | ||
| >>> arr[np.arange(arr.shape[0])[:, np.newaxis], column_indices] | ||
| array([[ 1, 3], | ||
| [ 4, 6], | ||
| [10, 10]]) |
There was a problem hiding this comment.
This is a good example, but I feel like it is a bit cryptic. Maybe expand a little bit on the motivation or print a few of the steps to make it easier for the reader?
doc/source/user/how-to-index.rst
Outdated
| Use :ref:`slicing-and-striding` to access chunks of an array. | ||
| But if you want to access multiple scattered elements to create | ||
| complicated subsets, you have to use :ref:`advanced-indexing`. Use | ||
| :func:`ix_` to quickly contruct index arrays:: |
There was a problem hiding this comment.
I think at some point we had discussed not encouraging the use of ix_ - @rossbar do you remember this?
There was a problem hiding this comment.
I don't remember specifically, but I generally agree.
doc/source/user/how-to-index.rst
Outdated
| Replace values | ||
| -------------- |
There was a problem hiding this comment.
Is it on purpose that this is a sub-header to "Filter values"?
There was a problem hiding this comment.
Yes... My idea was "after you filter the values you can even replace them this way".
|
The rendered page is here. |
There was a problem hiding this comment.
Hi @Mukulikaa, I have a few notes but nothing major - I think this is good and any further improvements can be done in a follow up, so I'm approving. Thanks again for doing great work!
doc/source/user/how-to-index.rst
Outdated
| Index columns | ||
| ------------- | ||
|
|
||
| Use :ref:`dimensional-indexing-tools` to avoid shape mismatches:: |
There was a problem hiding this comment.
I'm not sure this is very clear on first read - maybe show what would happen if you used a "naive" approach here first?
Also fixed minor typos and styling errors
02753aa to
916b65a
Compare
|
Thanks for your help, @melissawm! |
| ========================================== | ||
|
|
||
| Use :ref:`basic-indexing` features like :ref:`slicing-and-striding`, and | ||
| :ref:`dimensional-indexing-tools`. |
There was a problem hiding this comment.
The rendered page for the latest commit https://23276-908607-gh.circle-artifacts.com/0/doc/build/html/user/how-to-index.html is showing italic text for all the output. Does the line before the indent need a : or is a code formatting directive needed to force <code> format?
There was a problem hiding this comment.
I think it is always like that? I checked a couple of other examples. I didn't use : in some places because I didn't think it was appropriate...
There was a problem hiding this comment.
ok. let's put this in as-is, we can always iterate on the formatting.
|
Thanks @Mukulikaa |
Addresses most points in #19586.
Looking forward to any feedback regarding best practices or other use-cases that should be included!
cc: @melissawm @rossbar